Video

Video for a studio

A studio is the folder with studio.json. Videos live in videos/<slug>/, listed in videos/manifest.json; a published entry is a page at /videos/<slug>/ on the studio's site, playing the 16:9 cut (the 9:16 cut on a portrait phone). Everything runs through scripts/video.mjs in this skill's folder (Claude Code: node "${CLAUDE_PLUGIN_ROOT}/skills/video/scripts/video.mjs" <command>), from inside the studio. It needs Node 22, ffmpeg and Chrome; --json on every command.

Check disk before any capture or render (df -h .): keep 10 GB free. Raw frames are deleted once encoded. Finish in this turn: start the local site with the app's background-task tool (not nohup ... & inside a command, which dies with the command) and wait on it.

The rules that come first

references/HONESTY.md has them in full. In short:

• No fabricated gameplay. Anything shown as the game is captured from the game running. A generated shot is never passed off as gameplay, and a trailer that mixes both says which is which. Bots are bots: never imply a crowd that was not there.
• No real people, no real brands. No likeness, voice or name of a real person, no real logo, product or copyrighted character, in prompts, references or type.
• Money only with a budget. Every paid call is priced first, fits inside the cap the person set, and leaves a receipt the moment the provider accepts it.

Which video

• A gameplay trailer (15 to 60 s): real footage of the studio's own game, cut on the beat of the studio's music. No provider, no money. Recipe: section A below, detail in references/TRAILER.md.
• A music video, a cutscene, a teaser with generated footage: fal models under a budget, then drawn over. Section B, detail in references/METHOD.md.
• A recording of a page while it is used: the studio's own game page (land, press Play, play a little), a site walkthrough, a product demo, a tutorial. A steps file drives it. Section C, detail in references/RECORD.md.

Both start with node <video.mjs> check (ffmpeg, Chrome, the studio; fal only if a key is set).

A. A gameplay trailer

One command films the game, rebuilds its sound, picks the shots and delivers three shapes:

npm run dev                                                    # background task; the site at http://127.0.0.1:8787
node <video.mjs> trailer <slug> --game <id> --url http://127.0.0.1:8787 --seconds 45 --length 20 --title "<GAME NAME>" --end "Play free"

(npx --no-install homie-studio trailer <id> … is the same command, into videos/<id>-trailer/.)

• It renders the game frame by frame on a virtual clock: in each frame the page's requestAnimationFrame, performance.now, Date, setTimeout, setInterval and its CSS and Web animations all move on by exactly 1/30 s, then the frame is copied. No frame is ever held, however heavy the game or slow the computer (heldFrames is 0; speed says how it compared with real time).
• The sound is rebuilt, not recorded. The sound skill's player (sound.js) logs every sound it schedules when a recorder asks; the files it names are fetched from the game's own address and mixed again on the film's clock (work/capture/sound.wav, and sfx.wav and music.wav apart). A game whose sound does not go through sound.js (and does not push the same events) comes out silent, and the result says so: use capture below for those, which records the speaker in real time.
• The shots are picked from what the game played: a rare sound (a win, an explosion) counts for more than a common one (a step), with the picture's motion as the smaller part. When the game played music, a shot is a bar of it and the music runs on under the cuts; shotsPlayed says what is in each shot. work/edl.json is the edit: change it and run cut <slug> --square.
• Out: <slug>.mp4 (16:9), <slug>-square.mp4 (1:1), <slug>-vertical.mp4 (9:16), a poster, an end card (and a title card with --title) in the game's look. --keep-capture edits the film already made (another --length, another --end) without filming again. --steps <file> presses things while it films (references/RECORD.md; only wait, waitFor, click, tap, key, keys, type, focus).
• What the virtual clock does not reach: the audio clock, <video>/<audio> elements, Web Workers, and the network. The default page is the big screen of a live room: a relay keeps real time, so when frames render slower than real time (speed well under 1) the room runs fast in the film, and the result warns. Then render smaller (--scale 0.5) or film in real time with capture. --page <path> films another page of the site (one whose game runs in the page itself is exact).
• Then look (sheet), check (qa.mjs on each file), and add. Detail: references/TRAILER.md.

By hand, in real time, with the studio's own song as the bed:

npm run dev                                                    # background task; the site at http://127.0.0.1:8787
node <video.mjs> capture <slug> --game <id> --url http://127.0.0.1:8787 --seconds 60
node <video.mjs> card <slug> --name title --text "<GAME NAME>" --sub "<one line>" --game <id>   # the game's palette and font
node <video.mjs> card <slug> --name end --text "Play free" --sub "<site>/<id>/play" --small "Real gameplay. Empty seats are filled by bots."
node <video.mjs> edl <slug> --length 30 --song <music slug> --title "<GAME NAME>"
node <video.mjs> cut <slug>
node <video.mjs> sync <slug>
node <video.mjs> sheet <slug> --in videos/<slug>/<slug>.mp4

• When the trailer is done, stop the local site with npx --no-install homie-studio dev --stop (it stops exactly this studio's server), never with a name pattern like pkill -f wrangler.
• Port 8787 taken by another site (curl it: a different studio's title answers)? Run npx --no-install homie-studio dev --port <free port> and use that address.
• capture records the game's big screen (/<id>/tv: a spectator in a live public room, bots in empty seats) off a headless GPU Chrome for real seconds, with the game's own WebAudio sound on the same clock (the browser is muted; nothing plays out loud). It presses nothing. The live site works too (--url the studio's address); a local run keeps strangers out of the shot. A heavy game paints few frames at 1920x1080 (it prints "fps from the page" and a note when that is well under the film's 30): capture again with --scale 0.67 (a 1280x720 page, scaled up to 1920x1080 when it is encoded) or a lower --fps. One game measured 8 fps at 1080p and 39 at 720p.
• The bed is the studio's own song (--song, from the music skill) or the game's sound alone. No song yet: the sound skill synthesizes a theme for free (its bar grid cuts the trailer the same way), or the music skill renders one with ElevenLabs (credits: ask).
• edl finds the song's bar lines, picks the busiest moments of the capture (motion, not guesses), and writes work/edl.json: a title card of one bar, shots of one bar each, the end card on what is left. Title and end cards made with card … --game <id> wear the game's palette and display font (games/<id>/style.json, the style skill's decisions). Every cut lands on a bar line. Read it and change it: order, which moments, where the song starts (--bed-from-bar).
• cut renders both deliveries: 16:9 (1920x1080) and 9:16 (1080x1920, the whole game frame over a blurred fill, never a crop that hides the action), and 1:1 (1080x1080) with --square; 30 fps, the song and the game's sound mixed, -14 LUFS, faststart, and a poster frame. Every cut is on the frame nearest its beat (segments are counted in frames, so cuts never drift from the music: cuts lists each one's frame), and the picture is yuv420p, limited range, converted and tagged BT.709 (a capture's frames are full range; cut fails if the file does not read back that way).
• sync checks every cut: the picture must change within one frame of the sound's onset. sheet makes a contact sheet: open it and look before anyone else sees the video.
• node <skill folder>/scripts/qa.mjs videos/<slug>/<slug>.mp4 checks the delivered file itself: every frame decodes, phone-safe encoding, faststart, no black or frozen stretches, loudness and true peak, under the site's 25 MiB. Fix every FAIL before add. Delivery, capture and honesty traps: references/DELIVERY.md.