video-to-shorts

動画からショート動画を作成

依存関係

/video-understand は前提条件です。最初に実行し、ショート動画で検証済みの ソーストランスクリプトと正規のタイムラインを使用できるようにしてください。 開始前に、インストールされていることを確認してください。インストールされていない場合は、 この前提条件が満たされていないことをユーザーに警告し、メディアの処理を開始する前に中止してください。

メディアを処理する前に、ffmpeg／ffprobe が PATH 上にあり、Python と Pillow が 利用できることを確認してください。

対象範囲

このスキルには、次の 2 つのプロジェクトフェーズがあります。

1. レンダリング前に計画: 理解済みのトランスクリプトをプログラム時間に対応付け、候補を作成して 承認を得てから、work/shorts/shorts-plan.json に書き込みます。このフェーズでは 最終動画を書き出しません。
2. レンダリング後に仕上げ: 選択したメインシーケンスの編集がすべて承認され、共有のメイン納品物が検証されたら、 plan.py を再実行して、同じ承認済み範囲をその納品物に紐付けてから、横型と任意の縦型の出力を抽出します。

このスキルは、ショート動画候補の判断、決定的な適格性判定、横型の抽出、 ショート動画に合わせたトランスクリプト、および任意の決定的な縦型納品を担当します。プロジェクトモードでは 文字起こしを行わず、メインシーケンスの変更、字幕やグラフィックの追加、 カラーグレーディング、公開、継続的な被写体追跡も行いません。

納品するショート動画は final/final-video.mp4 の派生物ですが、候補の計画はそのファイルの作成より前に行います。 この処理をプロジェクト DAG に記録します。ただし、sequences.main.operations には追加しないでください。 メインの納品物と、オリジナルと最終版の比較は変更しないままにします。

プロジェクト入力

• work/project.json
• project.source.path に記録されたプロジェクトソース
• ソース時間の work/understand/transcript.json
• work/timeline.json
• 各フェーズの有効なメイン操作リビジョン

計画には final/final-video.mp4 は必要ありません。仕上げと抽出には、 render.status: verified を満たす、当該プロジェクトの正確なレンダリング結果が必要です。

prepare_transcript.py --timeline は共有の projectlib.map_transcript_to_timeline を呼び出します。そのため、候補と抽出の時刻は、 実際の最終動画上のプログラム秒になります。メイン編集で削除された単語は、ショート動画では使用できません。 残された各単語には、source_range、program_range、clip_id が保持されます。

プロジェクトのトランスクリプトメタデータは、プロジェクトソース、ソーストランスクリプト、タイムラインを、 絶対パス、サイズ、更新日時、SHA-256 で紐付けます。候補確認用のフレームは、timeline.json を介して プログラム時刻をソース動画に対応付けます。候補の検証では、紐付けが変更されていると処理を拒否します。

出力レイアウト

work/shorts/
|-- transcript.json
|-- transcript_metadata.json
|-- candidates.json
|-- shorts-plan.json
|-- review/
|   |-- candidate_review.json
|   `-- approved_candidates.json
`-- short-001/
    |-- transcript.json
    |-- extraction-report.json
    `-- vertical-agent/
        |-- agent_vertical_plan.json
        |-- vertical_plan.json
        `-- review/vertical_review.json

work/cache/shorts/                 # disposable frames/sheets/intermediate media

review/06-shorts/
|-- candidates-<review-id>.html              # immutable authoritative page
|-- candidates-<review-id>-question.md
|-- assets/candidates-<review-id>/            # immutable start/middle/end frames
|-- candidates.html                           # non-authoritative latest alias
|-- candidates-summary.md
|-- short-001-horizontal.jpg
|-- short-001-vertical-preview.mp4
|-- short-001-vertical-contact-sheet.jpg
|-- short-001-vertical-preview-summary.json
|-- short-001-vertical-preview-probe.json
|-- <short-id>-vertical-review-<review-id>.html # immutable authoritative page
|-- <short-id>-vertical-review-<review-id>-question.md
|-- <short-id>-vertical-review.html             # non-authoritative latest alias
|-- <short-id>-vertical-review-assets/
|   `-- <review-id>/                             # immutable authoritative evidence
|       |-- preview.mp4                          # absent for REVIEW_REQUIRED
|       |-- contact-sheet.jpg                    # absent for REVIEW_REQUIRED
|       |-- preview-summary.json
|       `-- media-probe.json
`-- shorts-summary.md

final/shorts/
|-- short-001-horizontal.mp4
`-- short-001-vertical.mp4          # only when selected and approved

