video-add-captions

動画にキャプションを追加

依存関係

/video-understand が前提条件です。まずこれを実行し、検証済みの単語単位の文字起こしと正規タイムラインを使ってキャプションを作成してください。 開始前に、インストールされていることを確認してください。インストールされていない場合は、この前提条件が不足していることをユーザーに警告し、メディアの処理を開始せずに終了してください。

ffmpeg／ffprobe が PATH 上にあること、Pillow を含む Python、および 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 (only for eligible B-roll composites)
`-- 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、判断レシート、レビュー用証拠は永続的なデータです。

Caption Plan

work/captions/captions-plan.json は正規のキャプションプランです。overlay を対象とし、番組時間を使用します。次の情報を記録します。

• timeline_id、program_duration_s、およびソーストランスクリプトのパス。
• キューのグループ化設定。
• 承認済みのスタイル、決定モード、根拠、ギャラリーの選択、および解決済みスタイルの完全な定義。
• ソースに基づくレビュー証拠と承認者。
• 互換性フィールド start、end、text、lines、words を含むキュー。
• すべてのキューの program_range と source_ranges。
• すべてのマッピング済み単語の番組／ソース範囲と clip_id。
• 正確な有理数 FPS とハッシュ付きランタイムアセットを含むローカルレンダラーのレシピ。

ジェネレーターは、旧形式のトップレベルキュー配列も受け付けます。これは単独の互換性アダプターにすぎず、タイムラインの出所情報を表現したり、承認済みのプロトコルへの寄稿を再生成したりすることはできません。

標準はデフォルトの表示モードです。標準プランに presentation フィールドは不要であり、追加だけを目的として移行してはなりません。表現的は明示的に指定する表示モードであり、プリセットではありません。--presentation-mode expressive で指定してください。ビルド手順では、安定したキュー ID、デフォルトの単語 semantic_role 値、下書き用の presentation プランニングシェルが追加されますが、レイアウトバリアントは推測されません。

表現的でサポートされるのは bottom-standard と center-emphasis のみです。シェルに記入する前に reference/caption-rules.md をお読みください。既存のレンダラーが使用するのは、完成済みの presentation.layout_beats のみです。ビート内の位置を推測したり、レイアウトを変更したりすることはありません。

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

アクティブでレビュー承認済みの B-roll 操作に、承認済みまたは検証済みの話者インセット合成が含まれる場合、キャプションは凍結済みの上流プラン、証拠、正規化された合成、および明示的なサブショット display_mode から caption-spatial-context.json を導出できます。これによって B-roll のレイアウトが変更されたり、再選択されたりすることはありません。表現的プランニングの前にキュー境界を調整し、維持対象の preset-bottom、frame-center、panel-center、および境界限定の panel-bottom の配置のみを解決します。panel-bottom は、下部中央に焦点を当てたパネルに隣接する unsplittable_word_boundary に限り使用できます。この場合、安定したキューを、構造化された話者矩形の下に確保された帯の中で中央揃えします。このようなキューは、単語の中点を含むコンテキストだけでなく、交差するすべての視覚的コンテキストに対して検証されます。このコンテキストがない場合、既存の標準および表現的の配置動作はすべて変わりません。

スタイル

メンテナンスされているプリセットは clean、minimal、social-bold、pill、boxed、stroked、shorts です。ギャラリーの組み合わせ ID では、pill-yellow、stroked-blue、shorts-green など、メンテナンスされているテーマを指定できます。Karaoke はオプションであり、独立したプリセットではありません。

デフォルトの委任時の選択は clean、Karaoke はオフです。より表現豊かなプリセットは、用途や映像に適している場合にのみ選んでください。ジョブ固有の変更は overrides JSON に保存し、通常のスタイルに関するフィードバックのためにジェネレーターを編集しないでください。

Expressive は semantic-only（Karaoke オフ）と semantic-plus-karaoke（Karaoke オン）の両方に対応しています。どちらの設定でも、意味的な強調はキュー全体にわたって維持されます。共存モードでは、意味的な強調とアクティブな Karaoke 単語の前景色として、すべてのハイライトモードで style.wordHighlight.activeColor が使用されます。背景のハイライトは追加効果として残ります。有効なスケールは max(semantic scale, karaoke active scale) であり、両者の積ではありません。Expressive では、互換性のある contrast の意味的ロールを含め、下線は描画されません。

既存のレビュー契約では、引き続き semantic-only を Expressive の主要な根拠として使用し、semantic-plus-karaoke を個別に紐付けます。互換性のため、ペイロードのフィールド名は引き続き 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 を使用します。

Human モードでは agent コマンドが失敗し、agent モードでは human コマンドが失敗します。空間コンテキストなしの Standard では、メンテナンスされているソースに裏付けられた 4 枚の画像が必要です。Expressive とコンポジット対応のレビューでは、それぞれの動的な根拠要件が適用されます。ソース、プラン、タイムライン、スタイル、オーバーライド、プロジェクトメタデータ、レビューページ、または根拠に変更があると、承認は無効になります。空間コンテキスト、上流の B-roll の改訂、または紐付けられたコンポジットの変更も同様です。影響を受ける成果物を再構築し、再度レビューしてください。

標準ワークフロー

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

$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 の識別子は翻訳せず、質問はユーザーが現在使用している会話の言語で表示します。このファイル内の以下の英語のソースプロンプトはそのまま残し、現在のセッションでローカライズした選択肢を提示してから、提示して停止します。

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 は空のままにします。空のコンテキストを作成したり、 アタッチしたりしないでください。

スタイルの選択やプレビューの生成を始める前に、エージェントは Expressive プログラム全体を 一度に計画する必要があります。

1. トランスクリプト、利用可能な理解アーティファクト、正規タイムライン、 生成済みキャプションキュー、およびレイアウト変更を正当化するために必要な実際のソースフレームの エビデンスを読みます。
2. すべての presentation.layout_beats を埋め、例外的な単語に semantic_role の値を付記し、妥当な場合は正規の level: hero を持つ 連続した hero_line をキューに最大 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 $SourceVideo --captions $Plan `
  --review-dir $Review --no-open true @SpatialArgs
