Metadata-Version: 2.4
Name: fasr-vad-marblenet
Version: 0.5.8
Summary: NVIDIA MarbleNet 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: onnxruntime>=1.16.0

# fasr-vad-marblenet

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

NVIDIA MarbleNet 语音活动检测插件。插件内置 ONNX 模型，所以默认 `marblenet` 注册项无需额外下载权重即可使用。

## 安装

```bash
pip install fasr-vad-marblenet
```

## 注册模型

| 注册名 | 类 | 适用场景 |
|---|---|---|
| `marblenet` | `MarbleNetForVAD` | CPU 友好的离线 ONNX VAD |

## 流水线使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe(
        "detector",
        model="marblenet",
        speaking_score=0.55,
        silence_score=0.45,
        fusion_threshold=0.2,
    )
    .add_pipe("recognizer", model="paraformer")
)
```

| 目标 | 写法 | 效果 |
|---|---|---|
| 减少噪声起点 | `speaking_score=0.65` | 需要更高置信度才开始语音 |
| 保留轻声 | `speaking_score=0.35` | 起点更敏感，但噪声风险更高 |
| 更快结束语音 | `silence_score=0.35` | 片段更短，尾部静音更少 |
| 减少碎片 | `fusion_threshold=0.3` | 合并短暂停顿隔开的片段 |
| 过滤点击声/短噪声 | `min_speech_duration=0.1` | 过滤短于 100ms 的片段 |
| 限制 ASR 片段长度 | `max_speech_duration=15.0` | 把长语音硬切成 15 秒片段 |

## Confection 配置

```toml
[vad_model]
@vad_models = "marblenet"
speaking_score = 0.55
silence_score = 0.45
fusion_threshold = 0.2
```

放在流水线里：

```toml
[pipeline]
@pipelines = "AudioPipeline.v1"
pipe_order = ["detector"]

[pipeline.pipes]

[pipeline.pipes.detector]
@pipes = "thread_pipe"

[pipeline.pipes.detector.component]
@components = "detector"

[pipeline.pipes.detector.component.model]
@vad_models = "marblenet"
speaking_score = 0.55
silence_score = 0.45
fusion_threshold = 0.2
```

## 单独使用

```python
from fasr.config import registry
from fasr.data import AudioSpan, Waveform

model = registry.vad_models.get("marblenet")(
    speaking_score=0.55,
    silence_score=0.45,
)

audio = AudioSpan(waveform=Waveform.from_file("example.wav"), start_ms=0)
segments = model.detect(audio)
```

## 参数

| 参数 | 类型 / 范围 | 默认值 | 调高时 | 调低时 | 什么时候改 |
|---|---|---|---|---|---|
| `speaking_score` | `float`，`0.0` 到 `1.0` | `0.5` | 起点更严格 | 起点更敏感 | 起点误检或轻声漏检 |
| `silence_score` | `float`，`0.0` 到 `1.0` | `0.5` | 结束更晚 | 结束更早 | 片段太长或被截断 |
| `fusion_threshold` | `float >= 0`，秒 | `0.1` | 合并更宽的间隔 | 保留相邻片段分离 | 输出太碎或太粘 |
| `min_speech_duration` | `float >= 0`，秒 | `0.05` | 过滤更多短片段 | 保留更短片段 | 短噪声泄漏或短词消失 |
| `max_speech_duration` | `float > 0` 或 `None`，秒 | `None` | 更长硬切上限 | 更短硬切上限 | ASR 需要限制片段长度 |
| `intra_op_num_threads` | `int >= 0` | `2` | 更多 CPU 并行 | 更少 CPU 占用 | CPU 吞吐调优 |
| `inter_op_num_threads` | `int >= 0` | `0` | 更多算子级并行 | 交给 ORT 决定 | 高级 ORT 调优 |

## 调参建议

| 现象 | 优先尝试 |
|---|---|
| 噪声触发语音起点 | `speaking_score=0.6` 或 `0.7` |
| 轻声开头漏掉 | `speaking_score=0.35` 或 `0.4` |
| 片段尾巴太长 | `silence_score=0.35` 或 `0.4` |
| 语音太早截断 | `silence_score=0.6` |
| 片段太碎 | `fusion_threshold=0.2` 或 `0.3` |
| 很短的误检片段多 | `min_speech_duration=0.1` |

## 依赖

- `fasr`
- `numpy >= 1.24`
- `onnxruntime >= 1.16.0`
- Python 3.10-3.12
