Contributing to Kinetograph

The most useful pull requests start with a real problem. If you can, link an issue that shows how the problem affects people who render with Kinetograph, such as a Remotion project that draws wrong or a CSS property that is skipped. Put a before-and-after comparison in the pull request: a still or a short clip from before your change and one from after.

Issues and pull requests go to github.com/0xS4N4TG/kinetograph.

Report a problemCopy Anchor Link

A good report lets someone else see the problem on their own machine in a few minutes. Include:

• The version from npx kinetograph --version, and the output of npx kinetograph doctor with no arguments.
• The smallest project that shows the problem. One composition and a few frames is ideal. Leave out private footage and fonts you can't share.
• The frame where it goes wrong, and a still of it: npx kinetograph still <entry> <frame> -o frame.png.
• What you expected. For a Remotion project, a still of the same frame from Remotion is the clearest way to show it.
• The output of npx kinetograph doctor <entry>, which lists what the engine can't draw and on which frames.

Check What works first. If your problem is listed there, a comment on the matching issue with your project helps more than a new report.

Before a large changeCopy Anchor Link

Open an issue before you write a new feature, a new public API or a change that touches many packages. Say what you want to build and why. Small fixes, such as a wrong colour, a crash or a docs mistake, can go straight to a pull request.

Set up a cloneCopy Anchor Link

Follow Installation: From source, then:

git clone https://github.com/0xS4N4TG/kinetograph.git
cd kinetograph
npm ci
npm run build

Run the CLI from the clone with node packages/cli/dist/cli.js <command>. How the engine works lists where each part of the code lives.

Run the testsCopy Anchor Link

Run the tests for the part you changed, not the whole repository:

# One TypeScript package
npm test -w kinetograph

# One test file, from inside the package
cd packages/cli && npx vitest run test/render-export.test.ts

# One Rust crate, or one test target
cargo test -p kinetograph-core
cargo test -p kinetograph-core --test golden

The golden tests compare rendered frames with stored images. If your change is meant to alter the picture, regenerate them with UPDATE_GOLDEN=1 cargo test -p kinetograph-core --test golden. Say in the pull request which images changed and why.

The GPU tests, the goldens and the benchmarks run on Apple Silicon. On Linux and Windows, CI builds the addon and renders a few frames.

Rules for the codeCopy Anchor Link

A pull request that breaks one of these will be asked to change.

• A frame depends only on the project and the frame number. Nothing reads the wall clock.
• No browser draws anything. Chrome for Testing appears only in tests, as the reference a native drawing is compared against.
• Draw it natively, or say you can't. Content the engine can't draw is skipped or approximated and reported in the warnings and in doctor. --strict turns it into an error.
• Write your own code. Remotion APIs are rebuilt from Remotion's documented behaviour. Reading another project's source to understand it is fine. Copying it is not.
• random(seed) matches Remotion bit for bit.
• Speed claims need a measurement. Include the command, the machine and the numbers before and after.
• Use an existing crate for text shaping, layout and rasterising, and write the glue.

Send a pull requestCopy Anchor Link

• One change per pull request, on its own branch.
• Commit messages follow Conventional Commits, such as fix(dom): ..., feat(cli): ... or docs: ....
• Add or update a test that fails without your change.
• Visual changes include before-and-after stills or clips. A compatibility fix includes a comparison with what Remotion or Chrome draws for the same frame.
• Add a line to CHANGELOG.md under Unreleased, and the same line to packages/site/content/docs/changelog.mdx.
• Update the docs page that describes the behaviour you changed, and What works if you fixed a gap listed there.

LicenceCopy Anchor Link

Kinetograph is source-available under the PolyForm Small Business License 1.0.0 (LICENSE.md). It is free for individuals, non-profits and small companies. Other companies need a commercial licence (COMMERCIAL.md).

Kinetograph is a commercial project: companies above the small-business limit pay for a licence. By sending a pull request, you agree that your changes can be used, changed and licensed as part of Kinetograph, including under its commercial licences.