video-add-content-cards

動画用コンテンツカードの追加

承認済みのセマンティックな場面を、ひとまとまりの HyperFrames グラフィックオーバーレイに仕上げます。共有済みのエビデンスと正規タイムラインを使用してください。このスキル内でソースを再文字起こししたり、再分析したりしないでください。

依存関係

/video-understand は前提条件です。先に実行し、カードで検証済みの セマンティックエビデンスと正規タイムラインを使用できるようにしてください。 開始前に、インストールされていることを確認してください。インストールされていない場合は、 前提条件が不足していることをユーザーに警告し、メディアの処理を開始せずに終了してください。

ffmpeg が PATH にあること、Python、および Node.js >= 22（npx hyperframes の実行時に取得）を必要とします。hyperframes render／snapshot はヘッドレス Chrome を起動します。Chrome は専用の chrome-headless-shell を管理し、キャッシュされたものを使用できない場合はシステムの Chrome にフォールバックします（上書きするには CHROME を設定します）。メディアを処理する前に、これらを確認してください。

入力

• work/project.json：操作のリビジョンと依存関係
• work/understand/understanding.json：レビュー済みのセマンティックな場面とエビデンス
• work/timeline.json：ソースからプログラムへのマッピング、またはカットがない場合の恒等タイムライン
• コントラストやパレットをルックに照らして評価する場合は、選択したカラーグレーディングのリビジョン（任意）

カットやカラーグレーディングがなくても、このスキルは有効です。字幕が有効な場合は先に実行し、その現在のリビジョンに依存させて、字幕の占有領域を厳格な除外ゾーンとして扱ってください。両方が有効な場合、コンテンツカードはモーショングラフィックスより前に配置する必要があります。これらの相対ルールは、選択したペアすべてに適用されます。実際に使用した依存関係のみを宣言し、その現在のリビジョンを based_on に記録してください。

主要人物、前景の人物、話者、プレゼンター、インタビュー対象者、または意味的に重要な人物について、見える顔と頭部のシルエットを、カードの表示時間全体を通じた厳格な除外ゾーンとして扱ってください。これには表示時と消失時も含まれます。物語上または視覚上の焦点ではない、背景にのみ映る偶発的な人物は対象外です。判断がつかない場合は保護してください。カードが保護対象の顔や頭部と重なる場合は、まず位置を変更し、それからサイズ変更またはデザイン変更を行ってください。要件に適合する配置がない場合は、そのカードをスキップしてください。

作業ファイル

work/content-cards/cards-plan.json          # durable editorial plan
work/cache/content-cards/index.html         # code-is-the-edit composition
work/cache/content-cards-overlay.mov        # transparent render contribution
review/03-content-cards/card-stills/        # one useful still per card
review/03-content-cards/content-cards-preview.mp4  # optional short cue windows
review/03-content-cards/content-cards-summary.md
review/03-content-cards/content-cards-review.html  # local candidate review board
review/03-content-cards/content-cards-review-assets/  # one source frame per candidate
review/03-content-cards/content-cards-review.json  # validated human choices

再利用可能なレビュー用ページは skills/video-add-content-cards/assets/content-cards-review.html にコミットされています。 内容を入力した HTML、スクリーンショット、オーバーレイ、プレビューのレンダー結果は再生成できます。 プランは cache/ の外に保持してください。work/cache/ を削除した後でも、破棄可能な HTML とアルファアセットを再生成できるよう、すべての表示テキスト、タイミング、配置、ビジュアル処理の値、レンダラーのコンポジションパス、レンダラーのアセットパス、ソース FPS をプランに含める必要があります。プランレベルの renderer_recipe を1つ記録し、ソース例／テンプレート、コンポジションの出力パス、レンダリングエンジン、およびすべてのローカルランタイムアセットについて、出力パス、正確なバージョン、取得元、SHA-256 を含めてください。キャッシュされた HTML ファイルやダウンロードしたスクリプトだけでは、永続的なレシピがない限り、再生成の要件を満たしません。

ワークフロー

1. 下書きの前にインタビューする

まず understanding.json と有効なタイムラインを読み込みます。インタビューの前に、対象となるグラフィックの場面数を数え、推奨するカード数を計算します。

min(eligible moments, max(1, round(program minutes / 0.75)))

これは目標であり、自動的に切り詰めるルールではありません。質問する前に、現在の OS に対応するネイティブコマンドを使って、実際のアニメーション例を自分で開いてください。次のうち、必ず 1 つだけ実行します。

# Windows PowerShell
Start-Process (Resolve-Path 'skills/video-add-content-cards/examples/gallery-animated.html')

