| name | space-video-audio |
| description | 视频配音与配乐。三件事——(1) 配音：把口播稿用 TTS 生成旁白音频；(2) 配乐：根据视频内容/节奏匹配合适的 BGM，从免版权曲库找到并下载；(3) 混音：把 BGM + 旁白 + 视频用 ffmpeg 合成，自动压音(BGM 在人声下自动变小)、响度归一、淡入淡出、对齐视频长度。当用户说「配音」「配乐」「加 BGM」「背景音乐」「找音乐」「给视频配旁白」「TTS 口播」「混音」「audio」时触发。 |
space-video-audio · 配音与配乐
给视频补上声音：旁白(TTS) + 背景音乐(BGM) + 混音。三块可单用，也能一次做完。
一、配音（TTS 旁白）
把口播稿变成旁白音频。按可用后端分档，优先质量高的：
| 档 | 后端 | 说明 |
|---|
| 高 | IndexTTS2 / 克隆音色 | 有本地模型/配置时用，最像真人、可定制音色 |
| 中（默认） | edge-tts | 免费、自然，中文音色好。uvx edge-tts 直接跑 |
| 兜底 | macOS say | 无网络/无依赖时用，机械感强 |
edge-tts 生成（推荐中文音色 zh-CN-XiaoxiaoNeural / zh-CN-YunxiNeural）：
uvx edge-tts --voice zh-CN-YunxiNeural --rate=+8% \
--text "$(cat 02_脚本/口播.txt)" --write-media 05_音频/voice.mp3
- 长稿按句/段分段生成再拼接，避免一句错整条重来
- 生成后走
space-video-subtitle 用旁白音频重转写做字幕对齐（TTS 段时长只是规划元数据，不能当字幕时间轴）
- 语速：口播偏快更精神，中文
+8%~+15% 常用
二、配乐（找 BGM 并下载）
选曲：先定情绪，再找曲
根据视频内容和节奏定 BGM 的情绪与 BPM：
| 视频类型 | BGM 方向 |
|---|
| 干货/教程 | 轻快 lo-fi / 简约电子，低存在感，不抢话 |
| 产品/科技 | 干净的合成器 pad / 节奏感电子 |
| 生活/小红书 | 明亮 ukulele / 轻流行 / 暖钢琴 |
| 观点/严肃 | 极简钢琴 / 环境氛围 |
| 快节奏盘点 | 有鼓点的 upbeat，卡点用 |
免版权来源（务必看授权）
见 references/music-sources.md。核心几个：
- Pixabay Music：免费、多数免署名（需网页/API）
- YouTube Audio Library：免费，部分需署名（需登录）
- Free Music Archive / ccMixter：CC 授权，多数需署名
- Incompetech（Kevin MacLeod）：CC-BY，需署名
下载
- 有直链的 →
curl -L -o 05_音频/bgm.mp3 "<直链>"
- YouTube/B站 的免版权曲目 →
yt-dlp -x --audio-format mp3 -o 05_音频/bgm.mp3 "<URL>"
红线：只用有权使用的曲目；需署名的记下来放视频简介；不搬运受版权保护的流行音乐；不确定授权就不用。选曲/授权是用户的决定，拿不准先问。
三、混音（合成到视频）
用 scripts/mix.sh，一条命令把 BGM(+旁白) 压进视频：
bash scripts/mix.sh --video in.mp4 --bgm bgm.mp3 [--voice voice.mp3] \
--out out.mp4 [--bgm-db -20] [--fade 1.0] [--duck]
管线做的事（见 references/mixing-recipes.md 全套 ffmpeg）：
- 对齐长度：BGM 太短自动循环，太长裁切到视频时长
- 响度归一：
loudnorm 把整体拉到 -14 LUFS 左右（平台友好）
- 压音 ducking：有旁白时用
sidechaincompress，人声一响 BGM 自动下沉，人声停 BGM 回来
- 淡入淡出：首尾
afade，别硬切
- BGM 音量：无旁白约 -12~-16dB，有旁白垫底约 -20~-26dB
- 封装：
-c:v copy 不重编码画面，只替换/混合音轨
交接
- 上游：
space-video-script 的口播稿（→旁白）、space-video-edit 的成片、space-video-broll 的 B-roll
- 下游：带声音的成片 → 发布，或回
space-video-edit 做最终封装
依赖
ffmpeg（需带 loudnorm/sidechaincompress，本机已支持）、yt-dlp、uvx（跑 edge-tts）；克隆音色档需 IndexTTS2 环境。
核心原则
- BGM 垫底不抢话：有旁白必开 ducking，BGM 只做氛围
- 响度归一：别让视频忽大忽小，统一到 -14 LUFS
- 授权优先：只用免版权/有权曲目，需署名的记下来
- 不重编码画面：混音只动音轨，
-c:v copy 保画质
