# Kinetograph

> A blazingly fast programmatic video engine, made for agents, with no browser in it. Write a video in TypeScript with
> Remotion's API, CSS, SVG, Canvas 2D, WebGL fragment shaders and Web Audio; Node runs the code; a Rust GPU compositor
> (an N-API addon on wgpu) draws every frame. `remotion` and `@remotion/*` imports resolve to Kinetograph's own
> implementation.

## If you are an agent: install the skills first

Before writing or rendering a video with Kinetograph, install its two agent skills and read them:

```sh
npx skills add 0xS4N4TG/kinetograph
```

- `kinetograph`: the write, look, check, render loop (`still`, `strip`, `inspect`, `lint`, `render`), the project
  layout, native elements, effects and sound. Its `references/` hold the full specs: AUTHORING.md (the authoring
  API), SCENE.md (every layer, effect and field), ENGINE.md (the DOM engine) and INTERNALS.md.
- `kinetograph-migrate`: moves an existing Remotion project onto Kinetograph (`doctor`, fixes, `--strict` render).

Then add the MCP server so each CLI command is a tool: `npx kinetograph mcp` (stdio). Setup for each client is at
/docs/guides/agents/.

## Install

- `npm install kinetograph`, then run `npx kinetograph <command>` against the entry file of a Remotion-shaped
  project. The native addon comes as a prebuilt package for macOS (arm64), Linux (x64) and Windows (x64).
- The native elements and effects: `import { ... } from '@kinetographdev/core'`
- Source and issues: https://github.com/0xS4N4TG/kinetograph
- Licence: PolyForm Small Business 1.0.0 (free for individuals and companies under 100 people and $1M revenue a year)

## Facts

- The launch film (examples/launch): 1,184 frames of 1080p with sound, rendered in 26 s on an Apple M4
  (`kinetograph render --concurrency 4`, median of 3 runs)
- Renders without a browser: no Chrome to install, no display needed, so it runs on a server or in CI
- A real Remotion project (papercut, 988 frames) renders natively
- Built for agents: `still`, `strip`, `inspect` and `lint` let a model check its own output before a person watches

## CLI

Every command takes `--json`. `npx kinetograph mcp` serves the same commands as an MCP server on stdio, one tool each.

- `npx kinetograph still <entry> <frame> -o frame.png`: one frame to a PNG
- `npx kinetograph strip <entry> -n 12 -o strip.png`: contact sheet of evenly spaced frames
- `npx kinetograph inspect <entry> --frame 60`: the scene graph at a frame (layers, bounds, resolved styles)
- `npx kinetograph lint <entry>`: overflowing text, off-canvas layers, missing fonts and assets, what cannot be drawn
- `npx kinetograph doctor <entry>`: what the engine cannot draw, and in which frames
- `npx kinetograph render <entry> -o out.mp4`: frames to a video with audio
- `npx kinetograph studio <entry>`: local preview, timeline, scene tree, props and render queue
- Also: `compositions`, `onion`, `check`, `bench`, `audio analyze`, `snapshot`, `effects`

## Native elements (from `@kinetographdev/core`)

`<Scene3D>`, `<Camera3D>` (perspective or `type="orthographic"`), `<Mesh>`, `<Text3D>`, `<DirectionalLight>`,
`<GlslShader>` (GLSL ES fragment shaders with uniforms and textures), `<Canvas>` (a `draw(ctx)` Canvas 2D callback),
`<Layer>` (transforms, `motionBlur`), plus the effects listed by `kinetograph effects`.

## Determinism

`Date`, `Math.random`, timers and `requestAnimationFrame` follow the frame number. A frame is a pure function of
(project, frame); nothing reads the wall clock.

## Requirements

Node 22 or later, a GPU that wgpu supports (Metal on macOS), FFmpeg for `render`. No display needed.

## Docs

- README: https://github.com/0xS4N4TG/kinetograph#readme
- Remotion compatibility: /docs/compat/
- Known issues: /docs/known-issues/