hebrew-captions-asr
希伯來語轉錄與內嵌字幕:依據設定檔選擇 ASR 路線,取得詞彙時間,手動校對,建立支援 RTL 且具備入場與出場動畫的字幕卡,並透過 caption_qa 及覆蓋率聲明進行驗證。
優先級最高的規則
- 強制設為
language="he"。 HyperFrames 內建的transcribe預設使用small.en(對希伯來語效果差),且init會自動以此模型轉錄:請使用--skip-transcribe改用本地的 ivrit-ai 路線。 - 絕不讓 LLM 處理整個轉錄稿。 手動修正特定詞彙,並使用專案專屬的拼寫字典;若詞彙有歧義,則透過多次轉錄結果的多數決決定,之後不再反覆更改。交付標準:零拼寫錯誤(包含名稱、品牌、引文);希伯來語閱讀者接受後,模型評論員僅能提出建議。
- 未附上註明日期的估價與批准前,禁止使用雲端 ASR/TTS 服務(
paid-generation-gate)。預設使用本地且免費的方案;「本地=$0」不包含設定、建置時間與修正時間。 - 不要在 HyperFrames 的根元素上設定
dir="rtl"。 改為在<html>上設定lang="he";僅在文字元素上使用direction: rtl。這是針對特定引擎/版本的相容性解法(0.8.98 測試未重現黑色渲染問題,E12):保留此規則,每次更新版本時重新測試,切勿教導「根元素 RTL 是無效 HTML」。 - 從檔案載入字型(
hf/fonts/+@font-face);HyperFrames 瀏覽器無法依名稱找到已安裝的字型,會靜默地使用替代字型。 - 測量數據與機器綁定。 以「音訊秒數 / 實際牆上秒數」搭配已命名的計時範圍來報告速度;告知學生應在自己的硬體上重新測量。
- 規則 vs 內部預設集(決策預設 Q5)。 規則:必須有出場動畫(與入場動畫相同)、零拼寫錯誤、無根元素 RTL、鎖定字型前必須進行相似字元測試、重新剪輯後須進行反向轉錄。內部預設集 v1(可覆寫):Rubik 字型、1-3 個詞彙的字幕卡、字幕軌底部 y <= 1450、以及下方指定的停留時間。
- Whisper 工具在非 ASCII 檔案路徑下會出錯(
whisper-cli在希伯來語路徑上):請使用 ASCII 臨時目錄。長時間的 ASR 執行需與其他大量工作一樣,在render_lock下進行。
輸入 -> 輸出
輸入:音訊或影片、DESIGN.md/品牌類型套件、若字幕在剪輯之後則須提供最終剪輯。輸出(相對於專案根目錄):data/words.json([{"text","start","end"}] 秒)、transcript.srt、transcript.txt、data/captions.json(字幕卡)、合成檔中的字幕元件、以及包含覆蓋率聲明的 _work/qa/captions_report.json。
依設定檔選擇 ASR 路線(僅在所有者機器上測量)
| 設定檔 | 路線 | 證據與限制 |
|---|---|---|
| 任何 CPU(可攜帶基準) | faster-whisper + ivrit turbo CT2, int8, 8 實體核心執行緒 | 614.22 秒音訊花費 731.4 秒 = 0.84 音訊秒/牆上秒 (E08) |
| AMD/Windows 搭配 Vulkan 驅動 | 以 -DGGML_VULKAN=ON 建置的 whisper.cpp + ivrit GGML 模型 | 相同音訊花費 105.6 秒 = 5.82 音訊秒/牆上秒;相同建置在 CPU 上花費 1033.0 秒(慢 9.78 倍);RX 7600S 需要設定 GGML_VK_DISABLE_COOPMAT=1(僅限本地:僅在執行崩潰時設定,退出碼 127) |
| NVIDIA | faster-whisper CUDA 12 / cuDNN 9 或 whisper.cpp CUDA | 未測量 |
| Apple Silicon | whisper.cpp Metal | 未測量 |
語料庫:68 個 FLEURS he_il 片段,614.22 秒的朗讀語音,單次執行,機器閒置,計算整體花費時間。該語料庫上的 WER(使用 NFC 正規化、小寫、標點轉為空格):whisper.cpp CPU 18.09%,Vulkan 18.26%,CT2 純文字 17.74%,CT2 + VAD 19.38%(在 1161 個詞彙中編輯 4-19 處:數值接近,不代表相等)。未測量真實對話、吵雜電話音訊及人工詞邊界準確度。完整表格、建置方法及限制:references/asr-routes.md;附註日期的數據:references/volatile-facts.md。 |
程序
- 路線。 探測機器(
doctor),選擇上方路線,寫入asr_route.json(模型路徑/版本/雜湊值、裝置、精度、執行緒、後端日誌行)。權重必須固定,絕不使用「最新」版本。 - VAD 決策(可選,依片段而定,決策預設 Q8)。 不使用 VAD 時,Whisper 會對 3 秒的數位靜音以及 3 秒的低噪音(E02)返回非空的希伯來文字;在 E08 中執行的明確區間 VAD 速度較慢且準確度低於純 CT2(225 次 vs 206 次詞彙編輯)。因此:對此音訊的一個 60 秒樣本進行 A/B 測試,保留 WER 較低的結果,並在音訊包含長時間非語音內容時,務必執行靜音控制。
- 使用詞彙時間戳記進行轉錄;消費計時區域內的每個片段。儲存
words.json、.srt(--words-per-cue 3詞彙快顯模式,6 字句子模式)、.txt。歌唱或配樂音訊:使用references/asr-routes.md中定義的無 VAD「歌詞模式」及信心度過濾器。 - 校對全文:名稱、品牌、數字(使用數字,而非數字文字)、拼寫字典、透過多數決處理歧義詞。標記填充詞(「אה/אממ」通常不在 Whisper 輸出中:找出有聲音的間隙),且絕不自動刪除話語詞。
- 在每次重新剪輯後,對完整的組合 VO 進行 ASR,並將結果與預期文字進行比對(
join_diff);個別連接片段顯示「乾淨」,但完整檔案中會聽到殘留。對 TTS 輸出也進行相同的反向轉錄。 - 建立字幕卡(
references/caption-timing.md):1-3 個詞彙,關鍵字使用關鍵字顏色、雙向隔離、入場 + 出場動畫、提早 2 幀交換、領先語音 0.08-0.1 秒、將開始時間限制為不小於 0;依references/hebrew-typography.md進行字型測試;依references/rtl-and-bidi.md進行版面與雙向處理。 - QA。 對
captions.json執行scripts/caption_lint.py、對渲染結果執行caption_qa --band <top>:1450、hf_preflight、在每個關鍵字幀處拍攝快照(--describe false)、frame_qa;撰寫覆蓋率聲明(已解碼的幀數、頻帶、假設的 FPS、未檢查的項目)。
檢查關卡
狀態:pass | fail | blocked | n/a 並附帶原因;超時、空字幕卡列表或檔案遺失則為 blocked。
| 關卡 | 條件 | 證據 | 若為 false | 負責人 | 何時重新檢查 |
|---|---|---|---|---|---|
| G1 ASR 路線 | 從能力探測中選擇路線;模型+權重已固定;強制 language=he | asr_route.json(路徑、版本、裝置、精度、執行緒、計時範圍) | 降級至 CPU CT2 int8 | 此技能 | 新機器、驅動程式、模型 |
| G2 VAD | VAD 開/關由一個 60 秒真實樣本的 A/B 測試決定;當音訊包含長時間非語音時執行靜音控制 | 記錄兩個 WER(scripts/wer.py)及控制輸出 | 如果 WER 較差則關閉 VAD;如果出現幻覺則加入過濾器 | 此技能 | 新的音訊類型 |
| G3 轉錄稿 | 每個名稱/品牌/數字都已校對;套用拼寫字典;經希伯來語閱讀者批准,零拼寫錯誤 | 已批准的轉錄稿 + 字典;對樣本執行 wer.py 與修正後的文字比對 | 手動修正詞彙;絕不對全文使用 LLM | 此技能 + 人類 | 任何文字變更 |
| G4 組合剪輯 | 對完整的組合 VO 進行 ASR,結果與預期文字相符;無額外 token;每個句子的前/後 2 個詞彙都存在 | join_diff JSON | 修正連接處、重新剪輯、重新 ASR | edit-talking-head G2 | 每次重新剪輯 |
| G5 RTL / bidi | 無根元素 dir=rtl;設定 lang="he";拉丁字母、數字、貨幣、URL 已隔離;無遺留的 bidi 控制字元;檢視最終幀 | scripts/caption_lint.py bidi 區塊 + hf_preflight + 已檢視的幀 | 隔離區間;移除控制字元 | 此技能 | 任何字幕文字變更 |
| G6 相似字元 / 字型 | 每個關鍵字以最終尺寸及 360x640 尺寸渲染;ו/ז、ד/ר、ה/ח 不能被誤認為其他詞;字型從檔案載入 | hf/QA.md 中的字型樣本記錄(字型檔案、雜湊值、尺寸、幀)+ 顯示無替代字型的快照 | 為該詞彙更換字體(例如 Karantina 字型下的「לבזבז」會被讀作「לבובו」) | 此技能 | 任何字型、尺寸或關鍵字變更 |
| G7 時間 + 動畫 | 詞彙 >= 0.25 秒,字幕卡 >= 0.9 秒,最後一個詞彙 >= 0.25 秒;存在出場動畫;交換重疊 1-2 幀;無負數開始時間 | caption_lint 報告 + caption_qa + 幀檢查 | 重新設定時間;加入出場動畫 | 此技能 | 任何重新剪輯或重新設定時間 |
| G8 安全區域 + 對比度 + 覆蓋率 | 字幕底部 y <= 1450(內部預設集);品牌顏色的關鍵字在字幕條上 >= 4.5:1 的對比度;caption_qa 說明其覆蓋範圍 | 包含覆蓋率聲明及對比度數值的 caption_qa 報告 | 移動、更改顏色或加入背景 | 此技能 | 任何版面變更;新的長寬比 |
內部預設集 v1 數值(每個都可覆寫;參考資料中附有來源日期)
Rubik:關鍵字使用 Black (900) 粗體,小詞彙使用 Regular/600;在 1080x1920 解析度下使用 54-66 px(E03 暫定預設值;Alef 700 和 Noto Sans Hebrew 600 評分相同;Karantina 在單一模型靜態審查中得分為 1.8 對比 4.2,未經人工小組、手機或動畫測試)。詞彙快顯模式使用 1-3 個詞彙,每張字幕卡停留 0.35-0.7 秒;入場動畫與出場動畫對稱(向上模糊淡出,約 4 幀,向上位移 10 px,模糊 6 px);A-roll 素材的字幕軌 y 範圍 900-1240,底部 <= 1450;關鍵文字 y <= 1248。9:16 平台規格表日期為 2026-09,未經驗證為強制規則:請在手機上執行疊加測試。
參考資料(需要時載入)
references/asr-routes.md- 選擇/建置 ASR 路線、WER 協議、VAD、歌詞模式、雲端選項(均未執行)。references/hebrew-typography.md- 選擇字型、相似字元測試、E03 表格、授權。references/rtl-and-bidi.md- 混合希伯來語/英語/數字行、HyperFrames 與 After Effects 的 RTL 陷阱。references/caption-timing.md- 模式、精確時間設定方法、安全區域、對比度腳本。references/volatile-facts.md- 在引用速度、WER、固定版本、授權、安全區域數值之前使用。- 腳本:
scripts/caption_lint.py(字幕卡時間/bidi/軌道 lint)、scripts/wer.py(WER/CER 並附帶宣告的正規化方式);兩者皆使用標準函式庫,支援--self-check;腳本路徑相對於此技能資料夾。 - 倉庫層級附註日期的模組(由其他方維護):
agent-content/references/asr-routes.md、agent-content/references/hebrew-rtl-captions.md、agent-content/references/platform-specs.md、agent-content/techniques/caption-collision.md;當你需要附註日期的表格或碰撞檢測方法時載入。 - 同層技能:
edit-talking-head、render-qa-deliver、video-analysis(分析報告,非字幕)。
證據狀態
ASR 來自實驗 E02/E08(所有者機器);字型來自 E03;時間與出場規則來自所有者的專案。無人工時間基準值、無雲端 ASR 執行、無 ONNX 轉換的模型授權解析。已指定;僅執行確定性檢查;未執行模型評估 (Q4)。