scenario-video-assembly

シナリオ動画の組み立て

概要

Scenario の MCP インターフェースには編集ツールがありません。コンポジター、連結ツール、トリマー、キャプション追加ツールはすべて、model_run を通じて実行する決定論的モデルです。コンポジター、連結ツール、トリマーの ID は固定されており、以下に記載しています。Scenario にはキャプション追加ツールが 2 つあるため、recommend で検出します。接続と基本的な操作手順については scenario スキルを、クリップ自体については scenario-video を参照してください。ここに記載されている関連スキルが利用可能なスキルにない場合は、インストールするようユーザーに依頼してください（npx skills add scenario-labs/skills --skill <name>）。無人で処理を進める場合は、ツールのスキーマに基づいて続行し、不足している点を明示してください。

クイックリファレンス：まずバックエンドを選択

必要な処理	モデル
クリップを最初から最後まで、必要に応じてトランジションを追加	model_scenario-video-concat
オーバーレイ、ベッド、タイトルなど、重ね合わせが必要なもの	model_scenario-compose-video
静止画レイアウト（サムネイル、シート、キービジュアル）	model_scenario-compose-image

これらの ID は定数です。それぞれの処理に対応する Scenario の決定論的ツールは 1 つだけなので、検出しても同じ ID を導き出すだけです。

Concat は順番に連結します。videos には 2～50 個のファイルを指定します（1 個は不可）。preserveAudio（デフォルトは true）は、各クリップ固有の音声トラックをカットに含めます。省略可能な transitions 配列の長さは「動画の数 - 1」である必要があります。各要素は文字列単体ではなく、{type, duration} 形式のオブジェクトです。type はスキーマに記載されている 18 種類の名前のいずれかです（デフォルトの fade は通常のクロスフェード、dissolve は別のエフェクト、none はハードカットです）。duration は 0.1～5 秒で、デフォルトは 0.5 です。全編をハードカットにするには配列を省略してください。あるショットから次のショットへのつながりを依頼されていない場合は、これが適切な呼び出し方です。

preserveAudio は同期を保証しません。連結したカットで、トランジションの有無にかかわらず、音声と映像がずれた事例が確認されています（執筆時点で確認済みの不具合）。セリフや効果音を含むクリップの連結結果は、必ず検証し、決してそのまま信用しないでください。出力に対して asset_get を実行し、properties.duration を入力の合計と比較します（各トランジションによってカットは最大でその duration 分短くなります）。次にダウンロードし、音声ストリームと映像ストリームの長さが一致していること（ダウンロードしたファイルのローカルでの調査は検証であり、編集ではありません）、および映像上で確認できる合図（カット、口が開く動き、衝撃）が音と一致していることを確認してください。音声を映像に同期させる必要がある場合は、代わりに Video Studio で組み立ててください。各クリップレイヤーはそれぞれのトラックを自身の startTime に配置するため、連結によるずれが発生する余地はありません。ただし、トランジションセットの代わりにハードカットまたはレイヤーごとのフェードを使います。Concat は、無音クリップや、後からベッドを追加するカットに適しています。

Video Studio は絶対時間のタイムラインです。layers には、startTime で配置し、zIndex で重ねる（数値が大きいほど前面）画像、動画、音声ソースを 1～50 個指定します。クリップ間に適用する配列ではなく、レイヤーごとの fadeIn／fadeOut を使うため、2 つのクリップ間のクロスフェードには concat を使用します。レイヤーには動画が少なくとも 1 つ必要なので、静止画に音楽ベッドを重ねる指定は拒否されます。

Video Studio の契約

レイヤーごとに、名前が紛らわしいタイミングの概念が3つあります。

• startTime と endTime は、タイムライン上にレイヤーを配置します。
• trimStart と trimEnd は、インポイントとアウトポイントではなく、ソースの先頭と末尾から削る量です。90秒のトラックの最初の20秒を再生するには、trimEnd: 70 を設定します。
• duration はレイヤーの長さを上書きします。トップレベルの duration は別のフィールドで、コンポジション全体の長さを設定し、durationMode が "custom" の場合にのみ適用されます。

すべて秒単位で、step: 0.1 です。そのため、フレーム単位で正確にカットできるとは約束しないでください。x と y はピクセル、パーセンテージ、または単語を指定する文字列で、anchor はレイヤーのどの位置を指定するかを表します。指定できる値は top-left、top-center、top-right、center-left、center、center-right、bottom-left、bottom-center、bottom-right です（中央は center のみ）。デフォルトは "top-left" です。右下にロゴを配置するには、x: "right"、y: "bottom"、anchor: "bottom-right" とします。パーセンテージで内側にずらさない限り、端にぴったり配置されます。