$StartOutput | Write-Host

start は、正規の captions-style-review-<UUID>.html プロジェクトページのパスと、固定の質問を 出力します。captions-style-review.html は、正規ではない最新の簡易エイリアスにすぎません。 エージェントは Caption style review: の後に出力された UUID パスを取得し、その完全一致パスを $StyleReviewPage に割り当て、ホスト OS のネイティブコマンドで開く必要があります。

Windows PowerShell：

$StyleReviewPage = "<authoritative UUID page path printed after Caption style review:>"
Start-Process -FilePath (Resolve-Path $StyleReviewPage)

macOS：

open "$StyleReviewPage"

Linux：

xdg-open "$StyleReviewPage"

開けない場合は、コマンドまたはパスを診断して再試行します。ユーザーにページを探させないでください。 開いたギャラリーと固定の質問を、出力されたとおりに提示してから、提示して停止します。 人間がページから構造化された要約をコピーするまでは続行しないでください。形式は次のとおりです。

Caption style review
Review: <UUID from the opened page>
Decision: select
Choice: pill-yellow

ユーザーの要約を変更せず、そのまま select --response に渡します。PowerShell では、 単一引用符のヒア文字列を使うと各行を安全に保持できます。

$StyleResponse = @'
Caption style review
Review: <UUID from the opened page>
Decision: select
Choice: pill-yellow
'@
node "$SkillRoot\scripts\caption_interaction.mjs" select `
  --state $Receipt --response $StyleResponse

上のブロックは形式を示しています。ユーザーが返したブロックを使い、レビュー UUID と選択肢も含めてください。 人間の応答を推測、正規化、または模擬してはいけません。

明示的に委任する場合は、別個のエージェントモードのレシートを作成します。バインドされたギャラリーは維持し、 スクリプトによる Windows 専用の自動起動を抑止します。上記の対応するネイティブコマンドで正規の UUID ページを開き、 選択する前に内容を確認します。

$StartOutput = node "$SkillRoot\scripts\caption_interaction.mjs" start `
  --state $Receipt --source $SourceVideo --captions $Plan `
  --review-dir $Review `
  --decision-mode agent `
  --delegation-note "User delegated caption style and preview approval." `
  --no-open true @SpatialArgs
