Metadata-Version: 2.3
Name: fasr-enhancement-deepfilternet
Version: 0.5.8
Summary: DeepFilterNet audio enhancement model for fasr
Author: fasr
Author-email: fasr <790990241@qq.com>
Requires-Dist: deepfilternet-rs>=0.1.0
Requires-Dist: fasr
Requires-Dist: numpy>=1.24
Requires-Python: >=3.10, <3.13
Description-Content-Type: text/markdown

# fasr-enhancement-deepfilternet

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

DeepFilterNet 音频增强插件。离线 `enhance()` 和流式 `push_chunk()` 现在都
使用 `deepfilternet-rs` 包，由它通过 PyO3 将官方 DeepFilterNet Rust
runtime 暴露给 Python。

## 安装

```bash
pip install fasr-enhancement-deepfilternet
```

`stream_backend = "rust"` 由独立的 `deepfilternet-rs` 包提供。使用
`deepfilternet-rs` 预编译 wheel 时，目标机器不需要 Rust。

## 注册模型

| 注册名 | 类 | 适用场景 |
|---|---|---|
| `deepfilternet` | `DeepFilterNetEnhancement` | 高质量离线与流式降噪 |

## 使用方式

```python
from fasr.data import Waveform
from fasr_enhancement_deepfilternet import DeepFilterNetEnhancement

model = DeepFilterNetEnhancement(sample_rate=16000)
enhanced = model.enhance(Waveform(data=audio, sample_rate=16000))
```

流式使用：

```python
from fasr.data import AudioChunk, Waveform
from fasr_enhancement_deepfilternet import DeepFilterNetEnhancement

model = DeepFilterNetEnhancement(sample_rate=16000, stream_backend="rust")
for enhanced_chunk in model.push_chunk(
    AudioChunk(
        stream_id="session-1",
        waveform=Waveform(data=chunk_audio, sample_rate=16000),
        is_last=False,
    )
):
    ...
```

## Confection 配置

```toml
[enhancement_model]
@enhancement_models = "deepfilternet"
sample_rate = 16000
post_filter = true
compensate_delay = true
attenuation_limit_db = 100.0
stream_backend = "rust"
stream_log_level = "warn"
post_filter_beta = 0.0
```

## 参数

| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| `sample_rate` | `int` | `16000` | 输出给下游模型的采样率 |
| `deepfilter_sample_rate` | `int` | `48000` | DeepFilterNet Rust runtime 内部处理采样率 |
| `binary_path` | `str | None` | `None` | 为兼容旧配置保留的废弃字段 |
| `model_path` | `str | None` | `None` | 为兼容旧配置保留的废弃字段 |
| `post_filter` | `bool` | `true` | 是否启用 DeepFilterNet post-filter |
| `compensate_delay` | `bool` | `true` | 是否传入 `-D` 补偿算法延迟 |
| `attenuation_limit_db` | `float` | `100.0` | 降噪衰减上限，会传给 `-a` |
| `timeout_seconds` | `float` | `120.0` | 为兼容旧配置保留的废弃字段 |
| `stream_model_path` | `str | None` | `None` | Rust 流式 backend 可选的官方 DeepFilterNet `.tar.gz` 模型路径 |
| `stream_log_level` | `str | None` | `"warn"` | 流式 backend 支持时使用的日志级别 |
| `stream_backend` | `"rust"` | `"rust"` | 流式 backend。仅支持 `deepfilternet-rs` 提供的 `rust` backend |
| `post_filter_beta` | `float` | `0.0` | 流式 backend 支持时使用的 post-filter beta |

## Realtime 状态

当前插件支持一种流式 `push_chunk()` backend：

- `rust`：使用 `deepfilternet-rs`，它通过 PyO3 封装官方 DeepFilterNet Rust
  `DfTract` runtime。

音频会在内部重采样到 backend 要求的采样率，处理完成后再重采样回 `sample_rate`
供下游 fasr VAD/ASR 使用。现在 batch 与 realtime 共用同一条 runtime 路径，
两种模式下的增强行为会保持一致。
