Skip to content

A motion design studio on your own machine: Claude makes the video step by step, you approve every stage. Bring your own Claude Code or API key.

16.4 KB
Raw Blame
// Kinetograph: the studio's video renderer. A GPU engine (Rust, as a Node addon) that renders the same Remotion-API
// TSX projects with no Chrome: a project's `remotion` and `@remotion/*` imports resolve to Kinetograph's own
// implementation, so a project needs no node_modules of its own. github.com/GTKottman/kinetograph (a fork of
// 0xS4N4TG/kinetograph; PolyForm Small Business 1.0.0).
//
// One shared install per studio, in tools/kinetograph. It comes from the owner's fork build when one is here: the npm
// tarballs the fork's `node scripts/pack-local.mjs` writes (its packs/ folder), found in MFX_KINETOGRAPH_PACKS, config.json
// tools.kinetographPacks (either may name the fork's folder) or tools/downloads/kinetograph. With none, it is the
// pinned npm release (KINETOGRAPH_VERSION). Nothing is compiled here either way. A local build of the fork can also be
// run in place: MFX_KINETOGRAPH (or config.json tools.kinetograph) naming its cli.js, its package folder
// (node_modules/kinetograph or packages/cli) or the fork's own folder.
//
// kgRender and kgStill return shell command strings for the render queue's `bash -c` lines. They never pass --json:
// it silences the `rendering frame N/T` progress line on stderr, which the queue reads for its percent.
import { replayOn, KG_STUB } from './replay.mjs';
import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { homedir } from 'node:os';
import { join } from 'node:path';
import { loadConfig, studioRoot } from './studio.mjs';

// The fork's release. The fork's main is ahead of it (motion tracking, onVideoFrame, SVG foreignObject and gradient
// fixes, a bundled monospace font); none of the studio's renders need those. Move this when a newer release is out.
export const KINETOGRAPH_VERSION = '0.2.0';
export const KINETOGRAPH_NODE = 22;

// The prebuilt addon (and its ffmpeg) for this computer; Kinetograph publishes no others.
const NATIVE = { 'linux-x64': 'linux-x64-gnu', 'darwin-arm64': 'darwin-arm64', 'win32-x64': 'win32-x64-msvc' };
export const nativePackage = (platform = process.platform, arch = process.arch) => {
  const p = NATIVE[`${platform}-${arch}`];
  return p ? `@kinetographdev/native-${p}` : null;
};

export const kgDir = (root) => join(root, 'tools', 'kinetograph');
const modules = (root) => join(kgDir(root), 'node_modules');
// What tools/kinetograph was installed from: written by setup for a fork build ({source: 'fork', commit, branch, packs}).
export const kgSourceFile = (root) => join(kgDir(root), 'source.json');
const readJson = (f) => { try { return JSON.parse(readFileSync(f, 'utf8')); } catch { return null; } };

/**
 * The owner's fork build as npm tarballs, if there is one: {dir, build, files: {<package name>: <tarball path>}}, where
 * build is the pack's BUILD.json (commit, branch, platform). It needs the CLI's tarball and this computer's platform
 * package; a folder that holds a packs/ folder (the fork's checkout) counts as that packs/ folder.
 */
export function kgPacks(root) {
  let saved = null;
  try { saved = loadConfig(root).tools?.kinetographPacks || null; } catch { saved = null; }
  const native = nativePackage();
  for (const d of [process.env.MFX_KINETOGRAPH_PACKS, saved, join(root, 'tools', 'downloads', 'kinetograph')].filter(Boolean)) {
    const dir = existsSync(join(d, 'packs', 'BUILD.json')) ? join(d, 'packs') : d;
    const build = readJson(join(dir, 'BUILD.json'));
    if (!build || !Array.isArray(build.packages)) continue;
    const files = {};
    for (const p of build.packages) if (p && p.name && p.file && existsSync(join(dir, p.file))) files[p.name] = join(dir, p.file);
    if (files.kinetograph && native && files[native]) return { dir, build, files };
  }
  return null;
}
const installedCli = (root) => join(modules(root), 'kinetograph', 'dist', 'cli.js');
// Where npm puts the `kinetograph` command; sessions get it on their PATH.
export const kgBinDir = (root) => join(modules(root), '.bin');

// A named place as its cli.js: the file itself, a package folder (dist/cli.js) or the fork's folder.
function asCli(p) {
  let dir = false;
  try { dir = statSync(p).isDirectory(); } catch { return null; }
  if (!dir) return p;
  return [join(p, 'dist', 'cli.js'), join(p, 'packages', 'cli', 'dist', 'cli.js')].find((f) => existsSync(f)) || null;
}

