asset-import

アセットのインポート

ファイルがすでにインポートされている可能性がある場合は、まず browse_assets を確認してください。

同じマシンからのエディターへのインポート（推奨）

1. browserHandoff.url または editorUrl を使って対象プロジェクトを開きます。このプロジェクトのエディタータブは、シェルと同じマシン／ネットワーク名前空間上で、必ず1つだけ開いてください。リモートサンドボックスの localhost は、ユーザーの localhost ではありません。
2. 実際のエディター URL のオリジンを使い、PATH 上の Node で同梱サーバーを起動します。

node <this-skill-dir>/scripts/serve-local-media.mjs --origin <editor-origin> /path/to/source.mp4

MCP の呼び出し中は、ホストのバックグラウンドプロセス機能を使ってこのプロセスを起動したままにします。JSON の行を1行出力し、900秒後に自動終了します。アクセストークンなしで、ループバック URL 経由でリストされたファイルのみを提供します。URL には、既存エディターとの互換性を保つため、公開されている chatcut-local-media-v1 パスプレフィックスを使用します。従来のトークンプレフィックス付き URL も引き続き使用できます。JSON の token フィールドには認証情報ではなく、この公開プレフィックスが含まれています。

3. 複数のファイルは、1回の import_media 呼び出しでインポートします：{"action":"from_editor","files":[...]}。出力された imports 配列から各ファイルの assetId、url、filename、sizeBytes を files にコピーし、ファイルごとの action は省略します。各 URL は別々に起動しているヘルパーから取得してもかまいません。1回の呼び出しにつき1〜16個のファイルを送信します。それを超える場合は、16個ずつ続けてバッチ送信します。最大8個のファイルが同時に処理されます。エディターは各ファイルをローカルストアに直接ストリーミングするため、ダウンロード開始と同時に転送の進捗を示すカードが表示されます。ループバック固有のファイルサイズ上限はありません。従来のトップレベル引数を使った単一ファイルの指定も引き続き機能します。
4. results のすべての項目を確認します。成功した項目は ok:true と status:"locally_imported" を持ち、失敗した項目には error が含まれます。結果は入力順を維持し、assetId と filename、さらにトップレベルの succeeded／failed 件数を含みます。同じアセット ID を使って、失敗したファイルのみ再試行します。成功とは、エディターがローカルのバイトデータを永続化し、アセットをローカルに登録した状態を指します。すべてのファイルのインポートが成功してから、ヘルパーを停止してください。サーバーとの同期、バックグラウンドアップロード、文字起こしのため、エディターは開いたままにします。
5. タイムラインでの作業には、返されたアセット ID を使います。トランスクリプト／キャプションの作業を始める前に、track_progress target:"transcription" の完了を待ちます。ブラウザーでレンダリング可能なタイムラインでは元ファイルのアップロードが保留されます。クラウドのみのタイムライン、または未対応のタイムラインでは自動的にアップロードされます。target:"upload" の完了を待つ前に browse_assets を確認してください。アップロードが保留中の場合、処理は進行していません。クラウド上のバイトデータが必要な場合は、同じアセット ID を維持したまま、エディターの Upload アクションを使います。サーバーとの同期が追いついていない場合は、アセットの検索を再試行してください。

タイムアウトした場合は、browse_assets を確認し、同じ assetId を使って再試行します。インポートがまだ実行中の可能性があります。再試行すると、最初からやり直すのではなく、中断したダウンロードの続きから再開します。ヘルパーを再起動して URL が変わっても、同じ ID を維持してください。やみくもに2つ目のインポートを開始しないでください。プロンプトが表示された場合は、エディターのブラウザーにローカルネットワークへのアクセスを許可してください。エディターがヘルパーに接続できない場合、またはブリッジが利用できない場合は、フォールバックを使用してください。ホストポリシーによる拒否は、別の転送方法を試す許可ではありません。

視覚的な分析では、クラウドへのアップロードを待たずに、読み取り可能な元ファイルをローカルで確認します。元のソースアセットをインポートしてください。編集内容をローカルの事前レンダリングに統合しないでください。

既存のアセットを再リンクする

ローカルメディアが見つからない場合は、既存のアセットとそのタイムライン参照を保持します。

1. browse_assets から既存の assetId を取得し、対応する元のソースファイルを特定します。
2. 上記と同じループバックヘルパーを使って、そのファイルを配信します。
3. ヘルパーの url、filename、sizeBytes を指定して import_media を呼び出します。ただし、action: "relink_from_editor" を設定し、生成された assetId を既存の assetIdに置き換えます。 複数のファイルの場合は、各エントリーに既存のアセット ID を指定して、同じ files 配列形式を使用します。
4. ヘルパーを停止する前に、status: "locally_relinked" になるまで待ちます。アップロードや文字起こしはまだ保留中の場合があります。エディターは開いたままにしてください。

再リンクでは、エディターにバイト列がキャッシュされていても、指定されたファイルを必ず読み込みます。メディアの種類は一致している必要があります。別の置き換え用クリップではなく、対応する元のファイルを使用してください。再リンクでは既存の編集内容と文字起こしが保持されます。エディターに対象が見つからない場合は、プロジェクトの同期が完了するまで待ってから再試行してください。再リンクに失敗しても、新しいアセットの作成に切り替えてはいけません。

アップロードヘルパーを使う代替手段

リモートサンドボックス、エディターが利用できない場合、またはブラウザー接続がブロックされている場合：

1. {"action":"create_session"} を指定して import_media を呼び出します。
2. 返されたトークンとエンドポイントを使い、バンドルされたヘルパーをフォアグラウンドで実行します。パスは最大 4 つまで指定できます。

node <this-skill-dir>/scripts/upload-media.mjs --token <token> --endpoint <endpoint> /path/to/source.mp4

スクリプトはこのスキルからの相対パスで解決してください。Node をインストールしたり、ヘルパーを手書きのアップロード／トランスコードコマンドで置き換えたりしないでください。MCP OAuth は MCP クライアント内で処理されます。ヘルパーに渡すのは有効期限の短いインポートトークンだけです。より大きなバッチには、4 ファイルごとに新しいセッションが必要です。

ヘルパーはプレースホルダーを早い段階で登録しますが、アップロードが完了した後に最終的な JSON を出力します。imports[].result.assetId を確認してください。エラーに retry が含まれている場合は、新しいセッションを取得し、返された引数を使って再実行し、同じアセットの処理を再開します。

ホストのポリシーによって転送が拒否された場合は、そこで停止し、エディターからアップロードするか、許可を付与するようユーザーに依頼してください。拒否を回避してはいけません。公開 URL はローカルにダウンロードし、上記の適切な方法でインポートできます。