$StartOutput | Write-Host

node "$SkillRoot\scripts\caption_interaction.mjs" agent-select `
  --state $Receipt --choice clean `
  --rationale "Conservative readable treatment preserves the talking-head frame."

バインドされたギャラリーを確認してから agent-select を使用し、実際の根拠を記録してください。人間の要約を捏造したり、Agent モードで select を使用したりしないでください。

透明なプレビュー構成を生成します。プロジェクトにはローカルの GSAP ファイルとフォントファイルのみが含まれ、project-meta.json では有理数の FPS が保持されます。

node "$SkillRoot\scripts\generate_caption_project.mjs" `
  --video $SourceVideo --captions $Plan --out $PreviewProject `
  --interaction-state $Receipt --project-root $ProjectRoot --mode preview @SpatialArgs

npx.cmd hyperframes check $PreviewProject --at 1 --timeout 10000 --no-contrast

Expressive の主レビューでは、--karaoke false を追加します。同じソース、プラン、インタラクション選択、タイミングから、出力ディレクトリのみを変更し、--karaoke true を追加して、サポートされている共存比較を生成します。

node "$SkillRoot\scripts\generate_caption_project.mjs" `
  --video $SourceVideo --captions $Plan --out $ComparisonProject `
  --interaction-state $Receipt --project-root $ProjectRoot `
  --karaoke true --mode preview @SpatialArgs

Standard では、対応付けられた序盤・中盤・終盤・キャプションなしのエビデンスを作成します。このコマンドは透明な HyperFrames スナップショットを取得し、timeline.json を使って各プログラム時刻を対応付け、元ソースの一致するフレームを抽出して、Pillow で合成します。

python "$SkillRoot\scripts\build_caption_review.py" `
  --source $SourceVideo --timeline "$Work\timeline.json" --plan $Plan `
  --project $PreviewProject --cache "$Cache\review-cache" --out $Review `
  --interaction-state $Receipt @SpatialReviewArgs

Expressive では、同じビルダーが網羅的な機械サンプル、人間レビュー用のコンパクトなインデックス、および別途バインドされたセマンティクスのみ／Karaoke 比較を出力します。

python "$SkillRoot\scripts\build_caption_review.py" `
  --source $SourceVideo --timeline "$Work\timeline.json" --plan $Plan `
  --project $PreviewProject --comparison-project $ComparisonProject `
  --cache "$Cache\review-cache" --out $Review --interaction-state $Receipt `
  @SpatialReviewArgs

ビルダーは、唯一の正式なページとして captions-review.html を書き出します。空間コンテキストのない Standard には、管理対象のエビデンスラベルがちょうど4つ含まれます。Expressive または合成対応レビューでは、captions-evidence.json.samples にすべての高密度な機械エビデンスを保持し、review_samples には実際に存在する各カテゴリの代表サンプルを最大1つ含めます。カテゴリは bottom-standard、center-emphasis、preset-bottom、frame-center、panel-center、Hero 1.5x です。1つの PNG に複数のカテゴリラベルを付ける場合があります。存在しないカテゴリを捏造してはいけません。no-caption は機械エビデンスとして保持し、Karaoke 比較は代表サンプル数に含めず、別のままにします。Agent は、ホスト OS に対応するネイティブコマンドでそのページを開く必要があります。たとえば、$EvidenceReviewPage = "$Review\captions-review.html" を設定して、次のいずれかを実行します。

Start-Process -FilePath (Resolve-Path $EvidenceReviewPage)

open "$EvidenceReviewPage"

xdg-open "$EvidenceReviewPage"

開けない場合は原因を診断して、再試行してください。すべての代表的なメイン画像について、読みやすさ、安全領域への配置、切り抜き、単語の折り返し、ビート配置の安定性、不要なピクセルの有無を確認してください。このゲートに進む前に、no-caption を含むすべての高密度サンプルについて機械検証に合格している必要があります。空間コンテキストのない Standard では、管理対象の4枚の画像をバインドします。

