video-search

動画から場面を探す、または動画に質問する

どの方法を使うか

1. VideoDB コネクタツールが利用できる（upload_media、search_video、ask_video、understand_video などの名前）：それらを使います。Claude のウェブ版、デスクトップ版、モバイル版のチャットと Cowork ではこの方法を使います。何もインストールせず、API キーも求めないでください。
2. VideoDB ツールは利用できないが、シェルは使える（Claude Code、Cowork、Python を実行できるエージェントなど）：VideoDB API キーを親しみやすい一文で尋ねます（https://console.videodb.io で無料、クレジット 20 ドル分付き、カード不要）。ユーザーがチャットなど、どのような方法でキーを教えてくれた場合でも、自分でプロジェクトの .env に VIDEO_DB_API_KEY として保存し、決して表示せず、このファイル末尾にある Python SDK の方法で続行します。Claude Code では、/mcp を使ってから videodb を認証する方法も使えます。
3. VideoDB ツールもシェルも使えない：Claude のチャットを使っています。次の文だけを、依頼に合わせて調整して返信します。「VideoDB はまだ接続されていません。設定 → コネクタを開き、VideoDB を見つけて［接続］をクリックし、ログインしてください（無料、カード不要）。その後、もう一度この依頼を送っていただければ、こちらで対応します。」ここでは API キー、.env、シェル、Claude Code、/mcp について触れないでください。チャットではいずれも該当せず、コードを実行できないため、チャットに貼り付けられたキーは使用できません。

ユーザーとのやり取りでは、返信に「index」、「indexed」、「indexing」と書かないでください。「検索可能になりました」（「発言された内容と画面に映っている内容から検索できるようになりました」）と表現し、処理名ではなく「文字起こし」と言ってください。一度に表示する進捗状況は一行にとどめ、その後に結果を伝えます。

時間のかかる処理では status: processing が返されます。返信には output_url と、ポーリングに使うツール名（poll_with、古いサーバーでは retry_with）が含まれます。処理が done になるまで、そのツールを output_url とともに呼び出してください。processing が何度も続けて返されるのは正常です（YouTube へのアップロードが 10 分かかる場合、処理には約 5 分かかります）。結果が空の done が返された場合は、もう一度ポーリングしてください。書き込み処理を再実行しないでください。二つ目のジョブが開始されます。

コネクタツールを使う場合

1. 動画を取得します。 まず、動画のタイトルまたはリンクに含まれる語句を使って search_videos_by_title(query) を実行します。すでにアカウントにある場合は、m- ID を再利用してください。見つからない場合は、YouTube リンクまたは公開 URL に対して upload_media(url) を実行し、done になるまでポーリングして、m- ID と秒単位の length を控えます。ユーザーが URL を持っておらず、ファイルがパソコンにある場合、コネクタはローカルファイルを受け取れません。https://console.videodb.io のコンソールからアップロードするよう案内し、その後 m- ID を使って続行してください。

2. 高速パスかインデックスパスを選びます。

単発の「何と言っていたか」という質問では、高速パスがデフォルトです。 文字起こしを自分で読み、該当する場面を探します。

generate_transcript(media_id)                                   # a job; poll until done (instant if already transcribed)
get_transcript(media_id, timestamped=true, segmenter="sentence")   # sentence segments with start and end seconds

セグメントを確認し、ユーザーが説明した場面を探して開始時刻と終了時刻を控え、手順 4 に進みます。インデックスは不要です。注意点が 2 つあります。文字起こしジョブの done 結果にはテキストと単語リストが含まれますが、リストは途中で切り詰められるため、必ず get_transcript で読み取ってください。また、デフォルトのセグメンターは 1 単語につき 1 セグメントで、上限は 2000 セグメントです。そのため、segmenter="sentence"（数時間分の音声を処理できます）または start と end のウィンドウを指定してください。ツールが動画を切り詰めてしまう場合や、ユーザーが同じ動画について繰り返し質問する場合は、インデックスパスを使う目安です。

一致するものがない場合は、その旨をはっきり伝え、曖昧な一致をユーザーの質問に対する回答として無理に扱わないでください。YouTube にアップロードされた動画が、より長い講演の抜粋であることもあります。最も近い場面を、そのように明記して提示するか、別の動画を尋ねてください。

インデックスパス。 質問が発言内容ではなく映像に映っているものについての場合、件数や厳密なフィルターを求められている場合、同じ動画やライブラリについて何度も質問される場合、または文字起こしが長すぎて読めない場合に使います。まず list_indexes(video_id) を確認します。準備できているものがなければ、次を実行します。

understand_video(video_id, analyzers=[
  {"type": "spoken_words", "name": "transcript"},
  {"type": "vlm", "name": "scene", "config": {"prompt": "Describe the scene and any on-screen text."}}
])

すべてのアナライザーが done になるまで get_understanding(video_id, understanding_id) をポーリングし、その後、アナライザーごとに 1 つずつインデックスを作成します。

create_index(video_id, understanding_id, analyzer_name="transcript")
create_index(video_id, understanding_id, analyzer_name="scene")

音声だけが重要な場合（ポッドキャストや通話など）は、spoken_words アナライザーだけを実行します。物体や件数（「車はいくつあるか」）については、{"type": "object_detection"} または {"type": "activity_recognition"} を追加します。

3. 取得します（インデックスパス）。

ユーザーの要望	呼び出し
タイムスタンプ付きの場面	search_video(video_id, query, include_clip=true)
出典付きの文章による回答	ask_video(video_id, question, include_sources=true)
ライブラリ全体を対象にする	search_collection(query) または ask_collection(question)
件数と分類（「最も多く登場する物体は何か」）	aggregate_index(video_id, index_name="objects", group_by="frames.detections.label")
厳密なフィルター（「label = car のシーン」）	query_index(video_id, index_name, filter)
追加質問を含む詳細な調査	search_video(..., mode="deepsearch") を実行し、次の呼び出しで session_id を渡す

4. 提示します。 該当する場面は、開始から終了までを mm:ss 形式で示し、一致した語句も添えます（文字起こし、または各検索結果の text を引用します）。include_clip を設定した場合は、各クリップの player_url も提示してください。一致した場面をまとめたクリップを作成します：generate_clip(video_id, timeline=[[start, end], ...])（秒単位。前後に数秒の余裕を持たせると見やすくなります）。完了するまでポーリングし、その後 player_url を共有します。

index_spoken_words または index_scenes（v1）でインデックス化された古い動画は、legacy_search_video と legacy_search_collection で検索します。

Python SDK（Claude Code）を使う場合

import videodb が失敗する場合は、まず /videodb:setup でセットアップしてください。リファレンス全文：${CLAUDE_PLUGIN_ROOT}/python/SKILL.md および ${CLAUDE_PLUGIN_ROOT}/python/reference/search.md。

from dotenv import load_dotenv; load_dotenv(".env")
import videodb, time
conn = videodb.connect(); coll = conn.get_collection()
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
u = video.understand(analyzers=[{"type": "spoken_words", "name": "transcript"},
                                {"type": "vlm", "name": "scene", "config": {"prompt": "Describe the scene."}}])
u.wait_until_complete()
for a in u.list_analyzers():
    if a.is_successful: video.index(source=a, name=a.name).wait_until_complete()
r = video.search("the part about pricing")
for s in r.shots: print(f"[{s.start:.0f}s-{s.end:.0f}s] {s.text}")
print(r.compile())   # stream URL of the matches; player: https://console.videodb.io/player?url={STREAM_URL}