Metadata-Version: 2.4
Name: fasr-vad-silero
Version: 0.5.8
Summary: Silero VAD model for fasr
Author-email: fasr <790990241@qq.com>
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: fasr
Requires-Dist: numpy>=1.24
Requires-Dist: torch>=2.0.0

# fasr-vad-silero

英文文档地址: [README_EN.md](README_EN.md)

Silero 流式 VAD 插件。官方 TorchScript 权重随包分发，启动时不依赖
`torch.hub` 或网络下载，并封装为 fasr 的流式 `VADModel`，输出带有
`segment_start`、`segment_mid`、`segment_end` 状态的 `AudioChunk`。

## 安装

```bash
pip install fasr-vad-silero
```

## 注册模型

| 注册名 | 类 | 适用场景 |
|---|---|---|
| `silero` | `SileroStreamVAD` | 轻量流式 VAD |

## 流式使用

```python
from fasr.config import registry

vad = registry.vad_models.get("silero")(
    threshold=0.5,
    silence_duration_ms=500,
)

for input_chunk in audio_chunks:
    for speech_chunk in vad.push_chunk(input_chunk):
        print(speech_chunk.vad_state, speech_chunk.start_ms, speech_chunk.end_ms)
```

## 批量使用

```python
from fasr.data import AudioSpan

segments = vad.detect(
    AudioSpan(
        start_ms=0,
        waveform=waveform,
    )
)
```

`detect(...)` 会把整段音频按流式路径重放一遍，因此批量分段和实时模式共享同一套
阈值、prefix padding 与端点规则。

| 目标 | 写法 | 效果 |
|---|---|---|
| 减少噪声触发 | `threshold=0.65` | 需要更高语音概率 |
| 保留轻声 | `threshold=0.35` | 更敏感，误检风险更高 |
| 更快结束 | `silence_duration_ms=200` | 端点延迟更低 |
| 避免停顿切碎 | `silence_duration_ms=700` | 更容忍短暂停顿 |

## Confection 配置

```toml
[vad_model]
@vad_models = "silero"
threshold = 0.5
silence_duration_ms = 500
prefix_padding_ms = 0
sample_rate = 16000
chunk_size_ms = 32
```

## 参数

| 参数 | 类型 / 范围 | 默认值 | 调高时 | 调低时 | 什么时候改 |
|---|---|---|---|---|---|
| `threshold` | `float`，`0.0` 到 `1.0` | `0.5` | 更严格，噪声起点更少 | 更敏感，保留更多弱语音 | 噪声误触发或轻声漏掉 |
| `silence_duration_ms` | `int >= 0` | `500` | 更久静音才结束 | 更快结束 | 语音被切碎或结束太晚 |
| `prefix_padding_ms` | `int >= 0` | `0` | 更不容易截掉句首，但可能带入更多前置噪声 | 片段更紧，但更容易丢掉第一个音节 | 句首被截断，或前置噪声过多 |
| `sample_rate` | `int` | `16000` | 建议保持 16k | 建议保持 16k | 通常不要改 |
| `chunk_size_ms` | `int` | `32` | 输入块更大，调用更少 | 块更小，延迟更低 | 流式延迟和调度开销调优 |

## 调参建议

| 现象 | 优先尝试 |
|---|---|
| 背景噪声触发语音 | `threshold=0.6` 或 `0.7` |
| 轻声被漏掉 | `threshold=0.35` 或 `0.4` |
| 语音结束太晚 | `silence_duration_ms=200` 或 `300` |
| 停顿中被切开 | `silence_duration_ms=600` 或 `800` |
| 第一个音节被截掉 | `prefix_padding_ms=64` 或 `128` |

## 运行时断句更新

`silero` 支持通过 `apply_turn_detection(...)` 做实时断句参数更新。
这个接口主要给 websocket 这类长连接会话使用。

当前支持的运行时参数：

- `silence_duration_ms`
- `threshold`
- `prefix_padding_ms`

`prefix_padding_ms` 在 wrapper 状态机层实现：第一次检测到语音时，会把输出片段
起点按设定值向前回退，并在已有缓冲音频范围内做裁剪。

## 依赖

- `fasr`
- `numpy >= 1.24`
- `torch >= 2.0.0`
- Python 3.10-3.12
