0xsline/openchatcut

書き出し

納品のために OpenChatCut の書き出しツールを使用します。書き出しリクエストでは submit_export（または非同期処理の場合は submit_render_job）を呼び出し、結果がすぐに返ってこない場合は track_export を使用してステータスを確認し、最終的な納品を行います。

デフォルトポリシー：

• ユーザーが OpenChatCut のタイムラインを書き出し/共有/最終確定するよう依頼した場合は、submit_export を優先します。
• 編集作業中は、オリジナルファイルをデフォルトでローカルに保持します。クラウド書き出し/プルーフでリモートアセットが必要で、ユーザーがアップロードを禁止していない場合にのみ、オリジナルをアップロードします。
• サンドボックスの ffmpeg 処理を OpenChatCut のツールとしてラップしないでください。ユーザーが OpenChatCut の編集ワークフロー外で、スタンドアロンのローカルファイル操作を明示的に依頼した場合にのみ、完全な動画処理にサンドボックスの ffmpeg を使用します。OpenChatCut の編集タスクでは、事前編集済みまたはフラット化されたローカルレンダリングをプライマリのレビュー/最終納品物として生成せず、OpenChatCut の書き出し機能を使用してください。

永続的な書き出し

実行パスには submit_export を使用します：

{
  "format": "video",
  "codec": "h264",
  "resolution": "1080p",
  "fps": 30,
  "name": "final-cut"
}

動画コーデックのオプションは h264（MP4、デフォルト）と vp8（WebM）です。動画フレームレートのオプションはエディタの UI に合わせて 24、25、30、50、60 から選択します。タイムラインに合わせるには fps を省略します。音声書き出しは MP3 です。"format":"audio" を渡し、明示的に "codec":"mp3" を渡さない限り codec / fps は省略します。

submit_export は永続的な renderId を返します。字幕ファイルなどの一部の書き出しタイプは即座に完了し downloadUrl を返す場合があります。動画/音声は通常、完了を待つために track_export が必要です。

各 downloadUrl を取得した後：

• ユーザーの Downloads フォルダを解決します。macOS/Linux の場合は ~/Downloads、Windows の場合は %USERPROFILE%\Downloads です。
• エージェント/ブラウザのダウンロードをトリガーする前に、Downloads フォルダ内に、数分以内に作成された、予想される書き出し名、拡張子、またはレンダー/ダウンロード URL のベース名に一致する新しい Chrome ダウンロードアーティファクトがないか確認します。完了したファイルと進行中の .crdownload ファイルの両方を含めます。
• 一致する新しい .crdownload が存在する場合は、別のダウンロードをトリガーしません。Chrome が .crdownload サフィックスを削除し、最終的なファイルサイズが変化しなくなるまで待ってから、その完了したファイルを使用します。
• 一致する新しい完了ファイルがすでに存在する場合は、再度ダウンロードせずに直接使用します。
• 古いファイルのみが存在する場合は、それらを現在の書き出しではなく衝突として扱います。
• 既存のファイルを上書きしないでください。必要に応じて、name (1).mp4 のような安全な番号付きファイル名を選択します。
• 常に、完了した書き出しファイルを temp やワークスペースディレクトリではなく Downloads フォルダにダウンロードします。
• ダウンロードした動画は常にチャット内にインラインで表示します。複数の動画が書き出された場合は、最初のものだけでなく、すべてをダウンロードしてすべてのプレビューを表示します。

プロジェクトにローカルのみのアセットが含まれている場合は、レンダリング前にクラウドで読み取り可能な代替アセットをアップロード/登録するか、ユーザーがローカルに留まりたい場合はローカル CLI 書き出しパスを使用します。

返された renderId がある場合は報告します。ジョブはエディタの右上にある書き出しキューにも表示され、進捗状況とキャンセルが可能です。ユーザーが結果をマイメディアに保持するよう要求した場合、またはアクティブなワークフローが明示的に自動マテリアライズをデフォルトとしている場合（livestream-to-clips など）は、saveToMediaPool:true を使用します。それ以外の場合のデフォルトは、通常のダウンロード可能な書き出しです。長い動画の場合は、track_export を action:"wait" と timeoutSeconds:20 で 1 回呼び出します。waitExpired:true が返された場合は、レンダリングがバックグラウンドで続行されていることを報告し、ターンを終了します。後で action:"status" で確認します。繰り返し待機すると、Agent のターンが開いたままになります。このレンダリングがアクティブな間は、同じタイムラインに対して別の書き出しを開始しないでください。

ユーザーが書き出し/レンダリングのステータスについて質問した場合、または現在のターンで送信された動画/音声レンダリングを待つ必要が本当にある場合は、track_export を使用します。完了したコネクタ書き出しは downloadUrl を返します。完了したエントリごとに、上記の衝突回避ルールを使用してファイルを Downloads にダウンロードし、チャット内にインラインで表示します：

{
  "action": "status",
  "renderIds": "abc123"
}

最新のプロジェクト書き出しの場合は、renderIds を省略し、"latest": true を渡します。track_progress は生成/文字起こし/アップロードジョブ用であり、レンダリングジョブ用ではありません。

NLE XML の場合は、format:"xml" を指定して submit_export を使用します：

