メインコンテンツへ移動
AIチュートリアル

CDAFでAIエージェントに高速で検証済みの動画コンテキストを提供する

このチュートリアルでは、CDAFのインストール、タイムスタンプ付きサイドカーの生成、ソース動画との照合、テキストのAIワークフローへの統合方法を説明します。さらに、バッチ処理、詳細プロファイル、エージェントスキルのインストール、Python APIの使用方法、ローカル生成オプション、動画ライブラリを効率的に検索するテクニックについても学べます。

約16分で読了
CDAFでAIエージェントに高速で検証済みの動画コンテキストを提供

CDAFの役割

CDAF（Cached Descriptive Asset Filesの略）は、動画用のオープンなサイドカーフォーマットです。動画と同じベース名を使い、タイムスタンプ付きのプレーンテキスト形式の説明を動画の隣に保存します。たとえば、sunset-drone.mp4にはsunset-drone.cdafを組み合わせます。

目的は、動画を一度説明し、その説明を後続のAIタスクで再利用できるようにすることです。質問ごとに同じ映像を動画理解モデルへ送る代わりに、エージェントははるかに小さいCDAFファイルを検証して読み取れます。

footage/
sunset-drone.mp4
sunset-drone.cdaf

元の動画は変更されず、通常の動画ソフトウェアで再生できます。サイドカーはUTF-8テキストで構成され、小さなメタデータヘッダーの後に、言語モデル向けに最適化されたMarkdown形式の説明が続きます。

サイドカーを安全に再利用できる理由

CDAFヘッダーには、動画の正確なSHA-256ハッシュとバイトサイズが記録されます。準拠ツールはこれらの値を使って、説明が有効なままかどうかを判定します。動画が変更された場合、サイドカーは古くなるため使用しないでください。

--- CDAF/1.0
video: sunset-drone.mp4
sha256: 4a7d1ed4…
bytes: 48211394
duration: 00:00:31.500
generator: gemini-2.5-flash
created: 2026-08-26T14:03:12Z
---

## Summary
31秒間の、ゴールデンアワーの海岸沿いの高速道路を撮影した空撮ドローン映像…

## Segments
[00:00.0-00:05.2] 海岸線を広く捉えた空撮の導入ショット…
[00:05.2-00:12.8] ドローンが前進しながら下降する…

## Transcript
（発話なし）

## On-screen Text
（なし）

## Tags
ドローン, 空撮, 海岸沿いの高速道路, ゴールデンアワー, 夕日

本文には、要約、タイムスタンプ付きセグメント、トランスクリプト、画面上のテキスト、タグを記載できます。規範となるフォーマット、鮮度の意味、バージョニング規則、セクション文法については、プロジェクトのCDAF 1.0仕様を参照してください。

主な機能

  • 検証済みの再利用: SHA-256とバイトサイズのメタデータにより、サイドカーと説明対象の正確な動画を紐付けます。
  • 読みやすいテキスト形式: エージェントは、動画を再度デコードせずに説明を利用、検索、再利用できます。
  • タイムスタンプ付きセグメント: セグメント範囲をクリップ選択やカットリスト作成に利用できます。
  • 依存関係ゼロのコア: 解析、シリアライズ、ハッシュ計算、鮮度チェック、セグメント抽出にはPython標準ライブラリを使用します。
  • バッチ指向CLI: コマンドラインツールでディレクトリ内のサイドカーを生成でき、すでに最新のものはスキップできます。
  • 複数の詳細プロファイル: 生成ではbrief、standard、richの出力に対応しています。
  • エージェントスキル: パッケージ化されたスキルにより、動画を分析する前に検証済みサイドカーを確認する方法をコーディングエージェントに教えられます。
  • ローカル生成（オプション）: リポジトリには、APIキーなしでローカルモデルを使って生成する--localプロバイダーが含まれています。
  • プロービング（オプション）: CDAFはffprobeを使って再生時間、解像度、フレームレートのメタデータを取得できます。ffprobeが利用できない場合も、機能を縮退させて正常に動作します。

エージェントスキルのインストール

対応するコーディングエージェントにサイドカー優先のワークフローを教える最も簡単な方法は次のとおりです。

npx cdaf-skill

デフォルトでは、スキルを~/.claude/skills/cdafにインストールし、複数のプロジェクトで利用できるようにします。その他の対応インストールモードは次のとおりです。

