Metadata-Version: 2.4
Name: fasr-vad-marblenet
Version: 0.5.0
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

基于 NVIDIA MarbleNet ONNX 推理脚本封装的 VAD 插件，为 `fasr` 提供离线语音活动检测能力。插件已内置 `model.onnx`，默认可直接加载。

## 安装

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

## 注册模型

| 注册名 | 类 | 说明 |
|---|---|---|
| `marblenet` | `MarbleNetForVAD` | NVIDIA MarbleNet 非流式 VAD，ONNX Runtime 推理 |

## 使用方式

### 在流水线中使用

```python
from fasr import AudioPipeline

pipeline = (
    AudioPipeline()
    .add_pipe("detector", model="marblenet", checkpoint_dir="/path/to/onnx_dir")
    .add_pipe("recognizer", model="paraformer")
)
```

### 单独使用模型

模型实例化时会自动执行 `download_checkpoint()` + `load_checkpoint()`，默认使用插件内置 ONNX，无需手动调用：

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

model = registry.vad_models.get("marblenet")()

waveform = Waveform.from_file("example.wav")
segments = model.detect(waveform)
for seg in segments:
    print(f"{seg.start_ms}ms - {seg.end_ms}ms")
```

若需使用自定义权重目录，可重新调用 `load_checkpoint`：

```python
model.load_checkpoint("/path/to/custom/marblenet")
```

## 运行期 / 会话参数

构造时传入，或通过字段赋值覆盖：

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `checkpoint` | `str \| None` | `None` | 远程 repo_id；非空时实例化会自动下载到 `cache_dir`，默认使用插件内置 ONNX |
| `cache_dir` | `str \| Path \| None` | `None` | 缓存目录，`None` 使用 `fasr.utils.get_cache_dir()` |
| `endpoint` | `Literal["modelscope", "huggingface", "hf-mirror"]` | `"hf-mirror"` | 下载端点 |
| `model_path` | `str \| Path \| None` | `None` | 直接指定 `.onnx` 文件路径，优先级高于 `checkpoint_dir` |
| `providers` | `list[str] \| None` | `["CPUExecutionProvider"]` | ONNX Runtime provider 列表 |
| `intra_op_num_threads` | `int` | `2` | ONNX Runtime 算子内并行线程数 |
| `inter_op_num_threads` | `int` | `0` | ONNX Runtime 算子间并行线程数 |

### VAD 算法参数

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `speaking_score` | `float` | `0.5` | 语音激活阈值，高于此值判定为开始说话 |
| `silence_score` | `float` | `0.5` | 语音结束阈值，高于此值判定为回到静音 |
| `fusion_threshold` | `float` | `0.1` | 邻近片段合并阈值（秒），间隔小于此值的片段会合并 |
| `min_speech_duration` | `float` | `0.05` | 最小语音段时长（秒），短于此值的片段会被过滤 |
| `output_frame_length` | `int` | `320` | 每帧采样点数，默认对应 20ms@16kHz |

## VAD 参数调优

片段长度主要由 `silence_score` 和 `fusion_threshold` 控制：

| 问题 | 调整方式 | 说明 |
|---|---|---|
| 片段过长 | 降低 `silence_score` 或 `fusion_threshold` | 让模型更容易切分 |
| 片段过短/碎片化 | 提高 `silence_score` 或 `fusion_threshold` | 让模型更稳定，合并邻近片段 |

### 参数调整示例

**减少片段长度（更细粒度切分）：**

```python
pipeline.add_pipe(
    "detector",
    model="marblenet",
    silence_score=0.3,        # 降低阈值，更容易检测到语音结束
    fusion_threshold=0.05,    # 降低合并阈值，减少片段合并
)
```

**增加片段长度（减少碎片化）：**

```python
pipeline.add_pipe(
    "detector",
    model="marblenet",
    silence_score=0.7,        # 提高阈值，需要更确信才结束片段
    fusion_threshold=0.3,     # 提高合并阈值，合并更多邻近片段
    min_speech_duration=0.1,  # 过滤短片段
)
```

**单独使用模型时调整参数：**

```python
model = registry.vad_models.get("marblenet")(
    silence_score=0.3,
    fusion_threshold=0.05,
)
# or mutate after construction
model.silence_score = 0.3
model.fusion_threshold = 0.05
```

## 依赖

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