Index of every page on this site: llms.txt
All skills
nilbuild avatar

/video-demo

@767bfb8
by Kamran Ahmednilbuild/video-demo350 stars
30
Run it yourself

Films a web app as narrated, zooming, cursor-driven demo videos with retina screenshots, either from a repo it builds and mocks or from a live URL as it is served. Use when the user asks for a demo video, product video, walkthrough, screencast, screen recording of an app or of a URL, hero or landing-page footage, app screenshots for a website, "show off this feature", "record a demo of <url>", or wants to add, re-film, re-narrate or fix a demo scene.

Use this Skill: https://skilld.dev/gh/nilbuild/video-demo/video-demo

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesruns.md

≈3.8k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Runs: the environment a recording needs

Everything in capture.md assumes the browser is pointed at the right thing and nothing else is touching the files a run writes to. Both of those turned out to need real engineering, because both failed silently: a run that read the wrong app, or that collided with another run, does not throw. It films 4K video of the wrong page, cleanly, and the scenes that depended on what should have been there fail one by one, later, in a way that looks like a broken app rather than a broken setup.

Two modes, and only one of them has a server

build compiles the app here and serves a private copy; site opens a URL that is already live. Everything below about pinning, serving and verifying the bundle is the build mode. In site mode there is no build step (the runner skips it, and pin-build.mjs exits saying so), no webServer block in the Playwright config, and no mocks: the site is the server. The isolation knobs still matter, except DEMO_PORT, which nothing is listening on.

Film a pinned build, never a dev server

A studio does not attach to pnpm dev or whatever your dev server is called. It builds the app, copies the build somewhere the rest of the repo cannot touch, and serves that copy. This looks like extra ceremony until you have lost a run to skipping it, and this project lost two.

The first was a sibling process editing the app's own source mid-run. A dev server's module graph belongs to whoever is currently editing it; a save elsewhere invalidates modules the running page had already loaded, and the scenes that touched those modules started failing on locators that should have existed. The second was pnpm install (or the equivalent for your package manager) rewriting node_modules underneath the bundler while a recording was in flight, which produces the same symptom for a different reason: the module resolution the dev server was relying on stopped being true out from under it. Both times, the failing scenes looked like the app was broken. It wasn't; the ground had moved.

A build cannot be invalidated by a keystroke. It is also what actually ships, so filming it is filming the real thing rather than a development approximation of it. The studio's own static file server resolves paths the way a production web server does and in the same order: a real file first, then a directory's own index.html (what a prerendered route looks like on disk), and only then the SPA shell as a last resort. Reversing the last two would serve the client-rendered shell over a page your deployment actually serves pre-rendered, and the corpus would be demonstrating a load behavior nobody's users see.

Verify the build's API base by reading the bundle, not by trusting the env

A build with the wrong API base looks completely fine. It builds without error, the file exists, the size is reasonable, and it fails only once a scene tries to talk to the app and the app can't reach anything it expects.

This happened for a specific, structural reason: a concurrent rebuild ran without the same-origin API environment variable set, so it baked a real external API host into the bundle instead of a same-origin /api path. Every request the app made then went cross-origin, hit CORS, and the app did exactly the right thing with no reachable backend, which was to render its own signed-out home page. Fifty-four scenes failed in a row, each one timing out waiting for calendar UI that was never going to appear, and nothing in any individual failure pointed at a build config problem twenty steps upstream. Debugging it meant working backward from "the app is stuck on its login screen" through the network log to "these requests aren't even same-origin" before the actual cause showed up.

The fix that holds is to check the built assets, not the environment used to build them: after building, grep the emitted JS for the real external host your app should never be calling from a demo build. If it's in there, the build is wrong regardless of what you intended to set, and the pipeline should refuse to serve it and say why, in one message, rather than let it surface as a wall of unrelated scene failures. That is the whole job of the pin-and-verify step between "build" and "serve": build fresh, copy the output somewhere private, scan it for whatever patterns would mean "this build can see the real world," and stop before filming a single frame if one matches.

Two isolation knobs: a port and an output directory