プログラムトランスクリプト

リポジトリのルートから実行します。

$RepoRoot = (Resolve-Path ".").Path
$SkillRoot = Join-Path $RepoRoot "skills\video-to-shorts"
$ProjectRoot = (Resolve-Path "<project-root>").Path
$Work = Join-Path $ProjectRoot "work"
$ShortsWork = Join-Path $Work "shorts"
$ProjectSource = (Resolve-Path "<project-source-from-work/project.json>").Path
$FinalVideo = Join-Path $ProjectRoot "final\final-video.mp4"
$ShortsReview = Join-Path $ProjectRoot "review\06-shorts"
New-Item -ItemType Directory -Force $ShortsWork,$ShortsReview | Out-Null

python "$SkillRoot\scripts\prepare_transcript.py" $ProjectSource `
  --transcript "$Work\understand\transcript.json" `
  --timeline "$Work\timeline.json" `
  --out $ShortsWork

プロジェクトタイムラインモードでは、指定された正規のトランスクリプトが必要です。スタンドアロンモードでは --timeline を省略できます。その場合、入力動画に対する相対時間を維持し、一時的な video-understand/scripts/transcribe.py のフォールバックを使用できます。トランスクリプトは自動検出されません。

候補の作成

長尺動画のビジュアルコンテキストをキャッシュに生成し、判断に必要なシートをすべて確認して、候補 JSON を手動で作成します。決定論的なコードは編集上の判断を検証しますが、候補やスコアを作り出すことはありません。

python "$SkillRoot\scripts\prepare_visual_context.py" $ProjectSource `
  --timeline "$Work\timeline.json" `
  --out "$Work\cache\shorts\candidate-visual" --interval 15

互換性を保つため、候補入力は引き続き shorts-candidates.v2 を使用します。 selection.evidence_mode とすべての候補の evidence_mode を text_visual に設定します。 各候補には次の項目が必要です。

• 安定した candidate_id、タイトル、シーンの種類。
• プログラム時間で指定した完全な start_time／end_time。
• 重複するトランスクリプトの単語と完全に一致する transcript_excerpt。重複するセグメント全体ではありません。
• 6 つすべてのスコア項目と、空でない理由。
• 空でない metadata.editorial_reason。
• 任意の、確認済みの filler_drop_spans およびビジュアル証拠フィールド。

合計 score は指定しないでください。バリデーターが 6 つの評価項目を合算します。

評価項目	最大値
hook	20
completeness	20
audience_value	20
emotion_tension	15
quotability	15
pace_editability	10

短い断片よりも、単独で理解できる完全な考えを優先してください。必要な場合は、依存関係のあるインタビュアーの質問、前提、主張の裏付け、逆転、または結末を含めてください。境界は単語や考えの途中ではなく、区切りに合わせてください。

作成したファイルを検証します。

$CandidateDir = Join-Path $ShortsWork "preview\text_visual"
python "$SkillRoot\scripts\candidates.py" `
  --out $CandidateDir `
  --candidates "$CandidateDir\candidate-input.json" `
  --transcript "$ShortsWork\transcript.json" `
  --project-root $ProjectRoot

これにより、互換性プレビュー用ファイル、永続的な work/shorts/candidates.json、および review/06-shorts/candidates.{html,summary.md} が書き出されます。

レビューモード

候補の選択と納品モードは、ハッシュでひも付けられた 1 つのゲートです。納品モードは horizontal_only または horizontal_and_vertical のいずれかです。

人間モードで、ひも付けられたインタラクティブページを開きます。

python "$SkillRoot\scripts\interaction.py" candidate-open --out $ShortsWork --review-out $ShortsReview

このコマンドは、レビュー ID にひも付けられた正式なページを出力します。レシートは、そのページ、候補 JSON、トランスクリプト、ソースメディア、固定された質問、および抽出されたすべてのフレームを SHA-256 でひも付けます。candidates.html は、最新ページへの正式ではない便宜上のエイリアスにすぎません。出力された正式なパスを、現在の OS のネイティブコマンドで開きます。

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agent: Present the authoritative page and STOP.

開けない場合は、ネイティブコマンドを再試行し、それでも開けなければ失敗を報告します。表示した後は続行しないでください。ページを開くと、すべての候補チェックボックスと 2 つの納品方法は、どちらも未選択の状態です。ユーザーは 1〜5 件の候補と、1 つの納品モードを選択する必要があります。ひも付けられたページが、候補を暗黙的に選択することはありません。

承認する場合は、このページが生成した構造化サマリーを変更せずに candidate-answer にコピーします。

Shorts candidate review
Review: <review-id>
Candidates: text_visual/cand-001, text_visual/cand-002
Delivery: horizontal_and_vertical

修正する場合は、このページが生成した構造化サマリーを変更せずにコピーします。

Shorts candidate review
Review: <review-id>
Decision: revise
Changes: <non-empty requested changes>

後続の応答は書き換えずに記録します。

python "$SkillRoot\scripts\interaction.py" candidate-answer `
  --out $ShortsWork --response-file "<verbatim-summary-file>"

