Lyric Video 技能
使用者提供的輸入: 一個音訊檔案、一張封面圖片,以及歌詞純文字(可選)。你交付的成果: 一個完整的 .mp4 檔案。使用者無需提供 SRT 檔案——auto_srt.py 會自動從音訊建立它。
執行指令
pip install pillow imageio-ffmpeg vosk # ffmpeg 會隨 imageio-ffmpeg 一併安裝
python scripts/make_video.py \
--audio song.mp3 --cover cover.png --lyrics lyrics.txt \
--title "歌曲名稱" --artist "演出者名稱" \
--style spotify --out lyric_video.mp4
這一個指令即可完成:辨識語音 → 將使用者提供的歌詞對齊 → 寫入 SRT → 分段渲染影片 → 合併 → 輸出 lyric_video.mp4。
--style spotify(預設)— 模糊背景、專輯卡片、進度條、平滑滾動的歌詞。--style cinematic— 全幅背景(可透過--bg plate.png指定,否則會自動生成),2.35:1 寬螢幕比例,Kalam 字體,逐詞高亮。--start 9.6 --duration 20— 製作預告片段。- 無封面圖片?會從歌曲標題自動生成。無歌詞?使用語音辨識結果。
輸入項目及其缺失時的處理方式
| 輸入 | 說明 | 若缺失時 |
|---|---|---|
| 音訊 | mp3 / m4a / wav | 必要項目——請向使用者索取 |
| 封面圖片 | 正方形,尺寸 ≥1000×1000 | 以程式方式生成;或可在 Figma 中製作(使用 generate_image,提示文字請參考 PROMPTS.md) |
| 歌詞文字 | 純文字,每行一句歌詞 | 使用語音辨識結果,時序仍然自動計算 |
| 歌名 / 演出者 | 文字 | 從封面圖片推斷,或保留通用名稱 |
| 語言 | --lang hi(預設)或 en | 從歌詞腳本中自動判斷 |
錯字是預期中的且會妥善處理:兩端文字都會經過標準化(標點符號、nukta 變音符號、大小寫),並使用模糊比率進行單詞比對,因此 "कोलम्बस" 與 "कोलंबस" 或 "आईंस्टीन" 與 "आइंस्टाइन" 仍能正確對齊。無法比對的單詞則會在其前後鄰近單詞之間進行插值。
處理流程(各腳本的功能)
auto_srt.py— 將音訊解碼為 16 kHz PCM 格式,執行 Vosk(離線,會自動下載約 40–80 MB 的模型一次),可選地使用使用者提供的歌詞作為語法來限制解碼範圍,透過difflib加模糊比對進行對齊,最終為每句歌詞寫入一個 SRT 時間提示。spotify_lyrics.py/motivational_render.py— 使用 Pillow 渲染影格,並將原始影格傳送至 ffmpeg。make_video.py— 分段渲染(預設每段 45 秒,可將記憶體使用量維持在 2 GB 以下),使用ffmpeg -f concat -c copy進行合併。
品質標準
- 持續流暢的動態,絕無停頓:逐格插值攝影機/捲動效果。
- 當前歌詞行更大更亮;前後行依層級縮小並調暗。
- 長行會自動縮小至安全寬度;絕不讓文字超出影格邊緣。
- 根據文字使用正確字型:天城文字行需要使用天城文字型(內建於
assets/fonts/),拉丁文字行需要使用拉丁文字型。絕不在同一字串中混合使用。 - 每個影格只處理一個動態:背景移動或文字移動,兩者不會同時進行。
交付前驗證
ffmpeg -ss 12 -i out.mp4 -frames:v 1 check.jpg # 檢查 2–3 個時間點
確認項目:無文字被裁切、當前歌詞行顯示正確、無方塊(字型問題)、進度時間正確、音訊同步無誤、長寬比與色調一致。
常見問題與解決方案
| 症狀 | 原因 | 解決方法 |
|---|---|---|
| 出現方塊而非文字 | 文字使用的字型不正確 | 使用 font_for(text, …);天城文字型位於 assets/fonts/ |
mkl_malloc: failed to allocate memory | 2 GB 記憶體加上大型模型/音訊 | 此處使用的 Vosk 可避免此問題;若使用 whisper,請將音訊分塊為 8–10 秒 |
ffmpeg Cannot allocate memory | 同時處理過多影格 | 使用 --chunk 40、-threads 2、rc-lookahead=4 參數 |
| 歌詞隨時間偏移 | 在較長的間奏段落中對齊失敗 | 使用 --lyrics 參數;確保每行文字對應一句歌詞 |
| 背景跳動 | 預渲染的關鍵影格被交換而非混合 | 內建的渲染器會自動進行混合/插值處理 |