Communitygithub.com

lattifai/EdgeSpeak

建立逐字高亮的卡拉 OK ASS 字幕,可選雙語翻譯第二行,並透過一次 EdgeSpeak 轉錄請求(含內建逐字強制對齊)將字幕嵌入本地影片。

EdgeSpeak 是什麼?

EdgeSpeak Karaoke 技能專注於從單次 EdgeSpeak 轉錄請求中產生逐字高亮的卡拉 OK ASS 字幕,支援雙語(原文+翻譯)輸出,並可將字幕嵌入影片。它使用一套零依賴的 Node.js 腳本進行確定性 ASS 生成、基於實際影片畫格的即時風格預覽,以及 FFmpeg 渲染。此技能適用於 Claude Code 等 AI 代理平台,協助用戶快速完成卡拉 OK 字幕製作。其工作流程包括:讓用戶選擇字幕風格(提供 classic、minimal、boxed、high-contrast 四種預設,並可根據影片內容自動推薦)、執行一次 EdgeSpeak 轉錄以取得逐字時間戳、生成 ASS 字幕檔案,以及可選的硬字幕嵌入。技能特別強調翻譯字幕的處理:翻譯行位於原文行上方或下方(可選),且僅原文行有掃描效果,翻譯行則為純色填充。此外,技能會自動處理字型選擇,根據文字腳本(如 CJK)使用 fc-match 選取對應字型,避免出現方塊字。對於硬字幕嵌入,腳本會自動比對來源影片的位元率,以避免不必要的檔案大小膨脹。技能也提供完整的錯誤處理與回退機制,確保流程穩定。

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

在你喜歡的 AI 中提問

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

說明文件

EdgeSpeak Karaoke

從一次 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": "/absolute/path/source-media",
      "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。對齊必須使用最終的詞序列;編輯後絕不保留過時的時間戳。

無法放置文字的對齊是錯誤,而非空結果:edgespeak_align 會回傳 isError: true,並附帶 JSON {"code": "alignment_failed" | "alignment_search_budget_exceeded", ..., "alignment": {...}} 且不含任何詞(CLI 會以非零退出碼退出,並在 stderr 行輸出相同的程式碼和物件,該行以 error: alignment_failed: 或 error: alignment_search_budget_exceeded: 開頭)。僅根據 alignment 物件決定:

  • alignment.retry_recommended: true → 使用 "search_effort": "extended"(CLI:--search-effort extended)再呼叫一次 edgespeak_align。它搜尋範圍更廣,執行速度更慢且使用更多記憶體;告知用戶 alignment.estimated_extra_bytes 的值。
  • 否則,或遇到 alignment_search_budget_exceeded,請勿重試相同的呼叫。檢查轉錄稿是否與此媒體匹配,或對齊較短的片段。請參閱 edgespeak-align 以取得完整的程式碼和欄位列表。

絕不從失敗的對齊中建立卡拉 OK 提示:沒有均勻間隔的詞、沒有區段時間回退、沒有從編輯前的轉錄稿繼承的時間戳。

需求

  • 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 上,引導用戶前往 https://edgespeak.com/docs/cli#install 的獨立安裝程式(不需要桌面應用程式;在 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 <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
  -o /output/source.karaoke.ass \
  --style classic \
  --title "Source title"

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

node <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.json \
  -o /output/source.karaoke.ass \
  --style classic \
  --preview-media /path/to/source-video \
  --preview-dir /output/source.karaoke-previews

當另一個畫格更具代表性時,使用 --preview-at <seconds>,並在來源混合明亮和黑暗場景時,以不同的時間戳執行兩次。使用 --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 <skill-dir>/scripts/karaoke-ass.mjs /path/to/transcript.zh.json \
  -o /output/source.karaoke.ass --style boxed

兩行都位於同一個 Dialogue 事件中,以 \N 分隔,因此 ASS 將其作為一個區塊疊放在共享的邊距上。兩個獨立的事件則會各自錨定到該邊距並重疊。

  • --layout translation-top(預設)將翻譯放在來源文本之上;source-top 則翻轉順序,適用於以來源語言跟讀的觀眾。頂行以預設大小渲染,底行則為 72%,因此無論如何,視線都會落在主要語言上。
  • --layout source-only 忽略翻譯,產生單一語言的檔案。
  • 只有來源行具有掃描效果。逐字時間戳描述的是來源音訊,因此翻譯行不會有 \k 標籤 — 它會在整個提示期間保持純色填充。將提示持續時間分配給翻譯行的字元將是虛構的時間戳;請勿添加。要獲得真實的目標語言逐字時間戳,請使用語音合成技能(如果已安裝)朗讀翻譯內容,並對該音訊進行對齊。

字型並非可選 — 兩行都是

libass 不會像瀏覽器那樣為每個字形替換字型。使用拉丁風格字型顯示 CJK 文字會渲染為空白方塊 — 靜默地,貫穿整個燒錄過程。每個預設都附帶一個拉丁字型,因此生成器會根據文字腳本選擇字型,而不是繼承預設的字型。這也適用於來源行,而不僅僅是翻譯行:中文轉錄稿若未指定 --font,否則會燒錄出一排方塊。

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

部分翻譯的轉錄稿會被直接拒絕 — 這表示翻譯步驟提前停止,而為剩餘部分產生僅來源行的提示,會將一個不完整的檔案偽裝成完成的檔案。

燒錄硬字幕

當來源包含影片且用戶想要硬字幕時:

node <skill-dir>/scripts/render-hardsub.mjs \
  /path/to/source-video \
  /output/source.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 <rate> 取代推導出的上限,例如 --maxrate 4M。
  • --maxrate none 完全停用上限,恢復為純 CRF 行為。

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

CLI 回退

當 MCP 無法完成工作時,回退到 edgespeak-cli — 包括當 MCP 伺服器本身執行中但其工具失敗時。最常見的情況是:桌面應用程式未執行,因此每個 EdgeSpeak MCP 工具都會回傳 runtime_error: could not reach gateway。這並非安裝故障,也不需要重試;長時間執行的 MCP 伺服器故意不自行啟動引擎(駐留的伺服器持有...

[etc. 因長度限制截斷]

相關技能