academic-video-demo
Use when making a research demo video, an animated explainer intro followed by a recorded run of the user's prototype (conference booth loop, demo-track or supplementary video), or when re-rendering,
SKILL.mdacademic-video-demo/SKILL.md
GitHubAcademic video demo
Make a video that explains one research idea and then shows the system doing it. The proven shape: a 60 to 70 s animated intro (title, problem, method, evidence, architecture, hand-off), then one recorded demo round per case study, then a closing card. Everything renders off screen, frame by frame: exact, reproducible, 4K, and the computer stays free.
references/worked-example.md describes the first video made this way (GridMind, SIGSPATIAL 2026 booth); read it at the start for the structure and the user's decisions.
Workflow
- Design interview (one question at a time): audience and setting (booth loop with a presenter talking over it, or a standalone video with audio), target length, the two or three points the video must make, the case studies to demo, sources (paper figures, poster, manuscript), what exists already.
- Storyboard in
DESIGN.mdin the video folder: one table row per shot with length, content, and caption. Get the user's approval on the table before building. Record every later decision in it. - Scaffold: copy the bundled scripts and assets into the project's video folder (bare
playwrightimports resolve from the script's folder), thennpm i -D playwrightandnpx playwright install chromethere. Python packages are the user's to install; name the package and the command. - Build the intro from
assets/scene_template.html, one<section>per shot, one paused timeline. Check withscripts/stills.mjs sceneat shot boundaries and mid-animation before every render. - Write the recorders for the live app on
scripts/recorder.mjsandassets/overlay.js; readreferences/live-app-recording.mdfirst. Verify every fact a shot shows (IDs, times, values) against the app's data with a script, not from memory. - Render in segments:
render_scene.mjsfor the HTML parts, the recorder with--segfor each demo segment,--stillsfor a still per shot and popup. - Assemble with
scripts/assemble.mjs(a spec lists the parts; segments of one recording hard-cut, parts crossfade). - Review with the checklist below. Fix, re-render only the affected segment, re-assemble, review again.
- Narration: write the presenter's script last, from the final timing table (see below).
Commit scripts, scenes, small assets, and docs; git-ignore renders (*.mp4, frames/).
On-screen text
- Academic register: precise verbs ("infers", "attributes", "derived from the grid topology", "escalates"), proper names for case studies, every place with its country. No slogans, internal shorthand, or casual verbs.
- Name conditions honestly: only the proposed method is "grounding" (or the paper's own term); a baseline is named for what it does ("coordinate inference").
- Lead with the framing: the problem's principle goes in the slide heading, not in a note under the example.
- Show, don't list: an abstract set (base cells, levels, channels) gets a picture (a diagram in matching colours), never bare labels.
- One caption per shot, unique to that shot (no caption reused across shots); bottom of the frame, at most 84 % of the width and 3 lines; body text at least 29 px and captions about 44 px at 1080p.
- Follow the user's writing rules (no em dashes, no "·" separators, term choices recorded in memory).
Visual rules
- Parallel parts look and move the same: if one case-study transition highlights its card, every one does; same caption positions, same pacing.
- Nothing covers content: a popup or panel that does not fit its space is replaced by another example or skipped.
- No flashes, no loading states, no cursor jumps; the video ends on a frame that loops into the first.
- Use the app's defaults; switch extra layers on for their shot only.
- Reuse the paper's figures and the poster's colours; draw a diagram yourself when no figure explains the idea (a canvas drawn from
tinsideseek, checked against the reference library or data).
Review checklist (before every hand-off)
Run all of it; the user should not find what this list finds.
- Contact sheet of the intro at every shot boundary and mid-transition (
stills.mjs scene); read every tile. - Every recorder still and popup still: nothing covered, clipped, or overlapping; captions clear of panels.
flashscan.mjson every rendered segment and the final video: 0 hits.- Frames either side of every hard cut and every crossfade in the final video (
stills.mjs video). - Parallel parts side by side (both demos, both transitions, all captions): consistent.
- Facts on screen against the data; captions against the storyboard.
- Total length matches the timing table; the narration's times match the final cut.
Report what was checked and the numbers (length, flash hits), with the stills you looked at.
Narration
When a presenter talks over the video, write NARRATION.md: a one-line pitch for visitors who arrive mid-video, then one section per part headed with its time range (## Intro (0:00 to 1:08)). Inside, each beat is a line **Cue: <what is on screen>.** followed by the lines to say as a > quote. Conversational in transitions ("Let's start with", "So", "Now look at"), precise in technical terms (no "works out", "figures out"). Regenerate the section times whenever a part's length changes.
Bundled resources
scripts/render_scene.mjs: HTML scene to MP4 (seek per frame, Playwright screenshot, ffmpeg).node render_scene.mjs intro.html 69 frames/A_intro.mp4scripts/recorder.mjs: live-app recorder core (virtual clock, capture after data arrives, segments, stills, eased mouse, captions).scripts/stills.mjs: contact sheet from a scene or a video at given times.scripts/assemble.mjs: parts and segments to the final MP4 from a JSON spec; prints where each part starts.scripts/flashscan.mjs: transient bright frames.scripts/ffmpeg.mjs: ffmpeg/ffprobe lookup (PATH, then WinGet) andduration().assets/scene_template.html,assets/gsap.min.js: intro scene skeleton with theme tokens, captions, and the seek contract.assets/overlay.js: recording-time captions, highlight, cursor, and fetch counter for a live app.
These are starting points. Change them freely, or use other tools when the video needs it (a voice-over, a desktop app, real screen capture); the workflow, text rules, and review checklist still apply.