canvasMode と durationMode はどちらもデフォルトで "auto" となり、レイヤーから計算されます。カスタムフレームを指定するには、canvasMode: "custom" と数値の canvasWidth、canvasHeight を設定します（トップレベルに width／height はなく、レイヤーの文字列型の width／height とは異なり、これらは数値です）。カスタムの長さを指定するには、durationMode: "custom" とトップレベルの duration を設定します。fit が作用するのは、レイヤー自身の width と height も設定されている場合のみです。これらは x や y と同様に文字列です。クリップのフレームを調整するには、どちらもキャンバスサイズを示すピクセル数を文字列で指定します（width: "1920"、height: "1080"。これはスキーマ自体のデフォルト値 "0" と同じ形式です。パーセンテージの文字列も使用できます）。さらに "cover"（クロップ）または "contain"（レターボックス）を指定します。デフォルトの "fill" は引き伸ばします。オーバーレイレイヤーには、元のサイズのままであっても、明示的に width と height を指定してください。空欄にすると元のサイズが保持されると説明されていますが、実際には安定せず、1920x1080のキャンバス上で560x80の帯が1792x256で返されました。ここでの出力フィールドは videoOutputFormat、Image Studio では imageOutputFormat、結合ツールとトリミングツールでは outputFormat です。

レイヤーの type（image、video、audio、または mask）は省略可能で、省略した場合は source から推定されます。テキストレイヤーはありません。そのため、タイトル、ローワーサード、エンドカードは、画像レイヤーとして合成されたレンダリング済みPNGで渡されます。scenario-text-overlay を使えば、文字を正確にレンダリングできます。

作業例：3本のクリップ、BGM、字幕

1. すべてのソースについて、asset_get を実行して properties を確認します。実際の duration（音声にも含まれます）、動画の frameRate、動画と画像の両方の width／height を確認してください。8秒を指定しても、モデルが必ずちょうど8秒の素材を返すとは限りません。
2. それらを合計して各クリップの startTime を求めてから、model_schema_get で model_scenario-compose-video を確認します。
3. model_run を実行し、layers に計算した startTime を設定した3本のクリップ（zIndex: 0）、x／y／anchor で位置を固定したロゴPNG（zIndex: 1）、さらにクリップの合計時間に合わせて trimEnd でトリミングした音楽のオーディオレイヤーを指定します。自動の durationMode はBGMを含むすべてのレイヤーから長さを計算するためです。volume（0～2）と mute はレイヤーごとに設定でき、動画レイヤーにも適用されるため、どちら側からでもBGMの音量を調整できます。canvasMode: "custom" を設定し、canvasWidth と canvasHeight も指定します。fps の既定値は30で、1～120の整数を指定できます。クリップの計測済み frameRate が一致する場合は、四捨五入した値を設定してください。ステップ1で frameRate を確認したのはこのためです。
4. jobs_wait を実行したら、各クリップではなく完成した映像に字幕を付けます。model_scenario-caption-studio（Scenarioには字幕生成ツールが2種類あるため、これは作成時に選びます。recommend で再度確認してください）に video として渡すと、マスターに実際に含まれる音声を文字起こしします。そのため、会話をミュートするのではなく、BGMの volume を下げてください。Caption Studioでは、ファイル型のスキーマからアップロード方法を推測するのではなく、修正済みSRTの入力と字幕描画の確認について scenario-caption-studio に従ってください。公開されている upload_asset の種類にはテキストが含まれていません。字幕は既定で映像に焼き込まれ、outputSrt が true の場合はサイドカーファイルが返されます。位置は textPosition（top、middle、bottom。既定値は bottom）で指定できるため、画面下端のオーバーレイと重なる場合は位置を変更してください。ほかの字幕生成ツールには、それぞれ独自の実行時入力仕様があります。
5. asset_display で確認してから、format を未設定のまま asset_download を実行してファイルを取得します（format は画像変換の出力形式です）。

修正を引き継ぐ場合は、クリーンなマスター、ソースアセット、実際に送信したレイヤーペイロード、計測したタイミング、ナレーションのテキストと音声設定、編集可能なレイアウト設定を含むタイトルPNG、修正済みSRTと返された字幕テーマを保持してください。出力IDはレシピに関連付けておきます。変更するレイヤーを修正し、クリーンなマスターから字幕を付け直してください。字幕を焼き込んだ書き出しに新しい字幕を重ねないでください。これらの記録は再構築に役立ちますが、ネイティブな編集プロジェクトが得られることや、新しい環境で再生を検証済みであることを保証するものではありません。

トリミング、分割、サイズ変更には、それぞれ専用のツールモデルがあります。model_scenario-video-cut の startTime／endTime は、タイムライン上の配置ではなく、ソースのイン点とアウト点であることに注意してください。

よくある間違い

• video_compose のようなMCPツールや、編集そのものを行うためのローカルのffmpegに頼ること。編集には、ツールモデルに対して model_run を使用します。ダウンロードを調べるのは問題ありません。
• クリップ1本をconcatに渡すこと、またはクリップごとに1つずつトランジションを指定すること。最低でも動画は2本必要で、トランジションの数は動画より1つ少なくなります。
• ここでの検証として dry_run を信用すること。返されるのはコストの見積もりだけであり、アセンブリのペイロードはカタログ内でも特に構造が複雑です。
• 同期を確認せずに、連結したマスターに字幕を付けること。字幕生成ツールは聞き取った音声に合わせて字幕のタイミングを設定するため、音声がずれていれば、ずれた字幕を重ねたまま出力されます。