CLI

npx kinetograph <command> [entry] [options]
npx kinetograph <command> --help

The entry is a project file (.tsx, .ts, .jsx or .js) or a .json scene. Some commands take a frame number or a range after the entry, such as still.

Behaviour shared by all commandsCopy Anchor Link

• --json prints one JSON object on stdout instead of text. Progress goes to stderr, and stderr stays quiet with --json. A failure prints { "error": { "code", "message" } } and exits with 1.
• --help or -h prints the command's usage.
• kinetograph --version or -v prints the package version. kinetograph --help lists the commands.
• Exit code 0 is success. Exit code 1 is an error. A check that fails also exits with 1: check with type errors, lint with errors, and snapshot with a mismatch or a missing approved image.

Commands that open a project take two more options:

These commands open a project: still, render, strip, onion, inspect, lint, bench, audio analyze, snapshot and doctor.

Frames and rangesCopy Anchor Link

• A frame is a whole number from 0.
• 10..40 is frames 10 to 39. 10..=40 is frames 10 to 40.
• Leave out the start to begin at 0, as in ..40. Leave out the end to run to the last frame, as in 10... An inclusive range (..=) needs an end.
• --frames and snapshot --frames take a comma-separated list, such as 0,30,60.

compositionsCopy Anchor Link

Lists the compositions in a project: id, size, frame rate, length in frames and in seconds.

npx kinetograph compositions <entry>

No options beyond the shared ones.

stillCopy Anchor Link

Renders one frame to a PNG.

npx kinetograph still <entry> <frame> -o <output.png> [options]

renderCopy Anchor Link

Renders frames to a video with audio.

npx kinetograph render <entry> -o <output.mp4> [options]

The export flags are checked before the project is bundled. A refusal says which flag to change.

render prints the output path, size, frame range, codec, encoder, pixel format and time. It also says how many frames were the same as the one before and were not drawn again.

stripCopy Anchor Link

Writes a contact sheet of evenly spaced frames, labelled with the frame number and time.

npx kinetograph strip <entry> -n 12 -o <sheet.png> [options]

onionCopy Anchor Link

Blends frames of a range over one another, to show a motion path.

npx kinetograph onion <entry> <a..b> -n 6 -o <onion.png> [options]

inspectCopy Anchor Link

Prints the scene graph at one frame: each layer's id and type, its bounds, its effects, and its text or file.

npx kinetograph inspect <entry> --frame 30

With --json, the result is the full scene graph.

lintCopy Anchor Link

Checks a project at a few frames. It reports text that overflows its box or the canvas, layers off the canvas, overlapping text, missing fonts and assets, type errors, and content the engine cannot draw. Each finding names its rule, its layer and its frames.

npx kinetograph lint <entry> --frames 0,30,60

Exit code 1 means at least one error. Warnings do not change the exit code.

checkCopy Anchor Link

Runs tsc --noEmit on the project, using the nearest tsconfig.json. A misspelled prop renders without an error, so this finds it.

npx kinetograph check <entry>

No options. A scene file, or a JavaScript project with no tsconfig.json, has nothing to check.

benchCopy Anchor Link

Times each stage of drawing a frame, in milliseconds. The stages are js, then stringify, then the addon's handoff, resolve, raster, composite and readback, and total.

npx kinetograph bench <entry> --frame 30 --runs 10
npx kinetograph bench <entry> --range 40..90

bench and the studio run React's development build unless NODE_ENV is set. To time the production build, run NODE_ENV=production npx kinetograph bench ....

audio analyzeCopy Anchor Link

Mixes the audio of a project and measures it.

npx kinetograph audio analyze <entry> --scenes 0..90,90..180

The output gives the integrated loudness (LUFS), the true peak (dBTP), the number of clipped samples and the silences. See Audio.

snapshotCopy Anchor Link

Compares rendered frames with approved PNGs. The approved files are in a __snapshots__/ folder next to the entry. Each one is named after the file and the composition, with the frame number, for example card.Title.f30.png.

npx kinetograph snapshot <entry> --frames 0,30,60
npx kinetograph snapshot <entry> --update

A frame matches when no colour channel differs from the approved image by more than 2 levels. A mismatch or a missing approved file exits with 1.

effectsCopy Anchor Link

Lists every effect with its type, description and fields.

npx kinetograph effects

No options.

doctorCopy Anchor Link

Runs every frame in the range without the GPU, and reports what the engine cannot draw, with the frames it happens in. Use it before a long render. See Remotion compatibility.

npx kinetograph doctor <entry> --range 0..120
npx kinetograph doctor

With no entry, doctor prints the Node version, the platform and whether the addon loaded.

studioCopy Anchor Link

Opens the studio in a browser: a preview, the timeline, the scene tree, props and a render queue.

npx kinetograph studio <entry>

The studio is the @kinetographdev/studio package. The command loads it by name, so it must be installed next to kinetograph. Stop the studio with Ctrl-C.

mcpCopy Anchor Link

Runs the MCP server on stdio. It has one tool for each command except studio. See Use with agents.

npx kinetograph mcp

Export optionsCopy Anchor Link

The render options that set the codec and quality follow Remotion's names. These are the defaults, unless a flag changes them:

• H.264 uses crf 18 with the software encoder. With the VideoToolbox encoder on macOS, it uses a bit rate of 0.2 bits per pixel per frame.
• VP9 uses crf 30, and H.265 uses crf 28.
• The audio bit rate is 96 kbit/s per channel. The encoder choice for each codec is in AUTHORING.md, section 9.

--crf is not used for prores or gif.