npx cdaf-skill --project
npx cdaf-skill --dir <path>
npx cdaf-skill --print
  • --projectは、現在のプロジェクトの./.claude/skills/cdafにインストールします。
  • --dirは、指定したディレクトリにインストールします。
  • --printは、スキルを標準出力に書き出すため、別のエージェントフレームワークに貼り付けられます。

インストーラーは安全に再実行できます。変更されていないスキルはそのまま残り、変更されたスキルは置き換える前にSKILL.md.bakとしてバックアップされます。

動画ファイルを分析する前に、同じベース名の.cdafファイルを探してください。そのbytesとsha256のヘッダー値が動画と一致する場合は、動画を処理する代わりにそのファイルを読み取ります。

CDAF CLIのインストール

Python CLIにはPython 3.10以降が必要です。PyPIでのリリースはまだ予定段階のため、現在のREADMEではリポジトリから直接インストールします。

pip install "cdaf[generate] @ git+https://github.com/UditAkhourii/cdaf.git#subdirectory=cli"

クローンしたリポジトリから作業している場合は、ローカルのcliディレクトリからCLIをインストールします。

pip install ./cli[generate]

生成機能はGemini Files APIを使用します。Google AI StudioからGemini APIキーを取得し、環境に設定してください。

macOSとLinux

export GEMINI_API_KEY=your-key

Windows PowerShell

$env:GEMINI_API_KEY="your-key"

映像はご自身のAPIキーを通じて処理されます。既存のサイドカーを読み取る、または検証するだけのコマンドには、APIキーも生成用の依存関係も必要ありません。

サイドカーの生成

1つ以上の動画をディレクトリに置き、そのディレクトリに対してcdaf generateを実行します。

cdaf generate ./footage

CDAFは動画を説明し、ベース名が一致するサイドカーを作成します。再度実行すると、サイドカーがすでに最新の動画はスキップされます。

詳細プロファイルの選択

--detailを使って、ドキュメント化された3つの生成プロファイルのいずれかを選択します。

cdaf generate ./footage --detail brief
cdaf generate ./footage --detail standard
cdaf generate ./footage --detail rich

下流タスクで必要となる説明コンテキストの量に応じて、プロファイルを選択します。--modelでGeminiモデルを選択したり、--forceで再生成を要求したりすることもできます。

cdaf generate ./footage --model <gemini-model>
cdaf generate ./footage --force

動画ライブラリの状態を確認する

statusコマンドを使用すると、サイドカーをFRESH、STALE、MISSINGに分類できます。

cdaf status ./footage
  • FRESH: サイドカーが現在の動画と一致しています。
  • STALE: サイドカーは存在しますが、記録された識別情報が動画と一致しなくなっています。
  • MISSING: 一致するCDAFサイドカーがありません。

このコマンドにはAPIキーも生成用の依存関係も必要ないため、既存のアセットライブラリを軽量にチェックする用途に適しています。

検証済みの説明を読む

エージェント、スクリプト、プロンプトでサイドカーの本文を使用したい場合は、cdaf readを使います。

cdaf read ./footage/sunset-drone.mp4

このコマンドは説明を出力する前にハッシュを検証します。古いサイドカーの出力を拒否するため、鮮度のルールをエージェントの指示だけに頼らず、ツール側で維持できます。

自動化でサイドカーを検証する

検証コマンドは、一致するサイドカーが正しい形式で、かつ最新である場合にのみ正常終了します。

cdaf validate ./footage/clip.mp4

有効で最新のサイドカーに対してのみ終了ステータス0を返すため、スクリプトや継続的インテグレーションのワークフローで使用できます。検証にAPIキーやオプションの生成用依存関係は必要ありません。

PythonからCDAFを使う

コアPython APIを使うと、サイドカーを検索、読み込み、検証してから、その本文を言語モデルに渡せます。

from cdaf import load, check_freshness, sidecar_path_for

video = "footage/sunset-drone.mp4"
sidecar = load(sidecar_path_for(video))

if check_freshness(video, sidecar) == "fresh":
    context_for_llm = sidecar.body

このパターンがCDAF統合の基本です。想定されるサイドカーのパスを導出し、ファイルを解析し、動画に対する鮮度を検証し、結果がfreshの場合にのみsidecar.bodyを使用します。

パッケージのコアは、シリアライズ、チャンク単位のSHA-256計算、セグメント抽出にも対応しています。これらの処理では標準ライブラリのみを使用します。生成固有のコードは、生成が要求された場合にのみインポートされます。

