@homie-rocks/studio 0.51.4 → 0.51.5

package/guides/video/references/HONESTY.md

@@ -0,0 +1,40 @@
+# Honesty rules
+
+## Gameplay is captured, never made
+
+- Anything presented as the game is recorded from the game running (`capture`), in a live room,
+  with nothing pressed for the camera and nothing drawn over the play.
+- Generated footage (a model's clip) is never cut into a trailer as if it were gameplay. A
+  trailer may open on a generated or drawn title sequence; the moment gameplay starts, it is the
+  game.
+- No speed-ups, no reversed footage, no frame interpolation passed off as the game's frame rate.
+  Held frames are counted in `capture.json`; if the game ran slowly, say so or capture again.
+- Bots are bots. The game's own bots fill empty seats; never caption or voice them as people,
+  and never claim player counts the room did not have.
+- A page recording (`record`) is pressed by a script, in real time: it says so, and the cursor and
+  press rings it draws are the recorder's, not the page's. Its frames are the page's own, held when the
+  page did not repaint, never interpolated; on a software renderer or under 20 fps it is a recording
+  of a slow computer, and is not shown as the game's speed.
+- A studio's score or player numbers shown on screen are what the game drew during the capture.
+
+## No real people, no real brands
+
+- No likeness, voice or name of a real person (celebrities, public figures, private people) in a
+  prompt, a reference image, a voice or the type. Invent the cast.
+- No real logos, products, brands or copyrighted characters; no screenshots of other people's
+  posts, videos or games; no "in the style of" a living artist.
+- References a person supplies (a photo, a sketch) are theirs to give: ask when unsure.
+
+## Money
+
+- A budget before the first paid call; every call priced from the provider's own pricing and
+  checked against the approved cap by the owner’s AI before submitting. Record the accepted
+  request ID and poll that job instead of submitting again. Record actual cost, estimate or
+  unknown explicitly in provenance. Homie does not enforce a provider-side spending cap.
+
+## Rights of what is made
+
+- Music: the plan at render time decides (the `music` skill's `references/RIGHTS.md`).
+- fal: outputs belong to the person under fal's terms, but each model has its own licence and
+  content policy. Read the model page's licence line before commercial use and put the models in
+  the video's credits (`add` does).

package/guides/video/references/METHOD.md

@@ -0,0 +1,144 @@
+# A music video (or a cutscene) from generated footage
+
+The method: the generated clips are the motion; a hand-built JavaScript drawing is the picture;
+the words are a main event, not subtitles; everything sits on the song's beat grid, and nothing
+ships until a frame-by-frame check says the mouths, the words and the hits land.
+
+## 0. The song and the grid
+
+The song comes from the `music` skill. Use word timestamps if the official MCP returns them,
+or obtain timings through an available official transcription capability and check them by ear.
+The local grid needs timing metadata; generation alone does not guarantee it. Then:
+
+```sh
+node <video.mjs> grid <slug> --song <music slug>
+```
+
+`videos/<slug>/grid.json`: the tempo, every beat, every bar line, the sections of the song's
+plan with their start times, and every sung word (`w`, start `s`, end `e`, in seconds of the
+song). The model's own word stamps ran 50 to 80 ms after what is heard on some words, so `grid`
+moves each word to the vocal onset nearest its stamp (the original stays in `stamp`), and lyric
+type then pops on the consonant. Plan everything in these numbers.
+
+## 1. A style sheet
+
+`videos/<slug>/STYLE.md`, one page, before any image is made:
+
+- **The risk.** One real aesthetic decision the video is built around (a limited palette with a
+  meaning, a print process, a camera rule). Not "cinematic", not generic AI gloss.
+- **Palette** as hex values and what each colour stands for; **line** (weight, texture); **type**
+  (two or three faces, each with a job: the big hits, the quiet lines, the machine voice).
+- **What never appears**: real people, logos, brands, copyrighted characters, text in the
+  generated images (models misspell it; type is drawn later).
+
+## 2. Character and set sheets
+
+One image call per sheet through the official fal MCP: discover a model, inspect its schema
+and price the requested size before calling `run_model`. A character sheet is one invented person or creature on a plain ground: front,
+three-quarter and profile, their palette, one prop that tells who they are. A set sheet is a
+place, empty, lit the way the style says. Look at each; redo the ones that break the style before
+anything moves. Keep the prompts in `videos/<slug>/prompts/`.
+
+## 3. The shot list on the grid
+
+`videos/<slug>/SHOTS.md`: one row per shot with its bar range and times from `grid.json`, the
+lyric it carries, what is seen, which sheets it uses, and whether it is a **performance** (a
+character sings: needs the song as an audio reference) or a **picture** shot (motion only). Cuts
+land on bar lines (or beats in a fast section). Characters on one side of the frame, words on the
+other. Price the whole list before generating anything: shots x price, against the budget.
+
+## 4. Bases
+
+For each shot, discover a reference-to-video model through the official fal MCP and read
+`get_model_schema`. Use `upload_file` for local references and pass its returned URLs in the
+fields supported by that model. Never pass Homie's former `@file:` shorthand.
+
+A performance prompt can ask for the singer from the character reference to sing the supplied
+audio, with a still camera, closed mouth during silence, no text and one continuous shot.
+Reference syntax, audio support and lip sync controls depend on the discovered model.
+
+- Slice the exact shot audio locally:
+  `node <video.mjs> slice <slug> --from <shot start> --to <shot end> --out work/audio/<shot>.wav`.
+- Choose an explicit supported duration covering the shot and quote it before submitting.
+- Price the supported resolutions. Use a lower resolution under a draw-over when it survives
+  review; use more detail where the base itself is seen.
+- Picture shots need image-to-video from a keyframe; disable generated audio if supported.
+- Review the keyframe before paying for its clip. Save the accepted job ID and retrieve that
+  job's output without submitting it twice. Import outputs with provenance and their consumer.
+
+## 5. The sync check on every base
+
+```sh
+node <video.mjs> lag <slug> --base work/bases/s03.mp4 --ref work/audio/s03.wav
+```
+
+A reference-to-video model that sings the reference plays it back in its own soundtrack, and
+draws the lips against that. Cross-correlating the clip's sound with the reference (GCC-PHAT)
+gives the offset: about 0 ms with a sharp peak means the lips are timed to the song by
+construction. No clear peak means the clip did not use the reference: regenerate it. A clear peak away from 0
+is a shift, not a failure: one 480p clip dropped the quiet half second before the first sung word
+of its reference, so its sound (and its lips) ran 475 ms ahead of the song; `lag` says so and
+gives the `baseStart` that puts the lips back on the song. At 120 BPM a beat is 500 ms, so
+check that the peak is far above the next one before trusting a shift near a beat's length. Then look:
+`film frames` the clip and check mouths at a few sung words (open on vowels, closed on m/b/p and in
+the gaps). A stylised mouth (a beak, a mask) at 480p opens with the phrases rather than each
+syllable; a human-like mouth at 720p syncs closer. Choose the character with that in mind.
+
+## 6. The draw-over and kinetic type
+
+```sh
+node <video.mjs> film init <slug>                          # film/index.html, film.js, look.js, shots.json
+node <video.mjs> film frames <slug> --base work/bases/s03.mp4 --id s03
+node <video.mjs> film render <slug> [--from 0 --to 12]     # work/film-h.mp4
+node <video.mjs> film render <slug> --mode v                # work/film-v.mp4 (1080x1920)
+```
+
+- `film.js` renders any frame as a pure function of time (`renderAt(t)`): the shot at that time,
+  the base frame under it, the look, the words. `film render` photographs every frame in order in
+  a headless GPU Chrome and encodes them with the song, so a render is the same film every time.
+- `look.js` is the look, and it is meant to be rewritten for each video: the starting point
+  prints the base as two inks on paper (halftone dots, line work, a hand-made boil twelve times a
+  second, paper tooth fixed to the card) and sets the sung words big for shots marked `big`,
+  quiet for `quiet`. Push it where the style sheet says.
+- `shots.json`: `at` and `dur` (on the grid), `base` (the frames folder), `baseStart` (where in
+  the clip to start: remap a story beat onto the lyric that needs it), `focus` (where the
+  subject is, 0..1, so a crop keeps them), `type` (`big`, `quiet`, `none`) and `side` (where the
+  words go, opposite the subject). `songStart` is where the song starts in the film.
+- Inserts with no character (a title, a graphic moment, an object) can be drawn entirely in
+  `look.js` with no base at all: a shot with no `base` gets only the paper and the type.
+
+## 7. The sync loop
+
+```sh
+node <video.mjs> words <slug> --in work/film-h.mp4            # every sung word's frame, labelled
+node <video.mjs> sync <slug> --in work/film-h.mp4 --at 4.00,8.00,12.00
+```
+
+`words` makes a sheet with one frame at each sung word's onset: the mouth and the lyric type
+must match the word under it. A word lost at a cut (its first syllable before the cut) is carried
+by starting that line in the preceding shot. `sync` compares the sound's onset with the
+picture's change at each hit or cut: within one frame passes. Fix, re-render the range, check
+again, as many times as it takes.
+
+## 8. Contact-sheet review
+
+```sh
+node <video.mjs> sheet <slug> --in work/film-h.mp4 --every 1
+```
+
+Look at every cell: type that runs off the frame, a face under a word, a shot that reads as a
+different film, a frame gone black. Then a closer look at the hook and the chorus (every half
+second). Nothing is finished until the whole video has been watched this way.
+
+## 9. Deliver and publish
+
+Copy the finished cuts to `videos/<slug>/<slug>.mp4` (16:9) and `<slug>-vertical.mp4` (9:16),
+then `add … --kind music-video --for-song <music slug> --publish` and `publish`. Credits name the
+song (and its provider) and the models the footage came from.
+
+## A cutscene
+
+The same steps with a script instead of a song: the audio reference is the scene's dialogue or
+sound design (made with the `music` skill or recorded), the grid is the scene's own timing (a
+`grid.json` you write: `beats` at the story's hits, `words` from the dialogue's timing), and it
+is delivered at the game's own resolution for playback inside the game (`games/<id>/public/`).

package/guides/video/references/RECORD.md

@@ -0,0 +1,137 @@
+# Recording a page while a script drives it
+
+**Server rules keep real time.** A trailer for a rules game uses live `capture`, not a
+virtual browser clock: slowing the view cannot slow the server. Scripted inputs use
+`record`, then `edl`/`cut`. Keep a real participant in the room while filming a wall/TV;
+a spectator does not keep an empty room alive. Do not switch to a browser host for footage
+presented as online play. Inspect the room and actual action, sound and held frames.
+
+
+`record` (scripts/record-page.mjs) records any web page in real time while a steps file drives it:
+clicks, taps, keys, typing, scrolls, drags, and waits for a selector, a text or a state. Use it for
+a studio's own game page (land, press Play, play a little), a site walkthrough, a product demo or a
+tutorial. `capture` is still the one for a trailer's gameplay (the game's big screen, nothing pressed).
+
+```sh
+npm run dev                                                    # background task; the site at http://127.0.0.1:8787
+node <video.mjs> record <slug> --steps <steps.json> --url http://127.0.0.1:8787
+node <video.mjs> record <slug> --steps <steps.json> --url http://127.0.0.1:8787 --device phone --name phone
+node <video.mjs> sheet <slug> --in videos/<slug>/work/record/recording.mp4
+```
+
+Outside a studio (any project, any address): `node <skill folder>/scripts/record-page.mjs --steps
+<steps.json> --out <folder>`. It needs Chrome, ffmpeg and `puppeteer-core` (a studio has it; elsewhere
+install it yourself with `npm install --no-save puppeteer-core`).
+
+The take lands in `videos/<slug>/work/record/` (`--name <take>`: `work/record-<take>/`):
+
+- `recording.mp4`: 1920x1080 at 30 fps for a computer, 1080x1920 for a phone (`--device phone`: a
+  360x640 page at 3x, touch on, a phone's user agent), H.264, faststart;
+- `recording.json`: every step with the second it started and how long it took, what its own frame
+  received while it ran (`received`: keys, pointer presses, touches, or "another page opened"), the
+  page's and the game's real frame rates, frames painted and held, the GPU renderer, warnings;
+- `captions.vtt` when steps have captions (copy it to `videos/<slug>/captions.vtt` for the page).
+
+The command prints a few lines (`--json`: a small object of paths and numbers, never media).
+
+## The steps file
+
+```json
+{
+  "path": "/gem-rush/",
+  "device": "computer",
+  "tail": 2,
+  "steps": [
+    { "wait": 1500, "caption": "Gem Rush, on the studio's own site" },
+    { "click": "a[data-play]", "caption": "Press Play" },
+    { "waitFor": { "frame": "game", "selector": "canvas" }, "timeout": 30000 },
+    { "key": "ArrowRight", "hold": 900, "frame": "game" }
+  ]
+}
+```
+
+Where it starts: `"url"` (any address), or `"path"` joined to `--url` (the local `dev` site or the
+live one). The page is opened and settled (`"settle"`, 1.5 s), then the recording starts and the steps
+run one after another, at the speed they take. It ends `"tail"` seconds after the last step, or at
+`--seconds` (120 by default, 600 at most).
+
+Every step is one of these (`{ "click": "a" }` is short for `{ "do": "click", "selector": "a" }`). Any
+step takes `"caption"` (a cue from the second it starts, `"captionSeconds"` long, 3 by default),
+`"timeout"` (ms, 20000) and `"optional": true` (a failure is noted and the steps go on).
+
+| Step | What it does |
+| --- | --- |
+| `{ "wait": 1500 }` | Waits, in milliseconds. |
+| `{ "waitFor": "<selector>" }` | Until it is visible. `{ "waitFor": { "text": "Round 2" } }`, `{ "waitFor": { "js": "window.game?.started" } }` (any expression, true when it is), `{ "waitFor": { "frame": "game" } }` (until the frame exists). |
+| `{ "click": "<selector>" }` | The cursor glides there (`"ms"`, 450), a press ring, a real click. `"at": [x, y]` instead of a selector (CSS pixels, or 0..1 of the page), `"offset": [0.5, 0.7]` inside the element. On a phone, a tap. |
+| `{ "tap": "<selector>" }` | A touch tap, with a ring. |
+| `{ "drag": { "selector": "canvas", "offset": [0.5, 0.7], "to": [90, 0], "ms": 500, "hold": 900 } }` | A held press that moves by `to` (CSS pixels) over `ms`, then held: a virtual stick on a phone, a drag on a computer. |
+| `{ "hover": "<selector>" }` | The cursor glides there; hover styles answer. |
+| `{ "key": "ArrowRight", "hold": 900 }` | One key held for `hold` ms. `"Shift+ArrowUp"` holds both. `"times": 3` repeats it. |
+| `{ "keys": ["ArrowUp", "ArrowLeft"], "hold": 300, "gap": 120 }` | Several, one after another. |
+| `{ "type": "Owl", "into": "input[name=nick]" }` | Clicks into the field, then types at `"delay"` ms a letter (70). |
+| `{ "scroll": 600 }` | Scrolls by wheel over time (`"ms"`), never a jump. `{ "scroll": { "to": "#pricing" } }` brings it to the top quarter. |
+| `{ "focus": "game" }` | Gives a frame the keyboard (a play page usually does it itself). |
+| `{ "goto": "/games/" }` | Opens another address (a path joins `--url`). |
+| `{ "caption": "…" }` | A caption on its own, with no action. |
+
+`"frame"` on any step names where its selector, keys or check are: `"game"` (a studio game's own
+frame, `/<id>/__game/`), a piece of a frame's address, or the page itself (the default). Keys go to
+the frame that has the keyboard; `"frame": "game"` gives it to the game first.
+
+Examples:
+
+- `references/examples/studio-play.json`: a studio's own game from its landing: Play, then the arrow
+  keys, on a computer.
+- `references/examples/studio-play-phone.json`: the same on a phone: a tap on Play, then the game's own
+  touch stick, dragged and held.
+- `references/examples/site-walkthrough.json`: an ordinary page (example.com): a scroll and a hover.
+
+The two studio examples are tested: `scripts/studio-check.mjs --record` records both against a new
+studio's Gem Rush under `homie-studio dev` (CI runs it on Linux), and fails when a step fails or the
+game's frame received none of the input.
+
+For another game: its id in `path`, and its own controls (`games/<id>/src`: what its keydown and
+pointer handlers listen for).
+
+## Honest frames, at real speed
+
+- **Real time.** The steps run at the speed the page answers; the film lasts exactly as long as the
+  recording. Nothing is sped up, slowed down, cut or reordered in the take; any edit comes after, in
+  the open.
+- **Every frame is one the page drew.** Chrome's compositor frames are kept with the time each was
+  presented and laid onto 30 fps by holding the newest one. A moment the page did not repaint is held,
+  and counted (`heldFrames`); a still page lasts as long as it showed. Never interpolated, never
+  blended (the test suite guards it): **interpolated frames are fabrication.**
+- **A GPU, or say so.** Headless Chrome runs on the GPU flags; a software renderer (SwiftShader, on a
+  machine without a GPU) draws a WebGL game at a few frames a second and makes it look stuck. The
+  result names the renderer and the page's own frame rate (`pageFps`, measured with
+  requestAnimationFrame in the page and in the game's frame); under 20, or on a software renderer, it
+  warns, and the recording shows a slow computer, not the game. Record on a computer with a GPU, or at
+  `--scale 0.67`. `--min-fps 20` makes such a take fail instead.
+- **Delivered is not correct.** `received` says the keys and taps reached the game's frame; it does not
+  say the game did the right thing with them. Look at the take (`sheet`) before anyone else does.
+- **The cursor is the recorder's.** The arrow and the press rings are drawn over the page to show where
+  the script pointed and pressed (`--no-cursor` leaves them out). The take's honesty line says so, and
+  `add --file <the take>` puts it on the video page.
+- **Sound.** A studio game's own WebAudio (its `/__game/` frame), on the picture's clock: steady
+  presses land within a frame or two of their sound. Any other page records silent; a bed or a voice-over
+  is added in the edit.
+- **Bots are bots.** A studio game may fill empty seats with its own bots: never caption them as people.
+- **Mask before it is public.** A recording shows no address bar, but a page can print its own
+  address: a local `dev` address, a room code, a QR code that joins a room (the big screen's). Decode
+  every QR in a public video. The recorder's visits are tagged as the studio's own QA, so the studio's
+  stats never count them as visitors.
+
+## Frame by frame instead of real time
+
+`record-fixed.mjs` (the older browser-game trailer path) takes the same steps file but steps the page's clock
+1/fps a frame instead of filming it live: no held frames on a slow page, and waits and holds are in
+film time. It has wait, waitFor, click, tap, key, keys, type, focus and caption only, draws no cursor,
+films a computer's page only, and its sound comes from the game's sound log, not from the speaker.
+`references/TRAILER.md` section 0 says what its clock does and does not reach.
+
+## Disk and size
+
+A take keeps every painted frame as a JPEG until it is encoded (about 150 KB each at 1080p, up to 60
+a second), then deletes them. It stops below 10 GB free (`--min-free-gb`). Check `df -h .` first.

package/guides/video/references/TRAILER.md

@@ -0,0 +1,154 @@
+# A gameplay trailer (15 to 60 seconds)
+
+**Server rules keep real time.** A trailer for a rules game uses live `capture`, not a
+virtual browser clock: slowing the view cannot slow the server. Scripted inputs use
+`record`, then `edl`/`cut`. Keep a real participant in the room while filming a wall/TV;
+a spectator does not keep an empty room alive. Do not switch to a browser host for footage
+presented as online play. Inspect the room and actual action, sound and held frames.
+
+
+Real footage of the studio's own game, cut on the beat of the studio's own music. Free: no
+provider, no model, nothing generated.
+
+## 0. The short way: `trailer`
+
+```sh
+npm run dev      # as a background task
+node <video.mjs> trailer <slug> --game <id> --url http://127.0.0.1:8787 --seconds 45 --length 20 --title "GAME NAME"
+```
+
+For a server-rules game this captures live picture and speaker audio, picks shots by
+motion, and makes cards and three deliveries. It defaults to `--view play`: an idle
+camera occupies a seat and keeps the room awake. `--view tv` needs another participant
+in that same room. Inspect actual action; an idle seat is not gameplay.
+The output says frames were recorded live, including held frames; it does not claim
+reconstructed audio stems or beat-aligned shots without a sound log. Use record for
+scripted inputs. The virtual-clock flags are refused with that alternative.
+
+For an older browser game, the frame-by-frame path below needs no song:
+
+1. **Films frame by frame** (`record-fixed.mjs`): the page's clock is the recorder's. Each film frame,
+   `requestAnimationFrame`, `performance.now`, `Date`, `setTimeout`, `setInterval`, CSS animations and
+   transitions and Web Animations move on by exactly 1/fps, the page draws, the frame is copied. A
+   countdown on a timer, a callout faded by CSS and the game loop stay in step, and no frame is held.
+   `capture.json` gives `realSeconds` and `speed` (film seconds per real second).
+2. **Rebuilds the sound** from the capture log (`events.json`): the `sound` skill's `sound.js` pushes
+   every sound it schedules onto `window.__homieSoundCapture.events` when a recorder set that global
+   before the page ran (file, gain, rate, pan, loop, delay; stops, ducks, fader moves). The files are
+   fetched from the page's own origin and mixed at 48 kHz: `sound.wav`, `sfx.wav`, `music.wav`.
+   The player's compressor is stood in for by a peak limiter at -1 dBFS.
+3. **Picks the shots** from that log: each effect's start scores its tenth of a second, divided by the
+   square root of how often that sound played, plus 0.35 of the picture's motion. With music in the
+   log, a shot is one bar (two when a bar is under 1.2 s, half when over 2.6 s), the bed is the game's
+   own `music.wav` from one of its bar lines, and only `sfx.wav` is cut with the picture.
+4. **Cards and three deliveries**: an end card (`--end`, `--sub`, `--small`), a title card with
+   `--title`, in the game's look; 16:9, 1:1 and 9:16, each -14 LUFS.
+
+Limits of the older frame-by-frame path:
+
+- Sound that does not go through `sound.js` (the game's own oscillators, an `<audio>` element, speech):
+  not in the mix. A game with its own audio code can push the same events (the head of `sound.js`
+  lists them). No events at all: a silent film and a warning; use `capture` (it records the speaker).
+- The audio clock, `<video>`/`<audio>` elements, Web Workers and the network are not on the virtual
+  clock. The big screen (`/<id>/tv`, the default) follows a live room on a relay that keeps real time:
+  at a `speed` near 1 the film is right; well under 1 the room runs fast in the film, and the result
+  warns. Render smaller (`--scale`), or use `capture`. Rendering is never run faster than real time
+  unless `--no-pace` (for a page with no server behind it).
+- Steps (`--steps`) are wait, waitFor, click, tap, key, keys, type, focus and caption, timed on the
+  film's clock; no cursor is drawn, and hover, drag, scroll and goto belong to `record`.
+- A computer's page only (no phone emulation); the 9:16 and 1:1 files are made from the 16:9 film.
+- The highlights are a score, not a judgement: read `shotsPlayed`, look at the sheet, edit `work/edl.json`.
+
+`--keep-capture` re-edits the film already made. Sections 5 and 6 below still apply (look, check, publish).
+
+## 1. The music
+
+The bed is a song from the `music` skill (`--song <slug>` everywhere below): its plan gives the
+exact tempo and its bar lines. The best trailer bed has a clear beat and a lift in its first few
+bars; `--bed-from-bar <k>` starts the trailer at a later bar (a chorus). With no song, the
+trailer runs on the game's own sound and cuts every two seconds.
+
+## 2. The capture
+
+```sh
+npm run dev      # as a background task: the studio's site at http://127.0.0.1:8787
+node <video.mjs> capture <slug> --game <id> --view play --url http://127.0.0.1:8787 --seconds 60
+```
+
+- If another site already holds port 8787, start this one with
+  `npx --no-install homie-studio dev --port <free port>`, and check the address answers with
+  this studio's name before capturing.
+- Stop it afterwards with `npx --no-install homie-studio dev --stop` (this studio's server and
+  nothing else).
+- Without `--view play`, capture opens the game's big screen (`/<id>/tv`): a spectator
+  in a live public room. A server room needs a participant to tick. Bots may fill empty seats
+  according to the game's policy; do not assume there is always action. Nothing is pressed.
+- The picture is Chrome's own frame stream with the time each frame was shown; it is laid onto
+  30 fps, and a frame the page did not paint in time is held and counted (`heldFrames`). The
+  sound is copied off the game's WebAudio output on the audio clock, which is fitted to the page
+  clock, so a hit and its sound stay on the same frame.
+- Capture two or three times the trailer's length: the edit picks the best moments.
+- `--view play` films a seat instead of the big screen, but that seat is taken by the capture and
+  stands still (its avatar is idle, and the room counts it). Prefer the big screen when
+  other people are playing in that room. Never script a
+  player to look good for the camera: what is filmed is the game as it plays.
+- A 3D game on a laptop: check `sourceFps` in `capture.json`; under 30, capture again with fewer
+  other programs running, or a smaller `--width`/`--height`.
+
+## 3. Cards
+
+```sh
+node <video.mjs> card <slug> --name title --text "GAME NAME" --sub "a one-line promise"
+node <video.mjs> card <slug> --name end --text "Play free" --sub "<the play link>" --small "Real gameplay, recorded live."
+```
+
+Cards are drawn in Chrome at 1920x1080 and 1080x1920 (no font setup needed). Keep the title to a
+word or three; the end card is where people go next.
+
+## 4. The edit
+
+```sh
+node <video.mjs> edl <slug> --length 30 --song <music slug> --title "GAME NAME"
+```
+
+`work/edl.json`: a title card of one bar, shots of one bar (two beats when a bar is longer than
+2.6 s), the end card on what is left (at least 2.5 s). Shots are the busiest non-overlapping
+windows of the capture, measured as motion, that do not look like a shot already picked, shown in
+the order they happened. Each shot pushes in slowly (to 1.25x by default, `--push 1` for none)
+toward where the picture changes most: a camera move on the real footage, nothing added. Every
+cut is on a bar line. Edit it by hand: swap a shot for a better moment (`in` is seconds into the capture),
+make one shot two bars long (and shorten another), move the song's start. Keep the total.
+
+## 5. Cut, check, look
+
+```sh
+node <video.mjs> cut <slug>
+node <video.mjs> sync <slug>
+node <video.mjs> sheet <slug> --in videos/<slug>/<slug>.mp4 --every 0.5
+node <video.mjs> sheet <slug> --in videos/<slug>/<slug>-vertical.mp4
+```
+
+- 16:9 is 1920x1080; 9:16 is 1080x1920 with the whole game frame across the middle over a
+  blurred, darkened fill of itself (a crop would hide the action at the edges).
+- Sound: the song, with the game's own sound 8 dB under it where the game made any, both
+  deliveries at -14 LUFS and -1.5 dBTP; H.264 High, yuv420p in limited range, converted to and tagged
+  BT.709, faststart. `--square` adds 1:1 (1080x1080; `card … --square` draws its cards).
+- Cuts are counted in frames: each cut is on the frame nearest its bar line (`cuts` in the result
+  gives the frame, the time and how far from the bar it is, never over half a frame), every frame's
+  timestamp is its number over 30, and the film is exactly its frames long. A bar of 1.875 s is
+  56.25 frames: the shots run 56, 57, 56, 56 frames, and nothing drifts.
+- `sync` must pass (every cut within a frame of its beat), and the contact sheets must show the
+  game, readable, at every cell. A beat with no onset right on it (a rest, a pickup note just
+  before the bar) is listed, not judged: never move a cut off its bar to make the check pass.
+- A fixed camera on a whole arena reads small on a phone: prefer moments where players are close
+  together, or a bigger push (`--push 1.5`).
+
+## 6. Publish
+
+```sh
+node <video.mjs> add <slug> --title "GAME NAME trailer" --kind trailer --for-game <id> --for-song <music slug> --publish
+node <video.mjs> publish <slug>
+```
+
+The page gets a Play button for the game and the capture's honesty line ("recorded from the
+game running in a live public room; seats without a person are the game's own bots").

package/guides/video/references/examples/site-walkthrough.json

@@ -0,0 +1,14 @@
+{
+  "about": "A walkthrough of an ordinary page: no game, a scroll, a hover, a click and some typing. \"url\" is any address; captions become captions.vtt for the video page.",
+  "url": "https://example.com/",
+  "device": "computer",
+  "tail": 2,
+  "steps": [
+    { "wait": 1200, "caption": "The page as a visitor sees it" },
+    { "scroll": 400 },
+    { "hover": "a", "caption": "Its one link" },
+    { "wait": 800 },
+    { "scroll": -400 },
+    { "wait": 800 }
+  ]
+}

package/guides/video/references/examples/studio-play-phone.json

@@ -0,0 +1,15 @@
+{
+  "about": "The same game on a phone (a 9:16 film, 1080x1920): a tap on Play, then the game's own touch stick, dragged and held. Tested on the Gem Rush starter. A phone page has touch only: tap and drag, never a key.",
+  "path": "/gem-rush/",
+  "device": "phone",
+  "tail": 2,
+  "steps": [
+    { "wait": 1200, "caption": "Gem Rush on a phone" },
+    { "click": "a[data-play]", "caption": "Tap Play" },
+    { "waitFor": { "frame": "game", "selector": "canvas" }, "timeout": 30000 },
+    { "wait": 2500 },
+    { "drag": { "frame": "game", "selector": "canvas", "offset": [0.5, 0.7], "to": [90, 0], "ms": 500, "hold": 900 }, "caption": "Drag to move" },
+    { "drag": { "frame": "game", "selector": "canvas", "offset": [0.5, 0.7], "to": [0, -90], "ms": 500, "hold": 900 } },
+    { "wait": 1500 }
+  ]
+}

package/guides/video/references/examples/studio-play.json

@@ -0,0 +1,17 @@
+{
+  "about": "A studio's own game, recorded from its landing page: Play, then a few moves with the arrow keys. Tested on the Gem Rush starter (scripts/studio-check.mjs --record). For another game: its id in \"path\", and its own keys (games/<id>/src, the keydown handler).",
+  "path": "/gem-rush/",
+  "device": "computer",
+  "tail": 2,
+  "steps": [
+    { "wait": 1500, "caption": "Gem Rush, on the studio's own site" },
+    { "click": "a[data-play]", "caption": "Press Play" },
+    { "waitFor": { "frame": "game", "selector": "canvas" }, "timeout": 30000 },
+    { "wait": 2500, "caption": "A public room at once; bots fill the empty seats" },
+    { "key": "ArrowRight", "hold": 900, "frame": "game", "caption": "The arrow keys move" },
+    { "key": "ArrowUp", "hold": 700, "frame": "game" },
+    { "key": "ArrowLeft", "hold": 900, "frame": "game" },
+    { "key": "ArrowDown", "hold": 700, "frame": "game" },
+    { "wait": 1500 }
+  ]
+}