manwithshit/subtitle-focus

Subtitle Focus｜字幕美化與重點燒錄

將審查過時間軸的 SRT 轉換為黃色語義高亮、經認可的簡短樣片，以及可追蹤的全片燒錄版本。當使用者提供參考截圖時，額外為該專案校正字幕樣式。代理人根據 SRT 上下文、載入的詞彙表、專案證據和使用者修正來決定詞彙意義；捆綁的腳本擁有確定性旗標、精確替換、來源鎖定、混合 CJK/Latin 排版、渲染、審查幀和雜湊值。來源 SRT 和影片為唯讀。

需要已匯出的 SRT。僅有影片輸入或純文字逐行 MD 轉錄稿在本技能中沒有被接受的時間軸。請停止並要求使用者匯出 SRT；請勿呼叫 Video Use、剪口播、本機 Whisper、ASR 或 OCR。

分五個關卡進行。每個確認關卡前請暫停。

SRT 校對鎖定 → 高亮確認 → 樣片確認 → 全片抽幀 → 交付登記

關卡 1 — SRT 校對鎖定

1. 在機器上首次使用前執行 doctor。
2. 需要附時間軸的 SRT。拒絕純文字 MD/轉錄稿輸入以及僅影片轉錄請求。
3. 在專案開始時要求兩個明確選擇：使用個人詞彙表或明確跳過；使用專案詞彙表或明確跳過。請勿在安裝時詢問，且在這兩個選擇都透過 proofread 旗標記錄之前，請勿開始正式校對。
4. 執行 proofread。基礎詞彙表會自動載入。請閱讀 text-lock-schema.md 以了解明確選擇、分層、隱私行為和結構。 公開來源審查政策記錄在 glossary-sources.md。
5. 使用 SRT 相鄰片段、已載入的詞彙表來源、專案詞彙、產品名稱、專案檔案和使用者修正來檢查每個提示。僅在存在實際使用者/專案規則或列舉的詞彙表條目時，才套用拼寫、大小寫、數字、單位、代詞或間距規則。請勿發明一般的標準化政策。
6. 起草 corrections.json。詞彙表比對結果是建議，絕非自動編輯。請勿無聲重寫。
7. 執行 correct；向使用者顯示提示層級的修改前/後表格。輸出必須保留 SRT 文字中未提及的換行和重複空格。
8. 在明確文字核准後，執行 lock --confirmed。

停。 請勿從未鎖定的 SRT 規劃高亮。對 SRT 的任何位元組變更都會使其鎖定、字幕規劃、樣片和全片渲染失效。請重新產生它們。

關卡 2 — 高亮文字

1. 使用 --max-chars 16 執行 plan --lock ...，除非使用者另有要求。
2. 使用 highlight-schema.md 起草 highlight.json。
3. 執行 apply 和 review。調整選擇直到節奏報告通過，然後執行 validate。
4. 按時間軸順序將完整的字幕稿件傳送給使用者，每個提議的高亮直接以 Markdown 粗體標記在句子中。請勿先傳送單獨的關鍵字清單或高亮表格。要求使用者確認粗體位置或指出需要重新定位的句子。

選擇：僅含義承載的完整單詞或詞組。將每個渲染的字幕段落視為一個句子。每個相鄰對必須包含至少一個高亮段落，因此連續未高亮的句子最多只能有一個。一個提示的完整文字若被匹配的繁體中文或 ASCII 括號包圍，則為畫外音/子母畫面旁白：保持純文字並視為節奏邊界。正常句子中的行內括號不適用此豁免。使用者明確要求保持特定提示或段落為純文字時，優先於節奏，尤其是對於子母畫面/畫外音內容：將其記錄為 plain_overrides 條目，包含目標 id 和使用者確認的原因，保持純文字，即使沒有括號也視為節奏邊界。請勿僅因內容看似次要就發明此豁免，也請勿添加附近的填充性高亮來彌補。允許高亮每個句子，當這樣做能改善連續性時。一個簡短語義原子句可以完整高亮；較長的句子通常應保留一個主要含義承載詞組，或僅在真正並列或對比時保留兩個。請勿為了降低百分比而拆分單字、產品名稱或詞組。請勿僅為了滿足節奏而高亮填充詞、轉折詞或低資訊詞。覆蓋率絕不阻礙規劃。審查會在較長段落大部分被高亮或包含過多高亮範圍時發出非阻斷性密度警告，由使用者從完整的粗體稿件中決定。若無法以有意義的高亮或明確的使用者例外滿足節奏，則報告衝突的段落 id 供使用者審查。高亮期間請勿重寫鎖定的 SRT。

停。 在使用者確認完整的粗體稿件之前，請勿進行渲染。

關卡 3 — 樣片與參考圖樣式

1. 複製 default-style.json 或使用 style 衍生一個版本。
2. 在沒有參考示範時，將預設 center_y_ratio 保持為 0.82。
3. 當使用者提供參考截圖時，檢查它並使用明確覆寫（例如 --center-y-ratio、--safe-width-ratio 或 --font-size-max）執行 style --reference-image ...。輸出會記錄參考圖片的 SHA 和尺寸。請參閱 style-calibration.md。
4. 渲染一個從第一個高亮開始的 10–15 秒片段。
5. 執行 preview --video ... 以取得 CJK、Latin 和混合高亮的靜態圖，確保靜態圖使用目標影片的真實尺寸。
6. 檢查基線、重疊、裁切、手機框安全區域、頭像避讓以及參考示範對齊。
7. 執行 validate --video ... --style ... 以實際影片尺寸和所選字型測量每個字幕。渲染器可能將字幕縮小至 font_size_min；仍超出安全像素寬度的字幕將失敗。