// The cli.js to run: one named by the owner (a local build of the fork), else the studio's install.
function cliPath(root) {
  let saved = null;
  try { saved = loadConfig(root).tools?.kinetograph || null; } catch { saved = null; }
  return [process.env.MFX_KINETOGRAPH, saved, installedCli(root)].filter(Boolean).map(asCli).find((p) => p && existsSync(p)) || null;
}

const readVersion = (pkg) => readJson(pkg)?.version || null;

// Where `npx --yes kinetograph@<version>` keeps its copy: ~/.npm/_npx/<hash>/node_modules/kinetograph. Running that
// cli.js with this Node skips npx's own start-up (4.2 s against 1.16 s for the same inspect, plan G1).
// Only a copy of exactly the pinned version with its addon beside it counts; null when there is none.
export function npxCacheCli(version = KINETOGRAPH_VERSION, { cacheDir } = {}) {
  const base = join(cacheDir || process.env.npm_config_cache || join(homedir(), '.npm'), '_npx');
  let dirs = [];
  try { dirs = readdirSync(base); } catch { return null; }
  const native = nativePackage();
  for (const d of dirs) {
    const nm = join(base, d, 'node_modules');
    const cli = join(nm, 'kinetograph', 'dist', 'cli.js');
    if (!existsSync(cli) || readVersion(join(nm, 'kinetograph', 'package.json')) !== version) continue;
    if (native && !existsSync(join(nm, native, 'package.json'))) continue;
    return cli;
  }
  return null;
}

const resolved = new Map();
let warned = false;

/**
 * How the CLI is run, once per studio and process: {argv, source, version}. In order: the studio's install (or the
 * owner's local build) -> the npx cache copy of the pinned version -> npx itself (slow: warns once). The result is
 * remembered while its cli.js still exists. `warn` is where the npx warning goes (default console.warn).
 * Reuse this for any process that runs the CLI directly (motion data's inspect calls): spawn argv[0] with argv.slice(1).
 */
export function kgResolve(root, { warn = (m) => console.warn(m) } = {}) {
  const hit = resolved.get(root);
  if (hit && (hit.source === 'npx' || existsSync(hit.argv[1]))) return hit;
  let r;
  const cli = cliPath(root);
  if (cli) r = { argv: [process.execPath, cli], source: 'install', version: readVersion(join(cli, '..', '..', 'package.json')) };
  else {
    const cached = npxCacheCli();
    if (cached) r = { argv: [process.execPath, cached], source: 'npx-cache', version: KINETOGRAPH_VERSION };
    else {
      if (!warned) { warned = true; warn(`Kinetograph is not installed in ${kgDir(root)} and has no npx cache copy: every process pays npx start-up (about 3 s). Install it (components.install).`); }
      r = { argv: ['npx', '--yes', `kinetograph@${KINETOGRAPH_VERSION}`], source: 'npx', version: KINETOGRAPH_VERSION };
    }
  }
  resolved.set(root, r);
  return r;
}
export const kgResetResolve = () => { resolved.clear(); warned = false; seqSupport.clear(); };

// Whether the resolved CLI can write numbered pictures itself (`render --sequence <dir>`, the owner's fork build; npm 0.2.0
// can't). Asked once per CLI (`render --help` lists the flag) and remembered. MFX_KG_SEQUENCE=1|0 forces the answer.
const seqSupport = new Map();
export function kgHasSequence(root = studioRoot()) {
  const forced = process.env.MFX_KG_SEQUENCE;
  if (forced === '1' || forced === '0') return forced === '1';
  const r = kgResolve(root);
  const key = r.argv.join('\0');
  if (!seqSupport.has(key)) {
    const out = spawnSync(r.argv[0], [...r.argv.slice(1), 'render', '--help'], { encoding: 'utf8', timeout: 30_000 });
    seqSupport.set(key, out.status === 0 && /--sequence\b/.test(`${out.stdout || ''}${out.stderr || ''}`));
  }
  return seqSupport.get(key);
}

// How the CLI is run, as an argv prefix: this Node and the cli.js, or (nothing found) npx with the pinned version.
// replay mode (src/replay.mjs): the recorded-clip stand-in, never the real renderer
export const kgCommand = (root) => (replayOn() ? [process.execPath, KG_STUB] : [...kgResolve(root).argv]);

