video-edit

編集と構成

どの経路を使うか

1. VideoDB コネクタツールがある場合（render_timeline、upload_media、download_timeline_render などの名前）：それらを使用します。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 の返信があった場合は、もう一度ポーリングしてください。書き込み処理を再実行しないでください。新しいジョブが開始されます。処理が完了したら player_url を共有します。

以下の処理では、ffmpeg、moviepy、ローカルエンコードに切り替えないでください。すべて VideoDB のサーバー上で実行されます。

コネクタツールを使用する場合

まずアセットを準備します。 すべてのメディアには VideoDB の ID が必要です。動画は m-、音声は a-、画像は img- です。upload_media(url) には公開 URL または YouTube のリンクを指定します（音楽ファイルの場合は media_type="audio"、ロゴの場合は "image"）。list_videos、list_audios、list_images を使うと、すでにあるメディアを確認できます。ローカルファイルはコネクタ経由でアップロードできません。ユーザーは https://console.videodb.io からアップロードします。

1 回の呼び出しですべてを合成できます： render_timeline(tracks=[...], resolution="1920x1080", background="#000000")。各トラックにはクリップが含まれ、各クリップにはタイムライン上の開始位置（秒）を示す start、duration、asset があります。トラックは z_index の値が大きいものほど上に重なります。

ユーザーの要望	クリップ内のアセット
ソースの 10 秒目からの動画	{"type": "video", "id": "m-...", "start": 10, "volume": 1}
音量 20％の BGM	独立したトラックに {"type": "audio", "id": "a-...", "volume": 0.2} を指定
タイトルまたはローワーサード	{"type": "text", "text": "Launch day", "font": {"size": 64, "color": "#FFFFFF"}, "background": {"color": "#000000", "opacity": 0.6, "border_width": 12}} を指定し、クリップの fit: "contain" と position: "bottom" を設定
ロゴまたは画像	{"type": "image", "id": "img-..."} を指定し、クリップの scale: 0.2、position: "top_right"、opacity: 0.9 を設定
音声から字幕を作成	{"type": "caption", "src": "auto", "animation": "box_highlight"}。動画はすでに文字起こしされている必要があります（generate_transcript または spoken_words アナライザーの実行）。そうでない場合、レンダリングに字幕は表示されませんが、エラーも発生しません
クリップ間のフェード	クリップに transition: {"in": "fade", "out": "fade", "duration": 0.5} を指定
SNS 向けの縦型動画	resolution="1080x1920" とクリップの fit: "crop" を指定

テキストアセット：width と height が適用されるのは fit: "contain" の場合だけです。デフォルトの crop では、テキストボックスがフレームいっぱいに拡大されます。

タイトルと控えめな音楽を加えた 20 秒のクリップの例：

render_timeline(resolution="1920x1080", tracks=[
  {"z_index": 0, "clips": [{"start": 0, "duration": 20, "asset": {"type": "video", "id": "m-abc", "start": 30}}]},
  {"z_index": 1, "clips": [{"start": 0, "duration": 4, "fit": "contain", "position": "bottom",
                            "transition": {"in": "fade", "out": "fade"},
                            "asset": {"type": "text", "text": "Launch day", "font": {"size": 64}}}]},
  {"z_index": 0, "clips": [{"start": 0, "duration": 20, "asset": {"type": "audio", "id": "a-xyz", "volume": 0.2}}]}
])

MP4 ファイル： download_timeline_render(stream_url) を呼び出し、完了をポーリングして、ダウンロード URL を共有します。

AI による音楽、ナレーション、画像、動画の生成と吹き替え： コネクタでは利用できません。Claude Code では SDK を使って実行できます（以下を参照）。チャットでは、代わりにアップロードするホスト済みの音声または画像の URL をユーザーに尋ね、生成には Claude Code または SDK が必要だと伝えてください。

Python SDK を使用する場合（Claude Code）

import videodb が失敗する場合は、先に /videodb:setup でセットアップしてください。詳しいガイド：${CLAUDE_PLUGIN_ROOT}/python/reference/editor.md、生成について：${CLAUDE_PLUGIN_ROOT}/python/reference/generative.md。

from dotenv import load_dotenv; load_dotenv(".env")
import videodb
from videodb.editor import Timeline, Track, Clip, VideoAsset, AudioAsset, TextAsset, Fit, Transition
conn = videodb.connect(); coll = conn.get_collection()
video = coll.upload(url="https://www.youtube.com/watch?v=VIDEO_ID")
music = coll.generate_music(prompt="warm acoustic background", duration=20)   # or coll.upload(url=..., media_type="audio")
voice = coll.generate_voice(text="Welcome to the show", voice_name="Default")
timeline = Timeline(conn); timeline.resolution = "1920x1080"
v = Track(); v.add_clip(0, Clip(asset=VideoAsset(id=video.id, start=30), duration=20))
a = Track(); a.add_clip(0, Clip(asset=AudioAsset(id=music.id, volume=0.2), duration=20))
timeline.add_track(v); timeline.add_track(a)
stream_url = timeline.generate_stream()
print(f"https://console.videodb.io/player?url={stream_url}")

吹き替え：coll.dub_video(video.id, language_code="es")。