Communitygithub.com

EdgeSpeak 卡拉 OK 字幕

透過一次 EdgeSpeak 轉錄請求,生成逐字高亮的卡拉 OK ASS 字幕,支援雙語翻譯第二行,並可內嵌至本地影片。

EdgeSpeak 卡拉 OK 字幕 是什麼?

EdgeSpeak Karaoke 是一個 AI 助理技能,專門從單次 EdgeSpeak 語音轉錄請求中,產生具有逐字高亮效果的卡拉 OK 風格 ASS 字幕。它能產出單語或雙語字幕,並將最終成果直接燒錄(硬編碼)到影片中。此技能包含無依賴的 Node.js 腳本,負責產生 ASS 字幕、即時風格預覽,以及透過 FFmpeg 進行渲染。使用流程為:使用者提供影片來源路徑,並選擇字幕風格(經典、極簡、方框、高對比)及輸出類型(ASS 檔、硬字幕或兩者兼有)。技能會自動優化中文等非拉丁文字的顯示,避免缺字問題,並支援雙語字幕的版面配置控制。最終會產生一個可靠的 ASS 字幕檔案,並可將其內嵌至影片中,同時保留原始影片的位元率與容器格式,確保檔案大小合理。此技能相容於 macOS Apple Silicon、Linux x86_64 及 Windows x64,並在 MCP 工具不可用時,會自動轉而使用 EdgeSpeak 命令列工具。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/lattifai/EdgeSpeak-Skills/tree/HEAD/skills/edgespeak-karaoke

在你喜歡的 AI 中提問

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

說明文件

EdgeSpeak 卡拉 OK

從一次 EdgeSpeak 轉錄請求建立卡拉 OK 字幕。使用隨附的無依賴 Node.js 腳本來進行決定性的 ASS 產生、即時幀風格預覽,以及 FFmpeg 渲染。

讓使用者選擇外觀

收集來源路徑、輸出位置,以及使用者是否想要 ASS、硬字幕或兩者兼具。 風格是使用者能看到並可能提出異議的唯一決定,因此預設將其視為使用者的選擇:

  • 明確指定:遵守命名的預設集或覆寫設定。可用的預設集有 classic、minimal、boxed 和 high-contrast。
  • 自動:僅在使用者實際將決定權交出時使用 — 「你選」、「都可以」、「趕快處理就好」、「使用預設值」。從下方表格中選擇並繼續執行,不阻塞流程。
  • 預覽後詢問 — 當使用者未表達風格偏好時的預設行為。在真實的來源影片幀上渲染每個預設集,利用執行環境的圖片檢視功能顯示 PNG,然後提出一個簡潔的問題。終端機可以列出路徑和描述,但 ANSI 文字不是忠實的視覺預覽。

沉默不等於授權。從未提及風格的使用者,通常是因為還沒看過選項,而不是決定跳過選擇。提問只需一次簡短的交換;猜錯則需要重新渲染整部影片,而且對硬字幕來說這是一條昂貴的路徑。

對於雙語輸出,哪種語言在上方也是同樣明顯的選擇 — 將其歸入同一個問題,而不是詢問兩次。

絕不要渲染預覽卻不加以顯示。 --preview-media 每次執行都會渲染全部四種預設集,因此該命令完成時,完整的比較結果已存在於磁碟上。只打開一張 PNG、默默挑選並只回報勝出者,會隱藏使用者有權看到的取捨。

對於自動模式 — 以及為了給預覽提供建議的種子 — 檢查代表性的來源幀並使用以下預設值:

素材類型預設集
一般風景或混合內容classic
乾淨、大多為深色背景minimal
雜亂、明亮、簡報或螢幕錄影boxed
垂直/手機或持續困難的背景high-contrast

當來源影片的亮度變化很大 — 同一部影片中同時有暗景和亮景 — 單一幀無法決定選擇。在兩個對比明顯的時間點渲染預覽並進行比較,因為在亮幀上表現良好的預設集,在暗幀上可能變得看不見。

