ビデオユース

原則

LLMは生のトランスクリプトとオンデマンドのビジュアルから推論する。 価値のある唯一の派生成果物は、パックされたフレーズ単位のトランスクリプト (takes_packed.md) です。それ以外のもの（フィラータグ、リテイク検出、ショット分類、強調スコアリングなど）は、決定時に導出します。
音声が優先され、ビジュアルはそれに従う。 カット候補は発話境界と無音ギャップから得られます。ビジュアルに踏み込むのは決定ポイントのみです。
質問 → 確認 → 実行 → 反復 → 永続化。 ユーザーが平易な英語で戦略を確認するまでは、決してカットに触れないでください。
一般化する。 これがどのような種類の動画かを想定しないでください。素材を見て、ユーザーに尋ね、それから編集してください。
芸術的自由がデフォルトです。 このドキュメント内の特定の値、プリセット、フォント、色、持続時間、ピッチ構造、技術は、すべて実績のある一つの動画からの実例であり、強制ではありません。それらを読んで、何が可能で、なぜそれぞれが機能したかを理解してください。そして、素材が実際に何であるか、ユーザーが実際に何を望んでいるかに基づいて、自身の美的判断を行ってください。絶対に実行しなければならないことだけは、以下のハードルールセクションにあります。 それ以外はすべて、あなたの裁量に委ねます。
自由に発明する。 素材がここに記載されていないテクニックを必要とする場合（スプリットスクリーン、ピクチャー・イン・ピクチャー、L字型IDカード、リアクションカット、スピードランプ、フリーズフレーム、クロスフェード、マッチカット、Lカット、Jカット、呼吸に合わせたスピードランプなど）、それを構築してください。ffmpeg と PIL がそのためのヘルパーです。フォーマットがサポートするものなら、何でもできます。許可を待つ必要はありません。
ユーザーに見せる前に、自身の出力を検証してください。 自分が納得できないものを提示してはいけません。

ハードルール（プロダクションの正しさ — 絶対条件）

これらは、逸脱するとサイレント障害や壊れた出力を引き起こすものです。好みではなく、正しさの問題です。暗記してください。

字幕はフィルターチェーンの最後、すべてのオーバーレイの後に適用されます。そうしないと、オーバーレイがキャプションを隠してしまいます。サイレント障害です。
セグメントごとに抽出 → ロスレス -c copy で連結。単一パスのフィルターグラフは使用しないでください。そうしないと、オーバーレイが追加されるたびに全セグメントが二重エンコードされます。
すべてのセグメント境界に30msのオーディオフェード (afade=t=in:st=0:d=0.03,afade=t=out:st={dur-0.03}:d=0.03)。そうしないと、すべてのカットで可聴のポップノイズが発生します。
オーバーレイは setpts=PTS-STARTPTS+T/TB を使用して、オーバーレイのフレーム0をそのウィンドウの開始位置にシフトします。そうしないと、オーバーレイウィンドウ中にアニメーションの中間部分が表示されます。
マスターSRTは出力タイムラインオフセットを使用します: output_time = word.start - segment_start + segment_offset。そうしないと、セグメント連結後にキャプションがずれます。
単語の途中でカットしないでください。 すべてのカットエッジを、Scribe トランスクリプトの単語境界にスナップさせてください。
すべてのカットエッジにパディングを適用する。 作業ウィンドウ: 30～200ms。Scribe のタイムスタンプは50～100ms ドリフトします — パディングはそのドリフトを吸収します。テンポの速い動画では狭く、映画的なものでは広く設定します。
単語レベルの逐語的ASRのみを使用する。 SRT/フレーズモード（サブ秒のギャップデータが失われる）は決して使用しないでください。正規化されたフィラー（編集上のシグナルが失われる）も使用しないでください。
ソースごとにトランスクリプトをキャッシュする。 ソースファイル自体が変更されない限り、トランスクリプトを取り直さないでください。
複数のアニメーションには並列サブエージェントを使用する。 決して順次処理しないでください。Agent ツールを介して一度にN個を起動します。総壁面時間は最も遅いものとほぼ同じになります。
実行前に戦略確認。 ユーザーが平易な英語の計画を承認するまでは、決してカットに触れないでください。
すべてのセッション出力は <videos_dir>/edit/ に配置する。 video-use/ プロジェクトディレクトリ内には決して書き込まないでください。

このドキュメント内のその他すべては実例です。素材が必要とする場合は、いつでも逸脱して構いません。

ディレクトリ構成

