Render HTML-first videos with ak:html-video

Use ak:html-video to turn HTML, CSS, JavaScript, templates, and project assets into a local MP4 through nexu-io/html-video, headless Chromium, and FFmpeg. It fits template-driven product promos, explainers, data or social clips, article or repository summaries, and HTML-first motion prototypes.

Choose HTML-first video rendering

Use ak:html-video when

• A template and browser-rendered layout are a good fit for the video.
• You need a CLI project, browser preview, optional Studio editing, and MP4 export.
• Copy, screenshots, logos, structured data, or other project assets drive the scene.
• You want to inspect the generated HTML before paying the full render cost.

Choose another workflow when

• You need React and Remotion composition code, frame math, or Remotion-native rendering. Use ak:remotion.
• You only need transcode, trim, thumbnail, HLS or DASH, or batch FFmpeg work. Use ak:media-processing.
• The result is a static page, slide, document, diagram, or demo without an MP4. Use ak:preview or the relevant document workflow.
• You only need browser QA. Use ak:agent-browser, or ak:chrome-profile only when real signed-in state matters.

Prepare the engine and video brief

Before you start:

• Complete Onboarding, and confirm Engineer Kit is installed for the current runtime and scope.
• Define audience, goal, duration, aspect ratio, source assets or URLs, template preference, output path, and whether the deliverable is a draft or polished export.
• Prefer an existing published html-video binary. If none is available, keep a source checkout outside the target project and set HTML_VIDEO_HOME; do not vendor the upstream engine into the project or Kit.
• For the source path described by the shipped Skill, use Node.js 20 or newer, pnpm 9 or newer, and the upstream-declared package manager. The source build, dependency install, and Playwright Chromium download are separate mutations.
• Run html_video doctor and html_video list-engines, then inspect html_video --help, project-render --help, and studio --help. Upstream commands can evolve independently of this AgentKit release.
• Make FFmpeg, Chromium, project assets, enough disk, and a writable output directory available. Review whether templates or source URLs may contact the network.

Create a bounded video project

/ak:html-video "Create a 12-second 16:9 draft product promo from ./assets/cli-screenshot.png and the headline 'Ship with evidence'; use a discovered template, preview before rendering, write ./artifacts/ship-with-evidence.mp4, make no network asset requests, and do not commit or publish the video"

/ak:html-video "Create a 12-second 16:9 draft product promo from ./assets/cli-screenshot.png and the headline 'Ship with evidence'; use a discovered template, preview before rendering, write ./artifacts/ship-with-evidence.mp4, make no network asset requests, and do not commit or publish the video"

$ak:html-video "Create a 12-second 16:9 draft product promo from ./assets/cli-screenshot.png and the headline 'Ship with evidence'; use a discovered template, preview before rendering, write ./artifacts/ship-with-evidence.mp4, make no network asset requests, and do not commit or publish the video"

Use the live CLI workflow

Some templates expose CLI-settable variables; others have an empty schema and require Studio or project editing. Inspect the template before assuming the CLI can theme it.

Observe the render stages

1. The Skill pins the video brief. Audience, message, duration, aspect, assets, output path, quality level, and publication boundary are captured.
2. It checks the external engine. The selected binary or source checkout, current help, Chromium, FFmpeg, and writable project storage are verified.
3. It discovers before selecting. Candidate templates are searched and the chosen template's inputs are inspected.
4. It creates and configures a project. Template, inline text, local files, and supported variables are attached to a project ID.
5. It previews in a browser. The returned HTML is checked for layout, typography, missing assets, motion, timing, console failures, and network use.
6. It renders through Chromium and FFmpeg. The browser captures the scene and FFmpeg encodes the MP4 at the explicit output path.
7. It probes the artifact. ffprobe must report nonzero duration and expected video dimensions before the export is treated as complete.

Control code, network, process, and storage effects

• Cloning or updating the upstream source uses network and unpinned moving state unless you separately select a reviewed revision. pnpm install and the build create a large dependency tree; Playwright installation downloads Chromium.
• Studio starts a local server, with port 3071 shown in the shipped workflow. Bind and expose it only as intended, stop it after use, and do not assume the page is safe for a shared network.
• Preview and render start browser and FFmpeg processes and can consume heavy CPU, memory, disk, temporary files, and time. Test a short draft first.
• Source URLs, fonts, images, scripts, analytics, and embedded media can make external requests. Record or block network effects when privacy or reproducibility matters.
• Confirm rights for images, logos, copy, fonts, audio, and templates. The Skill does not grant publication or redistribution rights.
• The workflow writes project state, preview files, scratch data, and MP4 output. It does not commit, upload, publish, or deploy them without separate authority.

Verify the video and evidence

A complete result should include:

• CLI source or binary identity, current help checked, doctor results, engines, template ID, project ID, and variable schema.
• Input assets and URLs, inline text, network requests or blocked requests, and any Studio edits.
• Preview path, visual review notes, render command, progress result, and MP4 path.
• ffprobe evidence for duration, dimensions, video and audio streams, format, and file size.
• Browser, FFmpeg, dependency, port, storage, rights, privacy, or publication limitations that remain.

Stable and beta package the same ak:html-video wrapper. The release does not pin an upstream checkout revision or prove a published binary, live template catalog, source build, Chromium installation, or cross-runtime render parity.

Troubleshoot and interpret limits