ユーザーが判断を明示的に委任した場合：

python "$SkillRoot\scripts\interaction.py" candidate-open `
  --out $ShortsWork --review-out $ShortsReview --decision-mode agent `
  --delegation-note "User delegated shorts selection and vertical approval."

python "$SkillRoot\scripts\interaction.py" candidate-agent-approve `
  --out $ShortsWork `
  --candidates "text_visual/cand-001" `
  --delivery horizontal_and_vertical `
  --rationale "The selected range has a self-contained hook, explanation, and payoff."

エージェントは同じ正式なページを開いて確認し、候補を明示的に参照し、納品モードを明示して、空でない根拠を提示します。人間による応答や user_response を偽造することはありません。人間モードとエージェントモードは相互排他的です。エージェントモードでは人間の回答コマンドが失敗し、人間モードではエージェントの承認コマンドが失敗します。レシートの検証では、レビュー、ページ、メディアのハッシュを再確認します。ソース、候補、トランスクリプト、ページ、質問、フレーム、または承認済み候補の成果物を再生成すると、承認は無効になります。

標準プラン

python "$SkillRoot\scripts\plan.py" `
  --out $ShortsWork --project-root $ProjectRoot

work/shorts/shorts-plan.json では、整数の schema_version: 1 を使用します。次の情報を記録します。

• target: derived、timebase: program、および timeline_id；
• 計画中の delivery_status: awaiting_main_render；
• 候補のレビューに使用するプロジェクトソースとタイムラインのバインディング；
• アクティブなメインシーケンスから取得した正確な depends_on / based_on リビジョン；
• 選択モード、選択理由、納品モード、およびレビュー ID；
• 安定したショート ID；
• 明示的な program_range とマッピング済みの source_ranges；
• スコアリング／編集上の根拠、承認済みのフィラードロップ、およびプログラム時間上のキープ範囲；
• 作業用のトランスクリプト／レポートのパスと、納品先の ../final/shorts/*.mp4 パス。

最初の実行で計画フェーズは終了です。ここで停止し、リクエストされた字幕、コンテンツカード、モーショングラフィックス、その他の残りのメインシーケンス操作を正規の順序で続けてください。このスキルでは extract_shorts.py を実行せず、final.mp4 も作成しないでください。

共有レンダラーが final/final-video.mp4 を検証した後、同じ plan.py コマンドを再実行します。このコマンドは、承認済みのプロジェクトソースとタイムラインを再検証し、アクティブな全操作のリビジョンを更新し、検証済みのメインレンダーのフィンガープリントを追加して、delivery_status: ready に設定します。タイムラインが変更された場合は、新しい候補の作成と承認が必要です。コンテンツカードや字幕など、ピクセルのみに作用する操作ではその必要はありません。

適格性の判定は決定論的です。スコアが70以上、完全性が15以上、推定出力時間が20～90秒、有効かつ正確な抜粋であること、上位にランクされたショートとの重複が50%を超えないこと、設定で変更されていない限り出力が最大5本であることが条件です。

フィラードロップとして承認できるのは、安全な単語境界を持つ、単独で意味的に空のためらいの言葉のみです。却下された範囲や安全でない範囲は、理由とともにプランに残ります。削除の合計は15%を超えてはならず、キープ範囲は0.15秒未満であってはなりません。

横向き動画の抽出

python "$SkillRoot\scripts\extract_shorts.py" `
  --video $FinalVideo --out $ShortsWork `
  --project-root $ProjectRoot

抽出前に、スクリプトはメインレンダーのフィンガープリント、プロジェクトのレンダリングステータス、現在のメイン操作の完全なリストとリビジョン、候補のレシート、承認済み候補のハッシュ、ソース動画を再確認します。awaiting_main_render のプランは拒否されます。各キープ範囲は、シーク位置を指定した独立した -ss/-t/-i 入力になります。ffmpeg はこれらの入力を連結し、H.264/AAC で1回エンコードします。キープ範囲ごとにメイン動画全体をデコードすることはありません。

選択された最後のトランスクリプト語とメディアのカット位置は、別々の境界です。抽出では、選択した内容の後に少なくとも0.25秒のリリース音声を残し、0.30秒を目標にします。--no-refine-boundaries が無効にするのは意味に基づくフレーズ境界のスナップのみで、必須のリリースハンドルは無効になりません。ソースの終端が必要なハンドルを残せる位置より前にある場合、ショートを検証済みとしてマークせず、抽出は失敗します。

ショート相対のトランスクリプトでは、ドロップされた単語を除外し、それ以降の単語を連続したゼロ起点のタイムラインに移し、入力時のプログラム／ソースの根拠を保持します。横向き動画の出力先は final/shorts で、作業用ディレクトリにはトランスクリプトとレポートのみを保存します。

縦型動画の計画

縦型動画の作成は、承認済みの横型動画の出力から始めます。1 秒ごとに、動きが必要な場合は 0.5 秒ごとに、密度の高い視覚的な証拠を生成します。すべてのシートを確認し、次のいずれかを作成します。

• STATIC_CROP：安定した固定の 9:16 クロップを 1 つ使用します。
• SCENE_CROP：シーンごとに固定クロップを使用し、シーン内の横方向の情報をすべて含める必要がある場合に限り、LETTERBOX を使用します。
• LETTERBOX：シャープな前景全体を、ぼかすか暗くした背景の上に表示します。
• REVIEW_REQUIRED：固定クロップを確定的に決める証拠が不十分です。正式なレンダリングはブロックされます。

プレゼンターのシーンでは、頭部と胴体が安定して大きく映るようにします。スライド、製品、グループ、図表では、重要な情報を保持する必要があります。連続トラッキングを行うとは主張しないでください。クロップの変更はシーンの境界で行います。

各プランセグメントはショート動画のタイムライン全体をカバーし、戦略、コンテンツタイプ、空でない根拠、および該当する場合は有効範囲内のクロップを含める必要があります。必須のコンテンツタイプは PRESENTER、WIDE_INFORMATION、PRODUCT、MULTI_SUBJECT、OTHER です。

$ShortId = "short-001"
$Horizontal = Join-Path $ProjectRoot "final\shorts\$ShortId-horizontal.mp4"
$VerticalWork = Join-Path $ShortsWork "$ShortId\vertical-agent"
$ExtractionReport = Join-Path $ShortsWork "$ShortId\extraction-report.json"

python "$SkillRoot\scripts\prepare_visual_context.py" $Horizontal `
  --out "$Work\cache\shorts\$ShortId-vertical-visual" --interval 1