スキルは video-use/ にあります。ユーザーの映像はユーザーが置いた場所にあります。すべてのセッション出力は <videos_dir>/edit/ に配置されます。

<videos_dir>/
├── <ソースファイル、未編集>
└── edit/
    ├── project.md              ← メモリ; セッションごとに追記
    ├── takes_packed.md         ← フレーズレベルのトランスクリプト、LLMの主要な読み取りビュー
    ├── edl.json                ← カット決定
    ├── transcripts/<name>.json ← キャッシュされた生のScribe JSON
    ├── animations/slot_<id>/   ← アニメーションごとのソース + レンダリング + 推論
    ├── clips_graded/           ← グレーディングとフェードを含むセグメントごとの抽出
    ├── master.srt              ← 出力タイムラインの字幕
    ├── downloads/              ← yt-dlp の出力
    ├── verify/                 ← デバッグフレーム / タイムラインPNG
    ├── preview.mp4
    └── final.mp4

セットアップ

初回インストールは install.md にあります（クローン、依存関係、ffmpeg、スキル登録、APIキー）。セッションごとに再実行しないでください。コールドスタート時は、以下を確認するだけです:

ELEVENLABS_API_KEY が解決されること — 環境変数か、video-use リポジトリルートの .env にあること。ない場合、ユーザーにキーを貼り付けてもらい、.env に書き込むよう依頼してください（ユーザーの <videos_dir> には決して書き込まないでください）。
ffmpeg + ffprobe がPATHに存在すること。
Pythonの依存関係がインストールされていること（リポジトリ内で uv sync または pip install -e . を実行）。
セッションでHyperFramesまたはRemotionスロットが必要な場合、Node.js + npmが利用可能であること。HyperFramesは現在Node.js 22+を必要とします。
yt-dlp、HyperFrames、Remotion、Manimは初回使用時のみインストールされます。
初回使用時のアニメーションセットアップはスロットディレクトリ内で行われ、video-use リポジトリルートでは決して行われません。HyperFrames は npx --yes hyperframes ... で呼び出すことができます。Remotion は npx create-video@latest でスキャフォールドするか、プロジェクトローカルの依存関係としてインストールしてから remotion render コマンドを使用できます。
このスキルは skills/manim-video/ をベンダリングしています。Manim スロットを構築する際は、その SKILL.md を読んでください。

ヘルパー (helpers/transcribe.py、helpers/render.py など) はこの SKILL.md と同じディレクトリにあります。それらのパスは、このファイルを含むディレクトリからの相対パスで解決してください — スキルは通常、~/.claude/skills/video-use/ または ~/.codex/skills/video-use/ にシンボリックリンクされています。

ヘルパー