# macOS
open skills/video-add-content-cards/examples/gallery-animated.html

# Linux desktop
xdg-open skills/video-add-content-cards/examples/gallery-animated.html

コマンドが失敗した場合は、原因を調べて再試行してください。この操作を URI に置き換えたり、ユーザーにファイルを探してクリックするよう求めたりしないでください。ギャラリーでは 6 種類すべてのテーマを比較でき、ネイティブのピッカーで 1 つの列に焦点を合わせられます。

テーマ	先頭の文字
almanac	温かみのあるクリーム色、セリフ体、落ち着いた印象
teal	ダークな放送向け、シアンのアクセント
editorial	ドキュメンタリー風、インクとアンバー
dotgrid	ピクセルモノ、テクニカル
apex	エネルギッシュなスポーツ向け、赤のアクセント
air	透明感のある Lexend タイポグラフィ、背景プレートやスクリーンなし

次の順序で、一度に 1 つだけ質問してください。

1. この編集ではどのテーマを使いますか？
2. この編集のカード数の目標はいくつですか？計算した推奨数をデフォルトとして提示します。
3. 必ず含めるカードタイプはどれですか？intro、key-quote、stat、list、outro を提示し、デフォルトでは何も選択しません。

各質問の後は提示して停止します。3 つ目の回答を受けた後、テーマ、目標カード数、必須タイプ、ユーザーから提供されたメモを要約して、確認を求めます。ユーザーがキャンセルした場合は、分析内容を保持し、操作を draft のままにして、カードの作成やレンダリングは行いません。

2. 共通の理解に基づいてカードを下書きする

python skills/video-add-content-cards/scripts/build_cards_plan.py `
  work/understand/understanding.json `
  work/timeline.json `
  work/content-cards/cards-plan.json `
  --target-card-count 6 `
  --theme editorial `
  --must-include-type stat `
  --notes "Keep product names verbatim"

このスクリプトは、保持された意味上の場面をプログラム上の時間に対応付け、カットで削除された場面を省きます。ソース範囲と根拠への参照を保持し、長さを該当クリップの範囲内に収め、コピー、配置、ビジュアル処理を draft として記録します。stat は metric-spotlight から、list は side-by-side から開始します。候補のレビューでは通常のレイアウトを保持することも、リストを parallel-columns に切り替えることもできます。 確認済みのインタビュー内容は、cards-plan.json に brief として保存されます。複数の値を指定する場合は --must-include-type を繰り返します。該当しないフラグは省略してください。以前の任意の brief フィールドも互換性のために引き続き受け付けますが、通常のインタビューでは使用しません。

3. 編集上の判断を行う

各カードの時間位置にある証拠を確認します。ASRの人名や数字を修正し、根拠の弱い候補を除外して、簡潔なコピーを作成します。保護対象の顔、画面に見える頭部のシルエット、字幕に重ならない配置を選び、ビジュアルの処理を承認します。アナライザーのテキストを最終的なコピーとして扱わないでください。

画面に表示するコピーは、要約やタイトル案だけでなく、すべて copy.display（例：eyebrow、title、detail）に保存します。上記の保護対象となる顔と頭部の定義に照らして合成済み静止画を確認した後に限り、placement.face_clearance を verified に設定し、その静止画のプロトコル相対パスを placement.review_still に保存します。HyperFrames のコンポジション、アルファアセット、正確な有理数 FPS は renderer に保存します。

以下の対応関係を出発点として使用します。

意味上の種類	カードタイプ
hook	intro
key-point、quote、question	key-quote
stat	stat
list	list
cta	outro

repetition、tangent、risk は編集上の判断材料であり、自動的にカード化するものではありません。

5種類の標準カードタイプを維持してください。新しいトップレベルのカードタイプを作成するのではなく、以下の任意のレイアウトを visual_treatment.layout に保存します。

標準カードタイプ	使用可能なレイアウト
stat	default、metric-spotlight、bar-chart、pie-chart、line-chart
list	default、side-by-side、parallel-columns

証拠に裏付けられた数値、割合、金額、倍率、年、期間のうち、1つを強調する価値がある場合に限り、metric-spotlight を使用します。数値を簡潔な上部と下部の文脈の間に配置し、長い値が重ならないように収め、数値が両方のラベルの間で視覚的に中央に配置されるようにします。2～4個の短く、並列、対照的、相反的、または対応する概念には、side-by-side または parallel-columns を使用します。短いフレーズを優先し、映像に収まり、被写体を避けられる向きをレビューで選びます。

保持されたトランスクリプトに完全で証拠に裏付けられたデータセットが含まれている場合に限り、グラフを使用します。グラフデータを作成する前に reference/chart-data.md を確認してください。ディメンション、指標、単位、期間、順序付きのデータポイント、および各ポイントに対応するトランスクリプト上の証拠を、すべて data に手動で保存します。アナライザーの要約から値を推測したり、異なる動画のポイントを組み合わせたりしないでください。比較可能なカテゴリが2～6個の場合は bar-chart、互いに重複せず、全体を構成することが立証された要素が2～6個の場合は pie-chart、意味のある順序を持つポイントが3～8個の場合は line-chart を使用します。必要な値、ラベル、分母、時間順序、または単位が欠けている場合は、metric-spotlight、通常の stat カード、またはカードなしを選択します。グラフレイアウトでは、意味を変えずに長い説明を簡潔な補足コピーにまとめます。グラフでは、主に重要な値とその変化または関係を伝えてください。グラフですでに見える値、ラベル、期間、単位を列挙したり、言い換えて繰り返したりしないでください。

この段階では、証拠に裏付けられた候補をすべて残します。ブリーフで指定されたカード数を目指しますが、証拠に応じて、より有力な候補だけに絞ったり、カード数を少なくしたりしてかまいません。

4. 候補の選択を確認して適用する

候補プランの作成後、プロジェクト専用のブラウザレビューを生成します。プランの source_range に合わせたソース動画とアクティブなタイムラインを渡します。スクリプトは各エビデンスの中点を、そのエビデンスを含む保持クリップ内に収めてから、候補ごとに対応するソースフレームを1つずつ使用して、確定済みテンプレートにデータを入力します。

python skills/video-add-content-cards/scripts/build_review_page.py `
  work/content-cards/cards-plan.json `
  review/03-content-cards/content-cards-review.html `
  --video input/source.mp4 `
  --timeline work/timeline.json `
  --captions-plan work/captions/captions-plan.json

