Bilingual Video Subtitles 研修動画 二言語字幕
完全なパイプラインは scripts/pipeline.py（単一エントリポイント、ステージごとにキャッシュあり、途中再開可能）。
ホスト環境に関する注意: このスキルは複数環境に適応可能で、文字起こしバックエンドを自動選択します（元のサンドボックスにある Omni ゲートウェイ / OpenAI 互換 API / whisper ブリッジ）。Omni ゲートウェイがなく、API バックエンドも設定されていない場合は エージェントモード で動作します。transcribe/translate ステージは exit code 3 で一時停止し manifest を出力するため、ユーザーが対応する文字起こし/翻訳を完了した後、
buildを再実行して再開します。操作プロトコルとバックエンド設定の詳細は references/host-adaptation.md を必読。pipeline が exit code 3 で終了してもエラーではありません。manifest に従って対応する作業を完了してから再実行してください。
標準ワークフロー
- 入力の取得：動画ファイル + 対応する規則・参考文書（.docx / .txt / .md）。
- 参考文書を読み込み、それに基づいて用語集
glossary.txtを作成（各行中国語 = 英語、10～40 エントリ）。 用語集は動画全体の翻訳の一貫性を決定します。以下のカテゴリを必ずカバーすること：制度・規則名、役割と略称（例：PM=Project Manager）、業務伝票・フォーム名、内部システム名。 - ビルドを実行（フォアグラウンドで実行、十分なタイムアウト時間を確保。50分の動画で全プロセスは約15～25分）：
python3 scripts/pipeline.py build \
--video <動画パス> --doc <規則文書パス> \
--work <作業ディレクトリ> --out <出力ディレクトリ> \
--glossary <glossary.txt> \
--hotwords "安全红线,需求单,变更单,PM,QA,SRE" \
--preview 90
- 生成順序（各ステップはキャッシュされ、失敗後も同じコマンドを再実行すれば続きから再開）： setup（音声分割）→ transcribe（Qwen3-Omni による逐語録）→ timing（whisper タイムスタンプ） → align（ピンインアライメント）→ clean（口語表現の除去・文分割）→ translate（バッチ中国語→英語翻訳） → package（プロジェクトファイル + SRT + ASS）→ render（プレビュー版 + 完全版）。
- まず
--previewで出力されたプレビュー動画をユーザーに確認してもらい（media-read を使用してフレームを取得し、字幕レンダリングをチェック可能）、その後、完全版動画、SRT、字幕プロジェクトファイルを納品します。
納品物の説明
| ファイル | 用途 |
|---|---|
<名称>_中英双语字幕_完整版.mp4 | ハードサブタイトル成品（中国語は上段に白文字、英語は下段に水色文字、両方とも半透明黒背景バー付き。あらゆる背景で可読） |
<名称>_中英双语字幕.srt | 二言語字幕ファイル（プレーヤー/プラットフォームにインポート可能） |
<名称>_字幕工程.json | マスターデータ：全タイムスタンプ + 中国語・英語対訳テキストを含む。年度ごとの微調整はこれのみを修正 |
--work ディレクトリ | 中間生成物のキャッシュ（文字起こし原稿、whisper タイムスタンプ）。保持することで再文字起こしを回避 |
年度ごとの微調整（制度改定後の字幕更新）
制度の微調整が一部の文のみに影響する場合、文字起こしをやり直す必要はありません：
- ユーザーに修正が必要な時間帯・内容を指摘してもらい、または前年の
<名称>_字幕工程.json上で直接zh/enテキストを修正（タイムスタンプが変わらない場合は start/end は変更しない）。 - 再レンダリング：
python3 scripts/pipeline.py render --project <工程.json> [--video <新動画>] [--srt-only]
新しい動画で対応するセクションに文の追加・削除がある場合：新しい動画に対して build --stage transcribe を実行して新しい逐語録を取得し、手動で比較して、新しいテキストで工程ファイルの対応するエントリを置き換えてから render を実行します。
テーマ・役割ごとのショート動画分割（自己学習用）
すでに字幕が追加された完全版動画をベースに分割（二言語字幕を保持）。
- 字幕データからセクション境界を特定：参考文書の役割・セクションリストをキーワードとして使用し、 zh_lines.json（作業ディレクトリ）内でセクションの移行文を検索。典型的なパターン： "第N个角色是X"（N番目の役割はXです）、"上面是X的职责，要求是"（上記はXの責務であり、要求は）、"X的违规情形是"（Xの違反状況は）などの移行表現。 移行文の開始時刻を分割ポイントとします（その文は次のパートに含める）。
- 制約：1パートは10分以内（ハードリミット15分）。セクションが制限を超える場合は、セクション内の自然な区切り（例：「責務/違反行為/認定方法」の間）で2次分割。異なる役割のパートは結合しない。
- 分割計画 JSON を作成し実行：
{"base": "動画名", "lead_in": 0.35,
"chapters": [{"start": 0, "end": 288.4,
"title": "01_开场_目的与概述", "note": "内容说明"}]}
python3 scripts/pipeline.py split --plan plan.json \
--video <字幕付き完全版.mp4> --out <出力ディレクトリ>
<出力ディレクトリ>/<動画名>_拆分视频/に出力：自動命名された各パート +00_拆分目录.txt（パート名、時間帯、長さ、内容説明）。- スポットチェック：各パートの先頭フレームを取得（ffmpeg で PNG をキャプチャして確認）し、分割ポイントが正しく対象テーマの導入文に合っていることを確認します。
重要な実装上の約束（逸脱しないこと）
- qwen-omni バックエンドは、参考文書全文をプロンプトに用語コンテキストとして注入する必要があり、かつ
--timeout 900 --max-tokens 8192とすること（スクリプトに組み込み済み）。API バックエンドの専用 ASR（例：mimo-asr）はテキストプロンプトを解釈しないため、用語の誤り訂正は clean ステージで文書と照合して行う。 - whisper はタイムスタンプ抽出のみに使用し、その認識テキストはすべて破棄すること（中国語テキストの品質は低いが、タイムスタンプは正確）。
- アライメントは必ずピンイン文字列を使用してグローバルアライメントを行う（同音異字の誤りはピンレイヤーで自動解決）。文単位の貪欲アライメントは全体がずれる原因となる。
- アライメント品質：
alignの出力 qual mean ≥0.75 は正常。<0.6 の場合は、まず whisper の音声カバレッジを確認（references/troubleshooting.md 参照）。 - 長時間の CPU タスク（whisper/render）は、ホストのバックグラウンドタスククリーンアップポリシーに注意。必要に応じてフォアグラウンドで実行。
- ネットワーク制限：HuggingFace はミラーが必要。スクリプトには
HF_ENDPOINT=hf-mirror.comとHF_HUB_DISABLE_XET=1が組み込み済み。削除しないこと。
トラブルシューティング
references/troubleshooting.md を参照：アップロードタイムアウト、長い行の文字起こし、アライメント品質低下、フォント文字化け、レンダリング失敗などのシナリオへの対処。