Skip to content

Editing guide

Exporting

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

Last updated:

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#

Terminal
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.

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).

FormatFileWhat it is
mp4.mp4H.264 video and AAC audio (the default); needs an H.264 encoder
gif.gifthe composed frames, no audio; needs no encoder
wav.wavthe audio mix as 16-bit PCM, 48 kHz, stereo
aac.m4athe same mix as AAC in an MP4 container
Terminal
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 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.

Terminal
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.

Terminal
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.

Terminal
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#