プロジェクトでアクティブなキャプション操作がない場合は、--captions-plan を省略してください。キャプションプランがアクティブな場合、レビューのフレームには、実際に占有されている上部、中央、または下部の領域が表示されます。

続けて、現在のOSのネイティブコマンドを使い、入力済みのレビューを自分でただちに開いてください。以下のいずれか一方だけを実行してください。

# Windows PowerShell
Start-Process (Resolve-Path 'review/03-content-cards/content-cards-review.html')

# macOS
open review/03-content-cards/content-cards-review.html

# Linux desktop
xdg-open review/03-content-cards/content-cards-review.html

コマンドが失敗した場合は原因を調べて再試行してください。ユーザーにファイルの場所を探すよう求めてはいけません。このページには、各ソースフレーム、カードID、番組内の時刻、編集可能な文言、ビジュアル処理、配置が表示されます。チャートレイアウトには、編集可能な構造化データとポイントのエビデンス参照も表示されます。承認する前に、表示されたエビデンスとすべての値を照合してください。 すべての候補は、未選択かつ配置が bottom の状態で始まります。配置を変更すると、実際のフレーム上にグレーのカードプロキシが移動し、承認前に重なりのリスクを確認できます。ユーザーはカードを選択し、文言を編集して、ビジュアル処理と配置を選び、Copy summary をクリックして、表示されたサマリーを会話に貼り付けます。

提示して停止します。 貼り付けられた選択サマリーを待ちます。未確認のドラフト候補からHTMLを作成してはいけません。サマリーを review/03-content-cards/content-cards-review.json に変換します。プラン内のすべてのカードについてエントリーを1つずつ作成し、サマリーに含まれるIDは、選択済みとして、選択された文言、ビジュアル処理、配置を記録します。それ以外のIDは、未選択として、現在のドラフト文言と空の配置を記録します。レビューでの選択は、visual_treatment という名前の文字列フィールドに保存します。その後、検証済みのレビューを適用します。

python skills/video-add-content-cards/scripts/apply_cards_review.py `
  work/content-cards/cards-plan.json `
  review/03-content-cards/content-cards-review.json

適用処理は、未知、重複、または不足しているカードID、空の選択済み文言、無効な配置、正規のカードタイプと互換性のないビジュアル処理を検出すると、プランを変更せずに処理を拒否します。成功すると、選択済みカードを保持し、その文言、配置、ビジュアル処理、およびトップレベルのレビューを approved にします。次に進む前に、選択された数がブリーフの目標値と一致するか確認してください。

