README.md

Kintoun

Generate 3D GPX flyover videos locally, using CesiumJS in a headless Chrome.

Setup

1. Install ffmpeg — brew install ffmpeg on macOS.
2. Get a free Cesium ion token.
3. Copy the env example and paste the token:

   cp .env.example .env
   # edit .env, set CESIUM_ION_TOKEN

4. Install deps:

   npm install

Usage

npx tsx src/cli.ts render path/to/track.gpx \
  -o out.mp4 \
  --fps 30 \
  --width 1280 --height 720 \
  --duration 30 \
  --trailing 400 --altitude 200

Options:

Flag	Default	Meaning
-o, --output	out.mp4	Output MP4 path
--fps	30	Frames per second
--width / --height	1280 / 720	Resolution in pixels
--duration	track time or 30s	Video duration override
--trailing	400	Camera trailing distance (m)
--altitude	200	Camera altitude above target (m)

Tests

npm test

The E2E smoke test is skipped unless both CESIUM_ION_TOKEN is set and ffmpeg is on PATH.

Architecture

See docs/superpowers/specs/2026-04-13-kintoun-design.md for the design and docs/superpowers/plans/2026-04-13-kintoun-mvp.md for the implementation plan.

Pipeline:

GPX → parse → resample (per fps) → Puppeteer+Cesium → screenshot per frame → ffmpeg → MP4