cutcraft
Render a TSX video file to video, audio, stills, or a layout report
TLDR
SYNOPSIS
cutcraft FILE.tsx --out OUTPUT [options]cutcraft FILE.tsx --still SECONDS --out IMAGE [options]cutcraft FILE.tsx --check-layout [options]cutcraft FILE.tsx --srt FILE | --vtt FILE [options]cutcraft inspect | look | where | fonts | add | browser ...
DESCRIPTION
cutcraft is the command-line package of CutCraft, a React library for describing video as TSX. The binary name is cutcraft. The npm package of the same name re-exports the renderer CLI. It needs Node.js 22.19 or newer.An export draws frames in headless Chrome. The first export downloads Chrome for Testing into the CutCraft browser cache under the user cache directory. browser install does that download ahead of time. A Chrome 153 or newer binary can be named instead of the downloaded one; the environment variable is CUTCRAFT then CHROMIUM, joined with an underscore. The cache directory override is CUTCRAFT then BROWSER then CACHE, joined with underscores.The asset manifest is cutcraft.json, found in the file's folder or the nearest folder above it, unless the TSX file exports its own manifest or --manifest names another file. Media sits in the file's folder, beside the manifest, or in media/ beside the manifest, one file per asset id, unless --media names a folder. add writes manifest entries and picks up a transcript beside the media (talk.json, talk.vtt, or talk.srt).inspect prints the timeline as text and does not start a browser. look draws many frames into one contact sheet. where prints each on-screen box at the moments you name. --check-layout prints overlays that leave the frame, leave the safe zone, or cover captions or the subject, and writes no media file. Layout issues exit 3. Usage errors exit 2. Other failures exit 1.Output extension selects the container: .mp4 is H.264 and AAC, .webm is VP9 and Opus, .mp3 or .wav is the soundtrack alone, .png or .jpg is a still. The license is MIT.
PARAMETERS
--out FILE
Where to write. The extension picks the container. For look, the contact sheet path (default look.png). For fonts --sheet, the font image.--still SECONDS
Write the frame at this time instead of a video.--from SECONDS, --to SECONDS
Render only this part of the composition.--draft
A preview render: every second frame, shown twice as long, at half resolution and a low quality preset. Written beside --out as a .draft file. It does not replace the video.--quality PRESET
very-low, low, medium, high, or very-high, instead of --bitrate.--bitrate BPS
Video bits per second. Default is about 0.1 per pixel per frame.--codec NAME
avc (default for .mp4), vp9 (default for .webm), or av1 in either container.--copy
Copy encoded pictures from a VP9 source where a cut shows nothing else, and render only the ends.--tabs N
Browser pages that render pieces at once (default 1).--props JSON
Props for the file's component, over its defaults.--manifest FILE
Asset manifest. Default: the file's manifest export, then the nearest cutcraft.json.--media DIR
Folder of one file per asset id.--import SPEC
A module the file may import beyond react, zod, and the kit: three, or name=specifier. Repeatable. The specifier is a package or a path relative to the file.--font SPEC
An extra font: Name=file.ttf, Name:700=file.ttf, or Name:700:italic=file.ttf. Repeatable.--srt FILE, --vtt FILE
Also write the captions the cut plays, timed like the export. Either flag alone writes only the subtitle file.--check-layout
Report layout problems and write no media. --json prints JSON and exits 3 when it finds issues.--safe-zone ZONE
tiktok, reels, shorts, title-safe (default), action-safe, or four fractions top,right,bottom,left.--subject X,Y,W,H
Subject box as fractions of the frame, when the manifest has no subjects.--silent
No soundtrack.--continue
Draw a grey placeholder for an asset that cannot be read, instead of failing.--frame-timeout SECONDS
How long one frame may take (default 60). On expiry the command fails and names the frame.--keyframe SECONDS
Seconds between keyframes (default 2).--quiet
No progress.--no-cache
For look and --still, draw every frame again. Otherwise frames are kept in .cutcraft/cache beside the file.--help, -h
Print the usage text.
COMMANDS
inspect FILE.tsx
Print each track and element with its times, words, effects, keyframes, and cuts. --at adds what is on screen and heard at those moments. --json prints flat rows.look FILE.tsx
One contact sheet (default look.png) plus a JSON legend. With no --at or --around, the sheet is the first frame of each clip, both sides of every cut, and each overlay. --around samples a transition or an element. --without draws each frame with and without an effect or overlay. --motion is a strip of frames across a time range or an element id. --listen draws a waveform under the cells. --frames also writes each full frame as a PNG.where FILE.tsx --at MOMENTS
Print each thing's box in pixels, whether it is inside the frame and the safe zones, and what it overlaps. A part marked in the layer source with a data-name attribute is listed too. --json prints the same data.fonts
List bundled families and a short Google Fonts list. --for filters by role (headline, body, captions, numbers, accent). --category filters by sans, serif, slab, condensed, display, handwriting, or mono. --sheet draws them as one image.add MEDIA...
Append each file to the manifest: kind, duration, size, frame rate, and audio, plus words from the transcript beside it. --id sets the asset id (default: the file name without its extension). --transcript names a different transcript.browser install
Download Chrome for Testing now.
CAVEATS
The first export needs a network unless Chrome is already cached or CUTCRAFT CHROMIUM names a local binary (the real variable joins those two words with an underscore).--check-layout exits 3 when it finds issues, so a script can tell a layout problem from a crash.--draft writes a sibling file. It does not overwrite --out.look --motion cannot be combined with --at, --around, or --without. --zones cannot be combined with --without.
