Installation

There are two ways to install:

• Prebuilt from npm (recommended). About a minute, with no Rust, FFmpeg or compiler to set up.
• From source. Only to work on the engine, or on a platform with no prebuilt package (Intel Mac, Linux on ARM). It takes 15 to 30 minutes.

With a coding agentCopy Anchor Link

Paste this into Claude Code, Codex or another coding agent:

Set up Kinetograph (https://github.com/0xS4N4TG/kinetograph) for me by following its AGENTS.md:
https://github.com/0xS4N4TG/kinetograph/blob/main/AGENTS.md
Ask me first whether I want the prebuilt package (recommended) or a build from source,
and ask before installing anything system-wide or installing the Kinetograph agent skills.

The agent asks which install you want, installs it, runs doctor, and then asks whether to add the agent skills and the MCP server.

From npmCopy Anchor Link

npm install kinetograph

You need Node.js 22 or newer. The native addon comes prebuilt for macOS (arm64), Linux (x64, glibc) and Windows (x64). It carries FFmpeg, so you install nothing else.

Kinetograph uses the GPU when there is one: Metal on macOS, Vulkan on Linux and D3D12 on Windows. Without a GPU it draws on the CPU. It needs no window or display, so it runs on a server or in CI.

From sourceCopy Anchor Link

You need:

• Node.js 22 or newer.
• A stable Rust toolchain from rustup.
• The FFmpeg development libraries, pkg-config and libclang.

Install the system libraries:

• macOS: brew install ffmpeg pkgconf. Without pkg-config, set FFMPEG_DIR=$(brew --prefix ffmpeg) instead.
• Debian or Ubuntu: sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libavutil-dev libclang-dev pkg-config

A build from source uses the ffmpeg on your PATH for libx264 when it has it (Homebrew's does).

If Homebrew's rustc comes first on your PATH and does not start, put rustup first:

export PATH="$HOME/.cargo/bin:/opt/homebrew/opt/rustup/bin:$PATH"

Then, from the repository root:

npm ci
npm run build

npm ci installs the workspace packages. npm run build builds the TypeScript packages and a debug build of the addon. For timings, build the release addon too:

npm run build:release -w @kinetographdev/native

The GPU tests, the golden images and the benchmarks run on an Apple M4 Mac. CI builds the Linux and Windows versions.

Check the installCopy Anchor Link

npx kinetograph doctor

With no entry, doctor prints the Node version, the platform, whether the addon loaded and which renderer draws:

node v22.x.x on darwin-arm64
addon: loaded, version 0.3.0
renderer: Skia GPU (Metal)
kinetograph doctor <entry> reports what a project holds that the engine cannot draw

If the addon line says NOT loaded, the text after it gives the reason. If Skia draws on the CPU because the GPU could not be used, doctor says why.

FFmpeg licenceCopy Anchor Link

Kinetograph uses two FFmpeg builds. The libraries linked into the native addon (kinetograph.*.node) are LGPL 2.1 or later, built by scripts/build-ffmpeg.sh. They do all decoding and the default encoding. The bin/ffmpeg program (bin/ffmpeg.exe on Windows) in the same npm package is a separate executable under GPL 2 or later, built by scripts/build-ffmpeg-gpl.sh with libx264, libx265, libvpx and AAC. The addon runs it as a child process, only for libx264 and libx265, and sends it raw pictures on a pipe. The two share no memory or code, so the PolyForm licence does not cover bin/ffmpeg and the GPL does not cover the addon.

• Each @kinetographdev/native-<platform> package holds LICENSE.md, FFMPEG-LICENSE.md, COPYING.GPLv2, COPYING.LGPLv2.1 and bin/SOURCES.txt, which lists the tag and commit of every library in the program.
• The GPL program is built from unmodified upstream sources: FFmpeg 9.0.1 (tag n9.0.1, github.com/FFmpeg/FFmpeg), x264 (a pinned commit of the stable branch, code.videolan.org/videolan/x264), x265 4.2 (bitbucket.org/multicoreware/x265_git) and libvpx 1.15.0, BSD-3-Clause (github.com/webmproject/libvpx). The configure options and pinned refs are in scripts/build-ffmpeg-gpl.sh.
• The addon's own encoders are VideoToolbox (macOS, the fallback when libx264 is missing), OpenH264 (macOS, Linux), Media Foundation (Windows), NVENC, libvpx (macOS, Linux), ProRes, AAC and GIF.
• To use your own ffmpeg, set KINETOGRAPH_FFMPEG. Each encoder is looked up there first, then in bin/ffmpeg, then in an ffmpeg on your PATH. To keep the GPL program out of your install, delete bin/ffmpeg. Then --encoder libx264 and --encoder libx265 fail with an error naming the missing encoder, unless KINETOGRAPH_FFMPEG or your PATH supplies one.

Run the CLICopy Anchor Link

npx kinetograph <command> runs the CLI. In a clone, run it from the repository root, or use node packages/cli/dist/cli.js <command>. The CLI reference lists every command.

Next, write a first project: First video.