Running two studio instances at once, deliberately or by accident (a CI job and a local iteration, two people on the same machine), needs exactly two things to not interfere with each other: a port and an output directory. Without them, four distinct kinds of collision happened, each with a different symptom:

  • Port. Two runs both default to the same port. The first one to bind wins; the second either fails outright or, worse, silently talks to the first run's server. Set an explicit, different port per run, and configure the runner to refuse to reuse a server it did not start itself, since an inherited server is one the run cannot vouch for.
  • Manifest. Two runs both write manifest.json in the same place. Last writer wins, and whichever run finishes second erases what the first one filmed.
  • Stills. Two runs both write screenshots into the same theme directories. Filenames collide; one run's still silently becomes the other's.
  • Frames. Two runs both stage in-flight JPEG frames in one shared location, and a run cleaning up its own scratch space on exit deletes frames a still-running sibling hasn't encoded yet. The victim then fails on a missing file with an error that points nowhere near the real cause.

One environment variable for the port and one for the output directory fix all four, because frames, stills, and the manifest all live inside the output directory: moving that one path moves everything a run writes. Running two corpora side by side is then just two different values for two variables.

The corollary: if a port is already in use, take a different one. Killing whatever is bound to it by matching a process name or pattern is how one run ended another mid-flight, taking a browser down mid-scene rather than leaving it to finish. pkill-by-pattern has no way to know that the process matching its pattern is someone else's in-progress recording.

Manifest merging, and why "only mine" needs a place to live

--grep some-scene is the ordinary way to iterate on one scene without re-filming the whole corpus. For that to be useful rather than destructive, the step that writes the manifest at the end of a run has to merge its freshly filmed scenes into whatever manifest is already on disk, keyed by scene name and, within a scene, by theme independently: a re-film of the light pass must not evict the dark pass sitting next to it. Overwrite instead of merge, and a one-scene debugging run silently replaces a 27-scene corpus with a 1-scene one; the manifest file looks completely valid and is wrong.

Merging safely needs each run to know which entries are its own, and this took two attempts to get right. The first version had every run write into one shared entries directory and sweep the whole thing clean once it finished, which meant a run that finished while a sibling was still filming deleted that sibling's in-flight results. The second version tried to sweep "only its own" entries, but decided which ones were its own by reading the shared directory and guessing, which is the identical bug with a different face: you cannot tell your own work apart from someone else's by inspecting a place you both write to.

The fix is a run identity minted once, before any scene runs, in the test runner's global setup phase (which executes once in the parent process before any worker is forked), and passed down to every worker through the environment they inherit from it. Each run then files its per-scene results under a subdirectory named for its own id, nobody else's, so "which entries are mine" is answered by which directory you were handed rather than by reading the room. A worker that somehow starts without an id mints its own rather than colliding with another run's id: the resulting manifest comes up short, which is loud and immediately visible, and far better than two runs quietly deleting entries out of each other's output.

The manifest is the interface; nothing else is

Once a run finishes, the only file a consuming website (or anything else) should ever read is manifest.json. It lists every scene, its title and blurb, and per theme the stills, the clip, a poster frame, the measured frame rate, and how much narration is spoken over it: everything a page needs to swap a screenshot for a video on hover, or light for dark on a theme toggle, without knowing anything about screencasts, ffmpeg, or how any of this was produced.

The way to keep that contract honest is to build a page that proves it: a preview page generated from the manifest alone, with no special knowledge of the pipeline behind it. If the preview page can do the two things a real product page needs (swap still for video, swap theme) using nothing but the JSON, then any website can. If the preview page is missing something it needs, that gap shows up immediately, in a file this project owns, rather than three weeks later in someone else's.

Nothing real behind the browser

The studio answers every request the app makes from inside the test process: a mocked API layer intercepts network calls, the system clock is pinned to a fixed instant rather than read from the machine, and all data comes from a checked-in seed rather than a live account. This is not only about determinism, though a corpus that changes shape every time it's re-filmed is its own kind of bug. It is about what a corpus is: something that gets published. A demo filmed against a real account bakes real meetings, real names, and real addresses into an asset that ships to a website, and the fact that it looked convincing while filming is exactly the problem.

Mocking has to model writes, not just answer reads. A scene doesn't end the moment it sends a request: the panel it just edited reads its own change back, a list rehydrates by id, a sweep re-fetches what it thinks changed. A mock that answers every write with a bare "ok" and every subsequent read with the original, unmodified data shows the viewer's own change being quietly undone on camera, which is a worse failure than an outright error because it plays back looking like a real bug in the app.

One entry point, because a shell && cannot read its own arguments

scripts/demo is the only command, and it is a script rather than the two commands it runs.

