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 顏色、邊距、輸出格式和品質。
轉錄並對齊一次
-
確認來源存在,並使用
ffprobe檢查其時長、尺寸和容器格式。 -
呼叫一次
edgespeak_transcribe_file:{ "path": "/absolute/path/source-media", "timestamps": "word", "start_margin": 0, "end_margin": 0 }僅在用戶要求不同的字幕長度時才加入
min_chars/max_chars。僅在用戶指定模型時才加入model。如果地區性很重要,請檢查edgespeak_list_models,未經同意不要選擇遠端模型。 -
在成功的逐字時間戳轉錄後,不要呼叫
edgespeak_align。此要求已經執行 EdgeSpeak 的內建本地強制對齊路徑,並回傳segments[].words[]。 -
對於較長的 MCP 回應,使用
artifact_json_path。對於內聯回應,將result物件儲存為 JSON。轉換器接受直接的轉錄 JSON 或帶有result的包裝物件。 -
要求每個有時間的區段中都有非空的逐字時間。絕不憑空創造逐字時間,也絕不靜默地回退到區段時間。
僅當使用者提供了外部的最終轉錄稿或實質上編輯了 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. 因長度限制截斷]