# audio

**Repository Path**: starksdf/audio

## Basic Information

- **Project Name**: audio
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-15
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 音频处理工具 —— 需求文档

## 背景

已有一个音频音量归一化工具 `normalize_audio.py` + GUI 版 `normalize_gui.py`，功能：
- 基于短时 RMS 包络的动态增益调整
- 安静部分自动抬升，响亮部分自动压低
- 峰值限制防削波
- 输出 MP3（ffmpeg 转换）
- GUI 版支持参数调节、预设保存/加载
- 已打包为 EXE（PyInstaller）

已验证的默认参数（针对人声录制/讲座类音频）：
```
target=-20 dBFS   # 目标响度
gain_min=0.3      # 最小增益（最响部分最多压到 30%）
gain_max=200      # 最大增益（最安静部分最多放大 200 倍）
window=400ms      # RMS 分析窗口
smooth=300ms      # 增益平滑时间
```

## 新需求

基于现有工具，增加**人声减少 + 背景音乐放大**的功能，并与原有的动态范围压缩结合。

### 核心功能

1. **音源分离**：将输入音频分离为人声（vocal）和背景音乐（instrumental/accompaniment）
2. **独立增益控制**：
   - 对人声轨道：降低音量（人声减少）
   - 对背景音乐轨道：放大音量（背景音乐增强）
3. **动态范围压缩**：分离/混音后，对整个结果应用现有的 envelope_normalize 处理（安静抬升、响亮压低）
4. **批量处理 + GUI**：与现有 GUI 风格一致，支持选择文件/文件夹，一键处理

### 参数设计

在现有参数基础上增加：

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `vocal_gain` | 0.3 | 人声轨道的增益倍数（0=静音，0.3=保留30%，1=不变） |
| `music_gain` | 2.0 | 背景音乐轨道的增益倍数（2=放大2倍，1=不变） |
| `separation_model` | "htdemucs" | 音源分离模型（htdemucs / htdemucs_ft / ...） |

其余参数沿用现有：
- target, gain_min, gain_max, window, smooth（动态范围压缩参数）
- output_format（mp3/wav）

### 技术方案

#### 音源分离：Demucs（PyTorch）

- 使用 Meta 的 [Demucs](https://github.com/facebookresearch/demucs) 模型
- 分离为 4 轨：bass, drums, other, vocals
- 背景音乐 = bass + drums + other（或根据需求组合）
- 人声 = vocals

依赖：
```
demucs
torch（CPU 或 CUDA 版）
```

##### 关于 Demucs 的注意事项

1. **模型体积**：htdemucs 模型约 300MB，首次运行自动下载
2. **处理速度**：GPU（CUDA）可加速，CPU 也能跑但慢很多
3. **分离效果**：htdemucs 是目前开源中效果最好的，对大多数音乐分离干净
4. **如果不想用 PyTorch**：可降级为 Spleeter（TensorFlow）或经典频率滤波（效果差一些）

#### 处理流程

```
输入音频
  │
  ├─ Demucs 分离 ──┬─ vocal ── vocal_gain ──┐
  │                └─ music ── music_gain ──┤
  │                                        ├─ 混合 ── envelope_normalize ── 输出
  │                                        │        （复用现有压缩逻辑）
  │                                        └─ 可选：单独输出分离轨道
  │
  └─ 也支持不分离，直接做动态范围压缩（原模式）
```

#### 输出选项

- **模式1**：分离 → 调增益 → 混合 → 动态压缩 → 输出 MP3（默认）
- **模式2**：仅动态压缩（原模式，不分离）
- **可选**：额外输出分离后的人声和背景音乐单独文件

### GUI 界面变更

在现有 GUI 基础上增加：
- 折叠式"音源分离"参数区域（默认折叠，保持简洁）
- 人声增益滑块/输入框（0~1，默认0.3）
- 背景音乐增益滑块/输入框（0.5~5，默认2.0）
- 模式切换：仅压缩 / 分离+压缩
- 预设系统支持保存/加载新增参数

### 开发与打包

1. 开发阶段用 Python 脚本
2. 使用 PyInstaller 打包为单文件 EXE
3. 由于依赖 PyTorch + Demucs，EXE 体积预计较大（可能数百 MB）
4. 需考虑 CUDA（GPU 加速）的打包方式，或者默认用 CPU 推理

### 已知风险

1. PyTorch + Demucs 打包后体积很大（>1GB），可能需要考虑用 nvidia 的兼容包或分发包
2. CPU 推理速度较慢（10 分钟音频可能需要数分钟处理）
3. 分离质量因音频类型而异，纯音乐/纯语音效果最好，混合场景效果稍差
4. 如果用户有 GPU（NVIDIA CUDA），可显著加速

### 备选方案（如果 Demucs 太重）

如果用户接受较小依赖，可改用：
- **Librosa + frequency filtering**：基于频谱的简单分离，质量一般但无额外依赖
- **Spleeter**：比 Demucs 轻一些，质量也还可以
- **nnfilter**：更轻量的滤波方案

建议优先评估 Demucs，效果好，如果打包体积或速度不可接受再降级。