声音设计

使用 AudioFX 进行声音设计

AudioFX 将声音设计效果转换为 ffmpeg 滤波器图。每个效果都是一个可以直接用于 ffmpeg -af 的字符串，或者通过 CLI 直接应用于文件。您在网页工作室中听到的声音与渲染出的结果完全一致。

命令

在整个文档中，sfx 代表：

node {{AUDIOFX_DIR}}/bin/sfx.mjs

如果 sfx 在这台机器上不是有效命令，请使用完整路径。它可以在任何文件夹下工作。如果因 ffmpeg 原因失败，请运行 sfx doctor。

您需要	命令
效果目录	sfx list (或 --json)
参数、范围及何时使用某种效果	sfx describe <effect>
处理音频或视频文件	sfx apply <input> <output> <step...>
为您自己的 ffmpeg 命令生成滤波器图	sfx graph <step...>
测量响度和峰值	sfx analyze <file>
视频的长度和硬切点	sfx cuts <video>
歌曲的上升点（重拍候选）和下降点	sfx sections <file>
在时间线上混和语音、音乐和音效，并自动将音乐在人声下闪避	sfx mix <output> --voice v.wav --music m.wav [--sfx hit.wav@6] [--video cut.mp4]，或 sfx mix project.json <output>
保存录制的采样并分层	`sfx sample add <file
生成新的声音、音效或歌曲（已处理）	`sfx generate <sfx
让用户收听并调整	sfx studio (打开 http://127.0.0.1:5177)

一个步骤的写法是 effect[:param=value,param=value][@from-to]：

sfx apply voice.wav voice-phone.wav telephone
sfx apply clip.mp4 clip-fx.mp4 "underwater:[email protected]" --fade 0.4
sfx graph "reverb:space=cathedral,mix=0.4" "fade:in=0,out=2"

• 步骤按顺序执行。
• @3.2-7 将效果限制在该时间窗口内，并使用 --fade 指定的淡入淡出时间（默认 0.25 秒）在干信号和处理信号之间交叉淡入淡出。@3.2- 表示从 3.2 秒到文件结束。
• 如果输出为 .mp4、.mov、.mkv 或 .webm，则视频画面将直接复制而不重新编码，仅替换音频。
• 如果参数错误，CLI 会列出有效的参数。无需猜测：请运行 sfx describe。

工作流程

1. 阅读剧本或剪辑，标记需要处理的时刻：例如电话中传出的声音、镜头进入水下、回忆闪回、音乐重拍、喜剧剪切等。sfx cuts video.mp4 会打印视频的长度及其硬切点（降低 --threshold 阈值（默认为 10）可以捕捉到更柔和的切点）。以秒为单位记录这些时间点。
2. 从下表中选择效果。 不确定时，使用 sfx list 和 sfx describe。先从默认参数开始：它们经过调校，听起来清晰且不过度。
3. 在混音之前，分别处理每个轨道。 时代感、角色和空间效果应应用于人声或特定音效，而非整个混音。唯一的例外是那些影响所有声音的叙事性手法（如水下、炮弹休克、梦境）。
4. 对于剪辑内的变化，使用时间窗口 (@from-to)，而不是剪切和拼接文件。
5. 最后使用 sfx mix 进行混音和标准化（参见“混音”部分）：它会在人声下闪避音乐，并将总输出标准化至 -14 LUFS（适用于社交媒体和 YouTube），--loudness -16 用于播客，-23 用于广播）。对于单个文件，在其处理链末尾使用 loudness 效果可以达到相同效果。然后使用 sfx analyze 检查响度是否接近目标，并且真实峰值保持在 -1 dBTP 或更低。
6. 您无法直接收听。 告诉用户您应用了哪些效果以及何时应用，并提供 sfx studio 让用户可以凭耳朵进行微调。如果他们返回了新的参数值，编辑器会提供要复制的确切命令。

电影感瞬间：如何让剪辑更出彩

启动视频听起来“有电影感”，不是因为对人声加了滤镜，而是因为在恰当的时刻放置了正确的元素：一个在剪辑点处上升到顶点的上升音，一段短暂的静默停顿，然后当产品出现时伴随一个带有低频下潜的撞击声。这些效果在同一个滤波器图内合成这些元素（无需许可的采样），并通过 at=<second> 参数锚定到特定时间点：

瞬间	链条 (T 为剪辑点)
在剪辑点上的撞击声，产品展示	"riser:at=T,length=2.5" "drop-gap:at=T-0.45,gap=0.45" "hit:at=T"
标题或标志	"braam:at=T" "sub-drop:at=T,level=-4"
文本或UI飞入	"whoosh:at=T,length=0.8" (峰值在 T)
切至黑屏	"stop-tail:at=T,decay=3.5" "sub-drop:at=T,level=-4"
强调一个词语	"throw:at=T,kind=echo" 应用于人声
技术故障音效	"stutter:at=T,slice=0.12,repeats=4" (会拉长音频)

• at 是您正在处理的文件中剪辑点所在的秒数。对于 riser，它是结束点；对于 whoosh，它是峰值点；对于 drop-gap，它是静默间隙的开始点。
• 在调整 gain 之前，先使用 level (dB) 调整音量：hit 和 sub-drop 自带的音量已经很大。
• 少而精：每 15 秒一两个瞬间即可。每个剪辑点都加撞击声会让人感到疲劳。
• trailer-voice (深沉、史诗感的空间人声) 和 archival (档案采访) 是人声处理效果，没有 at 参数。
• 需要真实录制的声音（有分量的撞击声、门声、玻璃声、雨声）而不是合成效果吗？在 T 时刻叠加一个采样：参见下一节。

作为分层的真实采样

合成的撞击声快速且免费，但录制好的撞击声、呼啸声或拟音通常感觉更真实。layer 效果可以在同一个滤波器图内，在精确到秒的时间点上将任何音频文件混入信号中：

sfx apply mix.wav mix-door.wav "layer:file=door.wav,at=6,align=onset,level=-3"
sfx apply mix.wav mix-hit.wav "riser:at=6,length=2.5" "drop-gap:at=5.55,gap=0.45" "layer:file=library:ab12cd34ef56,at=6,align=onset" "sub-drop:at=6,level=-4"

• align=onset 会测量采样的起音位置，并将该起音点放置在 at 指定的时间上。采样通常以 20–300 毫秒的静音或预卷开始；若使用默认的 align=start，这些静音会导致撞击声落地延迟。对呼啸声和过渡音效使用 align=peak，因为这类音效的最响点应该与剪辑点对齐。
• level 以 dB 为单位，length 用于仅使用前几秒，fadeIn / fadeOut 用于塑形。sync=<s> 用于手动设置同步点（配合 align=start 使用）。
• 使用采样可以替换合成的 hit、braam 或 whoosh；请在其周围保留 riser、drop-gap 和 sub-drop。
• 如果需要对采样本身进行处理（如混响、距离感、扬声器效果），请先使用 sfx apply sample.wav sample-fx.wav ... 处理，然后使用处理后的结果进行分层。
• 过场音效（汽车、摩托车、无人机）：先将独立采样通过 doppler 效果渲染，其中 at 设置为过场最接近听众的点，然后将其与 sync 设置在同一秒上进行分层，使过场效果恰好落地在剪辑点上：sfx apply car.wav car-pass.wav "doppler:at=2,speed=90"，然后 "layer:file=car-pass.wav,at=6,sync=2"。
• 采样的电平差异很大。分层后，使用 sfx analyze 分析结果，如果峰值达到 0 dBFS，则需要降低 level。

采样的存放位置

采样是属于用户订阅的授权音频。它们存放在 ~/.audiofx/samples 目录下，每个采样旁边都有一个 .json 文件（包含 id、标题、来源、种类、轨干），绝不应放在项目文件夹或代码仓库中：

sfx sample add <file-or-url> --title "Door slam, heavy wood" --id <library id> --source epidemic-sound
sfx sample list            # 每个采样的 library:<id>、时长以及其起音位置

sample add 会复制本地文件或下载 URL，测量起音位置，并打印出 library:<id> 引用，供 layer:file=... 使用。编辑器在其采样标签页中显示这些采样，其瞬间效果可以使用一个合成撞击声或呼啸声。

从音效库获取（Epidemic Sound MCP）

当用户连接了 Epidemic Sound MCP（提供 SearchSoundEffects 和 DownloadSoundEffect 工具）时：

1. 优先重用。 sfx sample list：如果已存在合适的采样，直接使用。
2. 搜索 使用 SearchSoundEffects：使用简短、具体的术语（如“cinematic impact low”、“whoosh fast short”、“glass shatter”），first: 5，并使用符合用途的毫秒级时长过滤器（撞击声和呼啸声通常小于 4000 毫秒；氛围声则更长）。根据标题、标签和时长选择。
3. 下载 使用 DownloadSoundEffect (fileType: WAV)。它会返回一个带签名的 URL，该 URL 有时效性。
4. 保存：sfx sample add "<assetUrl>" --title "<title>" --id <id> --source epidemic-sound。切勿将签名的 URL 写入文件，也切勿将音频保存在项目内部。
5. 使用 sample add 打印出的 library:<id>："layer:file=library:<id>,at=T,align=onset"。

您无法直接收听，所以不要断言某个采样“听起来合适”。报告您可以测量的信息（时长、起音位置、结果的峰值），并且在需要做选择时，加入两三个候选采样，让用户在编辑器的采样标签页中凭耳朵挑选。如果下载失败并返回 RETRY_LATER，请等待它所指示的秒数后再重试。

混音：sfx mix

sfx mix 将人声、音乐和音效片段放置在一个时间线上，使音乐在人声下闪避，并对总输出进行标准化，这一切都在一次 ffmpeg 处理中完成。快速模式接受每个片段一个标志，格式为 file@second：

sfx mix final.mp4 --video cut.mp4 --voice [email protected] --music library:<id> --sfx [email protected]
sfx mix final.wav --voice vo.wav --music song.wav --duck 14 --loudness -16
sfx mix --video cut.mp4 --voice [email protected] --music song.wav --print > mix.json

• 当有人声播放时，音乐音量降低 10 dB (--duck <dB>，--no-duck 关闭此功能)。一个 --sfx 片段的起音会落在其 at 指定时间上，类似于 align=onset。
• 总输出被标准化至 -14 LUFS (--loudness <LUFS|off>)，然后应用 -1 dB 的峰值上限。混音被测量并通过固定增益提升到目标值，因此其动态被保留；当峰值首先达到上限时，限制器会被向上推最多 6 dB 以缩小差距，因此含有非常响亮的撞击声的混音仍然可以落在目标以下：使用 sfx analyze 检查。视频的 AAC 音频可能会超过上限约 0.3 dB ("master": { "ceiling": -1.5 } 可使其保持在 -1 dBTP 以下)。
• 混音持续 --duration 指定的时长，否则持续视频的时长，否则持续到最后一个片段的结束。使用 --video 和视频输出时，画面被直接复制，音频被替换。
• --print 改为输出项目 JSON 而不是渲染：编辑它，然后运行 sfx mix mix.json final.mp4。

项目文件可以为每个片段和轨道提供各自的设置。路径相对于项目文件，并且 library:<id> 在任何需要文件路径的地方都能工作：

{
  "version": 1,
  "video": "cut.mp4",
  "tracks": [
    { "id": "voice", "role": "voice", "clips": [{ "file": "vo.wav", "at": 1.5, "steps": [{ "effect": "voice-clean" }] }] },
    { "id": "music", "role": "music", "clips": [{ "file": "library:<id>", "fadeOut": 2 }], "duck": { "depth": 12, "release": 600 } },
    { "id": "hits", "role": "sfx", "clips": [{ "file": "door.wav", "at": 7.52, "align": "onset", "gain": -3 }] }
  ],
  "master": { "loudness": -14 }
}

• 片段 (Clip)：file、at（时间线上的秒数）、start 和 length（要使用的文件片段）、gain (dB)、fadeIn、fadeOut、align (start、onset、peak)、steps。
• 轨道 (Track)：id、role (voice、music、sfx)、gain、mute、solo、steps、duck (true、false 或 { depth, attack, release, threshold }；对音乐默认启用)。
• 步骤 (Step)：{ "effect": "underwater", "params": { "depth": 0.8 }, "from": 4, "to": 9.5, "fade": 0.35 }。片段步骤在片段时间内运行（0 = 片段开始）；轨道步骤在时间线时间内运行，因此它们的时间窗口与视频对齐。
• 主控 (Master)：steps、loudness (null 保持电平不变)、ceiling (dB，默认 -1)。

音乐适配视频

目标是剪辑一首歌，使其长度与视频精确匹配，并且将其重拍落在视频的主剪辑点上。您无法通过听觉判断哪个上升点是“那个”重拍：请通过测量、用数字提出建议，并让用户通过听觉确认。使用 Epidemic Sound MCP（SearchRecordings、DownloadRecording、EditRecording、PollEditRecordingJob、DownloadRecordingEdit）：

1. 测量视频。 sfx cuts cut.mp4 打印其长度（例如 30.000 秒）及其硬切点。与用户商定主剪辑点 C，重拍必须落在此处（例如 12.4 秒）。
2. 查找并保存一首歌。 SearchRecordings 使用 query: { term: "..." }、filter (bpm: {min,max}、duration: {min,max} 以毫秒计、moodSlugs、taxonomySlugs 用于流派、vocals: false 用于纯音乐）和 first: 5。根据 title、bpm 和 audioFile.durationInMilliseconds 选出两到三首候选；用户可以通过 audioFile.lqmp3Url 试听每一首。使用 DownloadRecording (id、options: { fileType: "WAV", stemType: "FULL" }) 下载所选音乐，并立即保存，因为其 assetUrl 有时效：

   sfx sample add "<assetUrl>" --title "<title>" --id <id> --source epidemic-sound --kind music
   

   它会打印出从此处开始使用的 library:<id> 引用（不是 Epidemic 的 id）。
3. 找到重拍候选点。 sfx sections library:<id> 列出最强的上升点及其以 dB 为单位的跳变幅度、整体和 150 Hz 以下（重拍通常是低频和贝斯进入的地方）、下降点和各个乐段。~ 标记一个渐进变化，其时间点是近似的。向用户提出前两三个候选点及其数值（“64.000 秒，+8.6 dB，低频段 +30.2 dB”），并请用户通过听觉在编辑器或预览中确认重拍位置。由用户自己选择。将确认的秒数记为 D。
4. 剪辑歌曲。 调用 EditRecording，使用录音的 id 和以下参数：

   { "targetDurationMs": 30000, "downloadAudioFormat": "WAV", "forceDuration": true,
     "requiredRegionsAtOffsets": [{ "startMs": 56000, "endMs": 72000, "offsetMsInEdit": 4400 }] }
   

   targetDurationMs 是视频的长度（最大 300000）。所需区域保留重拍前 lead 秒的铺垫和重拍后 hold 秒的延续，并将其放置使得重拍落在 C 上：startMs = D − lead、endMs = D + hold、offsetMsInEdit = C − lead，单位均为毫秒。以上示例中，D = 64、C = 12.4、lead = hold = 8：56–72 秒的区域在剪辑后版本中起始于 4.4 秒，因此重拍在 4.4 + 8 = 12.4 秒处播放。需要满足 C − lead ≥ 0 和 C + hold ≤ 视频长度。