$Evidence = @(
  "$Review\preview-early.png",
  "$Review\preview-middle.png",
  "$Review\preview-late.png",
  "$Review\preview-no-caption.png"
) -join ","

node "$SkillRoot\scripts\caption_interaction.mjs" preview-ready `
  --state $Receipt --project-meta "$PreviewProject\project-meta.json" `
  --evidence $Evidence --review-page "$Review\captions-review.html" `
  --timeline "$Work\timeline.json"

空間コンテキストがある場合は、管理対象の Standard サンプルをそのまま保持し、合成背景を含む配置ビートに限って、開始時点・25%・50%・75%・終了時点の高密度エビデンスを追加します。A-roll の配置ビートには高密度エビデンスを追加しないでください。

Standard に空間コンテキストがない場合に限り、この固定の4画像コマンドを使用してください。空間コンテキストがバインドされた Standard では、代表的な PNG のみをバインドし、完全な機械エビデンス文書は別途バインドしてください。Standard には共存比較がないため、--comparison-evidence は渡さないでください。

$StandardSpatialEvidenceDocument = Get-Content "$Review\captions-evidence.json" -Raw | ConvertFrom-Json
$Evidence = @($StandardSpatialEvidenceDocument.review_samples | ForEach-Object {
  Join-Path $Review $_.preview
}) -join ","

node "$SkillRoot\scripts\caption_interaction.mjs" preview-ready `
  --state $Receipt --project-meta "$PreviewProject\project-meta.json" `
  --evidence $Evidence --evidence-document "$Review\captions-evidence.json" `
  --review-page "$Review\captions-review.html" `
  --timeline "$Work\timeline.json"

Expressive では、代表的な PNG、完全な機械文書、および captions-evidence.json からの別個の共存ペアをバインドします。

$EvidenceDocument = Get-Content "$Review\captions-evidence.json" -Raw | ConvertFrom-Json
$Evidence = @($EvidenceDocument.review_samples | ForEach-Object {
  Join-Path $Review $_.preview
}) -join ","
$ComparisonEvidence = @($EvidenceDocument.experimental_comparison.samples | ForEach-Object {
  Join-Path $Review $_.preview
}) -join ","

node "$SkillRoot\scripts\caption_interaction.mjs" preview-ready `
  --state $Receipt --project-meta "$PreviewProject\project-meta.json" `
  --evidence $Evidence --evidence-document "$Review\captions-evidence.json" `
  --comparison-evidence $ComparisonEvidence `
  --review-page "$Review\captions-review.html" --timeline "$Work\timeline.json"

人間モードでは、開いたページとその画像を提示してから、提示して停止してください。人間は、ページから次の構造化要約のいずれかをコピーします。

Caption preview review
Review: <UUID from the opened page>
Decision: approve
Evidence: early, middle, late, no-caption

Expressive の承認では、動的なエビデンストークンを使用し、バインドされた比較エビデンスを確認した後に選択した Karaoke の明示的な選択が必要です。

Caption preview review
Review: <UUID from the opened page>
Decision: approve
Evidence: expressive-layout-beats
Karaoke: on|off

caption-spatial-context.json がバインドされている場合、正式なページは合成対応トークンを出力します。Standard では Karaoke の行を含めずに同じブロックを使用します。Expressive では Karaoke の明示的な選択が必要です。

Caption preview review
Review: <UUID from the opened page>
Decision: approve
Evidence: composite-aware
Karaoke: on|off

Caption preview review
Review: <UUID from the opened page>
Decision: revise
Changes: Raise captions 20 pixels.

返された要約は変更せずに confirm --response または adjust --response に渡してください。PowerShell では複数行の応答を安全に引用します。

$PreviewResponse = @'
Caption preview review
Review: <UUID from the opened page>
Decision: approve
Evidence: early, middle, late, no-caption
'@
node "$SkillRoot\scripts\caption_interaction.mjs" confirm `
  --state $Receipt --response $PreviewResponse

revise 要約の場合は、同じ方法で $PreviewResponse に保存して、次を実行します。

