analyze-footage

映像を分析する — AI による動画理解

TwelveLabs MCP を使って、ユーザーが既に所有している動画ファイルを理解できるよう支援します。これにより、エージェントは映像に何が映っているかを確認する「目」を得られます。

remotion-production スキルを読み込み、video-analysis ルールを確認してください。

ワークフロー

1. 動画ファイルを特定する

分析する動画ファイルをユーザーに尋ねるか、ファイルを探してください。

# Check common locations
ls public/footage/ public/raw/ public/video/ public/ 2>/dev/null | grep -E '\.(mp4|mov|avi|mkv|webm)$'

ファイルが見つからない場合は、映像が保存されている場所をユーザーに尋ねてください。

2. TwelveLabs にアップロードする

動画ファイルごとにアセットとしてアップロードします（分析にはインデックスは不要です）。

create-asset:
  file: [absolute path, e.g. /path/to/project/public/footage/source-video.mp4]

返されたアセット ID を控えてください。次の呼び出しでアセットの準備ができていないと表示された場合は、数秒待ってから再試行してください。

3. コンテンツを分析する

シーンの内訳 — video-analysis ルールに示されている、タイムスタンプ付きのシーンマップです。

async-analyse-video:
  assetId: [asset ID]
  modelName: "pegasus1.5"
  analysisMode: "time_based_metadata"
  segmentDefinitions: [one "shots" definition with fields: description, shot_type, people, on_screen_text, usable]

get-analyse-task を 5～10 秒ごとにポーリングし、ready になるまで待ちます。その後、result.data（セグメント定義の id をキーとする JSON 文字列）を解析してください。最大 2 時間の動画に対応しています。

「どのショットに製品が映っていますか？」「30 秒のプロモーション用クリップを選んでください」など、具体的な質問には sync-analyse-video を使います（assetId、modelName: "pegasus1.5"、prompt、および開始・終了時刻を数値で取得するための jsonSchema を指定します）。同期分析で処理できる動画は最大 1 時間です。

必ず modelName: "pegasus1.5" を渡してください。サーバーのデフォルトモデルは API から削除されています。

次の形式で提示してください。

📹 Video Analysis: [filename]

Scenes:
  0:00 - 0:15  │ Logo animation, dark background
  0:15 - 0:45  │ Speaker at podium, introducing topic, conference setting
  0:45 - 1:20  │ Product demo on laptop screen, close-up
  1:20 - 1:45  │ Audience reaction, medium shot, clapping
  1:45 - 2:00  │ Call to action slide, company branding

Key Elements (from the segment fields):
  - People: 1 speaker, audience (~30 people)
  - Shot types: wide, medium, close-up, screen capture
  - Text on screen: company logo, product name
  - Setting: conference room, professional lighting

結果を保存したら（例：analysis/[filename].json）、delete-asset（assetId）でアセットを削除してください。アセットはアカウントのストレージ容量を使用します。

4. 絞り込み検索（ユーザーに具体的な要望がある場合）

1 つのファイルについては、sync-analyse-video を直接呼び出してください（必要に応じて startTime／endTime で範囲を指定できます）。動画ライブラリ全体から該当する場面を探すには、ライブラリを一度インデックス化してから検索してください。

start-video-indexing-task:
  folderFilePath: [absolute path to the footage folder]   (or videoFilePath for one file)
→ poll get-indexed-asset until ready
search:
  query: "the part where the product is demonstrated"

search は開始・終了時刻とサムネイルを含む、順位付けされたセグメントを返しますが、その内容は説明しません。詳しい情報が必要な場合は、検索結果を分析してください。

5. クリップを提案する

分析結果に基づいて、ユーザーの動画に最適なクリップを提案してください。

🎬 Recommended Clips for a 30-second promo:

1. Opening (0:00-0:05)
   → Use 0:45-0:50 of source — product demo close-up, high energy
   
2. Main content (0:05-0:20)  
   → Use 0:50-1:05 of source — full demo walkthrough
   
3. Social proof (0:20-0:25)
   → Use 1:20-1:25 of source — audience clapping
   
4. CTA (0:25-0:30)
   → Use 1:45-1:50 of source — branded slide

6. Remotion での使用方法を示す

提案した各クリップについて、Remotion のコードを示してください。ソース範囲は、@remotion/media の <Video> における trimBefore（開始タイムスタンプ）と durationInFrames（クリップの長さ）に変換します。公式の remotion-markup スキル（video-editing.md）に示されているように、TransitionSeries または Track でクリップをつなぎ合わせてください。skills/remotion-production/rules/video-analysis.md に詳しい例があります。

import { Video } from "@remotion/media";
import { staticFile, useVideoConfig } from "remotion";

const { fps } = useVideoConfig();

// Opening (0:00-0:05) ← source 0:45-0:50
<Video
  name="Opening"
  src={staticFile("footage/source-video.mp4")}
  trimBefore={45 * fps}
  durationInFrames={5 * fps}
  objectFit="cover"
  style={{ width: "100%", height: "100%" }}
/>

TwelveLabs の小数のタイムスタンプは、最も近いフレームに丸めてください。例：Math.round(45.6 * fps)。

ヒント

• Remotion から staticFile() を使って public/ からの相対パスで参照できるよう、動画ファイルを public/（理想的には public/footage/）に置いてください。create-asset には同じファイルの絶対パスを渡します。
• 制限：同期分析は最大 1 時間、非同期分析は最大 2 時間、直接アップロードは最大 4 GB です。
• インデックスは search にのみ使用します。インデックスは多くの検索で再利用でき、アセットは分析ごとに作成します（分析後に削除してください）。
• その他については、公式ドキュメント（https://docs.twelvelabs.io および llms.txt）を参照してください。
• 分析した映像に Pexels のストッククリップを組み合わせて、不足部分を補ってください。