python "$SkillRoot\scripts\vertical_plan.py" `
  --video $Horizontal `
  --input "$VerticalWork\agent_vertical_plan.json" `
  --out $VerticalWork `
  --source-video $FinalVideo `
  --extraction-report $ExtractionReport

vertical_plan.json は、FPS を {num, den} として正確に保持し、ジオメトリ、カバレッジ、戦略の継続時間、警告を決定的に検証します。直接レンダリングのバインディングでは、検証済みのメイン動画と抽出レポートの正確な内容をハッシュ化します。プレビューのレビューでは引き続き承認済みの横型ショート動画のタイムラインを使用しますが、正式なレンダリングでは、記録された keep_spans を通じてそのタイムラインをマッピングし、検証済みのメイン動画からピクセルを直接読み取ります。

ユーザー向けのレビューディレクトリに、小さなプレビューをレンダリングします。

python "$SkillRoot\scripts\render_vertical.py" `
  --video $Horizontal --plan "$VerticalWork\vertical_plan.json" `
  --out $VerticalWork --review-out $ShortsReview --mode preview

このコマンドは、まず最新の利便性向け出力として、フラットな <short-id>-vertical-preview.mp4、<short-id>-vertical-contact-sheet.jpg、<short-id>-vertical-preview-summary.json、<short-id>-vertical-preview-probe.json を書き込みます。次に、正式な <short-id>-vertical-review-<review-id>.html ページを出力します。最新の <short-id>-vertical-review.html エイリアスは、正式なものではなく、利便性向けにのみ使用されます。

正式なページとレシートは、<short-id>-vertical-review-assets/<review-id>/ 配下にある、変更されないレビュー ID スコープのコピーに紐付けられます。対象は preview.mp4、contact-sheet.jpg、preview-summary.json、media-probe.json です。後続のプレビューでフラットな利便性向け出力が置き換えられても、以前のレシートは変更されません。REVIEW_REQUIRED の場合、プレビュー動画やコンタクトシートはレンダリングされないため、スコープ付きディレクトリには preview-summary.json と media-probe.json のみが保存されます。

出力された正式なパスを、現在の OS のネイティブコマンドで開きます。

# Windows PowerShell
Start-Process (Resolve-Path -LiteralPath "<printed-authoritative-page>")
# macOS
open "<printed-authoritative-page>"
# Linux
xdg-open "<printed-authoritative-page>"
# Agent: Present the authoritative page and STOP.

開けない場合はネイティブコマンドを再試行し、それでも開けなければ失敗を報告します。提示後は続行しないでください。プレビュー全体、コンタクトシート、すべてのセグメントとクロップ／フィットの判断、メディアプローブ、すべての警告を確認します。レシートは、ページ、プラン、ソース、プレビュー、コンタクトシート、プレビューのサマリー、プローブ、固定された質問をハッシュ化します。

人間によるレビューでは、ページにある正確な構造化サマリーを変更せずに vertical-answer にコピーします。サマリーは次の 3 種類です。

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: approve

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: revise
Changes: <non-empty requested changes>

Shorts vertical review
Short: <short-id>
Review: <review-id>
Decision: skip

python "$SkillRoot\scripts\interaction.py" vertical-answer `
  --out $VerticalWork --response-file "<verbatim-summary-file>"

