Metadata-Version: 2.4
Name: zipenhancer
Version: 0.2.0
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: 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://fastapi.tiangolo.com/"><img src="https://img.shields.io/badge/FastAPI-0.115+-teal" alt="FastAPI"></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>
  <a href="https://www.docker.com/"><img src="https://img.shields.io/badge/Docker-支持-2496ed" alt="Docker"></a>
  <a href="https://modelscope.cn/models/iic/speech_zipenhancer_ans_multiloss_16k_base"><img src="https://img.shields.io/badge/ModelScope-达摩院-6240ff" alt="ModelScope"></a>
</p>



### 做了什么

- **模型剥离** — 从 ModelScope 黑盒 pipeline 中提取出 ZipEnhancer，用原生 PyTorch 加载权重推理，不再依赖 pipeline 封装
- **FP16 半精度推理** — 仅模型计算部分使用 FP16，STFT/iSTFT 保持 FP32 避免 cuFFT 精度问题，显存占用降低 ~40%
- **长音频分段** — 4s 滑动窗口 + 75% 重叠的 overlap-add 策略，支持任意时长音频，彻底解决 CUDA OOM
- **多模型切换** — 同时支持 ZipEnhancer（轻量）、FRCRN（实时）、MossFormer2（高质）三种模型
- **声道/位深保持** — 立体声输入 → 立体声输出，32-bit float / 16-bit PCM 自动适配
- **PyPI 发布** — `pip install zipenhancer` 一键安装，也可作为库集成到你的项目中

### 它能做什么？

- 清除录音中的**环境噪声**（空调声、风扇声、键盘声、街道噪音等）
- 支持**单文件**和**批量处理**两种模式
- 多种降噪模型**一键切换**
- GPU 加速，实时率可达 **20x 以上**（RTX 4090）

无需 ModelScope pipeline 黑盒，一行命令启动服务，适合集成到语音处理流程、会议录音后处理、音频预处理管道等场景。

<!-- 效果演示暂时关闭，后续找到合适的方案再说
## 效果演示

两个测试样本的降噪前后对比（默认模型，全力降噪）：