transcribe.py <video> — 単一ファイルのScribe呼び出し。--num-speakers N はオプション。キャッシュされます。
transcribe_batch.py <videos_dir> — 4ワーカーの並列文字起こし。マルチテイク時に使用します。
pack_transcripts.py --edit-dir <dir> — transcripts/*.json → takes_packed.md（フレーズレベル、0.5秒以上の無音で区切る）。
timeline_view.py <video> <start> <end> — フィルムストリップ+波形のPNG。オンデマンドのビジュアル詳細調査。スキャンツールではありません — 決定ポイントでのみ使用し、常時使用しないでください。
render.py <edl.json> -o <out> — セグメントごとの抽出 → 連結 → オーバーレイ（PTSシフト） → 字幕（最後）。--preview で720p高速プレビュー。--build-subtitles でマスターSRTをインライン生成。
grade.py <in> -o <out> — ffmpegフィルターチェーングレーディング。プリセット + --filter '<raw>' でカスタム。

アニメーションについては、Bash で <edit>/animations/slot_<id>/ を作成し、Agent ツールを介してサブエージェントを起動します。

プロセス

インベントリ。 すべてのソースを ffprobe します。ディレクトリに対して transcribe_batch.py を実行します。pack_transcripts.py で takes_packed.md を生成します。視覚的な第一印象のために、1～2つの timeline_view をサンプリングします。
事前スキャン。 takes_packed.md を一通り見て、言葉の誤り、明らかな言い間違い、避けるべき言い回しをメモします。プレーンなリストにして、編集者の指示に渡します。
対話。 見えたものを平易な英語で説明します。素材に基づいて質問をします。収集する情報：コンテンツタイプ、目標時間/アスペクト、美的感覚/ブランドの方向性、ペースの感覚、絶対に残すべき瞬間、絶対にカットすべき瞬間、アニメーションとグレーディングの好み、字幕の必要性。固定のチェックリストは使用しないでください — 適切な質問は毎回異なります。
戦略を提案。 4～8文：形状、テイクの選択、カットの方向性、アニメーションプラン、グレーディングの方向性、字幕スタイル、長さの見積もり。確認を待ちます。
実行。 編集サブエージェントの指示を介して edl.json を生成します。曖昧な瞬間には timeline_view で詳細を調べます。アニメーションは並列サブエージェントで構築します。セグメントごとにグレーディングを適用します。render.py で構成します。
プレビュー。 render.py --preview。
自己評価（ユーザーに見せる前）。 レンダリングされた出力（ソースではなく）に対して、各カット境界（±1.5sウィンドウ）で timeline_view を実行します。各画像で以下を確認します:
- カット部分の視覚的な不連続性 / フラッシュ / ジャンプ
- 境界での波形スパイク（30msフェードをすり抜けたオーディオポップ）
- オーバーレイの後ろに隠れた字幕（ルール1違反）
- オーバーレイの位置ずれ、または間違ったフレームの表示（ルール4違反）
また、先頭2秒、末尾2秒、中間の2～3箇所をサンプリング: グレーディングの一貫性、字幕の可読性、全体的なまとまりを確認します。出力に対して ffprobe を実行し、持続時間が EDL の期待値と一致することを確認します。

オーディオを測定し、推測しないでください: ffmpeg -i out.mp4 -af ebur128=peak=true -f null - で統合ラウドネスとトゥルーピーク、さらにセクションごとのRMS（ダイアログ、音楽のみ、エンドカード）を確認します。エンドカードがダイアログより15dB低い、または効果音がスピーチより大きいのはバグです。あなたは聴くことができません: そう伝え、数値を報告してください。

ユーザーが公開するもの（ローンチ、プロモーション、広告）については、レンダリング済みファイル、EDL、およびユーザーから提供された参照動画を使って、1つの批評サブエージェントも起動します。賞賛ではなく酷評するように指示します: 評決、タイムコードと証拠（フレーム、レベル）を伴う問題のランク付け、そして最初に行うべき5つの修正。新鮮な目は、制作者が見逃していたものを見つけます — 途切れた決めゼリフ、0.5秒のミーム、電話サイズで読めない28pxのテキスト。

何か失敗した場合: 修正 → 再レンダリング → 再評価。自己評価は最大3回まで — 3回経過しても問題が残る場合は、無限ループせずにユーザーに報告してください。自己評価が通った場合のみ、プレビューを提示します。
反復 + 永続化。 自然言語でのフィードバック、再計画、再レンダリング。トランスクリプトは取り直さないでください。確認後に最終レンダリング。project.md に追記します。

カットの技術（テクニック）

音声優先。 カット候補は単語境界と無音ギャップから。
ピークを保持。 笑い、決めゼリフ、強調ビート。決めゼリフの後にはリアクションを含めるために延長 — 笑い自体がビートです。
話者の交代 は、発話の間に間を置くと効果的です。一般的な値: 400～600ms。テンポの速い動画では短く、映画的には長く。美的判断です。
オーディオイベントをシグナルとして。 (笑い)、(ため息)、(拍手) はビートを示します。それらを超えて延長します。
無音ギャップはカット候補。 400ms以上の無音は、通常最もクリーンです。150～400msのフレーズ境界は、視覚的な確認があれば使用可能です。150ms未満は安全ではありません（フレーズ途中）。
カットパディングの例（このスキルに同梱されたローンチ動画での値）: 最初の保持単語の前に50ms、最後の後に80ms。モンタージュのエネルギーに合わせて狭く、ドキュメンタリーには広く。30～200msの作業ウィンドウに収めてください（ハードルール7）。
音声とビデオを独立して推論しないでください。 すべてのカットは両方のトラックで機能しなければなりません。

パックされたトランスクリプト（主要な読み取りビュー）

pack_transcripts.py は transcripts/*.json をすべて読み取り、各テイクがフレーズレベルの行のリストであり、各行の先頭に [開始-終了] の時間範囲が付いた1つのマークダウンファイルを生成します。フレーズは、0.5秒以上の無音または話者の変更で区切られます。これは、編集サブエージェントがカットを選択するために読み取る成果物です — 生のJSONの1/10のトークンで、テキストのみから単語境界の精度を提供します。

行の例:

## C0103  (持続時間: 43.0s, 8 フレーズ)
  [002.52-005.36] S0 ウェブエージェントが行うことの90%は完全に無駄です。
  [006.08-006.74] S0 私たちはこれを修正しました。

編集サブエージェントの指示（マルチテイク選択用）

タスクが「複数のクリップから各ビートの最良のテイクを選択する」場合、以下のように構成された指示を専用のサブエージェントに与えてください。この構造は重要です。ピッチシェイプの例は強制ではありません。

あなたは <タイプ> 動画を編集しています。各ビートの最良のテイクを選択し、ソースクリップの順序ではなく、ビートの時系列順に組み立ててください。

入力:
  - takes_packed.md（すべてのテイクの時間注釈付きフレーズレベルトランスクリプト）
  - 製品/ナラティブコンテキスト: <ユーザーからの2文>
  - 話者: <名前、役割、話し方のスタイルに関するメモ>
  - 期待される構造: <アーキタイプを選択するか、発明する>
  - 避けるべき言葉の誤り: <事前スキャンパスからのリスト>
  - 目標実行時間: <秒>

一般的な構造アーキタイプ（選択、適合、または発明）:
  - テックローンチ / デモ:     フック → 問題 → 解決策 → メリット → 例 → CTA
  - チュートリアル:             イントロ → セットアップ → 手順 → 落とし穴 → まとめ
  - インタビュー:              (質問 → 回答 → フォローアップ) の繰り返し
  - 旅行 / イベント:           到着 → ハイライト → 静かな瞬間 → 出発
  - ドキュメンタリー:          テーゼ → 証拠 → 反論 → 結論
  - 音楽 / パフォーマンス:     イントロ → ヴァース → コーラス → ブリッジ → アウトロ
  - または独自のものを発明する。

ルール:
  - 開始/終了時間は、トランスクリプトの単語境界上になければなりません。
  - カット境界にパディングを適用します（作業ウィンドウ 30～200ms）。
  - 400ms以上の無音をカット対象として優先します。
  - より良いテイクがない場合、避けられない言い間違いは保持します。「理由」に記録します。
  - 予算超過の場合は、修正する: ビートを削除するか、末尾をトリミングします。合計を報告し、自己修正します。

出力（JSON配列、散文は不要）:
  [{"source": "C0103", "start": 2.42, "end": 6.85, "beat": "フック",
    "quote": "...", "reason": "..."}, ...]

最終的な EDL と、1行の合計実行時間チェックを返します。

カラーグレーディング（リクエスト時）

あなたの仕事は画像について推論することであり、プリセットを適用することではありません。フレームを見て（timeline_view 経由）、何が問題かを判断し、一つの要素を調整し、再度確認します。

思考モデルは ASC CDL です。チャンネルごとに: out = (in * slope + offset) ** power、その後グローバル彩度。slope → ハイライト、offset → シャドウ、power → ミッドトーン。

フィルターチェーンの例（grade.py に --list-presets があります。それらを出発点として使用するか、独自に組み合わせてください）:

warm_cinematic — レトロ/テクニカル、微妙なティール/オレンジ分割、彩度低め。実際のローンチ動画で出荷されました。トーキングヘッドに安全です。
neutral_punch — 最小限の補正: コントラスト強調 + 穏やかなSカーブ。色相シフトなし。
none — ストレートコピー。ユーザーが要求していない場合のデフォルト。

その他 — 肖像、自然、製品、ミュージックビデオ、ドキュメンタリー — については、独自のチェーンを発明してください。grade.py --filter '<raw ffmpeg>' は任意のフィルター文字列を受け入れます。

ハードルール: 抽出中にセグメントごとに適用します（連結後ではなく、後者は二重エンコードになります）。肌色をテストせずに積極的に適用しないでください。

字幕（リクエスト時）

字幕には、検討する価値のある3つの側面があります: チャンク化（1/...

（以降は翻訳のため省略）

アニメーションとオーバーレイ（リクエスト時）

アニメーションは <edit>/animations/slot_<id>/ で並行して構築します。各スロットは、ソース、レンダリング、および構築方法に関する推論を含む独自のディレクトリを取得します。利用可能なツール: HyperFrames、Remotion、Manim。最初の使用時にインストールします。

作業の永続化

各セッションの終わりに、project.md に追加します:

日付とセッションの簡単な説明
行われた決定とその理由
使用されたテクニックとその根拠
最終的な EDL またはその参照
注意すべき問題や未解決の項目

これにより、マルチセッションの編集プロジェクトが可能になり、LLMが過去の決定を記憶できます。

Video Use - 会話で動画編集