當前請求的指示優先。如果存在,也讀取來自 .edgespeak-skills/edgespeak-karaoke/EXTEND.md 的選擇性偏好設定,然後是 ~/.edgespeak-skills/edgespeak-karaoke/EXTEND.md;專案偏好設定優先於使用者偏好設定。有用的偏好設定包括預設集、字型、字型大小、ASS 顏色、邊距、輸出格式和品質。

轉錄並對齊一次

  1. 確認來源檔案存在,並使用 ffprobe 檢查其時長、尺寸和容器格式。

  2. 呼叫 edgespeak_transcribe_file 一次:

    {
      "path": "/絕對/路徑/來源媒體",
      "timestamps": "word",
      "start_margin": 0,
      "end_margin": 0
    }
    

    僅在使用者要求不同字幕長度時才加入 min_chars / max_chars。僅在使用者指定模型名稱時才加入 model。如果位置有關聯,請檢查 edgespeak_list_models,並且未經同意不要選擇遠端模型。

  3. 在成功的逐字時間戳轉錄之後,不要呼叫 edgespeak_align。此請求已執行 EdgeSpeak 的內建本地強制對齊路徑,並回傳 segments[].words[]。

  4. 對於較長的 MCP 回應,請使用 artifact_json_path。對於內聯回應,將 result 物件儲存為 JSON。轉換器接受直接的轉錄 JSON 或包含 result 的包裝物件。

  5. 每個有時序的區段都必須有非空的逐字時間。絕不要發明逐字時間或靜默地回退到區段時間。

僅在使用者提供了外部的最終轉錄稿或實質上編輯了 ASR 文字時,才使用 edgespeak_align。對齊必須使用最終的文字序列;編輯後絕不要保留過時的時間戳。

需求

  • Node.js 18 或更新版本,用於隨附的腳本。
  • 以 libass 編譯的 FFmpeg,以及 ffprobe — 必須另外存在於 PATH 中的可執行檔。每個預覽和每個燒錄都透過 ass 濾鏡進行,因此沒有 libass 的 FFmpeg 無論選擇哪個預設集,都會因 No such filter: 'ass' 而失敗。轉換為 MP4/MOV/MKV/TS 額外需要 libx264;WebM 需要 libvpx 和 libopus。Homebrew 和主要發行版套件都包含所有這些。
  • 用於轉錄的 edgespeak-cli(或 EdgeSpeak 應用程式),可在 macOS Apple Silicon、Linux x86_64 和 Windows x64 上執行。在 Windows 上,安裝 EdgeSpeak 桌面應用程式,其中包含 CLI。在 macOS 和 Linux 上,使用 curl -fsSL https://edgespeak.com/install.sh | sh(獨立安裝,不需要桌面應用程式;在 Linux 上,安裝程式會自動偵測 NVIDIA GPU 並安裝支援 CUDA 的執行環境)。前言中的 minCliVersion 是此技能所針對的最舊 CLI 版本 — 如果 edgespeak-cli --version 較舊,或 --help 中缺少某個已記錄的標誌,請執行 edgespeak-cli update。

當執行因缺少依賴項目而失敗時,請回報哪個檢查失敗,而不是重試:

node --version                       # v18+
ffprobe -version                     # 必須與 ffmpeg 一起存在
ffmpeg -filters   | grep -w ass      # ASS 渲染器 (libass)
ffmpeg -encoders  | grep -w libx264  # H.264 輸出

產生 ASS 和預覽

產生選定的預設集:

node <技能目錄>/scripts/karaoke-ass.mjs /路徑/到/transcript.json \
  -o /輸出/來源.karaoke.ass \
  --style classic \
  --title "來源標題"

為了呈現選擇,在實際來源影片的一個活躍提示字幕上渲染每個預設集。這是預設路徑,不是特例 — 而且它所產生的每個 PNG 都應該被顯示:

node <技能目錄>/scripts/karaoke-ass.mjs /路徑/到/transcript.json \
  -o /輸出/來源.karaoke.ass \
  --style classic \
  --preview-media /路徑/到/來源影片 \
  --preview-dir /輸出/來源.karaoke-預覽

