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 顏色、邊距、輸出格式和品質。
轉錄並對齊一次
-
確認來源檔案存在,並使用
ffprobe檢查其時長、尺寸和容器格式。 -
呼叫
edgespeak_transcribe_file一次:{ "path": "/絕對/路徑/來源媒體", "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。對齊必須使用最終的文字序列;編輯後絕不要保留過時的時間戳。
需求
- 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_…