joseflys-overlay-generator

Local helper for the José Flys flight-replay overlay export. The browser renders the telemetry overlay (glass-cockpit PFD or simple HUD) frame by frame and streams the raw pixels to this CLI, which pipes them into native ffmpeg to produce a single transparent .mov (QuickTime RLE by default, ProRes 4444 optional) — fast encode and true alpha, ready to drop over your real flight footage in DaVinci Resolve, Premiere, or Final Cut.

It's the "best of both worlds": the browser already knows how to draw the overlay (no renderer to reimplement), and ffmpeg on your machine encodes far faster than a browser can and can write real alpha (which browser video encoders cannot).

Usage

In the José Flys replay, load your track, open the export dialog and choose “Native export (ProRes)”. It will tell you to run:

npx joseflys-overlay-generator -o my-flight.mov

Keep that running, then click Export in the browser. Frames stream to the helper and ffmpeg writes my-flight.mov next to wherever you ran the command.

Options:
  -o, --output <file>     Output path (default: joseflys-overlay-<timestamp>.mov)
  -p, --port <number>     Port to listen on (default: 7842)
      --codec <name>      prores4444 | qtrle (default: prores4444)
      --ffmpeg <path>     Use a specific ffmpeg binary
      --keep              Keep running after a job (export several clips)
      --allow-origin <o>  Allow an extra browser origin (repeatable)
      --allow-any-origin  Accept any origin (loopback is always allowed)
  -h, --help / -v, --version

Requirements

• Node 18+.
• ffmpeg with ProRes support. The helper uses, in order: --ffmpeg <path>, the JOSEFLYS_FFMPEG env var, a system ffmpeg on your PATH, and finally a bundled ffmpeg-static binary (installed automatically as an optional dependency).
• A Chromium-based browser (Chrome/Edge). Browsers allow pages to talk to http://127.0.0.1 even from an HTTPS site, which is what makes the handshake work without certificates.

How it works

browser ──raw RGBA frames──▶  http://127.0.0.1:7842  ──stdin──▶  ffmpeg  ──▶  out.mov
 (renders the overlay)          (this helper)                  (QuickTime RLE / ProRes + alpha)

1. The browser polls GET /health until the helper answers.
2. POST /start { width, height, fps, frames } spawns ffmpeg.
3. Each frame is one ordered POST /frame with the canvas's raw RGBA bytes — sequential requests give both ordering and natural backpressure.
4. POST /finish closes ffmpeg's stdin and waits for the file to be written.

Security

The HTTP request never controls the output path or the codec — those come only from the CLI flags — so a stray cross-origin request can at worst produce a junk video, never write elsewhere or run arbitrary commands. Loopback origins are always accepted; other origins must be joseflys.com (or added with --allow-origin).

Codecs

The replay's export dialog picks the codec per job; --codec only sets the fallback.

• qtrle (default) — QuickTime Animation (RLE): lossless, alpha-capable, Resolve-native, and ~20× faster to encode than ProRes here (the encode is the bottleneck). RLE compresses the mostly-transparent overlay well, so files stay small. Best choice for this use case.
• prores4444 — ProRes 4444 with a 16-bit alpha channel (yuva444p10le). The classic interchange format, but much slower to encode; use it only if your pipeline specifically requires ProRes.

License

MIT © José F. Romaniello