Metadata-Version: 2.4
Name: zipenhancer
Version: 0.3.2
Summary: 语音降噪核心库 — ZipEnhancer/FRCRN/MossFormer2 纯 PyTorch 推理
License-Expression: MIT
Project-URL: homepage, https://github.com/gyj1201/zipEnhancer
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0
Requires-Dist: silero-vad
Requires-Dist: numpy
Requires-Dist: librosa
Requires-Dist: soundfile
Requires-Dist: click>=8.0
Provides-Extra: modelscope
Requires-Dist: modelscope; extra == "modelscope"
Provides-Extra: server
Requires-Dist: fastapi; extra == "server"
Requires-Dist: uvicorn; extra == "server"
Requires-Dist: python-multipart; extra == "server"
Requires-Dist: python-dotenv; extra == "server"
Dynamic: license-file

<div align="center">

<pre>
 ______       _____       _                               
|__  (_)_ __ | ____|_ __ | |__   __ _ _ __   ___ ___ _ __ 
  / /| | '_ \|  _| | '_ \| '_ \ / _` | '_ \ / __/ _ \ '__|
 / /_| | |_) | |___| | | | | | | (_| | | | | (_|  __/ |   
/____/|_| .__/|_____|_| |_|_| |_|\__,_|_| |_|\___\___|_|   
       |_|                                                
</pre>

</div>

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.9+-blue" alt="Python 3.9+"></a>
  <a href="https://pypi.org/project/zipenhancer/"><img src="https://img.shields.io/pypi/v/zipenhancer" alt="PyPI"></a>
  <a href="https://pytorch.org/"><img src="https://img.shields.io/badge/PyTorch-2.0+-ee4c2c" alt="PyTorch"></a>
  <a href="https://github.com/gyj1201/zipEnhancer/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT License"></a>
</p>

<p align="center">
基于阿里达摩院 <b>ZipEnhancer</b>（ICASSP 2025）的语音降噪 Python 库。</p>

---

## 安装

```bash
pip install zipenhancer
```

如需 FRCRN 或 MossFormer2 模型：

```bash
pip install zipenhancer[modelscope]
```

## 快速开始

```python
import soundfile as sf
from zipenhancer import denoise, write

audio, sr = sf.read("input.wav")
denoised, proc_time, duration = denoise(audio, sr)
print(f"处理耗时: {proc_time:.2f}s, 实时比: {duration/proc_time:.1f}x")

write("output.wav", denoised, sr)
```

### 降噪 + VAD 静音切除

```python
# 降噪后自动切除静音段
denoised, proc_time, duration = denoise(audio, sr, vad=True)
```

### 降噪强度控制

```python
# 全力降噪（默认）
denoised, _, _ = denoise(audio, sr, strength=1.0)
# 中度降噪
denoised, _, _ = denoise(audio, sr, strength=0.5)
# 关闭降噪（原样输出）
denoised, _, _ = denoise(audio, sr, strength=0.0)
```

## CLI 命令行

```bash
# 单文件降噪
zipenhancer denoise recording.wav

# 降噪 + VAD 静音切除
zipenhancer denoise recording.wav --vad

# 指定输出格式
zipenhancer denoise input.wav -o output.mp3 --bitrate 192k

# 批量处理
zipenhancer batch ./input/ ./output/

# 使用 FRCRN 模型
zipenhancer denoise test.wav --model frcrn

# 管道模式
ffmpeg -i meeting.mp3 -f wav - | zipenhancer denoise - -o clean.wav

# 查看可用模型
zipenhancer list
```

## API

### `denoise(audio, sample_rate, ...)`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `audio` | `np.ndarray` | 必填 | 音频数据，形状 `(samples,)` 或 `(channels, samples)` |
| `sample_rate` | `int` | 必填 | 输入采样率 |
| `model` | `str` | `ZipEnhancer` | 模型名称 |
| `normalize` | `bool` | `True` | 是否音量归一化 |
| `target_sr` | `int` | `0` | 输出采样率，`0`=保持原始 |
| `strength` | `float` | `1.0` | 降噪强度 `0.0`~`1.0` |
| `vad` | `bool` | `False` | 启用 VAD 静音切除 |

返回 `(denoised_audio, processing_time, duration)`。

### `remove_silence(audio, sample_rate, ...)`

直接使用 VAD 静音切除：

```python
from zipenhancer import remove_silence

clean_audio, segments = remove_silence(audio, sr)
```

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `audio` | `np.ndarray` | 必填 | 音频数据 |
| `sample_rate` | `int` | 必填 | 采样率 |
| `threshold` | `float` | `None` | VAD 阈值，`None`=自适应 |
| `hold_time` | `float` | `0.5` | 静音判定等待时间（秒） |
| `crossfade_ms` | `int` | `10` | 段间交叉渐变时长（毫秒） |

### `write(path, data, sample_rate, ...)`

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `path` | `str` | 必填 | 输出文件路径 |
| `data` | `np.ndarray` | 必填 | 音频数据 |
| `sample_rate` | `int` | 必填 | 采样率 |
| `fmt` | `str` | `wav` | 输出格式：`wav`/`flac`/`mp3`/`ogg` |
| `bitrate` | `str` | `None` | 比特率，仅 mp3/ogg |
| `compression` | `int` | `None` | 压缩级别，仅 flac `0`-`8` |

## 可用模型

| 模型 | 说明 | 需 modelscope |
|------|------|:---:|
| `zipenhancer` | ZipEnhancer 轻量降噪（默认） | 否 |
| `frcrn` | FRCRN 实时降噪 | 是 |
| `mossformer2` | MossFormer2 高质量降噪 | 是 |

```bash
# 安装 modelscope 依赖
pip install zipenhancer[modelscope]

# 切换模型
zipenhancer denoise test.wav --model frcrn
```

## 格式支持

| 格式 | 编码选项 | 引擎 |
|------|---------|------|
| WAV | PCM_16 / PCM_24 / PCM_32 / FLOAT | soundfile |
| FLAC | PCM_16 / PCM_24, compression 0-8 | soundfile |
| MP3 | 32-320 kbps | ffmpeg |
| OGG | 6-510 kbps | ffmpeg |

> MP3/OGG 需要安装 ffmpeg 并加入 PATH。

## License

[MIT](LICENSE)

## Credits

- 降噪模型：[阿里达摩院 ZipEnhancer](https://modelscope.cn/models/iic/speech_zipenhancer_ans_multiloss_16k_base)（Apache 2.0）
- 论文：[*ZipEnhancer: Dual-Path Down-Up Sampling-based Zipformer for Monaural Speech Enhancement*](https://arxiv.org/abs/2501.05183)（ICASSP 2025）
