Export

Export

Use OpenChatCut's export tools for delivery. An export request should call submit_export (or submit_render_job for async), then use track_export for status and final delivery when the result is not returned immediately.

Default policy:

• Prefer submit_export when the user asks to export/share/finalize the OpenChatCut timeline.
• Keep originals local by default during editing. Upload originals only when a cloud export/proof needs remote assets and the user has not forbidden upload.
• Do not wrap sandbox ffmpeg work as a OpenChatCut tool. Use sandbox ffmpeg for full video processing only when the user explicitly asks for a standalone local-file operation outside a OpenChatCut editing workflow. For OpenChatCut editing tasks, do not produce a pre-edited or flattened local render as the primary review/final deliverable; use OpenChatCut export.

Durable Export

Use submit_export for the execution path:

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

Video codec options are h264 (MP4, default) and vp8 (WebM). Video frame-rate options match the editor UI: 24, 25, 30, 50, or 60; omit fps to match the timeline. Audio export is MP3: pass "format":"audio" and omit codec / fps unless you explicitly pass "codec":"mp3".

submit_export returns a durable renderId. Some export types, such as subtitle files, may complete immediately and return downloadUrl; video/audio usually require track_export to wait for completion.

After getting each downloadUrl:

• Resolve the user's Downloads folder: ~/Downloads on macOS/Linux, or %USERPROFILE%\Downloads on Windows.
• Before triggering any agent/browser download, check the Downloads folder for fresh Chrome download artifacts from the last few minutes that match the expected export name, extension, or render/download URL basename. Include both completed files and in-progress .crdownload files.
• If a matching fresh .crdownload exists, do not trigger another download. Wait until Chrome removes the .crdownload suffix and the final file size stops changing, then use that completed file.
• If a matching fresh completed file already exists, use it directly instead of downloading again.
• If only older files exist, treat them as collisions, not as the current export.
• Do not overwrite an existing file; choose a safe numbered filename such as name (1).mp4 when needed.
• Always download the finished export file into the Downloads folder, not a temp/workspace directory.
• Always show the downloaded video inline in chat. If there are multiple exported videos, download all of them and show every preview, not just the first.

If the project contains local-only assets, upload/register cloud-readable replacements before rendering, or use the Local CLI Export path when the user wants to stay local.

Report the returned renderId when present. The job is also visible in the editor's top-right export queue, including progress and cancellation. Use saveToMediaPool:true when the user asks to retain the result in My Media or when the active workflow explicitly defaults to automatic materialization, such as livestream-to-clips; otherwise the default remains a normal downloadable export. For long videos, call track_export once with action:"wait" and timeoutSeconds:20. If it returns waitExpired:true, report that the render continues in the background and end the turn. Check it later with action:"status"; repeated waits only hold the Agent turn open. Do not start another export for the same timeline while this render is active.

Use track_export when the user asks about export/render status, or when the current turn genuinely needs to wait for a submitted video/audio render. Completed connector exports return downloadUrl; for every completed entry, download the file to Downloads using the collision-safe rules above and show it inline in chat:

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

For the latest project export, omit renderIds and pass "latest": true. track_progress is for generation/transcription/upload jobs, not render jobs.

For NLE XML, use submit_export with format:"xml":

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

nleFormat values are fcp_xml for Premiere XML (default) and fcp_xml_resolve for DaVinci Resolve XML. Omit timelineId for the active timeline, or pass a timeline id/prefix for a non-active timeline. Read and report warnings: captions, solids, SVG, unsupported clip attributes, and unrendered motion graphics may be dropped by the XML format. Motion graphics are only represented in XML when a transparent-ProRes MG export flow supplies motionGraphicRenderKeys; otherwise the exporter reports them as dropped.

For media-pool source download, use request_asset_download on a file-backed source asset. It returns a guarded backend download URL/path for the original source media. Do not use pull_asset for user downloads; pull_asset is sandbox-only.

For subtitle files, use submit_export with format:"subtitles":

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

Formats are srt and txt. The export uses the captions item's actual timeline word timing, source scope, translation variants, display-text overrides, and pacing fields such as wordsPerPage / maxCharactersPerLine, and creates a durable downloadable export job. It is appropriate for downloadable subtitle files. It does not yet reuse the browser Remotion caption page planner, so visual line wrapping/page breaks are timing-correct but approximate rather than byte-identical to burned-in caption pagination. For non-active timelines, pass timelineId from manage_timelines or read_project.

For one motion graphic as transparent ProRes 4444, use export_motion_graphic_prores:

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

Prefer itemId when exporting a specific timeline instance, because the item carries live propertyOverrides such as edited text. Use assetId for a media-pool motion graphic; the backend will use the first timeline instance for that asset when present, matching the editor's media-pool export behavior. For several motion graphics, pass itemIds or assetIds in one call. Each motion graphic still becomes a separate durable render; use track_export with the returned renderIds to wait, then download through each returned render download path.

When preparing XML that should reference rendered motion graphics, pass "filenameMode":"xml" and the same timelineId to export_motion_graphic_prores, then keep the returned motionGraphicRenderKey / motionGraphicRenderKeys; after the render completes, pass those keys and the same timelineId in submit_export.motionGraphicRenderKeys with format:"xml".

Local Render (this build)

All rendering is local: submit_export / submit_render_job drive the local render service (headless Chrome over the same timeline state the editor shows), reading media straight from /media/uploads/ on disk. There is no S3 requirement, no CLI, and no cloud job to wait on for disk-backed assets.

• submit_export: subtitles/XML return synchronously; video/audio also render in-call in this build (long timelines can take a while — warn the user instead of polling).
• submit_render_job + track_export: the async route — returns a renderId immediately, poll with track_export (renderIds / latest / onlyActive), then hand the user the returned download path.
• Assets still on blob: placeholders (upload in flight) are not renderable yet — wait for track_progress target=upload to report ready before submitting.

Fallbacks

If a render fails because an asset's bytes are missing (placeholder never relinked, file deleted from disk):

1. Ask the user to re-link the asset in 我的素材 (离线素材横幅) or re-import the file.
2. For URL-sourced media, re-run download_media to restore bytes, then resubmit.

Do not tell the user they need to understand HTML-in-Canvas, Remotion, or storage internals unless debugging. Explain at product level:

• "本地快速导出"
• "素材还在上传，稍等再导"
• "需要先重新链接本地素材"

Result Trace

For submit_export, record:

• renderId
• timeline/range/resolution/codec/fps
• that the user can download from the editor render-jobs panel

Record uploaded asset IDs and any fallback tried when cloud export was blocked by local-only assets.