選択されたチャートレイアウトについては、適用処理で構造化データ全体も検証し、data.status を approved にします。選択されたチャートが1つでも無効な場合、プランをコピーする前にレビュー全体を拒否します。チャート以外のレイアウトを選ぶと、未使用のドラフトチャートデータは削除されます。適用後も、実際に合成されたフレームに照らしてコンポジションを確認するまでは、顔とキャプションのクリアランスは未確定のままです。

5. 1 つの HyperFrames コンポジションを作成する

index.html を 1 つ用意し、一時停止した GSAP タイムラインを使用します。承認済みの各カードは、プランの program_start_s と duration_s をキーにした 1 つの .clip にします。モーションはシーク可能な状態に保ち、壁時計タイマーではなくデータ属性からタイミングを決定します。

チャートのキューは、一時停止したタイムラインを通じて、コンポジションの絶対時間でのみアニメーションさせます。棒は 1 つのゼロ基準線から表示し、円グラフの扇形は値に比例した形状でデータ点の順に表示し、折れ線はデータ点が表示される前に X 軸の順で線を描画します。ソースに対する相対サイズと固定レイアウトボックスを使用し、シーク、ラベル、動的な値によってレイアウトが跳ねないようにします。推奨時間は棒グラフと円グラフで 5～6 秒、折れ線で 6～8 秒とし、必ずクリップの長さ以内に収めます。

最も近いリポジトリのサンプルを基にします。

• examples/index-almanac.html
• examples/index-apex.html
• examples/index-dotgrid.html
• examples/index-editorial.html
• examples/index-teal.html
• examples/index-air.html

すべてのカードでビジュアル表現を統一し、ソースに対する相対サイズを使用して、選択したカラーグレードに対して十分なコントラストを保ちます。不透明パネルを使用する 5 つのテーマでは、読みやすさを確保するためにカードまたはスクリーンを使用できます。air では、シーンとテキストのコンテナを透明に保ちます。不透明または半透明の背景矩形、ピル、局所的な色面、装飾的なカラーバー、フレーム全体を覆うスクリーンは使用しません。主要テキストには白、補助的な小さなテキストにはライトグレーを使用します。Lexend のウェイト、テキストシャドウ、細いアウトライン、余白、配置は使用できますが、装飾的な罫線、ドット、塗りつぶされた幾何学的アクセントは使用できません。話者やキャプションを覆わないでください。

ソースの FPS を明示的に渡し、24000/1001 のような小数のレートは 24 や 30 に丸めず、そのまま維持します。Windows では npx.cmd、プロジェクトローカルの npm キャッシュ、ローカルアセットを使用します。

$env:npm_config_cache = "$PWD/work/cache/npm"
npx.cmd hyperframes check

レンダリング時にリモートのフォント、画像、スクリプト、スタイルに依存しないでください。air では、assets/fonts/Lexend-VariableFont_wght.ttf をプロジェクトのコンポジションアセットにコピーし、他のランタイムアセットと同様に、出力パスと SHA-256 を renderer_recipe に記録します。

承認済みプランには、コンポジションで使用する正確なスタイル値とモーション値を保持します。edge-slide のような説明ラベルだけでは不十分です。最低限、パネルの形状とパディング、色、境界線、文字サイズ／ウェイト／行の高さ、表示／罫線／テキスト／終了の各アニメーションの時間、オフセット、スタッガー、イージングを記録します。これにより、使い捨てのキャッシュにだけ隠れた決定を残さず、プランからクリエイティブ HTML を再現できます。

6. 小さなアーティファクトをレビューする

各キューの中ほどのスチルを、該当タイムスタンプの実際のベース動画フレームにカードを合成して作成します。有効な場合は、承認済みのキャプションオーバーレイを先に合成してください。透明な部分だけの HyperFrames スクリーンショットで証明できるのはアルファのみであり、顔とのクリアランスは確認できないため、承認には不十分です。出入りや移動する要素が保護対象の顔や頭部に近づく場合は、合成した短いモーション区間も確認してください。フレーム内で保護対象領域と交差している場合は、承認前にカードを再配置します。デフォルトでは全体のプレビューをレンダリングしないでください。

確認項目：

• コピーが evidence_ref に忠実であること。
• ソース時刻とプログラム時刻が正しく対応していること。
• テキストが読みやすく、収まっていること。
• グラフのキューでは、主要な値とその変化が視覚メッセージの中心であり、補足コピーがプロットされたデータセットを言い換えていないこと。
• 承認済みのビジュアル処理が正規のカードタイプと一致していること。
• air に背景プレート、装飾的な罫線、塗りつぶされた幾何学的なアクセント、または全画面スクリーンがないこと。
• air では、主要テキストが白、補助テキストがライトグレーであること。
• キュー全体を通して、保護対象の顔、見えている頭部のシルエット、キャプションが見える状態であること。
• アニメーションが話されたフレーズに合っていること。
• カード領域以外が透明なアルファであること。