委任モードでは同じページを使用し、根拠を空にせず、エージェントの判断を正直に記録します。

python "$SkillRoot\scripts\interaction.py" vertical-agent-approve `
  --out $VerticalWork `
  --rationale "All sampled scenes preserve the subject and essential information."

REVIEW_REQUIRED で選択できるのは revise または skip のみです。エージェントによる承認はブロックされます。新しい候補のレビューが作成されると、以前の縦型動画のレシートは無効になります。最終的な縦型動画のレンダリングは、承認後にのみ可能です。承認済みでハッシュが一致するレビュー用メディアとプランのみ、最終レンダリングに使用できます。修正やスキップによって最終的な縦型動画ファイルが作成されることはありません。

正式なレンダリングでは、承認済みのすべての成果物を再検証します。

python "$SkillRoot\scripts\render_vertical.py" `
  --video $Horizontal --plan "$VerticalWork\vertical_plan.json" `
  --out $VerticalWork --review-out $ShortsReview --mode final

正式なレンダラーは、有理数の num/den、検証済みのメイン動画から生成する H.264/yuv420p の 1 つの世代、libx264 -preset slow -crf 16、およびエンコード済みの連続した音声を使用します。プレビューのレンダリングは、レビューを速くするため medium／CRF 20 のままです。レンダラーは、寸法、長さ、FPS、音声の有無、ソース／レポートのハッシュ、キープ範囲のマッピングを確認します。

