Chess game film
This skill turns one chess game into a 1080p60 review film of about 40–110 seconds, using template/. The template is a finished, working film of the Opera Game (Morphy, 1858). You copy it, swap in your game, and edit one file.
The film is a deterministic HTML/canvas scene, where window.renderAt(t) draws the frame at time t. Puppeteer renders it frame by frame and ffmpeg encodes the result. The music and every sound are synthesized from the same schedule as the picture, so there's nothing to license and nothing drifts out of sync.
What makes these films good (keep all of it)
- The board is the film. It stays whole, sharp and uncovered from the first move to the last, and every move is played on it. Never put captions, titles, quotes or overlays on the board, and never blur or dim it. Viewers come to watch the game.
- Words live in the panel only. That means the move with its grade, one short note, a chapter heading, and the occasional quote. Keep notes to one sentence, a fact the viewer can check on the board.
- Real data only.
- Moves come from the PGN and grades from Stockfish.
- Quotes are the players' real words, verbatim, with a source.
- Never invent a quote, a thought, a motive or a number.
- If the request contradicts the data (e.g. "show White's pre-moves" when the move times show Black made them), follow the data and tell the person plainly.
- The music follows the game. Key moves land on a downbeat with a hit, the music thins under quotes, builds into the climax and rings out after the end. The scheduler and composer do this for you, provided you mark the right
KEYmoves. - Pace is storytelling. Ordinary moves go by on the beat; the moves that decide the game are slow, lifted and given room to read. Pick 3–8 key moves, no more.
- Frame 0 is the thumbnail. It shows the headline, the two kings on their squares, the names and one foot line, then flows straight into the board. Ship it as
out/poster.png. - Check stills before every full render, and look at them. Most faults (overflowing text, an arrow hiding the move, a quote card running into the graph) are visible in a still.
- No decoration for its own sake. That means no small uppercase "kicker" labels above headings and no pill-shaped status badges. Use plain sentence-case text.
What you need
- Node 18+ for
npm install(puppeteer-core) and the render. - Python 3.9+ with
pip install chess numpy. - ffmpeg on PATH.
- Chrome or Chromium:
render.mjsfinds the usual installs, or setCHROME=<path>. - Stockfish: from https://stockfishchess.org/download/. Pass
--engine <path>or setSTOCKFISH.
Steps
- Scaffold. Run
node <this skill>/new-film.mjs <project dir> [game.pgn]. It copies the template and runsnpm install. - Get the game as a PGN. See references/data.md for Lichess, Chess.com, databases and agent logs. Put it in
game.pgn. - Analyze. Run
python scripts/prepare.py game.pgn --engine <stockfish>. It writesdata/game.jsand prints a story sheet: every move with its grade, eval and swing, the biggest swings, the mistakes and great moves, and (if the PGN has clocks) move times, flagging instant moves. Read it: the story is in the swings. - Pick pieces and a board (optional). The default is cburnett pieces on a green board.
- Pieces:
node scripts/get-pieces.mjs --list, thennode scripts/get-pieces.mjs merida. - Board:
BOARD.themeintimeline.jsis green, brown, blue or grey. - See references/board-and-pieces.md, and mind the licences.
- Pieces:
- Write
timeline.js. This is the only per-game file. Follow references/timeline.md:FILM: names, headline, foot line, end card.KEYmoves.CHAPTERS,NOTES,ARROWS.QUOTES, if real words exist.- Optional
STRETCHandPREMOVES, plusHILITE. MUSIC: tempo, key, minor or major.
- Sound. Run
node scripts/plan.mjs, thenpython scripts/sound.py. This composesout/music.wavand mixesout/soundtrack.wavat −14 LUFS. Read the printed energy-by-bar line, and see references/music.md. - Stills. Run
node render.mjs --stills 0.5,<times>, then open every PNG inout/stills/.- Take frame 0, each key move about 0.5 s after it lands, each quote, the mate or the end, the summary (
T.SUMMARY + 3) and the end card. plan.mjsprints the film's length and the mate time. Each move's landing time isTL.PLY_T[n].- Fix, then render the stills again.
- Take frame 0, each key move about 0.5 s after it lands, each quote, the mate or the end, the summary (
- Render.
node render.mjswritesout/film.mp4. It takes about 1–5 minutes per minute of film, depending on cores;PAR=nsets the number of workers.- Then cut the poster:
ffmpeg -i out/film.mp4 -frames:v 1 out/poster.png.
- Check the file.
- Look at 3–4 frames cut from the MP4 (
ffmpeg -ss <t> -i out/film.mp4 -frames:v 1 x.png). - Measure loudness with
ffmpeg -i out/film.mp4 -af ebur128=peak=true -f null -. Aim for about −14 LUFS with the true peak under −1 dBTP.
- Look at 3–4 frames cut from the MP4 (
- Deliver.
- Give the film and the poster.
- Say what the film marks and why.
- Correct anything in the request the data contradicted.
- List the piece-set licence and any attribution it needs.
Files in a project
| File | Role |
|---|---|
timeline.js | The one file you edit. What matters in this game; the scheduler at its foot turns that into timing. |
game.pgn | The game. |
scene.html, scene.js | The game-agnostic scene: board, pieces, panel, graph, thumbnail, summary, end card. Read references/animation.md before changing it. |
scripts/prepare.py | PGN → Stockfish review → data/game.js + story sheet. |
scripts/get-pieces.mjs | Downloads a Lichess piece set into pieces/, with its licence. |
scripts/plan.mjs | Timeline → data/plan.json (music plan) + data/sfx.json (effects cue sheet). |
scripts/music.py | The composer (numpy synthesis). |
scripts/sound.py | Synthesizes the effects, mixes them with the music, sets loudness → out/soundtrack.wav. |
render.mjs | Parallel puppeteer render → out/film.mp4; --stills for single frames. |
fonts/inter.woff2 | Inter (SIL OFL), the only font. |
When something is wrong
- "timeline.js schedules N plies but data/game.js has M": you changed the game; re-run
prepare.py. - Text too long: names, headlines and titles shrink to fit on their own. Notes don't, so keep them under about 60 characters.
- The film is too long: a game over 90 plies plays at two moves per beat. Use fewer
KEYmoves and shorter quotes, or raiseMUSIC.bpm. See references/timeline.md. - No Chrome: run
npx @puppeteer/browsers install chrome-headless-shell@stableand setCHROMEto the path it prints. On a Linux server, also setNO_SANDBOX=1. - Slow render:
PARdefaults to cores − 2. Render a draft at 30 fps (FPS=30 OUT=draft.mp4), or run the project folder on a bigger machine; it's self-contained.