# How to Customize VAD Thresholds for Different Audio Environments in FluidAudio

> Customize VAD thresholds in FluidAudio for any audio environment. Adjust defaultThreshold and VadSegmentationConfig for precise voice activity detection and segmentation.

- Repository: [Fluid Inference/fluidaudio](https://github.com/fluidinference/fluidaudio)
- Tags: how-to-guide
- Published: 2026-03-02

---

**To customize VAD thresholds in FluidAudio, configure `VadConfig.defaultThreshold` for global entry sensitivity and `VadSegmentationConfig` for fine-grained hysteresis, silence detection, and segment boundaries.**

FluidAudio provides a configurable Voice Activity Detection (VAD) system that allows developers to customize VAD thresholds for different audio environments. Whether you are processing audio from noisy factory floors or quiet meeting rooms, adjusting these thresholds in [`Sources/FluidAudio/VAD/VadTypes.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadTypes.swift) ensures accurate speech detection and segmentation tailored to specific acoustic conditions.

## Understanding VAD Threshold Layers in FluidAudio

The VAD architecture separates threshold configuration into two distinct layers: global entry thresholds and segmentation-specific parameters.

### Global Entry Threshold (VadConfig)

The `VadConfig` struct controls the primary detection sensitivity. The `defaultThreshold` property (default value **0.85**) determines the probability score above which an audio chunk is classified as speech. When constructing a `VadManager`, you can override this value to suit your environment.

### Segmentation-Specific Thresholds (VadSegmentationConfig)

For fine-grained control over speech boundaries, `VadSegmentationConfig` provides fields such as `silenceThresholdForSplit`, `negativeThreshold`, `negativeThresholdOffset`, `minSpeechDuration`, `minSilenceDuration`, `maxSpeechDuration`, and `speechPadding`. These parameters control hysteresis behavior, determining when a segment starts and ends based on silence detection and duration constraints.

The streaming API automatically calculates exit thresholds using `VadSegmentationConfig.effectiveNegativeThreshold(baseThreshold:)`, which derives the negative threshold from the base entry threshold unless explicitly overridden.

### CLI Overrides for Rapid Testing

The command-line interface in [`Sources/FluidAudioCLI/Commands/VadAnalyzeCommand.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudioCLI/Commands/VadAnalyzeCommand.swift) and [`Sources/FluidAudioCLI/Commands/VadBenchmark.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudioCLI/Commands/VadBenchmark.swift) exposes these parameters as flags including `--threshold`, `--silence-split-threshold`, `--neg-threshold`, `--neg-offset`, `--min-speech-ms`, and `--min-silence-ms`, allowing quick experimentation without code changes.

## Configuring Thresholds for Specific Audio Environments

Different acoustic conditions require distinct threshold strategies to balance false positives against missed speech.

### Noisy Environments (Factories, Offices)

In high-noise environments, lower the entry threshold to **0.5** or **0.55** to ensure the model captures speech despite background interference. However, increase the exit hysteresis by raising `negativeThresholdOffset` (or using `--neg-offset` in CLI) to prevent rapid flip-flopping on transient noise spikes.

### Quiet Meeting Rooms

For controlled acoustic environments with minimal background noise, raise the entry threshold to **0.9** to suppress false positives from breathing or paper rustling. Tighten `silenceThresholdForSplit` to **0.4** or higher so that short pauses do not trigger unnecessary segment boundaries.

### Long Monologues and Continuous Speech

When processing lengthy single-speaker content such as lectures or audiobooks, increase `maxSpeechDuration` beyond the default to prevent artificial splitting. Enable `useMaxPossibleSilenceAtMaxSpeech` (default `true`) to ensure that when the maximum duration is reached, the system splits only at meaningful pauses rather than mid-word.

## Implementation Examples

The following Swift examples demonstrate how to apply these configurations programmatically using the `VadManager` API in [`Sources/FluidAudio/VAD/VadManager.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadManager.swift).

To initialize a manager with a lower global threshold for noisy environments:

```swift
import FluidAudio

let manager = try await VadManager(
    config: VadConfig(defaultThreshold: 0.55, debugMode: true)
)

```

To configure segmentation parameters for a quiet meeting room:

```swift
var segConfig = VadSegmentationConfig.default
segConfig.minSpeechDuration = 0.2          // Ignore coughs and short noises
segConfig.minSilenceDuration = 0.5        // Require longer pauses to close segment
segConfig.silenceThresholdForSplit = 0.4 // Stricter silence detection
segConfig.negativeThreshold = 0.35        // Custom hysteresis exit point

let audioSamples = try AudioConverter().resampleAudioFile(path: "meeting.wav")
let segments = try await manager.segmentSpeech(audioSamples, config: segConfig)

```

For streaming applications, apply the same configuration to each chunk:

```swift
var streamState = await manager.makeStreamState()

for chunk in microphoneChunks {   // Each ≈256 ms at 16 kHz
    let result = try await manager.processStreamingChunk(
        chunk,
        state: streamState,
        config: segConfig,
        returnSeconds: true,
        timeResolution: 2
    )
    streamState = result.state
    print("Prob:", result.probability,
          "Event:", result.event?.kind ?? "none")
}

```

For command-line workflows, use CLI flags to override thresholds without recompiling:

```bash

# Offline segmentation with higher threshold for quiet room

fluidaudio vad-analyze myMeeting.wav \
    --threshold 0.9 \
    --silence-split-threshold 0.45 \
    --neg-threshold 0.35 \
    --min-speech-ms 200 \
    --min-silence-ms 500 \
    --max-speech-s 30 \
    --pad-ms 100

# Benchmark a noisy environment with lower threshold

fluidaudio vad-benchmark \
    --threshold 0.45 \
    --activity-threshold 0.30 \
    --dataset vad-mini50 \
    --output noisy_bench.json

```

## Key Source Files and Architecture

Understanding the source layout helps when debugging threshold behavior or extending the VAD system:

- [`Sources/FluidAudio/VAD/VadTypes.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadTypes.swift) – Defines `VadConfig` and `VadSegmentationConfig`, including the `effectiveNegativeThreshold(baseThreshold:)` method that calculates hysteresis values.
- [`Sources/FluidAudio/VAD/VadManager.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadManager.swift) – Implements the high-level API including `segmentSpeech(_:config:)` and `processStreamingChunk` for streaming inference.
- [`Sources/FluidAudioCLI/Commands/VadAnalyzeCommand.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudioCLI/Commands/VadAnalyzeCommand.swift) – Parses command-line flags such as `--threshold` and `--silence-split-threshold` into configuration structs.
- [`Sources/FluidAudioCLI/Commands/VadBenchmark.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudioCLI/Commands/VadBenchmark.swift) – Provides benchmarking tools with threshold overrides for performance testing across different acoustic conditions.

## Summary

- **Customize VAD thresholds** in FluidAudio by modifying `VadConfig.defaultThreshold` for global entry sensitivity and `VadSegmentationConfig` for fine-grained segmentation control.
- **Noisy environments** benefit from lower entry thresholds (0.5–0.55) combined with increased hysteresis via `negativeThresholdOffset` to prevent flip-flopping.
- **Quiet environments** require higher entry thresholds (0.9) and stricter silence detection to suppress false positives from minor sounds.
- **Long-form audio** necessitates adjusting `maxSpeechDuration` and leveraging `useMaxPossibleSilenceAtMaxSpeech` to split only at natural pauses.
- **CLI tools** provide rapid experimentation through flags like `--threshold`, `--neg-threshold`, and `--silence-split-threshold` without recompiling.

## Frequently Asked Questions

### What is the default VAD threshold in FluidAudio?

The default entry threshold is defined in `VadConfig.defaultThreshold` with a value of **0.85**, located in [`Sources/FluidAudio/VAD/VadTypes.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadTypes.swift). This means audio chunks with a speech probability above 85% are classified as voice activity by default.

### How do I prevent rapid flip-flopping in noisy environments?

In high-noise environments, lower the entry threshold to capture more potential speech, but increase the exit hysteresis by setting a higher `negativeThresholdOffset` (or using the `--neg-offset` CLI flag). This creates a "sticky zone" where the model remains in the speech state unless confidence drops significantly, preventing oscillation on transient noise spikes.

### Can I use different thresholds for streaming versus offline processing?

Yes. The `VadManager` API accepts a `VadSegmentationConfig` parameter in both `segmentSpeech(_:config:)` for offline batch processing and `processStreamingChunk` for real-time streaming. You can instantiate separate configuration objects with different threshold values and pass them to the respective methods, allowing environment-specific tuning for each processing mode.

### Where are the VAD configuration structs defined?

The core configuration structures are defined in [`Sources/FluidAudio/VAD/VadTypes.swift`](https://github.com/fluidinference/fluidaudio/blob/main/Sources/FluidAudio/VAD/VadTypes.swift). This file contains `VadConfig` (global threshold settings), `VadSegmentationConfig` (fine-grained segmentation parameters), and the `effectiveNegativeThreshold(baseThreshold:)` method that calculates hysteresis values for the streaming API.