Communitygithub.com

chess-game-film

Video and animation skill. Make a polished game-review video of one chess game from its PGN. The board stays whole and sharp at left and every move is played on it. A panel at right shows each move with its Stockfish grade, short notes, the evaluation graph, accuracy, the players' own words, and a summary. The music is composed for the game, so every key move lands on a hit, and frame 0 is a ready-made thumbnail. Use when someone asks for a video, film, reel, clip, recap or animated review of a chess game or match, or giv

What is chess-game-film?

chess-game-film is a Claude Code agent skill that video and animation skill. Make a polished game-review video of one chess game from its PGN. The board stays whole and sharp at left and every move is played on it. A panel at right shows each move with its Stockfish grade, short notes, the evaluation graph, accuracy, the players' own words, and a summary. The music is composed for the game, so every key move lands on a hit, and frame 0 is a ready-made thumbnail. Use when someone asks for a video, film, reel, clip, recap or animated review of a chess game or match, or giv.

Works with~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Kamkmgamer/kamkmstack/tree/HEAD/skills/media/chess-game-film

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

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)

  1. 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.
  2. 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.
  3. 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.
  4. 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 KEY moves.
  5. 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.
  6. 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.
  7. 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.
  8. 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.mjs finds the usual installs, or set CHROME=<path>.
  • Stockfish: from https://stockfishchess.org/download/. Pass --engine <path> or set STOCKFISH.

Steps

  1. Scaffold. Run node <this skill>/new-film.mjs <project dir> [game.pgn]. It copies the template and runs npm install.
  2. Get the game as a PGN. See references/data.md for Lichess, Chess.com, databases and agent logs. Put it in game.pgn.
  3. Analyze. Run python scripts/prepare.py game.pgn --engine <stockfish>. It writes data/game.js and 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.
  4. Pick pieces and a board (optional). The default is cburnett pieces on a green board.
    • Pieces: node scripts/get-pieces.mjs --list, then node scripts/get-pieces.mjs merida.
    • Board: BOARD.theme in timeline.js is green, brown, blue or grey.
    • See references/board-and-pieces.md, and mind the licences.
  5. Write timeline.js. This is the only per-game file. Follow references/timeline.md:
    • FILM: names, headline, foot line, end card.
    • KEY moves.
    • CHAPTERS, NOTES, ARROWS.
    • QUOTES, if real words exist.
    • Optional STRETCH and PREMOVES, plus HILITE.
    • MUSIC: tempo, key, minor or major.
  6. Sound. Run node scripts/plan.mjs, then python scripts/sound.py. This composes out/music.wav and mixes out/soundtrack.wav at −14 LUFS. Read the printed energy-by-bar line, and see references/music.md.
  7. Stills. Run node render.mjs --stills 0.5,<times>, then open every PNG in out/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.mjs prints the film's length and the mate time. Each move's landing time is TL.PLY_T[n].
    • Fix, then render the stills again.
  8. Render.
    • node render.mjs writes out/film.mp4. It takes about 1–5 minutes per minute of film, depending on cores; PAR=n sets the number of workers.
    • Then cut the poster: ffmpeg -i out/film.mp4 -frames:v 1 out/poster.png.
  9. 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.
  10. 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

FileRole
timeline.jsThe one file you edit. What matters in this game; the scheduler at its foot turns that into timing.
game.pgnThe game.
scene.html, scene.jsThe game-agnostic scene: board, pieces, panel, graph, thumbnail, summary, end card. Read references/animation.md before changing it.
scripts/prepare.pyPGN → Stockfish review → data/game.js + story sheet.
scripts/get-pieces.mjsDownloads a Lichess piece set into pieces/, with its licence.
scripts/plan.mjsTimeline → data/plan.json (music plan) + data/sfx.json (effects cue sheet).
scripts/music.pyThe composer (numpy synthesis).
scripts/sound.pySynthesizes the effects, mixes them with the music, sets loudness → out/soundtrack.wav.
render.mjsParallel puppeteer render → out/film.mp4; --stills for single frames.
fonts/inter.woff2Inter (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 KEY moves and shorter quotes, or raise MUSIC.bpm. See references/timeline.md.
  • No Chrome: run npx @puppeteer/browsers install chrome-headless-shell@stable and set CHROME to the path it prints. On a Linux server, also set NO_SANDBOX=1.
  • Slow render: PAR defaults 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.

Related Skills