llvideo は何をしますか？
あなたは動画を見ることができません。動画ネイティブモデルなら見ることができます。このスキルは、そのモデルを CLI の背後に配置し、散文ではなく構造化された証拠を返すようにし、さらに実際のフレームをあなたに提供して、あなた自身の判断を形成できるようにします。
この違いこそが全てです。モデルの要約を中継するなら、あなたは単なる仲介者です。型付きのインデックスに基づいて推論し、自分で確認したピクセルと照合するなら、あなたはアナリストです。
セットアップ確認
llvideo providers
ffmpeg が PATH にあり、1つの API キーが必要です。GEMINI_API_KEY が全てを処理します。OPENROUTER_API_KEY は約半額ですが、アップロードエンドポイントがないため、URL と小さなクリップのみで、OpenRouter では動画リクエストを受け付ける前に $1.00 の購入クレジット が必要です (:free モデルでも同様)。
キーは最初に環境変数から読み取られます。フォールバックとして、~/.itachi-api-keys にある KEY=value ファイルも読み取ります。これは、キーをシェルプロファイルから分離しておくための便利な機能に過ぎません — 環境変数で十分です。
従うべきループ
1. 常に無料から始める
llvideo probe VIDEO # 再生時間、コーデック、解像度、トークン見積もり — 無料
llvideo plan VIDEO # コストと処理方法を表示 — 無料
plan は、サンプリングレート、トランスコードの必要性、トークン数、ドル見積もりを教えてくれます。費用をかける前に読みましょう。
2. 動画をインデックス化する
llvideo index VIDEO
llvideo index VIDEO --json # 解析用
llvideo index VIDEO --verify 3 # 画面上のテキストが重要な場合 — 下記参照
タイムスタンプ、画面上のテキスト、アクション、発話、キーモーメント、そして明示的な uncertainties リストを含むシーンを返します。また、コンタクトシート も書き出します。
3. コンタクトシートを見る。このステップは必須です。
index の出力はパスで終わります。ユーザーに答える前に、その画像を自分の視覚で読んでください。 タイムライン全体をカバーする1枚の画像で、約600〜1,600トークンです。グラウンディングには安価で、間違えると高くつきます。
あなたが主張するすべては、次のいずれかであるべきです：
- 自分でフレームで見たもの、
- ffmpeg の測定結果、
- 文字起こしの引用。
それ以外のものは、帰属を示す必要があります：「インデックスによると…」。モデルの推測を自分の言葉で決して偽装しないでください。
4. 重要な部分をさらに深掘りする
llvideo clip VIDEO --start 02:10 --end 02:40 --fps 4 -q "ロゴはきれいにアニメーションしますか？"
llvideo stills VIDEO --at 02:14,02:19 --width 1920 # フル解像度、自分で見る
llvideo sheet VIDEO --at 01:00,01:05,01:10 --tile 768 --cols 2 # 密集したUIテキスト
クリッピングはフレーム単位で正確で、数百トークンのコストがかかります。自由に使用してください。
理解に最適なビュー — timeline
llvideo timeline VIDEO
llvideo timeline VIDEO --transcribe # 単語レベルの正確な発話タイミング
index は scenes、speech、audio_events を3つの個別の配列として返します。それぞれは正確ですが、それらを結びつけるものは何もありません — そのため、「ダッシュボードのクローズアップ」と「彼は範囲が間違っていると言う」は異なるリストにあり、それらが同じ瞬間に発生しているという事実は、あなたが再構築するために残されています。
その共起こそがコンテキストです。 ショットの意味は、その上で何が話されているかによって異なります。timeline はすべてを1つのトラックにインターリーブします：
00:10-00:18 (8.0s) *KEY*
shot 運転手側のクローズアップ
see カメラが運転手に戻り、照明付きのガソリンスタンドが窓の外を通過する
does 車は照らされたキャノピーの下を通過する
says "ガソリンスタンドはクリップの9秒後に現れます。"
hear 低い車内アンビエントハム
why ガソリンスタンドのキャノピーが運転手のすぐ後ろを通過する
意味ではなく在庫についての質問の場合は、index よりもこちらを使用してください。
--transcribe は、モデルの発話の代わりにローカルの単語レベルの文字起こしを結合します。 モデルのオーディオタイムスタンプは約1秒ずれるため、高速なカットでラインが間違ったショットに結びつく可能性があります。発話は、最初に接触するビートではなく、最も重なるビートに割り当てられるため、カットをまたぐラインは、主に話された場所に着地します。
カバレッジを報告し、何も話されなかった実行時間の範囲に名前を付けます。穴のあるタイムラインは何かを見逃しており、それを明確にすることは、不完全なアカウントを完全なものとして提示するよりも優れています。
フォローアップ質問は無料
インデックスは、コンテンツIDとサンプリング設定に対して48時間キャッシュされます。測定結果：同じ動画での2回目の timeline は 12.5秒、$0.02 から 0.4秒、無料 になりました。必要なだけ質問してください — 反復が理解を構築する方法であり、最初のパスの後はコストがかかるべきではありません。--no-cache は強制的に新規実行します。
見つけた問題の修復 — fix
ほとんどの監査結果は、再生成を必要としません。音量の誤り、クリップしたピーク、先頭または末尾の黒フレーム — これらは決定論的な ffmpeg 操作であり、コストはかからず、幻覚を起こすこともありません。
llvideo audit render.mp4 # 見つける
llvideo fix render.mp4 # 修復する -> render_fixed.mp4
自動修復されるもの： 統合ラウドネス（−14 LUFS への2パス loudnorm）、トゥルーピーククリッピング（−1.0 dBFS に保持）、および黒または白の最初/最後のフレーム — フレーム数を仮定するのではなく、黒が実際にどこで終わるかを測定してトリミングします。
意図的に修復されないもの、それぞれ理由が記載されています：
| 結果 | 理由 |
|---|---|
| タイムライン途中の黒ギャップ | 編集上の判断であり、黙って削除する欠陥ではない |
| フリーズ | 保持されたフレームは意図的な可能性がある — タイムラインで短縮する |
| 低解像度 | アップスケーリングは、決してキャプチャされなかったディテールを偽造する |
| セーフマージン | レイアウトは構図の選択 — 要素を移動し、クロップしない |
| 長さ / アスペクト | レンダリング時に設定 — 収まるようにトリミングするとコンテンツがカットされる |
fix は その後再監査し、before/after のカウントを報告します。なぜなら、修復が機能したと再測定せずに主張することは、このツールが打破するために存在する習慣だからです。意図的に壊れたレンダリングで測定：5つのメジャー + 1つのマイナーが、1つのメジャー + 1つのマイナーになり、残った2つは人間の判断が必要な2つでした。
ソースを上書きすることはありません。--out を指定しない限り、出力は <name>_fixed.mp4 になります。
補完クリップの生成 — gen
他の場所で構築されたタイムラインに挿入する短いクリップ：導入ショット、Bロール、テクスチャ、ロゴスティング。長編映画ではありません。
llvideo gen "夜明けの霧の松林の上のゆっくりとした空撮プッシュ" --seconds 5
llvideo gen "ロゴがフレームに定着する" --image logo.png --seconds 3 # 画像から動画へ
llvideo gen "同じシーン、より寒色のグレード" --video clip.mp4 --seconds 5 # 動画から動画へ
llvideo gen-image "ウェザードウッドのタイトルカード" --out title.png
Grok Imagine を、既存の XAI_API_KEY を通じて実行します。これは xAI の Grok であり、Groq ではないことに注意してください — 別の会社です。1秒から15秒 まで1秒刻みで、Veo の固定 4/6/8 秒よりも柔軟です。
| 解像度 | 測定コスト |
|---|---|
| 480p | $0.05/秒 |
| 720p | $0.07/秒 |
| 1080p | ~$0.11/秒 (外挿、未測定) |
これらのレートは、ドキュメントではなく、実際のジョブの API 自身の使用状況フィールドから得られました。$1.00 を超える場合は --yes が必要です。
すべてのクリップは到着時に監査されます、そしてそれは飾りではありません。Grok のデフォルトは 848x480、約 -21 LUFS を生成します — 監査人はその両方をフラグします。そのため、gen はデフォルトで 720p になります。その後、自分で確認してください：
llvideo sheet clip.mp4
--audio は grok-imagine-video-1.5 に切り替わり、サウンドトラックを生成します。生成されたオーディオは静かに戻ってくる傾向があります。ラウドネスの指摘を期待し、クリップが他の素材の隣に配置される場合は、ポストでノーマライズしてください。
作成した動画の監査 — spec + --from-project
これが全体のループです。HyperFrames、brag、Remotion はすべて、何を構築しようとしているかを既に知っているため、誰も手動でインテント仕様を書くべきではありません：
llvideo audit render.mp4 --from-project ./my-hyperframes-project
llvideo audit brag-output/brag.mp4 --from-project ./brag-output
llvideo audit out.mp4 --from-project ./my-remotion-project
または、仕様を単独で抽出して検査または編集することもできます：
llvideo spec ./project --out intent.json
インテントの取得元と、その信頼度：
| ソース | 抽出されるもの | 信頼度 |
|---|---|---|
HyperFrames index.html | data-start / data-duration からのシーン開始/終了、DOM からの画面上テキスト | 正確 |
HyperFrames STORYBOARD.md | フレームごとのトランジションタイプと期間 (transition_in) | 作成者の意図 |
| brag | 構築する HyperFrames プロジェクトを composition/ の下で読み取る；brag-plan.md のシーン数と合計をクロスチェック | 正確 + クロスチェック |
Remotion .tsx | <Sequence from= durationInFrames=> ÷ フレームレート；<TransitionSeries.Transition presentation=> | リテラルおよび N * フレームレート は正確；計算値は スキップされ、推測されない |
静的に読み取れないものは、仮定されるのではなく、メモとして報告されます — springTiming の期間や from={computeIt()} はフラグされ、除外されます。
これが存在する理由。 HyperFrames の check は、ヘッドレス Chrome でシークされたコンポジションタイムラインを検証します。brag のデリバリーゲートはレンダリング前のスナップショットで停止します。Remotion には同等のゲートが全くありません。それらのどれもエクスポートされた MP4 を確認しないため、エンコーダのバグ、古いレンダリング、またはエクスポート時のドロップフレームが気付かれずに出荷されます。このツールがそのギャップを埋めます — そして、プロジェクト自身のチェックがパスしても audit を実行する価値がある理由です。
仕様で要求されたフェードトゥブラックは、黒フレームの欠陥として報告されません。宣言されていない黒だけが指摘事項です。
トランジション、カメラ、ペーシング — craft
「このカットはどうか」「どのトランジションが使われているか」「編集を分析して」「カメラは何をしているか」「なぜこれが速く感じるか」という場合 — index ではなく craft を使用してください。
llvideo craft VIDEO
llvideo craft VIDEO -q "00:14 のカットはビートに合っていますか？"
index は動画全体を 1 fps でサンプリングします。これは 何が起こっているか には適していますが、どのようにカットされているか には役に立ちません。ハードカットは1フレームを占めるため、1 fps ではカットの両側のショットは見えても、トランジションそのものは見えません。craft は異なる方法で動作します：
- 無料のローカルパスがすべてのフレームをスコアリングし、候補トランジションを見つけます。これにより、通常の検出器では捕捉できないソフトブレンドも捉えられます — 1秒のクロスフェードは約 0.025 でピークに達しますが、シーン検出は 0.12 でトリガーされます。
- 次に、各候補が タイトなウィンドウで 8 fps で再検査 され、モデルがトランジションをフレームごとに確認できるようにします。
- 各ウィンドウの明るさが ffmpeg で測定 されます。これにより、ブラックスルー fade とクロスフェードが区別されます。これがないと、モデルはフェードトゥブラックをクロスフェードと呼びますが、これにより正しくなります。
ショットリスト（サイズ、カメラムーブ、構図）、トランジションリスト（タイプ、正確な長さ、カットがそこで機能する理由）、ペーシング統計、色と照明を返します。
既知のトランジションを含む動画に対して検証済み — 4/4 タイプが正確、長さの誤差は 0.2 秒以内：
| 構築 | 検出 |
|---|---|
| ハードカット、瞬間 | hard_cut、瞬間 |
| クロスフェード、1.0秒 | crossfade、1.0秒 |
| フェードトゥブラック、0.6秒 | fade_to_black、0.5秒 |
| ワイプ左、0.8秒 | wipe、0.63秒 |
また、ウィップパンを含む連続ハンドヘルドテイクでは、カットを捏造する代わりに、正しく 1ショット、0トランジション を報告しました。
カメラムーブはカットではありません。 ウィップパン、高速ティルト、ラックフォーカスは、低フレームレートでは編集とまったく同じに見えます。craft はそれらを区別するように構築されています。index はそうではありません。質問が編集に関するものであれば、craft を使用してください。
フラグ：--zoom-fps 12（非常に高速なカット用） · --max-windows 12（より忙しい編集用） · --no-zoom（クローズパスをスキップ、安価だが精度はかなり低下）
画面上のテキストは失敗モードです。真剣に受け止めてください。
モデルはぼやけたテキストを自信を持って読み、間違えます。実際の映像で測定 — 同じモーションブラーの車のダッシュボードを3回質問：
呼び出し1: "642" "55 F" "330 mi"
呼び出し2: "23.9" "65 F" "330"
呼び出し3: "6:42" "55 F" "330 mi"
単一の回答には問題をフラグするものは何もありません。したがって、単一の回答に依存しないでください：
llvideo index VIDEO --verify 3
これによりクエリが3回実行され、どの読み取り値が 安定（毎回同一）で、どの読み取り値が 不安定 であるかが報告されます。不安定な読み取り値は、「ディスプレイは存在するが判読不能」として扱ってください。不安定な読み取り値が重要な場合は、フル解像度の静止画をエクスポートして自分で読んでください：
llvideo stills VIDEO --at 00:11 --width 1920
回答が行動に移される場合は常に --verify 3 を使用してください：画面収録のエラーメッセージ、ダッシュボードの数字、画面上のコード、価格、名前。追加の実行ごとに、最初の実行とほぼ同じコスト — ペニー単位です。
レンダリングの監査 — audit
動画（Remotion、HyperFrames、brag、ffmpeg、Veo）を作成した後、あなたはそれを見たことがありません。出荷前にチェックしてください：
llvideo audit out.mp4 # 無料の測定チェックのみ
llvideo audit out.mp4 --craft # プラストランジションとカメラ
llvideo audit out.mp4 --spec intent.json # プラス、要求した内容との差分
無料のチェックは、実際に出荷されるバグを捕捉します。 モデル不要、トークン不要、ネットワーク不要：
- 黒または白の 最初/最後のフレーム — 最も一般的なエクスポート欠陥、タイムラインの1つずれ
- ボディ内部の黒ギャップとフリーズした範囲
- EBU R128 ラウドネス とトゥルーピーククリッピング、-14 LUFS プラットフォームターゲットに対して
- 無音ギャップ、「オーディオトラックが実質的に空」
- 宣言されたフレームレートと実際のフレームレート、解像度、ビットレート
- フレームエッジに押し付けられた明るいディテール（タイトルセーフヒント）
検証済み：意図的に仕組まれた5つの欠陥すべてを捕捉し、実際のプロフェッショナル映像では ゼロの指摘でCLEAN を返します。狼少年になることはありません。
すべての指摘は、それが 測定済み（ffmpeg がそう言い、数値付き）か、判断済み（モデルがそう考えている）かを示します。判断済みの指摘を事実として決して提示しないでください。
終了コードは、ブロッカーがある場合のみ 1 になります。そのため、CI ゲートとして機能します。
インテントとの差分
動画がどうあるべきかを書き、それから差分を取ります：
{
"duration_seconds": 30,
"duration_tolerance": 0.5,
"aspect": "16:9",
"transitions": [
…