# 本地语音降噪与转写Demo（DeepFilterNet3 +FunASR ）

**Repository Path**: whiletruecontinue/voice_clear_demo

## Basic Information

- **Project Name**: 本地语音降噪与转写Demo（DeepFilterNet3 +FunASR ）
- **Description**: Voice Clear Demo 是一个面向中文语音场景的对比式 Demo：支持上传/录音输入，使用 DeepFilterNet3 进行降噪，再通过 FunASR 做中文转写，分别展示“原始音频”和“降噪音频”的识别结果与耗时，帮助快速验证降噪对 ASR 效果的提升。项目基于 Flask，前后端一体，开箱即可本地运行，适合作为语音预处理 + 识别链路的实验与原型参考。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

## Voice Clear Demo

一个基于 Flask 的语音处理 Demo，支持：

- 上传或录音输入音频
- 使用 DeepFilterNet3 做降噪
- 使用 FunASR 做中文转写
- 左右两列对比原始音频与降噪音频的转写效果
- 展示音频基础信息（采样率、时长、声道）
- 展示转写耗时（按左右列分别统计）

## 技术栈

- Python 3.11
- Flask
- DeepFilterNet3 (`deepfilternet`)
- FunASR
- PyAV + soundfile（音频解码/预处理）

## 目录结构

```text
voice_clear_demo/
├─ main.py                  # 唯一启动入口
├─ pyproject.toml           # 依赖配置
├─ src/
│  ├─ app_factory.py        # Flask app 初始化
│  ├─ routes.py             # 路由与页面状态管理
│  ├─ audio_pipeline.py     # DeepFilterNet3 降噪逻辑
│  ├─ asr_service.py        # FunASR 初始化/状态/转写
│  └─ config.py             # 路径与基础配置
├─ templates/
│  ├─ index.html            # 主页面（双列对比）
│  └─ _params.html          # 降噪参数区（独立模板）
├─ static/
│  └─ style.css             # 页面样式
└─ storage/
   ├─ uploads/              # 原始上传音频
   └─ outputs/              # 降噪结果音频
```

## 环境要求

- Windows / macOS / Linux
- Python 3.11（项目要求：`>=3.11,<3.12`）
- 建议使用 `uv`

## 安装与启动

```bash
uv sync
uv run python main.py
```

启动后访问：

- `http://127.0.0.1:5000`

## 使用流程

1. 左列上传音频或录音，然后点击“保存原始音频”
2. 左列点击“转写原始音频”，得到原音转写结果
3. 右列调整降噪参数并点击“降噪处理”
4. 右列点击“转写降噪音频”，得到降噪后转写结果
5. 对比左右两列的转写内容、转写耗时和音频基础信息

## ASR 初始化说明

- 系统支持启动时后台预热 ASR（默认开启）
- 页面提供“初始化 ASR”按钮手动触发
- 页面每 5 秒轮询一次 ASR 状态（未初始化/初始化中/已就绪/失败），初始化完成后自动刷新状态显示

可通过环境变量关闭启动预热：

```bash
ASR_PRELOAD_ON_START=0
```

## 常见问题

### 1) 转写时报 `[WinError 2] 系统找不到指定的文件`

通常是本机 `ffmpeg` 路径异常。当前代码已尽量避免依赖系统 `ffmpeg`，优先使用 `PyAV + soundfile` 预处理。如果仍出现，请确认：

- `av`、`soundfile` 安装成功
- 上传文件不是损坏音频

### 2) 第一次初始化很慢

首次会下载 FunASR 模型，这是正常现象。下载完成后会复用本地缓存。

## 路由说明

- `GET /`：主页
- `POST /upload_audio`：保存原始音频
- `POST /process`：执行降噪
- `POST /transcribe`：执行转写
- `POST /init_asr`：手动初始化 ASR
- `GET /asr_status`：查询 ASR 初始化状态
- `GET /audio/<kind>/<filename>`：播放音频（`kind` 为 `source` 或 `output`）

## 指标说明

- 音频基础信息：
  - 采样率：单位 Hz
  - 时长：单位秒，保留 2 位小数
  - 声道：1 为单声道，2 为双声道
- 转写耗时：
  - 从后端收到转写请求开始计时，到 FunASR 返回结果结束
  - 分左右列分别展示，不互相覆盖