停。 在使用者接受樣片之前，禁止全片渲染。樣式變更會建立 style-vN.json；文字變更則返回關卡 1。

關卡 4 — 全片與抽幀

1. 不帶 --start 或 --duration 執行 render。
2. 針對鎖定的 SRT 和最終影片長度執行 validate --video ...。
3. 對最終渲染影片使用 --already-burned 執行 frames，並在存在修正時傳遞 --corrections。它必須包含每個修正的提示、每個高亮段落，以及入點/中間/出點幀。
4. 檢查 contact-sheet.jpg 以及每個全解析度幀。審查幀中缺少修正提示即為交付失敗。

關卡 5 — 唯一交付

使用最終影片、鎖定的 SRT、高亮規劃、樣式、修正和審查目錄執行 deliver。該指令會寫入一個 subtitle-focus-delivery 清單，包含路徑、雜湊值、影片元資料、變更的提示 id、審查過的提示 id、參考示範來源以及交接檔案。

使用 --handoff-dir 複製最終 SRT 並產生轉錄稿。僅在使用者想要複製影片時加入 --copy-video。僅在已存在完成的發布文件時加入 --publish-copy。請勿發明發布副本。

請參閱 delivery-schema.md。

指令對照表

SCRIPT=skill/scripts/subtitle_focus.py

python3 "$SCRIPT" doctor
python3 "$SCRIPT" glossary-init --scope personal
python3 "$SCRIPT" proofread --srt /abs/in.srt --no-personal-glossary --no-project-glossary --output /abs/text-review.md
python3 "$SCRIPT" correct --srt /abs/in.srt --corrections /abs/corrections.json --output /abs/locked-text.srt --review /abs/corrections-review.md
python3 "$SCRIPT" lock --srt /abs/locked-text.srt --output /abs/srt-lock.json --confirmed
python3 "$SCRIPT" plan --srt /abs/locked-text.srt --lock /abs/srt-lock.json --output /abs/caption-plan.json
python3 "$SCRIPT" apply --plan /abs/caption-plan.json --highlights /abs/highlight.json --output /abs/caption-plan.highlighted.json
python3 "$SCRIPT" review --plan /abs/caption-plan.highlighted.json --output /abs/highlight-review.md
python3 "$SCRIPT" style --base skill/assets/default-style.json --reference-image /abs/demo.png --center-y-ratio 0.73 --output /abs/style-v1.json
python3 "$SCRIPT" validate --plan /abs/caption-plan.highlighted.json --video /abs/input.mp4 --style /abs/style-v1.json
python3 "$SCRIPT" preview --video /abs/input.mp4 --plan /abs/caption-plan.highlighted.json --style /abs/style-v1.json --cue 2 --output /abs/cue-2.png
python3 "$SCRIPT" render --video /abs/input.mp4 --plan /abs/caption-plan.highlighted.json --style /abs/style-v1.json --output /abs/edit/final-subtitled.mp4
python3 "$SCRIPT" frames --video /abs/edit/final-subtitled.mp4 --already-burned --plan /abs/caption-plan.highlighted.json --style /abs/style-v1.json --corrections /abs/corrections.json --output-dir /abs/edit/review-frames
python3 "$SCRIPT" deliver --video /abs/edit/final-subtitled.mp4 --srt /abs/locked-text.srt --plan /abs/caption-plan.highlighted.json --style /abs/style-v1.json --corrections /abs/corrections.json --review-dir /abs/edit/review-frames --output /abs/edit/delivery.json

執行 python3 scripts/subtitle_focus.py <command> --help 以查看所有旗標。

繪圖合約

視覺數字和排版規則在 visual-spec.md 中。請勿添加代理人端的繪圖手段。保持一個共享基線，僅放大高亮運行，將混合詞組（例如 C 組）保持在一起，並以完整運行方式繪製字串。

禁止事項

藉口	現實
"SRT 只改了一個字"	其雜湊值已變更。重新鎖定並重新產生所有衍生產物。
"高亮很明顯"	關卡 2 是用戶決定。等待。
"預設 82% 高度永遠正確"	僅在沒有參考示範時保持 82%；否則使用版本化的樣式覆寫。
"隨便幾個幀就夠了"	每個修正的提示和高亮段落都必須出現在審查幀中。
"最終檔案名稱告訴我們內容"	只有交付清單是權威的。
"影片或 MD 足以還原時間軸"	本技能需要已匯出的 SRT，且不執行 ASR/OCR。
"詞彙表比對結果一定是對的"	這是附有來源的建議。顯示它並等待文字核准。
"沒有詞彙表檔案就不需要決定"	關卡 1 仍然需要明確的個人和專案跳過選擇。
"一般排版規則很明顯"	保留 SRT。僅添加使用者要求或列舉的規則。
"壓平 SRT 行沒有影響"	渲染規劃可能衍生一個顯示行，但鎖定的 SRT 必須保留未提及的空白。
"連續四個純文字句子是可以接受的"	每個相鄰對需要至少一個高亮段落；驗證會阻止較長的純文字運行。
"括號旁白需要強制高亮以滿足節奏"	完全括號內的提示保持純文字並分隔節奏運行；行內括號仍是正常提示的一部分。
"節奏比用戶明確的純文字選擇更嚴格"	用戶確認的選擇優先。將目標提示或段落記錄在 plain_overrides 中；切勿代表用戶推斷例外。
"短句不能完整高亮"	當整個句子是一個有意義的觀點時，可以完整高亮；覆蓋率僅供參考。
"移除 30% 上限意味著長句可以全部變黃"	長且密集的高亮會顯示為審查警告；預設保留一個主要詞組，讓用戶從完整稿件中決定。