node "$SkillRoot\scripts\caption_interaction.mjs" adjust `
  --state $Receipt --response $PreviewResponse

要求された変更を適用し、プレビュー用プロジェクト、レビューページ、すべてのエビデンスを再生成してから、ゲートを再度提示してください。人間のフィードバックを Agent の判断に変換してはいけません。 委任モードでは、エージェントは自身の判断理由を記録する前に、同じ captions-review.html ページ、すべての主要なエビデンス、および共存比較があればその内容を確認する必要があります。 Standard では、既存のコマンドを変更せずに使用します。

node "$SkillRoot\scripts\caption_interaction.mjs" agent-confirm `
  --state $Receipt `
  --rationale "All bound primary frames are readable and collision-free; coexistence comparison evidence was inspected separately when present."

Expressive では、比較に基づいて選択した Karaoke を明示的に渡します。

node "$SkillRoot\scripts\caption_interaction.mjs" agent-confirm `
  --state $Receipt --karaoke off `
  --rationale "The semantic-only comparison is clearer for this footage."

承認済みのオーバーレイプロジェクトを生成します。この正式なレンダリングだけが、正規プラン内の style、review、およびハッシュ化されたランタイムアセットを確定します。 Expressive のオーバーレイ生成では、プレビューで承認された Karaoke の選択を使用します。明示的な --karaoke の値は、その承認内容と一致している必要があります。

Expressive では、正式なオーバーレイ生成時に、Human が確認できる代表 PNG が review.representative_evidence に保存されます。review.evidence は共有配信コンパイラーとの互換性を保つセットとして維持され、captions-evidence.json から選択された、各レイアウトビートにつきバインド済みの機械サンプル 1 件と no-caption で構成されます。これによって人間によるレビューにカードが追加されることはなく、ユーザーが機械専用サンプルを確認したと主張することもありません。完全なドキュメントのパス、ハッシュ、サンプル数は、引き続き review.machine_evidence_document に記録されます。

node "$SkillRoot\scripts\generate_caption_project.mjs" `
  --video $SourceVideo --captions $Plan --out $OverlayProject `
  --interaction-state $Receipt --project-root $ProjectRoot --mode overlay @SpatialArgs

npx.cmd hyperframes check $OverlayProject --at 1 --timeout 10000 --no-contrast

$RenderMeta = Get-Content -Raw "$OverlayProject\project-meta.json" | ConvertFrom-Json
$RenderFps = "$($RenderMeta.fpsRational.num)/$($RenderMeta.fpsRational.den)"
Push-Location $OverlayProject
try {
  npx.cmd hyperframes render --format png-sequence --fps $RenderFps --output $OverlayFrames
}
finally {
  Pop-Location
}

正規のオーバーレイ生成では、選択されたスタイル、判断者／判断理由、ハッシュのバインド結果を含むように、captions-summary.md の ## Approval セクションが更新されます。レンダリング済みフレームと共有配信のチェックは保留のままにします。操作を検証済みとしてマークする前に、保留中の行を測定結果に置き換えてください。

キャッシュを削除した後、承認を再実行せずにコンポジションを再構築します。

node "$SkillRoot\scripts\generate_caption_project.mjs" `
  --video $SourceVideo --captions $Plan --out $OverlayProject `
  --approved-plan true --project-root $ProjectRoot --mode overlay @SpatialArgs

このコマンドは、凍結されたランタイムハッシュが引き続き一致することを検証します。

プロジェクト登録

work/project.json に captions 操作を 1 つ追加するか、既存のものを更新します。understanding に依存させます。また、アクティブな cut 操作が存在する場合は、それにも依存させます。 アクティブな B-roll によって空間コンテキストが提供された場合は、depends_on に b-roll も追加します。その based_on の値は、バインドされたアクティブな B-roll リビジョンと一致している必要があります。 空間コンテキストがない場合は、depends_on と based_on から b-roll を省略します。すべての based_on 値は、現在の依存関係のリビジョンと一致している必要があります。

{
  "id": "captions",
  "skill": "video-add-captions",
  "revision": 1,
  "depends_on": ["understanding", "cut", "b-roll"],
  "based_on": {"understanding": 1, "cut": 1, "b-roll": 4},
  "status": "verified",
  "plan": "captions/captions-plan.json",
  "outputs": ["cache/captions/overlay-frames"],
  "target": {"sequence": "main", "scope": "captions"},
  "effects": {
    "changes_timeline": false,
    "changes_geometry": false,
    "changes_video_pixels": false,
    "changes_audio": false,
    "adds_track": "captions"
  },
  "check": {"status": "pass", "report": "../review/05-captions/captions-summary.md"},
  "render": {
    "kind": "overlay",
    "asset": "cache/captions/overlay-frames",
    "asset_type": "image-sequence",
    "pattern": "frame_%06d.png",
    "start_number": 1,
    "fps": {"num": 30000, "den": 1001}
  }
}

実際のタイムライン FPS を使用します。アクティブな content-cards および motion-graphics 操作より前に captions を挿入します。キャプションがこれらの下流操作に依存することはありません。すでにキャプションを含むプロジェクトに追加する場合は、アクティブなシーケンスの順序を変更する必要があります。その後、配信を 1 回コンパイルしてレンダリングします。

python "$RepoRoot\skills\video-understand\scripts\validate.py" project `
  "$Work\project.json" $ProjectRoot
