html-video

HTML Video

Author a video as plain HTML and CSS, then render it with a pinned, project-local Hyperframes CLI. The bundled CSS-only templates use local assets after explicit bootstrap provisioning; authoring and static audit need no network. Rendering arbitrary project code is not an offline sandbox: enforce external network isolation when that guarantee is required. Deliver editable HTML, its statically reachable asset closure, provenance and licence records, the verification reports, and the MP4 together.

When to Use

Request	Fit
Titles, comparison, diagram walk-through or captions rendered to MP4 from HTML/CSS	Use a bundled template
Edit or re-render an existing Hyperframes composition	Audit it first, then run the workflow
React or Remotion component, Manim scene, existing-video analysis, plain web page	Not this skill

No cloud rendering, avatar or model generation, publishing, or skill installation is part of this workflow. Do not read or invoke any other package from here.

Prerequisites

SKILL_DIR is the absolute directory containing this file. The scripts need Python 3.12+ and only the standard library. Rendering needs Node (major in config.toml), FFmpeg with ffprobe, a Chrome or chrome-headless-shell executable, and a font file the user may redistribute. The Hyperframes version is pinned once, in config.toml; never state or override it elsewhere.

Never install system binaries yourself, never run Hyperframes through npx, and never use @latest. If a prerequisite is missing, stop and tell the user what to install.

python3 "$SKILL_DIR/scripts/html_video.py" --help
python3 "$SKILL_DIR/scripts/html_video.py" init --list

Workflow

1. Pick and copy a template. init TEMPLATE DEST copies title-sequence, comparison, diagram-explainer or captioned-sequence. All are 1920x1080, text-editable and animated by finite CSS keyframes.
2. Get the font from the user. Ask for a font file (woff2, woff, ttf or otf), its licence text, SPDX id and source. Never download or assume one; never bundle a system font. fonts add PROJECT --font-file F --family NAME --license-id ID --license-file L --source S copies it, records provenance, writes fonts.css in the project's assets directory, and updates compiler-visible inline @font-face declarations in index.html. Templates use the alias HV Text; no manual HTML edit is needed. --family is only the provenance name; the CSS family is --alias (default HV Text). Provision a second family, such as a monospace, with its own --alias "HV Code" on each of its faces and reference that alias in CSS, or it becomes another face of HV Text.
3. Bootstrap once. bootstrap PROJECT --browser-path PATH pins an existing browser, or --download-browser runs the pinned CLI's own browser ensure. The package manager comes from the project lockfile (npm for a fresh project). The lock .html-video/environment.json records tool paths and actual versions, including the browser's own --version. Afterwards doctor PROJECT re-verifies offline.
4. Author. Edit text and data-start / data-duration values; see the contract below. Keep the root data-duration equal to the last clip end.
5. Audit. audit PROJECT rejects remote render-critical resources, path and symlink escapes, missing files, case mismatches, cycles, undeclared fonts and invalid timing. Fix every error.
6. Verify. run lint PROJECT, then run check PROJECT, then run snapshot PROJECT. Read the coverage table below, then open every .html-video/snapshots/contact-sheet*.jpg page and judge the frames yourself: layout, legibility, and motion at the sampled boundaries.
7. Render. run render PROJECT uses the FPS from config.toml, renders with strict, non-best-effort, software-browser capture and one worker, removes any previous output first, and checks the MP4 against the composition. Override FPS only by passing the same --fps N to all four run commands.
8. Deliver. deliver PROJECT --out DIR requires passing reports for the same source, verified toolchain, config and effective FPS, verifies every recorded artifact, re-audits copied source/ with provenance required, and writes RENDER.json plus reports/. Pass --fps N here too after an FPS override. Any failed rerun invalidates its prior report.