Communitygithub.com

zgyk4167/karaoke-subtitles

將逐字卡拉OK字幕燒錄到英文影片中。每個單字在念出時會從白色變成綠色並略微放大。可選擇性地為技術詞彙、難字、片語動詞和慣用語添加簡體中文注釋,適合約 CET-6 程度的中文學習者。

karaoke-subtitles 是什麼?

這個技能可以為英文影片生成逐字同步的卡拉OK字幕,並可選擇添加簡體中文注釋。它使用阿里雲百煉(DashScope)進行語音辨識(ASR)以取得每個單字的時間戳,並透過大型語言模型(LLM)挑選困難詞彙並撰寫中文注釋,最終生成 ASS 格式的字幕檔並使用 ffmpeg 和 libass 將其燒錄到影片中。 此技能支援本地影片檔案或來自 YouTube、X 等網站的 URL(只要是 yt-dlp 支援的)。使用者需要設定阿里雲百煉(DashScope)API 金鑰,但不需要額外的儲存桶。整個流程由一個非互動式的 CLI 工具 `scripts/pipeline.py` 驅動,支援逐步執行和斷點續傳,非常適合處理較長的影片任務。 其視覺風格預設為白色文字轉綠色並帶有縮放效果,使用者可以透過 `references/ass-style.md` 調整樣式。此技能特別適合希望為英語學習者製作帶有注釋的卡拉OK字幕的開發者或教育者。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add zgyk4167/karaoke-subtitles

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

卡拉OK字幕

流程:影片 → 16 kHz 音訊 → DashScope ASR 取得逐字時間戳 → LLM 挑選詞彙並撰寫中文注釋 → ASS 卡拉OK字幕 → ffmpeg 和 libass 燒錄。

所有工作透過一個非互動式 CLI scripts/pipeline.py 完成。此檔案中的路徑相對於技能目錄。從任何目錄執行指令時,需在前面加上技能路徑,例如 python3 /path/to/karaoke-subtitles/scripts/pipeline.py doctor。

初次執行前

  1. 執行 python3 scripts/pipeline.py doctor。傳回 0 表示準備就緒。當設定金鑰時,它會發送一次免費請求,檢查 DASHSCOPE_BASE 是否與金鑰的區域相符。不會上傳或計費任何內容。加上 --offline 可跳過該請求。
  2. 如果傳回 3,請執行 bash scripts/install.sh 並修復它列印出的每個 FAIL 行。如果腳本提示需要 sudo 密碼,或 API 金鑰遺失,請停止並詢問使用者。切勿要求使用者將金鑰貼入對話中;請要求他們將其放入 .env 檔案(請參閱 .env.example)。
  3. 設定細節和選項: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是
annotateannotations.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 可能誤聽專有名詞和術語,並可能回傳小寫文字。請告知使用者在分享影片前應先審查字幕。

相關技能