當另一個幀更具代表性時使用 --preview-at <秒數>,並且當來源混合了亮景和暗景時,以不同的時間戳執行兩次。使用 --list-styles 列出預設集。使用 --font、--font-size、--margin-v、--primary、--secondary、--outline 和 --back 進行微調;ASS 顏色使用 &HAABBGGRR 格式。腳本保留 EdgeSpeak 的區段邊界,僅將對齊後的時長/間隙映射到 \kf / \k 標籤。

單詞之間的間距來自提示字幕本身的 text,而不是來自每個單詞之間的空格。強制對齊將標點符號附加到其後的單詞,因此每個 words[] 條目都是 text 的一個子字串,且它們的位置只會向前移動 — 產生器會遍歷 text 一次,並重用兩個單詞之間實際存在的內容。這就是為什麼 high-performance 會保留連字號(對齊將其拆分為 high 和 performance,而連字號不屬於任何一個),以及為什麼 CJK 文字不會被渲染成 本 地 轉 錄。如果在 text 中找不到某個單詞,產生器會回退到單一空格,而不是進行猜測。

雙語卡拉 OK

當轉錄稿的每個區段都帶有 translation 時 — 也就是 edgespeak-translate 所寫入的 — 產生器會為每個提示字幕發出兩行,且不需要額外的標誌:

node <技能目錄>/scripts/karaoke-ass.mjs /路徑/到/transcript.zh.json \
  -o /輸出/來源.karaoke.ass --style boxed

兩行都位於一個由 \N 分隔的 Dialogue 事件中,因此 ASS 將它們視為一個基於共享邊距的區塊。兩個獨立的事件則會各自錨定到該邊距而導致重疊。

  • --layout translation-top(預設)將翻譯放在來源上方;source-top 則相反,適用於以來源語言跟讀的觀眾。上方行以預設大小渲染,下方行以 72% 大小渲染,這樣無論如何,視線都會落在主要語言上。
  • --layout source-only 忽略翻譯,產生單一語言的檔案。
  • 只有來源行會進行掃描(卡拉 OK 效果)。逐字時間描述的是來源音訊,因此翻譯不會得到 \k 標籤 — 它在整個提示字幕期間保持純色填充。將提示字幕時長分配到翻譯的字元上將是虛構的時間;請勿添加。要獲得真正的目標語言逐字時間,請使用 edgespeak-broadcast 合成並對齊該音訊。

字型不是可選的 — 兩行都是如此

libass 不會像瀏覽器那樣按字形替換字型。使用拉丁風格字型渲染的 CJK 文字會顯示為空白方塊 — 在整個燒錄過程中悄悄地發生。每個預設集都附帶一個拉丁字型,因此產生器會根據文字系統選擇字型,而不是繼承預設集的。這同樣適用於來源行,而不僅是翻譯:沒有 --font 的中文轉錄稿將會被燒錄成一排空白方塊。

  • 文字系統是從行本身的文字偵測到的,並透過 fc-match :lang=<標籤> 進行匹配,採用單一的 ASCII 系列別名(別名列表會破壞逗號分隔的 ASS 樣式行)。
  • --font <名稱>(來源)和 --translation-font <名稱>(翻譯)會覆寫此設定,並且在 fc-list 顯示該字型不支援偵測到的語言時被拒絕。不要透過挑選另一個拉丁字型來繞過此錯誤 — 請使用 fc-list :lang=zh-cn family 檢查何種字型涵蓋該文字系統。
  • 拉丁文字保持預設字型不變;只有在預設字型無法涵蓋該文字系統時才會進行切換。
  • 如果沒有 fontconfig,自動選擇會大聲失敗;請明確傳遞字型。當無法檢查涵蓋範圍時,執行會回報 source_font_verified: false / translation_font_verified: false,因此請回報此注意事項,而不是聲稱字型沒問題。
  • 當來源不是拉丁文字時,執行會回報 source_font / source_script。

部分翻譯的轉錄稿會被直接拒絕 — 這表示翻譯步驟過早停止,而為其餘部分發出僅來源的提示字幕,會將一個不完整的檔案冒充為已完成。

燒錄硬字幕

當來源有影片且使用者想要硬字幕時:

node <技能目錄>/scripts/render-hardsub.mjs \
  /路徑/到/來源影片 \
  /輸出/來源.karaoke.ass

