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:

```json
{
  "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:

```json
{
  "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"`:

```json
{
  "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"`:

```json
{
  "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`:

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