卡拉OK字幕
流程:影片 → 16 kHz 音訊 → DashScope ASR 取得逐字時間戳 → LLM 挑選詞彙並撰寫中文注釋 → ASS 卡拉OK字幕 → ffmpeg 和 libass 燒錄。
所有工作透過一個非互動式 CLI scripts/pipeline.py 完成。此檔案中的路徑相對於技能目錄。從任何目錄執行指令時,需在前面加上技能路徑,例如 python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor。
初次執行前
- 執行
python3 scripts/pipeline.py doctor。傳回 0 表示準備就緒。當設定金鑰時,它會發送一次免費請求,檢查DASHSCOPE_BASE是否與金鑰的區域相符。不會上傳或計費任何內容。加上--offline可跳過該請求。 - 如果傳回 3,請執行
bash scripts/install.sh並修復它列印出的每個FAIL行。如果腳本提示需要 sudo 密碼,或 API 金鑰遺失,請停止並詢問使用者。切勿要求使用者將金鑰貼入對話中;請要求他們將其放入.env檔案(請參閱.env.example)。 - 設定細節和選項:
references/prerequisites.md。
與使用者確認
- 影片:本機檔案或 URL。使用者必須擁有處理該內容的權利。
- 注釋:開啟(預設)或關閉(
--no-annotate)。 - 結果儲存位置。預設:回傳輸出檔案路徑。
除非使用者要求更改,否則保持視覺風格不變。風格數值:references/ass-style.md。
執行
一個指令即可執行所有步驟,並可在中斷後繼續:
python3 scripts/pipeline.py all "<url-or-file>" --work ./job [--no-annotate]
或者逐一執行步驟。每個步驟會在作業目錄中寫入固定的檔案名稱,並跳過輸出已存在的工作。加上 --force 可重做某一步驟。每個子指令都有 --help。
| 步驟 | 寫入檔案 | 付費 API |
|---|---|---|
fetch <url-or-file> | src.mp4 | 否 |
transcribe [--audio-url URL] | audio.mp3, asr_task.json, transcription.json | 是 |
annotate | annotations.json | 是 |
ass [--no-pop] [--no-annotate] | subs.ass | 否 |
render [--segment 1200] [--out FILE] | karaoke.mp4 | 否 |
ASR API 從 URL 讀取音訊。預設情況下,transcribe 會將 job/audio.mp3 上傳到 DashScope 的免費臨時儲存空間。該儲存空間會保留檔案 48 小時,且只有此帳戶的 ASR 模型可以讀取它。無需儲存桶或額外設定。如果使用者偏好自己的儲存空間,可以在 .env 中設定 AUDIO_URL_CMD 來上傳檔案並印出 URL,或者傳遞 --audio-url URL。
進度訊息輸出到 stderr。每個步驟會將其輸出的路徑印到 stdout。
結束代碼
| 代碼 | 意義 | 處理方式 |
|---|---|---|
| 0 | 完成 | 繼續。 |
| 2 | 使用方式錯誤 | 閱讀子指令的 --help。 |
| 3 | 環境未就緒 | 遵循 next: 行的指示,或執行 doctor。要求使用者提供金鑰或 sudo,或修正區域設定。 |
| 4 | 遠端服務失敗 | 遵循 next: 行的指示。重新執行相同指令會保留已完成的工作。 |
| 5 | 缺少先前步驟的輸入 | 執行 next: 行中命名的步驟。 |
| 1 | 非預期錯誤 | 閱讀錯誤訊息上方的工具輸出。 |
長時間作業
轉錄和渲染可能耗時超過 shell 工具允許的時間。請在背景執行指令並記錄到檔案,例如 nohup python3 scripts/pipeline.py all "<src>" --work ./job > job.log 2>&1 &,然後讀取日誌直到結束。如果程序終止,請再次執行同一個指令。轉錄會恢復已儲存的 ASR 任務,不會重複付費;渲染則會重複使用已完成的片段。
交付前檢查
從輸出影片的中段提取一幀畫面(ffmpeg -ss <seconds> -i job/karaoke.mp4 -frames:v 1 check.jpg),如果可以檢視圖片,請檢查它。如果來源影片已包含內嵌字幕,請告知使用者並提供兩個選項:使用模糊條遮蓋它們,或將新字幕移至頂部。
規則
- 絕不列印、記錄或提交
DASHSCOPE_API_KEY。doctor只回報是否已設定。 transcribe和annotate會從使用者帳戶扣費。除非使用者同意,否則請勿對它們使用--force。- 注釋僅限簡體中文。對於不識中文的觀看者,請使用
--no-annotate。 - ASR 可能誤聽專有名詞和術語,並可能回傳小寫文字。請告知使用者在分享影片前應先審查字幕。