| 样本 | 原始带噪 | 降噪后 |
|------|---------|--------|
| 样本 1 | [▶ 播放](https://raw.githubusercontent.com/gyj1201/zipEnhancer/master/demo/mp3_audio/speech_with_noise.mp4) | [▶ 播放](https://raw.githubusercontent.com/gyj1201/zipEnhancer/master/demo/mp3_audio/speech_with_noise_denoised.mp4) |
| 样本 2 | [▶ 播放](https://raw.githubusercontent.com/gyj1201/zipEnhancer/master/demo/mp3_audio/speech_with_noise1.mp4) | [▶ 播放](https://raw.githubusercontent.com/gyj1201/zipEnhancer/master/demo/mp3_audio/speech_with_noise1_denoised.mp4) |

> 测试音频来自 [ModelScope 官方 demo](https://www.modelscope.cn/models/iic/speech_zipenhancer_ans_multiloss_16k_base/summary)。
-->

## 快速开始

### 方式一：pip 安装（推荐）

```bash
pip install zipenhancer
```

如需 FRCRN 或 MossFormer2 模型（依赖 ModelScope）：

```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)
```

### 方式二：手动部署

**1. 创建虚拟环境**

```bash
conda create -n zipenhancer python=3.10 -y
conda activate zipenhancer
```

**2. 安装依赖**

```bash
pip install -r requirements.txt
```

GPU 加速（NVIDIA 显卡，**先于上一步**安装 CUDA 版 PyTorch）：

```bash
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu124
pip install -r requirements.txt
```

**3. 配置**

复制 `.env.example` 为 `.env`，按需求修改：

```bash
cp .env.example .env
```

**4. 启动**

```bash
uvicorn app:app --host 0.0.0.0 --port 8765
```

### 方式三：Docker 部署

**1. 前置条件**

安装 [Docker](https://docs.docker.com/engine/install/) 和 [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)。

**2. 构建并启动**

```bash
# 从 docker/ 目录启动
cd docker
docker compose up -d

# 或从项目根目录直接运行
docker run --gpus all -p 8765:8765 zipenhancer:latest
```

所有依赖和模型已在构建时下载，启动即用，无需额外等待。

## 文档

| 文档 | 说明 |
|------|------|
| [包使用文档](docs/guide/package.md) | `pip install zipenhancer` 的 Python API 参考（模型列表、降噪强度、输出格式） |
| [API 接口文档](docs/guide/api.md) | FastAPI 接口说明（curl 示例、参数、响应格式） |
| [CLI 命令行文档](docs/guide/cli.md) | 终端降噪命令（单文件、批量、管道、进度条） |
| [Docker 部署指南](docs/guide/docker.md) | Docker 构建与部署 |

## 可用模型

| 模型 ID | 说明 |
|---------|------|
| `iic/speech_zipenhancer_ans_multiloss_16k_base` | ZipEnhancer（轻量） |
| `iic/speech_frcrn_ans_cirm_16k` | FRCRN（实时降噪） |
| `iic/speech_mossformer2_ans_48k` | MossFormer2（高质量） |

## Roadmap

### 已完成
- [x] 单文件语音降噪
- [x] 批量文件语音降噪
- [x] 多模型切换（ZipEnhancer / FRCRN / MossFormer2）
- [x] 音量归一化
- [x] 自定义输出采样率
- [x] 声道/位深保持
- [x] FP16 半精度推理

### 计划中

#### P0 — 短期（完成）
- [x] Docker 一键部署（多阶段构建、GPU 直通、健康检查、优雅关闭）
- [x] 输出格式选择（WAV / MP3 / FLAC / OGG，编码参数可配）
- [x] 降噪强度控制（频域掩码指数，0~100% 可调）  论文参考：DeepFilterNet Base

### P1 — 中期（4-6 个月）
- [x] PyPI 发布（`pip install zipenhancer`）
- [ ] Noise Gate（Attack / Release / Hold / Hysteresis / Look-ahead）
- [ ] 残差监听（延迟对齐 + 位深统一，输出原始与降噪的差值信号）
- [ ] 频段选择降噪（Linkwitz-Riley 分频，各频段独立降噪强度）
- [ ] VAD 自动静音切除（Silero VAD + 状态机 + 自适应阈值 + Cross-fade 拼接）

### P2 — 中后期（5-7 个月）
- [ ] 噪声轮廓学习（基于 VAD 的自适应谱减法后处理、音乐噪声抑制）
- [ ] 质量评估指标（PESQ / STOI / Si-SNR / DNSMOS，离线评测管线）
- [ ] 音频格式转换（ffmpeg 封装，格式兼容矩阵，元数据透传）

### P3 — 长期
- [ ] 异步任务 + 进度查询（2-3 个月，任务持久化、队列调度、Worker 池、Webhook）
- [ ] 去混响（4-8 个月，WPE + DNN，场景分类 + 参数矩阵）
- [ ] 实时流式降噪（4-8 个月，WebSocket + 因果模型 + Jitter Buffer + AEC）

### 需要前端、CLI协助
- [ ] CLI 命令行工具（多命令、管道、进度条、配置文件）
- [ ] 输入音频信息预览（波形峰值、LUFS 响度、削波检测、完整性校验）
- [ ] Web UI 界面（3-4 个月，拖拽上传 + 波形/频谱可视化 + 在线试听 + Before/After 对比）

### 已评估放弃
- ~~超分（低采样率 → 高采样率）~~ — 研究级难题，和降噪正交
- ~~模型量化 int8~~ — 模型架构（自定义算子）不支持
- ~~语音识别（ASR）~~ — 另一个产品领域
- ~~说话人分离~~ — 重叠说话人问题当前无工业级开源方案


## 项目结构

```
├── app.py                 # FastAPI 服务主程序
├── log.py                 # 日志管理模块
├── zipenhancer/           # 降噪核心包
│   ├── __init__.py
│   ├── codec.py           # 音频编码模块（WAV/FLAC/MP3/OGG）
│   ├── denoise.py         # 降噪核心函数
│   ├── standalone.py      # 剥离版推理（纯 PyTorch）
│   ├── models/            # 模型架构
│   │   ├── zipenhancer.py
│   │   └── layers/
│   │       ├── generator.py
│   │       ├── scaling.py
│   │       ├── zipenhancer_layer.py
│   │       └── zipformer.py
│   └── configs/
│       └── configuration.json
├── docker/
│   ├── Dockerfile          # Docker 构建文件
│   └── docker-compose.yml  # Docker Compose 配置
├── docs/
│   ├── index.html           # GitHub Pages 降噪对比页面
│   ├── guide/
│   │   ├── docker.md        # Docker 部署指南
│   │   ├── package.md       # pip 包使用文档
│   │   └── api.md           # API 接口文档
│   └── mp3_audio/           # GitHub Pages 播放用 MP4 音频
├── images/                # README 截图
├── pyproject.toml         # 项目构建配置（PyPI 打包）
├── requirements.txt       # 依赖列表
├── LICENSE                # MIT 开源许可证
├── .env.example           # 环境配置模板
├── .gitignore             # Git 忽略规则
├── README.md              # 使用文档
└── logs/                  # 日志输出目录
    ├── app/               # 全部日志
    └── error/             # 错误日志
```

## Credits

- 降噪模型：[阿里达摩院 ZipEnhancer](https://modelscope.cn/models/iic/speech_zipenhancer_ans_multiloss_16k_base)（Apache 2.0）
- 模型提取参考：[boreas-l/zipEnhancer](https://github.com/boreas-l/zipEnhancer)

## License

[MIT](LICENSE) © 2026 gao yi jun
