RENDER KIT - Music Video in Code
Free files from the AI2Play tutorial. Square brackets [ ] = fill in your own.

WHAT IT IS
A small set of files that turns a three.js web page into a video. Headless Chrome draws every frame,
FFmpeg joins the frames into an mp4 and adds your song. Also inside: the one-wheel robot from the video
(built only from code, no model files) and a 5-second sample scene to test your PC.

THE FILES
  render.mjs     The renderer. Steps the page through time, frame by frame, and pipes the frames into FFmpeg.
                 It also makes test stills and runs the checks. All options are listed at the top of the file.
  common.mjs     Shared helpers: song timing (beats, drum hits), the renderer that draws each frame 10 times
                 (real motion blur) at double size (smooth edges), the film finish (soft glow, tone curve,
                 grain) and the lyric layer.
  wheelbot.mjs   Builds the robot from three.js shapes.
  robotrig.mjs   Makes the robot move like it has weight: springs, lean, a wheel that rolls without slipping,
                 eyes, arms, and a check that no arm goes inside the body.
  sample.html    A 5-second test scene: the robot rolls in, brakes, turns to the camera and dips on the beat.
  LICENCES.txt   What each part is and its licence.
  LICENSE.txt    The MIT licence for our code: you can use it, change it and share it, also for paid work.
                 Keep LICENSE.txt with the code when you share it.

INSTALL (once)
1. Node.js 22 or newer: nodejs.org. Nothing else to install for the kit: no "npm install".
2. Google Chrome (or Microsoft Edge). The kit looks in the usual places. If it cannot find it, add
   --chrome "[path to chrome.exe]" to the command, or set the CHROME_PATH environment variable.
3. FFmpeg, so that the command "ffmpeg -version" works in a terminal. Get it from ffmpeg.org
   (on Windows, for example: winget install Gyan.FFmpeg). Open a new terminal after you install it.
4. Internet the first time a page loads: three.js and the fonts come from the web.

RENDER THE SAMPLE
Open a terminal in this folder and run these, one at a time:

  node render.mjs stills --page sample.html --at 1,2.5,4.5
      3 test pictures in the "out" folder. Look at them first: it takes seconds, a video takes minutes.

  node render.mjs video --page sample.html --from 0 --to 5 --res 1080
      The video: out\draft.mp4 (1920x1080, 30 fps, 150 frames, 5 seconds, no sound).

  node render.mjs overlap --page sample.html --from 0 --to 5 --step 0.05
      The arm check. It should say: NO OVERLAPS.

Measured on our PC (RTX 4090, Windows 11): the stills took about 8 seconds, the 5-second video about
19 seconds with one Chrome, page loading included (before the speed-up below it took 2 minutes).

WHY IT IS FAST (and how to keep it fast)
- The slow part of rendering a web page to video is usually NOT the 3D drawing (about 0.05 s a frame here) but
  saving each frame as a picture: a perfect-quality screenshot took Chrome 1 to 2 seconds per frame.
- So the kit skips the screenshot when it can: a page that sets window.RAW_OK = true (nothing in HTML is shown
  over the 3D canvas) hands its canvas pixels straight to the video encoder. Same picture to the last pixel,
  proven with: node render.mjs rawcheck --page sample.html --at 1,2.5
- Pages that show HTML on top (lyrics, labels) use a quality-100 JPEG screenshot instead: about 8 times faster
  than the perfect-quality one, and it looks the same after the video encoder.
- Changed only a few seconds? Do not render everything again: keep the last silent render and run
  node render.mjs patch --page sample.html --base out\v1.mp4 --redo 2-3 --out out\v2.mp4
  (it renders only from the keyframe before the change and checks that every other frame is unchanged).
- The render runs at low priority, so your PC stays usable while it works.

YOUR OWN SONG AND SCENES
- Add your song: --song "[my song.wav]". The kit cuts it to --from and --to. Without --song the video is silent.
- 2560x1440: --res 1440. A bit faster: --jobs 2 = two Chromes render two parts at once (about 30 % faster
  here; 3 or more did not help, the graphics card is then the limit; each needs about 0.5 GB of graphics
  memory at 1080p; keep 1 on a small card or while you work on the PC).
- A new scene = a copy of sample.html. Every scene page must:
    1. set window.SONG before the modules load (the beat grid; for lyrics, the lines with word times),
    2. define window.renderFrame(t): draw the frame at time t, using only t (no clock, no random numbers),
       so every render gives the same frames (to within tiny, invisible graphics-card rounding),
    3. set window.__ready = true when it has loaded.
    4. if nothing in HTML shows over the canvas: set window.RAW_OK = true (the fast capture, see above).
  Optional: window.overlapAt(t) returns a list of problems at time t (the "overlap" check), window.diag(t).
- You can ask Claude Code: "Read README.txt, render.mjs and sample.html. Then make a new scene page like
  sample.html for my song [song file]. Show me stills before you render the video."

IF SOMETHING GOES WRONG
- "Chrome not found": add --chrome "[path to chrome.exe]".
- "song not found": check the path in --song (put it in quotes if it has spaces).
- It stops with "HANG" or "capture stalled": Chrome's screenshot got stuck on a frame. Run the same command
  again; if it keeps happening, try --fmt webp (a page with window.RAW_OK = true never takes screenshots).
- A black flash and the render stops on a slow card: one frame took too long for the graphics driver.
  Use --res 1080, or fewer sub-frames per frame: in the page, frame(t, draw, { n: 5 }) instead of the
  default 10 (less motion blur). More in "Render on Your PC - Notes.txt".
- No graphics card at all: --gl sw renders on the processor (very slow).