The obvious spelling is "demo": "node demo/pin-build.mjs && playwright test --config=demo/playwright.demo.ts", and it quietly breaks the first command anybody types: a separator reaches Playwright's CLI, which reads everything after it as positional file filters rather than as options, and does not complain. Every scene films. That is ten minutes and a gigabyte in place of the four-second check that was asked for, and the only evidence is a test count on a line nobody rereads.

engine/run.mjs, which it execs, is handed the arguments as an array, so it can drop any separator a package manager leaves behind and pass the rest through untouched. It also owns the two steps of a run, which is where DEMO_BUILD=0 lives: skipping the rebuild is the difference between a twenty-second iteration and a four-minute one while writing a scene, and the default is still to build, because a corpus of the code in the tree is the point.

It is also the only thing that knows where a workspace is. Every workspace records the repo it belongs to in .origin, so running scripts/demo from anywhere inside that repo finds it again with no flag, and --project names one explicitly.

Environment variable reference

Everything the studio reads from the environment, grouped by what it touches, with the default it falls back to when unset.

Stage and encode

variable default controls
DEMO_WIDTH 1920 stage CSS width
DEMO_HEIGHT 1080 stage CSS height
DEMO_VIDEO_SCALE 1 browser's real device scale factor; drives the screencast
DEMO_STILL_SCALE 2 Playwright context deviceScaleFactor; drives page.screenshot
DEMO_FPS 60 below 4K, 30 at or above 3840 wide encode frame rate
DEMO_FPS_FLOOR DEMO_FPS * 0.75 measured rate below which a clip is flagged as judder-prone
DEMO_MOTION_FLOOR 1 seconds of animation a clip needs before its rate is judged at all
DEMO_SLOW_SHARE 0.25 share of motion gaps slower than 50ms that scripts/gaps.mjs fails on
DEMO_FRAME_QUALITY 80 JPEG quality the screencast asks Chrome to encode at
DEMO_ENCODER hardware (h264_videotoolbox) set to x264 for software libx264 -crf
DEMO_BITRATE 36M hardware encoder target bitrate
DEMO_WEBM off also encode a VP9 .webm alongside the .mp4
DEMO_WORKERS 1 at or above 4K, else 2 parallel browser workers
DEMO_TRACE_FRAMES off print the inter-frame gap histogram per clip
DEMO_TRACE_NAV off print every main-frame navigation and page error per scene

Voice-over

variable default controls
DEMO_VOICE on set to 0 to film silent
DEMO_VOICE_NAME af_heart Kokoro voice
DEMO_VOICE_LANG en-us phonemiser language
DEMO_VOICE_SPEED 1 speech rate
DEMO_VOICE_SENTENCE_PAUSE 0.14 seconds of pause between sentences
DEMO_VOICE_CLAUSE_PAUSE 0.06 seconds of pause between clauses
DEMO_VOICE_RMS 0.12 target loudness each line is normalized to
DEMO_VOICE_HOME ~/.cache/demo-voice where the model and cached lines live; one directory for every demo on the machine

Run and corpus

variable default controls
DEMO_BUILD on set to 0 to film the build already pinned instead of making a new one
DEMO_PORT 5499 the static server's port; give a second run its own
DEMO_OUT <repo>/demo-out the whole output directory: manifest, stills, clips, in-flight frames
DEMO_THEMES dark comma-separated list, e.g. light,dark
DEMO_TOUR on set to 0 to skip stitching the end-to-end tour per theme
DEMO_RUN_ID minted per run internal: do not set by hand, it identifies which entries belong to which concurrent run

None of these should be read from the machine for anything that affects what gets filmed (the clock, the timezone, the window size are all pinned explicitly rather than defaulted from the host). The whole point of a demo pipeline is that the same command produces the same file next month, on a different laptop.

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 alert2mo3 checks · Risk CRITICAL
  • Gen Agent Trust Hub2mo

    This skill is flagged as critical because it performs high-risk remote code execution by downloading shell scripts from the internet and piping them directly to the system shell. It also downloads large binary models from third-party sources and dynamically executes code from project-specific configuration files, which could be exploited by a malicious repository.

  • Socket2mo

    1 alert: gptAnomaly

  • Snyk2mo

    Risk: LOW · No issues

Signed by skilld at 767bfb8. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last month.

Steadyupdated 2 months ago

README badge

README badge for nilbuild/video-demo