プロジェクトの運用

メインシーケンスには追加せず、派生操作を 1 つ work/project.json に追加します。

{
  "id": "shorts",
  "skill": "video-to-shorts",
  "revision": 1,
  "depends_on": ["understanding"],
  "based_on": {"understanding": 1},
  "status": "approved",
  "plan": "shorts/shorts-plan.json",
  "outputs": [],
  "target": {"sequence": "main", "scope": "derivatives"},
  "effects": {
    "changes_timeline": true,
    "changes_geometry": true,
    "changes_video_pixels": true,
    "changes_audio": true,
    "adds_track": null
  },
  "check": {"status": "pending", "report": "../review/06-shorts/shorts-summary.md"}
}

これはレンダリング前の状態です。プランに保存されている実際の依存関係リストとリビジョンを使用します。共有メインレンダリングの後に plan.py を再実行し、更新された依存関係に基づいて操作を更新してから、出力を抽出して検証します。その後、操作とチェックをそれぞれ verified／pass に設定し、納品ファイルを一覧にします。プロジェクト検証では DAG とファイルをチェックします。ショート動画は引き続きメインレンダリングプランの対象外です。

互換性

--project-root を指定しない場合、候補と shorts-plan.v2 は従来のスタンドアロンパスと入力相対の時間を維持します。抽出ツールは両方のプラン形式に対応します。従来の short_XX/source.mp4 を使用する縦型ワークフローと、人によるレビューコマンドも引き続き有効です。従来のバインドされていないテキストレビューのみ、デフォルトの上位 5 件の候補を使用できます。バインドされたインタラクティブページでは、常に明示的な選択が必要です。スタンドアロンのフォールバック文字起こしでは、標準の video-understand 文字起こしツールとプロジェクトローカルのモデルキャッシュを使用します。

セルフチェック

次を実行します。

python "$SkillRoot\scripts\check_project_protocol.py"
python "$RepoRoot\skills\video-understand\scripts\validate.py" project `
  "$Work\project.json" $ProjectRoot

納品する各ショート動画について、以下を確認します。

• 候補の抜粋が重複する番組内の言葉と一致し、話の流れが完結していること。
• ソース／番組の範囲と依存関係のリビジョンが解決できること。
• 横型動画の長さがキープ範囲の合計とおおむね一致すること。
• ショート動画の文字起こしが 0 秒から始まり、メディアの終了時間を超えず、削除された言葉とリリースハンドル内でのみ聞こえる言葉を含まず、tail_release_verified: true を報告すること。
• 横型出力が想定 FPS、H.264 動画、同期した音声、レビュー用静止画を備えていること。
• 縦型出力が 9:16 で、正確な有理数 FPS を使用し、必須コンテンツをセーフエリア内に保ち、音声が同期しており、承認済みのプレビュー／プランのハッシュと一致し、検証済みのメイン納品物を render_source として記録したうえで、direct_render: true を記録していること。
• ユーザー向けのメディアがすべて review/ または final/ の下にあり、破棄可能な素材が work/cache/ の下にあること。
• shorts-summary.md に出力、判断、警告、チェックが記録されていること。

ページの生成や JSON の検証だけでは成功とはみなされません。横型と縦型の出力を再生し、レビュー画像／コンタクトシートを確認してください。