python "$RepoRoot\skills\video-understand\scripts\build_render_plan.py" $ProjectRoot
python "$RepoRoot\skills\video-understand\scripts\render_project.py" `
  "$Work\render\render-plan.json"

共有レンダラーは、音声フィルターがなく、タイムラインが恒等変換の場合に限り、音声をコピーします。カットやリタイミングには、エンコード済み／フィルター適用済みの音声が必要です。キャプションのコードがこの判断を上書きすることはありません。

互換性

--timeline を指定しない場合も、build_captions.py は引き続き従来のキュー配列を書き込みます。 generate_caption_project.mjs は、その配列をインタラクションレシートとともに受け付けます。 単独での正確な ID 応答とスキップ応答は、レガシー互換性のためだけに残されています。 単独の approve も、レガシー互換の応答です。 過去の非英語エイリアスは入力互換性のために引き続き受け付けますが、ユーザー向けの指示として出力または記載されることはありません。 composite_caption_overlay.ps1 は、オーバーレイ動画または frame_%06d.png ディレクトリを受け付け、ソース音声をコピーしながら、互換性のある H.264/yuv420p を書き込みます。アクティブな操作で時間が変更されない場合に限り、この単独実行パスを使用してください。正規のプロジェクトでは共有レンダラーを使用します。

セルフチェック

操作が検証済みだと宣言する前に、次を実行してください。

python "$SkillRoot\scripts\check_project_protocol.py"
node "$SkillRoot\scripts\check_caption_style_config.mjs"
python "$SkillRoot\scripts\check_caption_spatial_context.py"
python "$SkillRoot\scripts\check_caption_review.py"
node "$SkillRoot\scripts\check_caption_interaction.mjs"
powershell.exe -ExecutionPolicy Bypass -File "$SkillRoot\scripts\check_structure.ps1"
node "$SkillRoot\scripts\caption_interaction.mjs" status --state $Receipt

また、次の点も検証してください。

• キューと単語の時間が有限で、順序どおりで、プログラムの長さの範囲内にあり、クリップをまたいでいないこと。
• 冒頭・中盤・終盤の字幕が、マッピングされた正しいソースピクセルに表示されていること。
• 削除された音声にキューがないこと。
• オーバーレイの最初のフレームが存在し、寸法が一致し、FPSがタイムラインの有理数FPSと等しく、フレーム数が ceil(program_duration_s * fps.num / fps.den) に等しく、長さがプログラム全体をカバーし、字幕以外のピクセルが透明であること。
• 共有納品物が存在し、音声が同期され、プロジェクトの納品レポートに合格していること。
• captions-summary.md に、選択したスタイル、承認モードとその根拠、証拠、検証結果が記録されていること。

HTMLの生成だけでは成功とはいえません。完了を報告する前に、実際のピクセルと最終納品物を確認してください。