預設的 --format source 會在可行時保留來源的容器:

  • MP4/M4V/MOV -> 相同副檔名,使用 H.264/AAC。
  • MKV -> MKV,使用 H.264 並複製音訊。
  • WebM -> WebM,使用 VP9/Opus。
  • TS/M2TS -> 相同副檔名,使用 H.264/AAC。
  • 不支援/不明確的來源副檔名 -> 回退到 MKV,並回報 container_fallback: true。

硬字幕總是需要重新編碼影片;保留容器並不表示要複製來源影片的編碼器。僅在使用者要求不同的傳遞格式時使用 --format mp4|mov|mkv|webm 或明確的 -o。僅在獲得授權時使用 --overwrite。

匹配來源位元率

以固定品質重新編碼會忽略來源的原始位元率,且差距可能很大:將 CRF 21 燒錄到一個精簡的 1.5 Mbps AV1 檔案中,會產生一個 4.2 Mbps 的 H.264 副本 — 是原始位元率的 2.8 倍,檔案大小將近 3 倍,且沒有明顯的品質增益。因此,腳本會探查來源,並根據其位元率推導出 -maxrate / -bufsize 上限,並根據輸出編碼器的效率差異進行縮放(H.264 需要大約 1.6 倍 AV1 的位元率才能達到可比較的品質)。品質仍然來自 CRF;上限只是為了防止品質目標導致位元率過高。

這對於 x264 目標是自動的。VP9/WebM 則保持不變,因為 .webm 設定檔會將 -b:v 0 固定為固定品質模式。報告中包含 source_video_bitrate、video_bitrate 和 bitrate_cap 的決定 — 在報告結果時比較前兩者。

僅在使用者要求特定位元率或品質等級時進行覆寫:

  • --crf <n> 設定品質目標(數值越低越好,H.264 預設為 21)。
  • --maxrate <速率> 取代推導出的上限,例如 --maxrate 4M。
  • --maxrate none 完全停用上限,恢復為純 CRF 行為。

位元率也是控制檔案大小的槓桿。當使用者對輸出大小提出異議時,在提出更改前,請同時引用來源位元率和輸出位元率,並記住扁平插圖或螢幕錄影的素材壓縮效率遠高於實景拍攝 — 即使在 CRF 28 下,字幕文字本身仍然清晰銳利,因此它絕不會是限制因素。

CLI 回退

每當 MCP 無法完成工作時 — 包括 MCP 伺服器本身正在執行但其工具失敗時 — 請回退到 edgespeak-cli。最常見的情況是:桌面應用程式未執行,因此每個 EdgeSpeak MCP 工具都會回傳 runtime_error: could not reach gateway。這並不是安裝損壞,也不該重試;長時間執行的 MCP 伺服器特意永遠不會啟動自己的引擎(一個駐留的伺服器持有引擎會與使用者接下來開啟的應用程式衝突)。CLI 沒有此限制 — 它會自行啟動裝置上的引擎。因此,將來自任何 EdgeSpeak MCP 工具的 could not reach gateway 視為「立即使用 CLI」,而不是需要回報的失敗。

如果找不到 edgespeak-cli 命令,請在 Windows x64 上安裝 EdgeSpeak 桌面應用程式,或在 macOS Apple Silicon 和 Linux x86_64 上使用 curl -fsSL https://edgespeak.com/install.sh | sh(獨立安裝,不需要桌面應用程式;在 Linux 上會自動偵測 CUDA)。

edgespeak-cli transcribe /路徑/到/來源媒體 -o /輸出/transcript.json \
  --start-margin 0 --end-margin 0

CLI 的轉錄 JSON 已經包含 segments[].words[]。不要對剛剛由同一個轉錄命令產生的文字執行 edgespeak-cli align。與隨附的腳本(在沒有 --overwrite 的情況下拒絕取代現有輸出)不同,edgespeak-cli -o 會靜默地覆寫現有檔案 — 如果轉錄稿路徑已存在,請在使用者覆寫前進行確認,或選擇新的路徑。

驗證和報告

  • 為 MCP 和 FFmpeg 提供合理的實際時鐘預算;不要中斷健康的靜默處理過程。
  • 保持 start_…

相關技能