Export a video

In your browser

Open the web editor, change or open a TSX composition, and choose Export MP4. The source, preview, and export use Celesta’s React scene evaluator. Add local media files by name with Add media. The browser needs H.264 WebCodecs support; audio also needs AAC encoding. The browser preview is silent, while the exported MP4 includes constant-rate audio clips. For text measurement/fitting (TextBox, fitText, useFitText, measureText, useTextMetrics), PSDs, project timelines, prepare(), third-party imports, animated audio automation, and native-renderer output, use the installed app or CLI.

From the app

Choose Export… and select an MP4 destination. For a section of the composition, press I and O to mark the start and end. The status bar shows progress; Cancel export stops the job.

From the command line

The app includes a command-line exporter. Open a terminal in the project folder containing first-scene.tsx. Select your platform:

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react first-scene.tsx output.mp4

& "C:\path\to\Celesta\Celesta-export.exe" --react first-scene.tsx output.mp4

Add --overwrite to replace an existing output file. Use --from and --to to select a time range:

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --from 0 --to 1 --react first-scene.tsx section.mp4

& "C:\path\to\Celesta\Celesta-export.exe" --from 0 --to 1 --react first-scene.tsx section.mp4

Encoding quality and speed

MP4 uses libx264 with --preset medium and --crf 18 by default. Faster presets such as veryfast reduce encoding time but usually increase file size at similar quality. CRF accepts 0–51; lower values give higher quality and larger files. --color-conversion accepts auto, gpu, or encoder. --render-quality draft speeds up timing checks by skipping scaled-text re-rasterization; use final (the default) to judge the finished image. --bit-depth 10 encodes 10-bit H.264 (High 10), which keeps dark gradients smoother but plays on fewer devices; the default is 8.

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react --preset veryfast --crf 18 first-scene.tsx draft.mp4

& "C:\path\to\Celesta\Celesta-export.exe" --react --preset veryfast --crf 18 first-scene.tsx draft.mp4

PNG frames and contact sheets

--frame / --frames selects zero-based frame numbers. Multiple frames create names such as check-000090.png. --every N selects every Nth frame of the --from/--to range (or the whole composition) and its last frame. Add --contact-sheet to place them in one labelled grid; --columns and --tile-width control its layout. Explicit frame numbers cannot be combined with --every, --from, or --to.

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react --frames 0,90 first-scene.tsx check.png

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react --every 30 --contact-sheet --columns 4 --tile-width 320 first-scene.tsx sheet.png

& "C:\path\to\Celesta\Celesta-export.exe" --react --frames 0,90 first-scene.tsx check.png

& "C:\path\to\Celesta\Celesta-export.exe" --react --every 30 --contact-sheet --columns 4 --tile-width 320 first-scene.tsx sheet.png

Add --debug-guides to draw a React composition's <DebugOverlay> and <DebugBounds> into the PNG frames or contact sheet, as the preview shows them. A video export never draws them.

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react --every 30 --contact-sheet --debug-guides first-scene.tsx sheet.png

& "C:\path\to\Celesta\Celesta-export.exe" --react --every 30 --contact-sheet --debug-guides first-scene.tsx sheet.png

Select the graphics API

Both the editor and exporter accept --driver auto (default), vulkan, dx12 (Windows), metal (macOS), or gl. Auto chooses an available adapter in wgpu’s backend order: Vulkan, Metal, DX12, then OpenGL. A specific driver must be available in the build and supported by the machine. This chooses the rendering API; MP4 encoding still uses libx264.

"/Applications/Celesta.app/Contents/MacOS/Celesta-export" --react --driver auto first-scene.tsx output.mp4

& "C:\path\to\Celesta\Celesta-export.exe" --react --driver auto first-scene.tsx output.mp4

For scripts and AI agents, add --json. The exporter then prints no progress, only one line of JSON when it finishes: the status, every file it wrote, warnings, the composition's size, fps and frame count once the exporter has loaded it, and on failure an error code and message. When the arguments are rejected, the JSON has only the status and the error.

Using a source build? The developer instructions include the equivalent Cargo command.

Time values accept seconds, MM:SS.mmm, or HH:MM:SS.mmm. The selected span becomes a new video starting at its own 00:00.

On Linux without a GPU

On Linux, use Vulkan with --driver vulkan. For machines without a GPU, such as CI runners and cloud containers, install Mesa’s software Vulkan driver (lavapipe), which renders on the CPU. This works with a source build:

sudo apt-get install -y mesa-vulkan-drivers

Software rendering is much slower than a GPU: with 4 CPU cores, 1080p compositions render at roughly 10 to 60 frames per second, depending on the scene. Check a single frame as a PNG before exporting the whole video. From the repository root:

cargo run -p celesta-exporter --release -- --react --driver vulkan packages/cli/examples/title.tsx --frame 0 frame.png

Minimal containers often have no fonts installed, and text cannot be drawn without at least one. Install some, such as fonts-dejavu-core (and fonts-noto-cjk for Japanese), or load font files with <Font>.

On a software renderer, --color-conversion auto leaves the RGB-to-YUV conversion to the encoder. --render-quality draft is quicker for checking timing, but not pixels. To export in a container without building Celesta yourself, build the Linux container image from the repository root, then run it from your project folder, which is mounted at /work. --user makes the output belong to you instead of root:

docker build -f packaging/linux/Dockerfile -t celesta-exporter .

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/work" celesta-exporter --react first-scene.tsx output.mp4