動画字幕追加

動画字幕追加 は何をしますか？

依存関係

/video-understand は前提条件です。字幕が検証済みの単語レベルのトランスクリプトと正規のタイムラインを使用するため、最初に実行してください。 開始前に、これがインストールされていることを確認してください。インストールされていない場合は、ユーザーにこの前提条件が不足していることを警告し、メディア処理を開始する前に停止してください。

ffmpeg/ffprobe がPATHに存在し、Python に Pillow、Node.js >= 22 (.mjs スクリプトとオンデマンドで取得される npx hyperframes のため) が必要です。hyperframes render/snapshot はヘッドレスChromeを駆動します。これは自身の chrome-headless-shell を管理し、キャッシュされたものが使用できない場合はシステムのChromeにフォールバックします（上書きするには CHROME を設定してください）。メディア処理の前にこれらを確認してください。

対象範囲

このスキルは、字幕のグループ化、スタイル選択、レビュー、および透明な字幕トラックを担当します。文字起こし、カット、タイミング調整、グレーディング、リフレーミング、配信オーディオポリシーの選択は行いません。

コンテンツカードやグラフィックモーションが選択されている場合は、それらの前に字幕を実行してください。承認された字幕レイアウトは、予約された字幕領域を確立し、後続の両方の操作はその領域を空けておく必要があります。この相対的な順序は、一方のペアのみがアクティブな場合にも適用されます。

最初に video-understand を使用してください。カットが存在する場合は、アクティブなプログラムタイムラインに字幕を付けてください。ソーストランスクリプトの秒数をプログラム秒として扱わないでください。

プロトコル入力

必須:

• work/project.json
• work/understand/transcript.json（単語レベルのソースタイムスタンプを含む）
• work/understand/media.json
• work/timeline.json
• work/project.json で指定されたソースビデオ

タイムラインが唯一のソースからプログラムへのマッピングです。すべての範囲は半開区間 [start_s, end_s) です。scripts/build_captions.py は共有の projectlib.map_transcript_to_timeline を使用します。ドロップされたソース範囲の単語は消え、保持された単語はプログラム時間に移動し、キューは常にクリップ境界で分割されます。

永続的な出力