// Whether it can render here: the CLI, its addon for this computer, and Node 22 or newer. No process is started.
export function kgStatus(root) {
  const node = Number(process.versions.node.split('.')[0]);
  const native = nativePackage();
  if (!native) return { ok: false, version: null, detail: `no renderer build for ${process.platform}-${process.arch} (Linux x64, macOS arm64 and Windows x64 only)` };
  const cli = cliPath(root);
  if (!cli) return { ok: false, version: null, detail: 'not installed' };
  const version = readVersion(join(cli, '..', '..', 'package.json'));
  if (node < KINETOGRAPH_NODE) return { ok: false, version, path: cli, detail: `The renderer ${version} needs Node ${KINETOGRAPH_NODE} or newer (this is ${process.version})` };
  // The studio's install must have the addon; a local build of the fork finds its own.
  if (cli === installedCli(root) && !existsSync(join(modules(root), native, 'package.json'))) return { ok: false, version, path: cli, detail: `${native} is missing: reinstall` };
  if (cli !== installedCli(root)) return { ok: true, version, path: cli, source: 'local', detail: `Renderer ${version} (built in)` };
  // The studio's install: the fork build it came from, or the npm release. A fork build that is here and not the one
  // installed (newer, or the install is still npm's) asks for a reinstall.
  const from = readJson(kgSourceFile(root));
  const packs = kgPacks(root);
  if (from?.source === 'fork') {
    const name = `Renderer ${version} (build ${from.branch || '?'} ${String(from.commit || '').slice(0, 8)})`;
    const stale = packs && packs.build.commit !== from.commit ? `: ${packs.dir} holds ${String(packs.build.commit).slice(0, 8)}, reinstall` : '';
    return { ok: !stale, version, path: cli, source: 'fork', commit: from.commit || null, detail: `${name}${stale}` };
  }
  if (packs) return { ok: false, version, path: cli, source: 'npm', detail: `Renderer ${version} from npm, but a newer build is in ${packs.dir}: reinstall` };
  const pinned = version === KINETOGRAPH_VERSION ? '' : ` (expected ${KINETOGRAPH_VERSION}: reinstall)`;
  return { ok: !pinned, version, path: cli, source: 'npm', detail: `Renderer ${version}${pinned}` };
}

// The ffmpeg that turns a render into numbered pictures: KINETOGRAPH_FFMPEG, else the one on the PATH (the studio needs
// it anyway: doctor checks it). Not the ffmpeg that comes with the addon: that build only encodes Kinetograph's videos
// (no PNG encoder, no image2 muxer, no ProRes decoder), so it can't read the ProRes file back.
export function kgFfmpeg() {
  return [process.env.KINETOGRAPH_FFMPEG].filter(Boolean).find((p) => existsSync(p)) || 'ffmpeg';
}

// ---- command lines ----

