> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zeroruntime.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# VAD and Interruptions

> Detect speech with Silero VAD, let users barge in while the agent is talking, and gracefully recover from false interruptions.

Voice Activity Detection (VAD) identifies when speech is present in an audio stream. It acts as a first-pass filter and enables interruption handling in your pipeline by signaling when a user starts talking. Zero Runtime uses Silero VAD for speech-activity detection; for the most reliable results, pair VAD with a turn detector.

## Configure Silero VAD

Configure VAD and pass it to your `Pipeline` as the `vad` component:

<CodeGroup>
  ```python Python theme={null}
  from zrt.plugins import SileroVAD

  # Configure VAD to detect speech activity
  vad = SileroVAD(
      threshold=0.5,                # Sensitivity to speech (0.3 to 0.8)
      min_speech_duration=0.1,      # Ignore very brief sounds
      min_silence_duration=0.75     # Wait time before considering speech ended
  )
  ```
</CodeGroup>

## Interruption Detection

Interruption Detection decides when user speech should stop the agent mid-response. It can use VAD, STT, or both. This avoids false triggers from short noises, filler words, or background audio.

**Using VAD** detects raw speech activity. It is faster but can be triggered by background noise.

<CodeGroup>
  ```python Python theme={null}
  from zrt import Pipeline, InterruptConfig

  pipeline = Pipeline(
      # ... other config
      interrupt_config=InterruptConfig(
          mode="VAD_ONLY",
          interrupt_min_duration=0.2  # 200ms of continuous speech
      )
  )
  ```
</CodeGroup>

**Using STT** relies only on recognized words from the transcript. It is slower but ensures the speech is intelligible.

<CodeGroup>
  ```python Python theme={null}
  from zrt import Pipeline, InterruptConfig

  pipeline = Pipeline(
      # ... other config
      interrupt_config=InterruptConfig(
          mode="STT_ONLY",
          interrupt_min_words=2  # At least 2 words recognized
      )
  )
  ```
</CodeGroup>

Use `HYBRID` mode to require both audio detection and recognized words.

## False Interruption Recovery

A false interruption is a brief accidental noise, like a cough, an "mm-hmm", or background
noise, that should not stop the agent. Instead of cutting off immediately, `InterruptConfig`
lets the agent pause and confirm whether an interruption is genuine before deciding to stop or
resume speaking.

### How it works

<Steps>
  <Step title="Maybe-interruption">
    The user makes a sound while the agent is speaking. Instead of cutting off, the agent
    pauses TTS and starts a timer (`false_interrupt_pause_duration`).
  </Step>

  <Step title="Confirm or resume">
    If a transcript with at least `interrupt_min_words` words arrives before the timer
    expires (or VAD confirms sustained speech), it's a real interruption and the agent
    stops. Otherwise the timer expires and the agent resumes speaking from where it paused.
  </Step>
</Steps>

### Enable it

Set `resume_on_false_interrupt=True` on the pipeline's `InterruptConfig`. Tune
`false_interrupt_pause_duration` for how long to wait before deciding it was a false alarm.

<CodeGroup>
  ```python title="main.py" Python theme={null}
  from zrt import Pipeline, InterruptConfig

  pipeline = Pipeline(
      # ... other config
      interrupt_config=InterruptConfig(
          false_interrupt_pause_duration=2.0,  # Wait 2 seconds to confirm
          resume_on_false_interrupt=True       # Auto-resume if interruption is brief
      )
  )
  ```
</CodeGroup>

## Configuration

| Parameter                        | Type                                       | Default    | Description                                                                                |
| :------------------------------- | :----------------------------------------- | :--------- | :----------------------------------------------------------------------------------------- |
| `mode`                           | `"VAD_ONLY"` \| `"STT_ONLY"` \| `"HYBRID"` | `"HYBRID"` | Detection method for interruptions.                                                        |
| `interrupt_min_duration`         | `float`                                    | `0.5`      | Minimum speech duration in seconds to trigger an interrupt.                                |
| `interrupt_min_words`            | `int`                                      | `2`        | Minimum words needed to confirm an interrupt.                                              |
| `false_interrupt_pause_duration` | `float`                                    | `2.0`      | Pause duration in seconds on a false interrupt, before deciding it was false and resuming. |
| `resume_on_false_interrupt`      | `bool`                                     | `True`     | Whether to resume agent speech after a false interrupt.                                    |

## What's Next

<CardGroup cols={2}>
  <Card title="Turn Detection" icon="comment-dots" href="/build/turn-detection-and-interruptions/turn-detection">
    Pair VAD with semantic turn detection.
  </Card>

  <Card title="De-noise" icon="headphones" href="/build/turn-detection-and-interruptions/denoise">
    Give VAD a cleaner audio signal.
  </Card>
</CardGroup>

## References

<Tabs>
  <Tab title="Python">
    #### Examples

    <CardGroup cols={2}>
      <Card title="Cascade Basic" icon="github" href="https://github.com/ZeroRuntimeAI/zrt-python-sdk-examples/blob/main/features/basic_cascade.py">
        Voice agent with VAD configured.
      </Card>
    </CardGroup>

    #### SDK Reference

    <CardGroup cols={2}>
      <Card title="VAD" icon="waveform-lines" href="/api-reference/python/core/pipeline#vad">
        `VAD` in the Python API reference.
      </Card>

      <Card title="Utterance Handle" icon="book" href="/api-reference/python/core/pipeline#utterancehandle">
        `Utterance Handle` in the Python API reference.
      </Card>
    </CardGroup>
  </Tab>
</Tabs>