work/captions/
|-- captions-plan.json
|-- caption-spatial-context.json (該当するBロールコンポジットのみ)
`-- caption-interaction.json
work/cache/captions/
|-- preview-project/
|-- preview-snapshots/
|-- overlay-project/
`-- overlay-frames/frame_000001.png ...
review/05-captions/
|-- captions.srt
|-- captions-style-review-<UUID>.html
|-- captions-style-review.html
|-- captions-review.html
|-- preview-early.png
|-- preview-middle.png
|-- preview-late.png
|-- preview-no-caption.png
|-- captions-evidence.json
`-- captions-summary.md

生成されたHTML、コピーされたランタイムファイル、抽出されたソースフレーム、およびオーバーレイフレームはキャッシュです。計画、オプションの空間コンテキスト、SRT、意思決定レシート、およびレビューエビデンスは永続的です。

字幕計画

work/captions/captions-plan.json は正規の字幕計画であり、overlay をターゲットとし、プログラム時間を使用します。以下を記録します:

• timeline_id、program_duration_s、およびソーストランスクリプトのパス;
• キューグループ化設定;
• 承認されたスタイル、決定モード、根拠、ギャラリー選択、および完全に解決されたスタイル;
• ソースバックアップされたレビューエビデンスと承認アクター;
• 互換性フィールド start、end、text、lines、words を持つキュー;
• すべてのキューに対する program_range と source_ranges;
• すべてのマッピングされた単語に対するプログラム/ソース範囲と clip_id;
• 正確な有理FPSとハッシュ化されたランタイムアセットを持つローカルレンダラーレシピ。

ジェネレーターは、古いトップレベルのキュー配列も受け入れます。これはスタンドアロンの互換性アダプターにすぎません。タイムラインの来歴を表現したり、承認されたプロトコルコントリビューションを再生成したりすることはできません。

Standard はデフォルトのプレゼンテーションモードです。Standard プランは presentation フィールドを必要とせず、単に追加するために移行してはなりません。Expressive は明示的なプレゼンテーションモードであり、プリセットではありません。--presentation-mode expressive でリクエストします。ビルドステップは、安定したキューID、デフォルトの単語 semantic_role 値、およびドラフトの presentation 計画シェルを追加します。レイアウトバリアントを推測することはありません。

Expressive は bottom-standard と center-emphasis のみをサポートします。シェルを埋める前に reference/caption-rules.md を読んでください。既存のレンダラーは、完了した presentation.layout_beats のみを消費します。位置を推測したり、ビート内でレイアウトを変更したりすることはありません。

Expressive のキューは、1つの連続したフレーズレベルの hero_line を定義することもできます。正規の level: hero を使用してください。フレーズを金色で 1.5x のサイズで独自の行にレンダリングします。レガシーの level: strong は入力エイリアスとして引き続き受け入れられ、同じようにレンダリングされますが、新しいAgent作成のプランはこれを出力してはなりません。維持されている単語ロール keyword、number、contrast はそれぞれ 1.22x を使用します。normal は 1.0x のままです。これらの処理はプリセットとは直交しており、新しいスタイルIDを作成しません。スキーマ、オーバーフローポリシー、カラオケルールについては reference/caption-rules.md を読んでください。

アクティブでレビュー承認済みのBロール操作に、承認済みまたは検証済みの話者インセットコンポジットが含まれている場合、字幕はフリーズされた上流計画、エビデンス、正規化されたコンポジット、および明示的なサブショット display_mode から caption-spatial-context.json を導出できます。これにより、Bロールレイアウトが変更されたり、再選択されたりすることはありません。Expressive 計画の前にキューの境界を調整し、維持されている preset-bottom、frame-center、panel-center、および境界のみの panel-bottom 配置のみを解決します。panel-bottom は、下部中央にフォーカスされたパネルに隣接する unsplittable_word_boundary に対してのみ許可されます。安定したキューを、構造化された話者矩形の下の予約済みストリップ内に中央揃えします。このようなキューは、単語の中点を含むコンテキストだけでなく、それが交差するすべての視覚コンテキストに対してチェックされます。このコンテキストがない場合、既存のStandardおよびExpressiveの配置動作はすべて変更されません。

スタイル

維持されているプリセットは、clean、minimal、social-bold、pill、boxed、stroked、shorts です。ギャラリーの組み合わせIDは、例えば pill-yellow、stroked-blue、shorts-green などの維持されているテーマを追加します。カラオケはオプションであり、別のプリセットではありません。

デフォルトの委任選択: clean、カラオケオフ。宛先や映像がそれを正当化する場合にのみ、より表情豊かなプリセットを選択してください。ジョブ固有の変更はオーバーライドJSONに保存してください。通常のスタイルフィードバックのためにジェネレーターを編集しないでください。

Expressive は semantic-only（カラオケオフ）と semantic-plus-karaoke（カラオケオン）の両方をサポートします。意味的な強調は、両方の構成で全キューの間持続します。共存モードでは、意味的な強調とアクティブなカラオケ単語は、すべてのハイライトモードで style.wordHighlight.activeColor を前景色として使用します。背景のハイライトは追加のエフェクトのままです。実効的なスケールは max(semantic scale, karaoke active scale) であり、その積ではありません。Expressive は、互換性のある contrast 意味論的ロールを含め、アンダーラインをレンダリングしません。

既存のレビューコントラクトは、引き続きセマンティックのみを主要なExpressiveエビデンスとして使用し、セマンティックプラスカラオケを別個にバインドします。互換性ペイロードフィールドは experimental_comparison という名前のままです。承認プロトコルの移行なしに名前を変更しないでください。

読むこと:

• グループ化制限を変更する前に reference/caption-rules.md;
• スタイル語彙については reference/caption-style-themes.md;
• オーバーライドマッピングについては reference/caption-feedback-mapping.md。

決定モード

2つの正直なモードがあり、同じハッシュバウンド状態マシンを共有します:

• human: コピーされた正確なギャラリーサマリーを select に渡し、すべての実際のプレビューエビデンスを表示し、コピーされた正確な承認または改訂サマリーを confirm または adjust に渡します。レビューページにバインドされたコマンドは、単純な承認フレーズを受け入れません。
• agent: ユーザーが明示的に字幕の決定を委任した場合にのみ使用します。空でない委任メモから始め、空でない根拠とともに agent-select と agent-confirm を使用します。

ヒューマンコマンドはエージェントモードでは失敗し、エージェントコマンドはヒューマンモードでは失敗します。空間コンテキストのないStandardは、4つの維持されているソースバックアップ画像を必要とします。Expressiveおよびコンポジット対応のレビューでは、動的なエビデンスコントラクトを使用します。ソース、計画、タイムライン、スタイル、オーバーライド、プロジェクトメタデータ、レビューページ、またはエビデンスへの変更は承認を無効にします。空間コンテキスト、上流のBロール改訂、またはバウンドコンポジットの変更も同様に行います。影響を受けるアーティファクトを再構築し、再度レビューしてください。

正規のワークフロー

リポジトリルートから実行します。プロジェクトパスを設定します:

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-add-captions"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$SourceVideo = "<absolute path from work/project.json>"
$Plan = Join-Path $Work "captions\captions-plan.json"
$SpatialContext = Join-Path $Work "captions\caption-spatial-context.json"
$SpatialArgs = @()
$SpatialReviewArgs = @()
$Receipt = Join-Path $Work "captions\caption-interaction.json"
$Review = Join-Path $ProjectRoot "review\05-captions"
$Cache = Join-Path $Work "cache\captions"
$PreviewProject = Join-Path $Cache "preview-project"
$ComparisonProject = Join-Path $Cache "preview-project-expressive-karaoke"
$OverlayProject = Join-Path $Cache "overlay-project"
$OverlayFrames = Join-Path $Cache "overlay-frames"
New-Item -ItemType Directory -Force -Path (Split-Path $Plan),$Review,$Cache | Out-Null

字幕計画を構築する前に、現在のリクエストが明示的にモードを選択していない限り、ユーザーにプレゼンテーションモードを選択するよう尋ねてください。質問をユーザーの現在の会話言語でレンダリングし、Standard と Expressive の識別子は翻訳せずにそのままにしてください。以下の英語のソースプロンプトをこのファイルに保持し、現在のセッションでローカライズされた選択肢を提示し、提示 + STOP してください:

Choose the caption presentation mode:

1. Standard: Uses stable conventional placement and suits most content.
2. Expressive: Switches between bottom and center placement based on meaning and emphasizes keywords and numbers.

Reply with Standard, Expressive, or "Use the default (Standard)."

ユーザーが応答するまで build_captions.py を実行しないでください。ユーザーが明示的に選択を委任した場合（どのような言い回しでも）、Standard を選択してください。計画を構築する前に、互換性を維持するデフォルトとして Standard が選択されたことを明記してください。

プログラム時間キューとレビューSRTを構築します:

python "$SkillRoot\scripts\build_captions.py" `
  "$Work\understand\transcript.json" `
  $Plan `
  "$Review\captions.srt" `
  --timeline "$Work\timeline.json" `
  --source-transcript "understand/transcript.json" `
  --max-chars 42 --max-lines 2 --max-dur 6 --gap 0.6

ユーザーがStandardを選択した後、上記のコマンドは変更されていないStandard計画を生成します。ユーザーがExpressiveを選択した後、同じコマンドを次のように実行します:

  --presentation-mode expressive

ドラフトキュー生成後、アクティブなBロール操作とそのバウンド計画を読み取り専用で検査します。操作がアクティブで、そのステータスが approved または verified であり、review.status が approved であり、話者インセット分析/エージェント入力/プレビュー/クリアランスのバインディングが完了しており、少なくとも1つの検証済みまたは正規化されたショットが維持されているコンポジットレイアウトを持つ場合にのみ、コンポジット対応の配置を有効にします。空間ビルダーは、話者のジオメトリに対して明示的なサブショット display_mode: enabled を使用します。pure_broll と話者エビデンスがない場合は、話者矩形を決して暗示しません。

該当する場合、Expressive layout_beats または hero_line を埋める前に、ドラフトキューをすべてのBロール視覚境界に合わせます。アライメントは単語の隙間でのみ分割し、アトミックに書き戻します。単語内の境界は単語を完全に保持し、必須のレビューエビデンスを記録します:

python "$SkillRoot\scripts\caption_spatial_context.py" align `
  --project-root $ProjectRoot --plan $Plan --out-plan $Plan