サイドカー優先のエージェントワークフローを構築する

  1. 編集、検索、または質問応答タスクの一部として動画パスを受け取る。
  2. 同じベース名の.cdafファイルを探す。
  3. 現在の動画に対するサイドカーの鮮度を確認する。
  4. 最新であれば、別の動画理解処理を実行せずにテキストを読む。
  5. 古い、または存在しない場合は、内容を信頼する前に再生成する。
  6. 要約、セグメント、トランスクリプト、画面上のテキスト、タグを下流タスクのコンテキストとして使用する。

同梱のエージェントスキルでは、探索中に軽量なサイズチェックを行い、重要な判断には完全なハッシュチェックを行うことを推奨しています。アプリケーションは操作に適した検証レベルを使用しつつ、古い説明を信頼してはならないという基本ルールを維持する必要があります。

高度なヒント

動画コレクションをテキストとして検索する

動画にサイドカーを用意すると、エージェントやコマンドラインツールはすべての動画を開く代わりに.cdafファイルを検索できます。タグと説明により、人物のいない夕暮れの海岸ショットといったリクエストを、アセットライブラリに対するテキスト検索に変換できます。

セグメントを編集判断に変換する

[00:05.2-00:12.8]のようなタイムスタンプ付きの行は、プログラムによる編集ツールがクリップやシーケンスに変換できる範囲を提供します。READMEでは、Remotion、HyperFrames、プロンプトから編集するツールを、この構造の恩恵を受けられるワークフローとして具体的に挙げています。

トランスクリプトのタイミングを再利用する

音声がある場合、Transcriptセクションは会話をタイムラインに対応付けます。編集ワークフローでは、別の理解処理を行う代わりに、この情報をキャプションや音声同期に再利用できます。

オプションのffprobeメタデータを使う

ffprobeが利用可能であれば、CDAFのprobeコンポーネントは再生時間、解像度、フレームレートのメタデータを収集できます。ffprobeがない場合もエンジンは適切に処理を継続するため、このオプション統合によって基本的なサイドカー操作が妨げられることはありません。

ローカル生成を検討する

リポジトリには--localで利用できるローカルプロバイダーが含まれています。APIキーを使用せず、ローカルモデルで生成するためのものです。現在サポートされているローカルモデルの設定については、リポジトリのローカルプロバイダー実装を確認してください。

バックエンドをフォーマットから分離する

CDAF自体はモデルに依存しません。Geminiは付属のリモート生成バックエンドであり、その他の動画言語モデルのバックエンドも同じSidecar型の背後に組み込めます。追加のClaude、GPT、ローカルVLMバックエンドはロードマップに記載されているものであり、現時点で利用できるとは限りません。

ベンチマークを再現する

リポジトリには、ffmpegを使用してスクリプト化されたレシピから動画を合成する客観的なベンチマークが含まれています。各ステージを順番に実行します。

python benchmarks/bench.py make
python benchmarks/bench.py run
python benchmarks/bench.py report

最初のステップでは ffmpeg が必要で、2番目のステップでは GEMINI_API_KEY が必要です。最後のステップでは benchmarks/RESULTS.md が書き込まれます。報告された20問のテストでは、サイドカーの回答は20問中20問正解を達成し、ダイレクト動画の19問中20問を上回りました。一方、1問あたりの平均プロンプトトークン数は3,066ではなく303でした。これらはリポジトリのベンチマーク結果であり、映像、モデル、プロンプト、環境によって変わる可能性があります。

現在の制限とロードマップ

READMEでは、いくつかの項目が現在の機能ではなく、将来の作業として挙げられています。PyPIリリース、MCPサーバー、ホスト型コンバーター、追加のジェネレーターバックエンド、NodeまたはTypeScriptエンジンへの移植、自然映像向けベンチマークの拡張、署名付きサイドカーなどです。現在は、文書化されたGitベースのPythonインストール方法と既存のCLIを使用し、これらのロードマップ項目が利用可能だと想定しないでください。

結論

CDAFは、繰り返し行う動画分析を、検証して読み取るワークフローに変換します。サイドカーを一度生成してソース動画の隣に保管し、アセットを使用するたびに検証して、その本文を下流のエージェントに渡します。フォーマットに含まれるハッシュにより、編集後の誤った再利用を防げます。また、要約、タイムスタンプ、トランスクリプト、テキスト、タグによって、動画ライブラリの検索と自動化が容易になります。

CDAFはMITライセンスで提供されています。ソースコード、仕様、サンプル、ベンチマークの詳細、エージェントスキルは、CDAF GitHubリポジトリで入手できます。