space-video-audio

space-video-audio · Dubbing and Music

Add sound to the video:Narration (TTS) + background music (BGM) + mixing. The three parts can be used separately or done all at once.

1. Dubbing (TTS narration)

Turn the spoken script into narration audio. Tiered by available backend,prioritize high quality：

Tier	Backend	Description
High	IndexTTS2 / voice cloning	Use when a local model/config is available; most human-like, customizable voice
Medium (default)	`edge-tts`	Free, natural, good Chinese voices.`uvx edge-tts` Run directly
Fallback	macOS `say`	Use when there is no network/no dependencies; strongly robotic

edge-tts generation (recommended Chinese voice zh-CN-XiaoxiaoNeural / zh-CN-YunxiNeural）：

uvx edge-tts --voice zh-CN-YunxiNeural --rate=+8% \
  --text "$(cat 02_脚本/口播.txt)" --write-media 05_音频/voice.mp3

For long scripts, generate in sentence/paragraph segments and then concatenate, to avoid redoing the whole thing because of one sentence error
After generation, run space-video-subtitle withnarration audiore-transcription for subtitle alignment (TTS segment durations are only planning metadata and cannot be used as the subtitle timeline)
Speech rate: a faster spoken delivery is more energetic; Chinese +8%~+15% commonly used

2. Music (find and download BGM)

Track selection: first determine the mood, then find the track

Determine the BGM's mood and BPM according to the video content and rhythm:

Video type	BGM direction
Informational/tutorial	Light lo-fi / minimalist electronic, low presence, does not compete with speech
Product/tech	Clean synth pad / rhythmic electronic
Lifestyle/Xiaohongshu	Bright ukulele / light pop / warm piano
Opinion/serious	Minimal piano / ambient atmosphere
Fast-paced roundup	Upbeat with drums, for beat-synced cuts

Royalty-free sources (be sure to check the license)

See references/music-sources.md. The core few:

Pixabay Music: free, mostly no attribution required (web/API needed)
YouTube Audio Library: free, some require attribution (login required)
Free Music Archive / ccMixter: CC licensed, most require attribution
Incompetech(Kevin MacLeod): CC-BY, attribution required

Download

If there is a direct link → curl -L -o 05_音频/bgm.mp3 "<直链>"
Royalty-free tracks on YouTube/Bilibili → yt-dlp -x --audio-format mp3 -o 05_音频/bgm.mp3 "<URL>"

Red line: only use tracks you have the right to use; note down any that require attribution and put it in the video description; do not reupload copyrighted pop music; if unsure about the license, do not use it. Track selection/licensing is the user's decision; if unsure, ask first.

3. Mixing (combine into the video)

Use scripts/mix.sh, one command to mix BGM (+ narration) into the video:

bash scripts/mix.sh --video in.mp4 --bgm bgm.mp3 [--voice voice.mp3] \
  --out out.mp4 [--bgm-db -20] [--fade 1.0] [--duck]

What the pipeline does (see references/mixing-recipes.md full ffmpeg set):

Align length: if BGM is too short, loop automatically; if too long, trim to the video duration
Loudness normalization：loudnorm Pull the overall level to around -14 LUFS (platform-friendly)
Ducking: when there is narration use sidechaincompress, as soon as the voice comes in the BGM automatically drops, and when the voice stops the BGM comes back
Fade in and out: at the start and end afade, do not hard cut
BGM volume: about -12~-16dB without narration, about -20~-26dB when laid under narration
Muxing：-c:v copy does not re-encode the picture, only replaces/mixes the audio track

Handoff

Upstream:space-video-script 's voiceover script (→narration),space-video-edit 's final cut,space-video-broll 's B-roll
Downstream: final cut with sound → publish, or back to space-video-edit for final muxing

Dependencies

ffmpeg(requires loudnorm/sidechaincompress, supported on this machine),yt-dlp、uvx(runs edge-tts); the cloned voice profile needs an IndexTTS2 environment.

Core principles

BGM underlays without stealing the conversation: always enable ducking when there is narration, BGM is only for atmosphere
Loudness normalization: do not let the video go loud and soft, unify to -14 LUFS
Authorization first: use only royalty-free/tracks you have rights to, note down any that require attribution
Do not re-encode the picture: mixing only touches the audio track,-c:v copy preserves image quality