該当するプロジェクトの場合、以降のすべてのゲートで使用されるオプションの引数を準備します:

$SpatialArgs = @("--spatial-context", $SpatialContext)
$SpatialReviewArgs = @("--spatial-context", $SpatialContext, "--project-root", $ProjectRoot)

該当するコンポジットがない場合、4つの空間コマンドすべてをスキップし、$SpatialArgs と $SpatialReviewArgs を空のままにします。空のコンテキストを作成したりアタッチしたりしないでください。

スタイル選択またはプレビューの生成を開始する前に、AgentはExpressiveプログラム全体を1回のパスで計画する必要があります:

1. トランスクリプト、利用可能な理解アーティファクト、正規のタイムライン、生成された字幕キュー、およびレイアウト変更を正当化するために必要な実際のソースフレームエビデンスを読む。
2. すべての presentation.layout_beats を埋め、例外的な単語 semantic_role 値に注釈を付け、正当な場合にキューの連続する hero_line を level: hero で最大1つ追加し、ビート/ヒーローラインごとに1つの根拠を書き、全体的な presentation.planner.rationale を書く。
3. すべてのキューが正確に1回カバーされた後にのみ presentation.planning_status を complete に設定する。
4. プレビュー生成の前に完了した計画を検証する:

python "$SkillRoot\scripts\build_captions.py" --validate-plan $Plan

該当するコンポジットの場合、最終的なキューIDとExpressive候補が完了した後にのみ、コンテキストを構築、検証、およびアタッチします。これにより、上流のレイアウトが保存され、その現在のリビジョンとハッシュが字幕計画にバインドされます:

python "$SkillRoot\scripts\caption_spatial_context.py" build `
  --project-root $ProjectRoot --plan $Plan --out $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" validate `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

python "$SkillRoot\scripts\caption_spatial_context.py" attach `
  --project-root $ProjectRoot --plan $Plan --context $SpatialContext

ユーザーにキューごとの位置選択を求めないでください。ユーザーは既存のHTMLエビデンスをレビューし、少数の異常なビートのみを修正します。計画後のインタラクションを開始することで、既存の字幕計画ハッシュバインディングが権威あるものとして維持されます。

1つの決定モードを開始します。ヒューマンモードの場合、ユーザーにファイルを探すよう求めずに、維持されているオフラインギャラリーをプロジェクトレビューディレクトリに公開します:

$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
  --state $Receipt --source $Sou