进阶 docs.voicebox.sh 2026-10-11 09:58:06 · 19 阅读

第27章音频特效管线与版本管理

开发者

Effects Pipeline

音频后期处理特效与生成版本管理

特效管线基于 Spotify 的 Pedalboard 库，提供专业级 DSP 音频处理。每个生成可以拥有多个版本，分别应用不同的特效链。

概述

核心概念：

Effects Chain（特效链）— 按顺序依次应用的特效配置列表，可序列化为 JSON
Generation Version（生成版本）— 某次生成的一个处理变体，拥有独立的音频文件和特效链
Effect Preset（特效预设）— 已保存的特效链配置（内置或用户创建）
Clean Version（原始版本）— 未做任何处理的原始生成音频

流程：

TTS 生成原始音频
特效链对音频进行处理
处理后的音频保存为新的生成版本

每个生成都会保留一个原始版本，此外可以创建任意数量的处理版本，各自应用不同的特效链。

特效类型

以下是可用的特效类型，每种都带有可配置的参数：

Chorus / Flanger（合唱 / 镶边）

调制延迟效果。centre_delay_ms 较短时呈镶边效果，较长时呈合唱效果。

参数：

rate_hz：LFO 速度，单位 Hz（范围：0.01 到 20，默认：1.0）
depth：调制深度（范围：0.0 到 1.0，默认：0.5）
feedback：反馈量（范围：0.0 到 0.95，默认：0.0）
centre_delay_ms：中心延迟，单位毫秒（范围：0.5 到 50，默认：7.0）
mix：干湿比（范围：0.0 到 1.0，默认：0.5）

Reverb（混响）

房间混响效果。

参数：

room_size：房间大小（范围：0.0 到 1.0，默认：0.5）
damping：高频衰减（范围：0.0 到 1.0，默认：0.5）
wet_level：湿声电平（范围：0.0 到 1.0，默认：0.33）
dry_level：干声电平（范围：0.0 到 1.0，默认：0.4）
width：立体声宽度（范围：0.0 到 1.0，默认：1.0）

Delay（延迟）

回声 / 延迟线效果。

参数：

delay_seconds：延迟时间，单位秒（范围：0.01 到 2.0，默认：0.3）
feedback：反馈量（范围：0.0 到 0.95，默认：0.3）
mix：干湿比（范围：0.0 到 1.0，默认：0.3）

Compressor（压缩器）

动态范围压缩，用于让响度保持一致。

参数：

threshold_db：阈值，单位 dB（范围：-60 到 0，默认：-20.0）
ratio：压缩比（范围：1.0 到 20.0，默认：4.0）
attack_ms：启动时间，单位毫秒（范围：0.1 到 100，默认：10.0）
release_ms：释放时间，单位毫秒（范围：10 到 1000，默认：100.0）

Gain（增益）

以分贝为单位调整音量。

参数：

gain_db：增益，单位 dB（范围：-40 到 40，默认：0.0）

High-Pass Filter（高通滤波器）

去除截止频率以下的频率成分。

参数：

cutoff_frequency_hz：截止频率，单位 Hz（范围：20 到 8000，默认：80.0）

Low-Pass Filter（低通滤波器）

去除截止频率以上的频率成分。

参数：

cutoff_frequency_hz：截止频率，单位 Hz（范围：200 到 20000，默认：8000.0）

Pitch Shift（变调）

以半音为单位升调或降调。

参数：

semitones：变调的半音数（范围：-12 到 12，默认：0.0）

生成版本

每个生成最初只有一个原始版本（无特效）。用户可以通过应用特效链来创建处理版本。

版本属性：

id — 版本唯一标识符
label — 用户自定义名称（如「机器人音」「加混响」）
audio_path — 处理后音频文件的路径
effects_chain — 特效配置的 JSON 数组
source_version_id — 该版本派生自哪个版本
is_default — 是否为该生成的默认音频

文件存储：
{generation_id}.wav（原始版本）
{generation_id}_{version_id}.wav（处理版本）

默认版本行为：

每个生成有且仅有一个版本被标记为默认
生成的 audio_path 始终指向默认版本的音频
删除默认版本时会自动将另一个版本提升为默认

特效预设

预设是已保存的特效链，可以在不同生成之间复用。

内置预设：

Robotic（机器人）：使用合唱（镶边风格）打造金属感机器人音色
Radio（电台）：通过带通滤波和轻度压缩实现单薄 AM 电台音色
Echo Chamber（回声室）：开阔的混响加尾部回声
Deep Voice（低沉嗓音）：通过变调加压缩实现低音调并增加厚度

用户预设：

通过特效界面创建
存储在数据库（SQLite）中
不能修改或删除内置预设
用于快速应用常用的特效组合

API 端点

特效管理

端点 / 方法 / 说明
/effects/available / GET / 列出所有特效类型及其参数定义
/effects/presets / GET / 列出所有预设（内置 + 用户）
/effects/presets / POST / 创建新的用户预设
/effects/presets/:id / GET / 获取指定预设
/effects/presets/:id / PUT / 更新用户预设
/effects/presets/:id / DELETE / 删除用户预设
/effects/preview/:generation_id / POST / 预览某生成的特效效果（返回音频流）

生成版本

端点 / 方法 / 说明
/generations/:id/versions / GET / 列出某生成的所有版本
/generations/:id/versions/apply-effects / POST / 应用特效链，创建新版本
/generations/:id/versions/:version_id/set-default / PUT / 将某版本设为默认
/generations/:id/versions/:version_id / DELETE / 删除某版本

请求体：应用特效

应用特效时的请求体：

effects_chain：特效对象数组
label：版本标签（如「with reverb」）
set_as_default：是否设为默认
source_version_id：来源版本 ID（可选）

实现细节

后端架构

文件：
文件 / 用途
backend/utils/effects.py / 特效注册表、校验和音频处理
backend/services/versions.py / 生成版本的增删改查
backend/services/effects.py / 特效预设的增删改查
backend/routes/effects.py / 特效和版本的 API 端点

特效注册表：
utils/effects.py 中的 EFFECT_REGISTRY 字典定义了所有可用特效，包括各自的参数、默认值和取值范围。

校验：
特效链在应用前会进行校验：

特效类型必须存在于注册表中
参数必须是数值且在 min/max 范围内
未知参数会被拒绝

音频处理：
使用 Spotify 的 Pedalboard 库：
from pedalboard import Pedalboard

# 根据特效链构建 pedalboard
board = build_pedalboard(effects_chain)

# 应用到音频（通过线程异步执行）
processed = await asyncio.to_thread(lambda: board(audio, sample_rate))

前端集成

关键组件：
组件 / 位置
特效链编辑器 / app/src/components/Effects/
版本选择器 / 生成详情页
预设管理器 / 特效面板
实时预览 / 预览按钮（流式返回处理后的音频）

状态管理：

特效链以 JSON 数组形式存储
实时预览在不保存的情况下获取处理后的音频
已应用的特效通过 POST 端点创建新版本

新增特效

要添加新的特效类型：

添加到注册表（backend/utils/effects.py）：
在 EFFECT_REGISTRY 中添加条目，包含 cls、label、description 和 params
从 Pedalboard 导入对应的特效类

按需更新前端类型定义

新特效会自动出现在 /effects/available 和特效链编辑器界面中。

最佳实践

特效顺序很重要。建议按以下顺序处理以获得最佳效果：

变调（如需要）
高通 / 低通滤波
合唱 / 镶边（时间类）
混响 / 延迟（空间类）
压缩器
增益（最终音量调整）