{
  "format": "xml",
  "nleFormat": "fcp_xml_resolve",
  "timelineId": "abc123"
}

nleFormat の値は、Premiere XML の場合は fcp_xml（デフォルト）、DaVinci Resolve XML の場合は fcp_xml_resolve です。アクティブなタイムラインの場合は timelineId を省略し、非アクティブなタイムラインの場合はタイムライン ID/プレフィックスを渡します。警告を読み取って報告します。キャプション、ソリッド、SVG、サポートされていないクリップ属性、および未レンダリングのモーショングラフィックスは、XML 形式ではドロップされる可能性があります。モーショングラフィックスが XML で表現されるのは、透明 ProRes MG 書き出しフローが motionGraphicRenderKeys を提供する場合のみです。それ以外の場合、エクスポーターはそれらをドロップされたものとして報告します。

メディアプールのソースダウンロードの場合は、ファイルベースのソースアセットに対して request_asset_download を使用します。元のソースメディアのガードされたバックエンドダウンロード URL/パスを返します。ユーザーダウンロードに pull_asset を使用しないでください。pull_asset はサンドボックス専用です。

字幕ファイルの場合は、format:"subtitles" を指定して submit_export を使用します：

{
  "format": "subtitles",
  "subtitleFormat": "srt"
}

フォーマットは srt と txt です。書き出しでは、キャプションアイテムの実際のタイムラインワードタイミング、ソーススコープ、翻訳バリアント、表示テキストオーバーライド、および wordsPerPage / maxCharactersPerLine などのペーシングフィールドを使用し、永続的なダウンロード可能な書き出しジョブを作成します。これはダウンロード可能な字幕ファイルに適しています。これはまだブラウザの Remotion キャプションページプランナーを再利用していないため、視覚的な行折り返し/ページ区切りはタイミング的には正しいですが、焼き込みキャプションのページネーションとバイト単位で同一というわけではありません。非アクティブなタイムラインの場合は、manage_timelines または read_project から timelineId を渡します。

1 つのモーショングラフィックを透明な ProRes 4444 として書き出すには、export_motion_graphic_prores を使用します：

{
  "itemId": "abc123",
  "filenameMode": "asset"
}

特定のタイムラインインスタンスを書き出す場合は itemId を優先します。アイテムは、編集されたテキストなどのライブの propertyOverrides を保持するためです。メディアプールのモーショングラフィックには assetId を使用します。バックエンドは、存在する場合、そのアセットの最初のタイムラインインスタンスを使用し、エディタのメディアプール書き出し動作に一致します。複数のモーショングラフィックの場合は、1 回の呼び出しで itemIds または assetIds を渡します。各モーショングラフィックは依然として個別の永続的なレンダリングになります。返された renderIds で track_export を使用して待機し、返された各レンダーダウンロードパスからダウンロードします。

レンダリングされたモーショングラフィックを参照する XML を準備する場合は、export_motion_graphic_prores に "filenameMode":"xml" と同じ timelineId を渡し、返された motionGraphicRenderKey / motionGraphicRenderKeys を保持します。レンダリングが完了した後、それらのキーと同じ timelineId を、format:"xml" を指定した submit_export.motionGraphicRenderKeys に渡します。

ローカルレンダリング（このビルド）

すべてのレンダリングはローカルです。submit_export / submit_render_job はローカルレンダリングサービス（エディタが表示するのと同じタイムライン状態に対してヘッドレス Chrome を使用）を駆動し、ディスク上の /media/uploads/ からメディアを直接読み取ります。S3 の要件はなく、CLI もなく、ディスクバックアップアセットのために待機するクラウドジョブもありません。

• submit_export：字幕/XML は同期的に返されます。動画/音声もこのビルドでは呼び出し内でレンダリングされます（長いタイムラインには時間がかかる場合があります。ポーリングする代わりにユーザーに警告してください）。
• submit_render_job + track_export：非同期ルートです。すぐに renderId を返し、track_export（renderIds / latest / onlyActive）でポーリングし、返されたダウンロードパスをユーザーに渡します。
• まだ blob: プレースホルダー上にあるアセット（アップロード中）は、まだレンダリングできません。送信する前に、track_progress target=upload が準備完了を報告するのを待ちます。

フォールバック

アセットのバイトが欠落している（プレースホルダーが再リンクされていない、ファイルがディスクから削除された）ためにレンダリングが失敗した場合：

1. ユーザーに、マイメディア（オフラインアセットバナー）でアセットを再リンクするか、ファイルを再インポートするように依頼します。
2. URL ソースのメディアの場合は、download_media を再実行してバイトを復元し、再送信します。

デバッグ中でない限り、ユーザーに HTML-in-Canvas、Remotion、またはストレージ内部を理解する必要があると伝えないでください。製品レベルで説明します：

• "ローカル高速書き出し"
• "素材はまだアップロード中です。少し待ってから書き出してください"
• "ローカル素材を再リンクする必要があります"

結果トレース

submit_export では、以下を記録します：

• renderId
• タイムライン/範囲/解像度/コーデック/fps
• ユーザーがエディタのレンダリングジョブパネルからダウンロードできること

アップロードされたアセット ID と、クラウド書き出しがローカルのみのアセットによってブロックされた場合に試行されたフォールバックを記録します。