Exporting
@cutcraft/render turns a file into a video (MP4 or WebM), a soundtrack (MP3 or WAV) or a still (PNG or JPEG). The export runs the same player as the preview, so what the preview shows is what the file holds. This page covers the formats, exporting on a server, motion blur, and making an export faster.
npm install cutcraft
npx cutcraft video.tsx --out video.mp4To check the file before or after you export it, see Checking a cut.
From the command line
--out names the file to write, and its extension picks the format. The other inputs come from the file when you leave them out:
| Option | Gives | When left out |
|---|---|---|
--out | The file to write; its extension picks the format. | Required. |
--manifest | The manifest. | The file's own manifest export, or else the nearest cutcraft.json from the file's folder upward. |
--media | A folder with one file per asset id. | The file's folder, the manifest's folder, or media/ beside the manifest. |
Where the manifest and the media are found has the details, and the CLI reference lists every option.
The export loads a file the way the editor does: it may import react, zod and @cutcraft/kit, plus what --import offers. A file that imports anything else fails with the same message in both, so a file that exports also opens in the editor.
Formats
--out | Writes |
|---|---|
video.mp4 | H.264 video and AAC sound. |
video.webm | VP9 video and Opus sound. |
sound.mp3, sound.wav | The soundtrack alone. |
poster.png, poster.jpg with --still 2 | One frame, at 2 seconds. |
--codec av1 writes AV1 video in either container.
The browser it runs in
The export runs the real player in headless Chrome. It steps the file frame by frame, waits for every clip, title, three.js scene and Motion sequence to draw the frame, then captures and encodes it in the page with the browser's own encoders.
The first export downloads Chrome for Testing into ~/.cache/cutcraft/browsers once and reuses it after that.
| To | Use |
|---|---|
| Download it ahead of time, for a Docker image or a CI cache | npx cutcraft browser install |
| Keep the cache somewhere else | CUTCRAFT_BROWSER_CACHE |
| Use your own Chrome or Chromium 153 or later instead of downloading one | CUTCRAFT_CHROMIUM |
The capture uses HTML-in-Canvas (drawElementImage), which Chrome ships behind a flag the export turns on.
Without a GPU, WebGL runs in software: about 6 frames a second at 1080p on a 4-core machine for a file with three.js, plus a few seconds to start the browser. With a GPU it is much faster.
On a server
A slim Linux image lacks a few system libraries Chrome needs that a desktop has. On Debian or Ubuntu, playwright-core (installed with the export) lists and installs them, and cutcraft browser install puts Chrome in the image, so no export downloads it at run time:
FROM node:22-bookworm-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
RUN npx --yes playwright-core install-deps chromium && npx cutcraft browser install
COPY . .
CMD ["npx", "cutcraft", "video.tsx", "--out", "out/video.mp4"]For an image built another way, npx playwright-core install-deps --dry-run chromium prints the packages instead of installing them.
In GitHub Actions the runners already have the libraries. Cache the browser so it downloads once per CutCraft version:
- uses: actions/cache@v4
with:
path: ~/.cache/cutcraft/browsers
key: cutcraft-chrome-${{ runner.os }}-${{ hashFiles('package-lock.json') }}
- run: npx cutcraft browser install # keeps a cached Chrome, downloads one otherwise
- run: npx cutcraft video.tsx --out video.mp4Most servers have no GPU, so Chrome draws on the CPU. --tabs spreads the work over more cores (Faster).
Motion blur
Motion blur smears whatever moves, the way a film camera does while its shutter is open. Turn it on with motionBlur on the <Composition>:
import { Clip, Composition, Motion, Track } from "@cutcraft/kit";
// A puck that crosses the frame in under a second and comes back: each exported frame averages
// 8 moments across a half-frame shutter, so it smears the way a film camera would.
export default function Video() {
return (
<Composition fps={30} width={960} height={540} motionBlur={{ shutterAngle: 180, samples: 8 }}>
<Track id="main">
<Clip id="bg" src="asset:cells" in={0} out={3} fit="cover" />
</Track>
<Track id="fx" layout="free">
<Motion
id="puck"
start={0}
duration={3}
sequence={[
[".puck", { x: [-180, 1000] }, { duration: 1.4, ease: "easeInOut" }],
[".puck", { x: [1000, -180] }, { duration: 1.4, ease: "easeInOut" }],
]}
>
<div
className="puck"
style={{
position: "absolute",
left: 0,
top: 200,
width: 140,
height: 140,
borderRadius: 70,
background: "#e8a33d",
}}
/>
</Motion>
</Track>
</Composition>
);
}| Option | Does |
|---|---|
shutterAngle | How long the shutter stays open, as a share of the frame. 180 (half the frame, the film default) looks natural, 90 is crisper and choppier, 360 blurs the most. |
samples | How many pictures are averaged per frame, 2 to 64, default 8. More is smoother and slower: 8 samples take about eight times as long. |
The export draws each frame samples times across the open shutter and averages the pictures. Every frame in CutCraft is a function of time, so footage, titles, <Motion>, three.js and free code all blur the same way.
TIP
The blur shows in exported videos and stills. The preview stays sharp.
Faster
Start with a draft to watch while you work. For the real export, try --tabs, then --copy.
A draft
--draft renders the video for watching, not for keeping:
npx cutcraft video.tsx --out video.mp4 --draft- It draws every second frame and shows each twice as long, so the draft is as long as the video and its sound is the same.
- Its pictures are half as wide and half as high, encoded at the
lowquality preset unless--bitrateor--qualityis given. - It is written beside the file
--outnames, asvideo.draft.mp4, so a draft never replaces the video.
A draft draws half the frames, but it is not twice as fast. Each frame is still drawn at full size and scaled down afterwards, and drawing is most of what an export does. A two minute film with a three.js scene took a little over nine minutes as a draft against about twelve in full.
A draft's pictures are the video's own, smaller. To see one move without rendering at all, use look --motion.
--tabs
--tabs 3 renders with three pages of the browser at once (the default is one), each on its own share of the frames. The pictures are the same as one page's, frame for frame; only where the keyframes fall differs.
Each page holds its own decoders and encoder, so memory grows with the count. On a machine with spare cores, two to four pages help most.
How the frames are shared
The frames are cut into runs of whole keyframe intervals, and each page renders and encodes its runs into small containers. Node joins them in order with the soundtrack, copying the encoded packets.
--copy
--copy skips drawing where the picture is nothing but a stretch of one source file. The encoded packets of whole groups of pictures are copied, and only the ends are rendered. Copied pictures keep the source's quality and are not decoded or encoded at all.
It applies to a stretch of frames when all of these hold:
- the source is VP9 and so is the output;
- the source has the composition's size and frame rate;
- one clip is shown, untransformed, at full size, at speed 1, with no fade, filter, crop, mask or blend, and no transition, title, caption or any other overlay at those times, and the file has no motion blur.
A stretch that does not qualify is rendered as usual.
WARNING
--copy is opt-in because a source whose stream does not match the encoder's fails when the pieces are joined, instead of falling back.
How the export works explains what runs where: the page, the pieces and the sound.
When a frame never finishes
Each frame has a deadline: 60 seconds unless --frame-timeout (or frameTimeout from code) says otherwise. A frame that outlasts it ends the export with the frame, its time and the step it was in:
frame 412 (13.73 s) did not finish within 60 s: stuck in settle| Step | What the page was waiting for |
|---|---|
step | The player, to decode and place that moment's media. A damaged or very large source is the usual cause. |
settle | A font, an image, or a layer that holds the frame until it has drawn (three.js, a shader) and never lets go. |
paint | The browser, to paint the page. |
draw | The painted page, to be copied into the frame. |
encode | The video encoder, to take the frame. |
cutcraft look video.tsx --at 13.73 draws that one moment, the quick way to see what is on screen there. A very slow machine can need a longer deadline for heavy frames; raise it only once you know the frame does finish.
"Captured without the browser confirming the paint"
An export can end with a warning that some frames were captured without the browser confirming the paint. The page asks the browser to say when a frame is painted, and waits a second for the answer. Without one it goes on after two animation frames, and such a frame may show the moment before.
It should not happen in the Chrome CutCraft installs. If it does, look at those frames before you publish.
What it draws
The export draws everything the preview draws, because it is the preview: footage, transitions, effects, crops, masks, blend modes, titles, shapes, SVG, stickers, layers with any CSS and React, captions, <Three>, <Motion>, and the effects and transitions a file declares in GLSL. A few limits remain, listed in What renders, and the check reports each as a not-rendered warning.
Fonts. Inter, Space Grotesk, Playfair Display, DM Sans and JetBrains Mono are bundled (regular and bold, italic where the family has one; see Themes). A title that names another font falls back to Inter unless the file declares it (font(), googleFont()) or you pass it with --font. TTF, OTF, WOFF and WOFF2 all work.
Sound. Volume, fades, ducking, pan and speed are mixed in, and mute and solo apply.
How the sound is mixed and encoded
Sound is mixed in the page by mixPlan, a pure function of the audio plan: volume, fades, automation, ducking, pan, speed and speed-key ramps (pitch follows speed, as in the preview), silence through freeze holds, and sample-rate conversion. Chrome encodes Opus itself; AAC and MP3 go through Mediabunny's WebAssembly encoders, since Chrome for Testing has none.
From code
renderVideo and renderStill do from a script what the command line does.
import { directoryResolver, loadVideo, renderStill, renderVideo } from "@cutcraft/render";
const video = await loadVideo("video.tsx");
const media = directoryResolver("media", video.manifest);
const result = await renderVideo({
state: video.state,
source: video.source, // the file's text: the export page loads it, as the editor does
media,
out: "video.mp4",
tabs: 2,
onProgress: ({ frame, frames }) => console.log(frame, frames),
});
// result: frames, audio, fps, width, height, wallMs, tabs, copiedFrames, warnings
// One frame, the same way:
await renderStill({ state: video.state, source: video.source, media, out: "poster.png", time: 2 });renderVideo stops with an error when an asset cannot be opened or decoded, rather than drawing a placeholder into a video you will publish. onAssetError: "continue" changes that. result.warnings lists what was left out and why.
Requirements
Node 22.19 or later, and the Chrome the first export downloads (or CUTCRAFT_CHROMIUM). There is no FFmpeg and no native module to install.
Next
- Checking a cut: read the timeline, look at frames, check the layout and the exported file.
- How the export works: what runs in Node and what runs in the page.
- CLI reference: every command and option.
- What renders: the few things the export draws differently.