// One word for bash: left bare when it's plain, else in single quotes.
export const shq = (s) => (/^[\w@%+=:,./-]+$/.test(String(s)) ? String(s) : `'${String(s).replace(/'/g, `'\\''`)}'`);

// --props takes the JSON itself. Remotion took a file too: a file's JSON is read by the shell when the command runs.
function propsArg(props) {
  if (props === undefined || props === null || props === '') return [];
  if (typeof props === 'object') return ['--props', shq(JSON.stringify(props))];
  const s = String(props).trim();
  return s.startsWith('{') ? ['--props', shq(s)] : ['--props', `"$(cat ${shq(s)})"`];
}

// Remotion's codecs as Kinetograph's: h264, h265, prores, vp9, gif.
const CODECS = { h264: 'h264', 'h264-mkv': 'h264', h265: 'h265', prores: 'prores', vp9: 'vp9', vp8: 'vp9', gif: 'gif' };

// [from, to] (both shown, as Remotion's --frames=a-b), or one frame -> Kinetograph's inclusive range.
function range(frames) {
  if (frames === undefined || frames === null) return null;
  const [from, to] = Array.isArray(frames) ? frames : [frames, frames];
  return { from: Number(from), to: Number(to ?? from) };
}

/**
 * A video render (or, with `sequence`, numbered pictures in the `output` folder) as one shell command, run in the
 * project folder. Options as Remotion names them:
 *   codec        h264 (default), h265, prores, vp9, gif; vp8 renders as vp9 and h264-mkv as h264 (Kinetograph writes
 *                .mp4, .mov, .webm and .gif only)
 *   crf, pixelFormat, scale, concurrency   as Remotion's
 *   imageFormat  only for `sequence` (png, the default, or jpeg): a video is always drawn losslessly and encoded
 *   sequence     numbered pictures in `output`, element-<frame>.png (from the first frame, zero-padded to the last frame's
 *                digits, as Remotion names them). With the fork build: `render --sequence <output>`, straight PNGs. Without
 *                it (npm 0.2.0, which renders video only) or for jpeg: the frames go into a ProRes 4444 file beside them,
 *                which ffmpeg (kgFfmpeg) writes out as the pictures
 *   frames       [from, to], both rendered
 *   props        an object, a JSON string or a JSON file
 *   strict       fail on content Kinetograph can't draw, instead of leaving it out with a warning
 *   root         the studio (default: this one), for where Kinetograph is installed
 */
export function kgRender({ root = studioRoot(), entry = 'src/index.ts', composition, output, codec, crf, imageFormat, pixelFormat, sequence = false, frames, scale, props, concurrency, strict = false } = {}) {
  if (!output) throw new Error('kgRender: no output');
  const kg = kgCommand(root).map(shq);
  const r = range(frames);
  const args = [...kg, 'render', shq(entry)];
  if (composition) args.push('--comp', shq(composition));
  args.push(...propsArg(props));
  if (strict) args.push('--strict');
  if (r) args.push('--range', `${r.from}..=${r.to}`);
  if (scale !== undefined && scale !== null && Number(scale) !== 1) args.push('--scale', String(Number(scale)));
  // Remotion's "50%" form has no equivalent: Kinetograph's own default (half the cores, at most 4) is used then.
  if (Number.isInteger(Number(concurrency)) && Number(concurrency) > 0) args.push('--concurrency', String(Number(concurrency)));
  if (sequence && !(imageFormat === 'jpeg' || imageFormat === 'jpg') && kgHasSequence(root)) {
    args.push('--sequence', shq(output.replace(/\/+$/, '')));
    return [`mkdir -p ${shq(output)}`, args.join(' ')].join(' && ');
  }
  if (sequence) {
    const ext = imageFormat === 'jpeg' || imageFormat === 'jpg' ? 'jpeg' : 'png';
    const tmp = `${output.replace(/\/+$/, '')}/.kg-sequence.mov`;
    const pad = r ? Math.max(1, String(r.to).length) : 4;
    const ff = kgFfmpeg();
    // The ProRes file is BT.709, limited range (tagged so); ffmpeg's own RGB conversion would read it as BT.601 and shift
    // the colours (#f97316 came back #ed6b1b), so the matrix is named.
    args.push('-o', shq(tmp), '--codec', 'prores', '--prores-profile', '4444');
    return [`mkdir -p ${shq(output)}`, args.join(' '),
      `${shq(ff)} -v error -y -i ${shq(tmp)} -vf scale=in_color_matrix=bt709:in_range=tv -start_number ${r ? r.from : 0}${ext === 'jpeg' ? ' -q:v 2' : ''} ${shq(`${output.replace(/\/+$/, '')}/element-%0${pad}d.${ext}`)}`,
      `rm -f ${shq(tmp)}`].join(' && ');
  }
  args.push('-o', shq(output));
  const c = codec ? CODECS[codec] : null;
  if (codec && !c) throw new Error(`The renderer can't render codec "${codec}" (${Object.keys(CODECS).join(', ')})`);
  if (c) args.push('--codec', c);
  if (crf !== undefined && crf !== null && c !== 'prores' && c !== 'gif') args.push('--crf', String(Number(crf)));
  if (pixelFormat && c !== 'gif') args.push('--pixel-format', shq(pixelFormat));
  return args.join(' ');
}

/**
 * One frame to a PNG, as one shell command run in the project folder. Kinetograph's still has no --scale: a scaled
 * still is a one-frame sequence render. Stills are always PNG.
 */
export function kgStill({ root = studioRoot(), entry = 'src/index.ts', composition, output, frame = 0, scale, props, strict = false } = {}) {
  if (!output) throw new Error('kgStill: no output');
  if (scale !== undefined && scale !== null && Number(scale) !== 1) {
    const dir = `${output}.frames`;
    const f = Number(frame);
    return `${kgRender({ root, entry, composition, output: dir, sequence: true, frames: [f, f], scale, props, strict })} && mv ${shq(`${dir}/element-${String(f)}.png`)} ${shq(output)} && rm -rf ${shq(dir)}`;
  }
  return [...kgCommand(root).map(shq), 'still', shq(entry), String(Number(frame)), ...(composition ? ['--comp', shq(composition)] : []), ...propsArg(props), ...(strict ? ['--strict'] : []), '-o', shq(output)].join(' ');
}