提示して停止。 カードのスチルと短いモーション区間を提示し、カード ID を示して、承認を待ちます。コピー、配置、タイミングに異議がある間は、オーバーレイ全体をレンダリングしないでください。

承認済みの各キューには、review/03-content-cards/card-stills/ 内の対応する合成スチル、face_clearance: "verified"、およびプラン内のスチルパスが必要です。レビュー結果を review/03-content-cards/content-cards-summary.md に記録します。

クリアランス確認は、ユーザーがカードと初期配置を選択した後に行います。キューの冒頭、中ほど、末尾、および話者が大きく動くフレームをサンプリングすることが、最低限必要なエビデンスの基準です。最終承認には、キュー全体を通して遮られていないことの確認も必要です。顔の輪郭、目、鼻、口、表情の領域が遮られていない場合にのみ、face_clearance: "verified" に設定します。キャプションが有効な場合は、実際にレンダリングされたキャプションオーバーレイを含むスチルを使い、caption_clearance: "verified" に設定します。キャプションが有効でない場合は、caption_clearance: "not-applicable" を使用します。合成スチルのパス、判定モード、空でない根拠を保存します。サンプリングしたフレームが衝突する場合は、まずカードを移動し、次に面積またはラベルの密度を減らし、その後、別のレイアウトを選択します。安全な結果が得られない場合は、カードを削除します。カードを収めるために、キャプションを隠したり、移動したり、書き換えたり、読みやすさを損なったりしてはいけません。

7. 透明な映像素材をレンダリングする

数秒分のグラフィックスによってプログラム全体の透明動画が作成されるのを避けるため、キューごとに短いアルファ付き MOV を1本ずつ作成する方法を優先します。それぞれをソースと同じ解像度、正確なソース FPS でレンダリングし、プログラム時刻のウィンドウを指定したレンダー素材として宣言します。全編の疎なオーバーレイが明らかに小さい場合、またはコンポジション上必要な場合に限り、単一の全編オーバーレイも有効です。

この処理の素材を project.json に記録します。content-cards を captions の後、motion-graphics の前に挿入し、キャプションが有効な場合は depends_on／based_on に captions を含めます。

{
"target": {"sequence": "main", "scope": "graphics"},
"effects": {
  "changes_timeline": false,
  "changes_geometry": false,
  "changes_video_pixels": false,
  "changes_audio": false,
  "adds_track": "graphics"
},
"check": {
  "status": "pass",
  "report": "../review/03-content-cards/content-cards-summary.md"
},
"render": [
  {
    "kind": "overlay",
    "asset": "cache/content-cards/card-001.mov",
    "start_s": 12.5,
    "duration_s": 4.0
  }
]
}

共有レンダラーは各短いクリップを start_s に合わせてオフセットし、duration_s の長さに制限した後、ベース動画のカラーグレーディング後に合成します。処理の outputs と各カードの renderer.asset が、これらの宣言済み素材と一致するようにします。

カードのレビュー後にのみ、処理を approved または verified に設定します。プラン、タイミング、または選択した入力が変わった場合は、整数の revision を更新します。すべての有効な処理で based_on のチェックに合格した後、共有レンダラーが最終合成を行います。

python skills/video-understand/scripts/build_render_plan.py .
python skills/video-understand/scripts/render_project.py work/render/render-plan.json

字幕との組み合わせ

字幕とカードは、別々のオーバーレイ要素として扱います。字幕は先に配置され、その占有領域にはカードを配置できません。レンダリング前に配置の競合を解決してから、共有の配信パスで宣言された順序に従って合成します。カードが字幕領域を占有する場合は、カードを別の安全な領域に移動してください。字幕を覆ったり、移動させたりしてはいけません。

字幕とカードの両方を追加する場合は、次の順序で人間による確認を挟みます。まず、字幕プリセットのレビューと、既存の提示して停止を完了します。次に、コンテンツカード候補のレビューと、その提示して停止を実行し、ユーザーがカードを承認して初期位置を選択します。その選択が完了してから、エージェントが合成コンポジションを作成し、顔と字幕のクリアランスを確認します。その後に行う合成静止画のレビューも引き続き必須であり、最終承認のためにクリアランスの根拠を提示します。