# Exporting

> Render a project to an MP4, GIF, WAV or AAC file, wait for it, and find the verified file.

Source: https://alexgalhardo.github.io/vukem-video/docs/guide/exporting/

## You will learn

- how to start an export and follow it;
- what must be true before an export is accepted.

## The idea

An export is a **job**. It renders the current revision, encodes an MP4 with FFmpeg and verifies the file (streams, duration, dimensions, pixel format and fast start) before the job is marked `succeeded`. A file that fails verification is never reported as done.

The export is refused while the lint finds an error, with `E_LINT_BLOCKING` and the first findings. Warnings never block.

## Quick start

**CLI**

```bash
vukem-video lint --project prj_7k2m9x4q1b
vukem-video export --project prj_7k2m9x4q1b
```

The CLI waits for the job. Use `--no-wait` to return at once and `vukem-video job:show <job id> --wait` later.

**MCP**

`job_start` with `{"project_id": "prj_7k2m9x4q1b", "kind": "export", "wait_ms": 25000}`, then `job_get` with `wait_ms` until the state is final.

The result of a succeeded export has the file path under `<workspace>/exports/<project id>/<job id>.<extension>`, its size and its duration.

## Formats

An export is an MP4 unless you choose another format with `--format` (CLI) or `args.format` (MCP and HTTP API).

| Format | File | What it is |
| --- | --- | --- |
| `mp4` | `.mp4` | H.264 video and AAC audio (the default); needs an H.264 encoder |
| `gif` | `.gif` | the composed frames, no audio; needs no encoder |
| `wav` | `.wav` | the audio mix as 16-bit PCM, 48 kHz, stereo |
| `aac` | `.m4a` | the same mix as AAC in an MP4 container |

```bash
vukem-video export --project prj_7k2m9x4q1b --format gif
```

With MCP: `job_start` with `{"project_id": "prj_7k2m9x4q1b", "kind": "export", "args": {"format": "wav"}}`.

## Exchange a timeline with OpenTimelineIO

`otio:export` writes the timeline of a project as an [OpenTimelineIO](https://opentimelineio.org) file, to open it in another editor. It writes the file on the machine that runs the command, in the current folder as `<project name>.otio`, or where `--out` says; it refuses to replace a file unless you add `--force`. The command lists what the format cannot carry (for example effects), so nothing is lost silently.

```bash
vukem-video otio:export --project prj_7k2m9x4q1b --out cut.otio
vukem-video otio:import cut.otio --project prj_7k2m9x4q1b --dry-run
vukem-video otio:import cut.otio --project prj_7k2m9x4q1b --base-revision 12
```

`otio:import` reads a file from the machine that runs the server and applies it to the project as one batch, so one `undo` reverts it. The frame rate of the file must be the project's. The media of the file are never opened: a reference is matched by name to an asset already in the project, and the ones that match nothing are listed as unresolved. `--dry-run` shows what would change; `--base-revision` defaults to the current revision. The HTTP API has `GET` and `POST /api/v1/projects/{id}/otio`. There is no MCP tool for OpenTimelineIO.

## Export a project bundle

A bundle is one file, `<name>.vvbundle`, that holds a project and everything it needs, to back it up or hand it to someone else. It is a zip with the project document, the original media, the fonts the project uses and, unless you leave it out, the operation log with the history of edits. Proxies, thumbnails and transcripts are not included; they are made again when the bundle is opened.

```bash
vukem-video bundle:export --project prj_7k2m9x4q1b --wait
vukem-video bundle:export --project prj_7k2m9x4q1b --no-log --wait
```

Like an export, a bundle is a job: `--wait` follows it, and the file is written under `<workspace>/exports/<project id>/` as `bundle-r<revision>-<job id>.vvbundle`. `--no-log` leaves the history out, which hides who edited and why. A project in the trash cannot be exported. The command runs on the machine that owns the workspace.

## Import a project bundle

`bundle:import` creates a project from a `.vvbundle` file. It reads the file on the machine that runs the server, checks it before it changes anything, and copies the media and the fonts it carries into the workspace. The project opens at once; its assets show as ingesting while the proxies, thumbnails and transcripts are made again.

```bash
vukem-video bundle:import launch-teaser.vvbundle
vukem-video bundle:import launch-teaser.vvbundle --as-new
vukem-video bundle:import launch-teaser.vvbundle --dry-run
```

Without `--as-new` the project keeps its id and its history of edits. If a project with that id exists, even in the trash, the import is refused with `E_ID_EXISTS`. With `--as-new` the project gets a new id and starts at revision 1 with no history, because the history of another project does not belong to a new one. A server with accounts requires `--as-new`. `--dry-run` checks the file and reports what would be created. A file that is damaged, too large, has a different format or comes from a newer version of the product is refused with `E_VALIDATION` and a reason, and nothing is imported. The HTTP API has the same operation as `POST /api/v1/projects/import`.

There is no MCP tool for bundles and the editor has no bundle entry yet.

## Common mistakes

- No H.264 encoder works on this machine: `E_NO_ENCODER`. `gif`, `wav` and `aac` still export.
- Importing a bundle whose project id already exists: `E_ID_EXISTS`. Use `--as-new`.
- Too many exports at once: `E_QUEUE_FULL`, retryable. `VUKEM_VIDEO_MAX_EXPORTS` sets the limit.

## Next steps

- [How an agent verifies its work](/docs/agents/verify)
