looties-io Changelog to Video
Overview
Turn a changelog into a feature-showcase video where every feature gets a real mock-up — a screenshot, recording, or faithful UI illustration — not a generic text card. The default failure mode of these systems is that every scene degrades to the same card; the fix is an explicit asset waterfall that exhausts real-mockup options before ever falling back, plus deduping overlapping entries.
Engine-dependent: this pairs with an HTML-to-video engine (HyperFrames or Remotion). For the motion layer, use the cinematic-hyperframes skill.
When to use
- A weekly/periodic changelog or "what's new" video.
- A release recap or feature-launch reel from release notes / shipped PRs.
- Symptom: your generated videos all look like the same neon card with a title and no real UI.
Not for: a single talking-head recut, or a one-feature launch film (use a product-launch flow).
The asset waterfall (the core)
For each feature, walk these rungs in order — first hit wins — and only fall back when truly stuck:
| # | Rung | Use when | Source |
|---|---|---|---|
| ① | Reuse | a prior/approved mock-up of this feature already exists (especially "improvement" re-mentions) | a small committed registry, keyed by feature |
| ② | Live capture | the feature has a public page (product / catalog / social / content) | Playwright screenshot of the public route → render as a framed image |
| ③ | Synthetic | no asset, but you know the feature's shape | a simple, faithful UI mock built from the description / codebase |
| ④ | Card | genuinely nothing to show | the generic motion card — last resort ONLY |
Principle: the context of the feature decides the rung. Product, social, and content features almost always have real assets — use them. The card is a fallback, never the default.
Dedup related entries
Before building scenes, group entries by feature and merge related ones into a single scene at the latest state: "X is live" + "X now supports Y" → one "X (now with Y)" scene. One scene per feature.
Render-safe motion
Whichever engine, keep scene motion deterministic and GPU-cheap — animate only opacity / x / y / scale (and scaleX/Y). No animated CSS filters, no Math.random, no Date.now, no network at render time. This keeps frames reproducible and the renderer fast.
Pipeline
- Parse the changelog into entries
{date, tag, title, desc}. - Dedup by feature (above).
- Per feature, resolve the asset waterfall into an
asset_plan(reuse|capture|synthetic|card) plus an archetype. - Resolve plans into real image files: reuse copies from the registry; capture screenshots the public route; failures downgrade one rung (never crash the render).
- Compose intro → per-feature scenes (real mock-ups) → outro, with kinetic transitions.
- Render both 16:9 and 9:16.
Mock vocabulary (archetypes)
A scene archetype maps structured slots → a .mock illustration. A useful set:
asset-grid— real screenshots in a 1/2/3-column gridproduct-card— one framed hero screenshotflow— a multi-step UI recreation (e.g. a moderation/checkout flow)duration-timeline— a before/after metric barartifact-card— a code-styled card for a shipped repo / skill / APIcard— the generic motion card (fallback)
Every archetype your router can pick MUST exist. A router that routes to an unimplemented archetype silently falls back to a card — the #1 cause of "always generic cards".
Common mistakes
- Always-card trap: no asset pipeline + strict slot validation → every feature degrades to the card. Build the waterfall; make the card the last rung.
- Phantom archetypes: routing to
asset-grid/product-cardthat were never implemented → instant card. Implement every archetype the router references, and wire the real-asset lookup (don't hardcode "no assets available"). - No dedup: "X is live" and "X now supports Y" render as two near-identical scenes.
- Non-deterministic motion: filter/random/time-based animation breaks reproducible rendering.
- Capturing logged-in pages first: start with public routes only; authenticated capture is a separate, heavier concern (seeded test account + secrets).
Reference architecture
A working implementation separates into four modules, whichever language you build it in:
- archetypes: one renderer per archetype (asset-grid, product-card, flow, and so on), so the router can only route to something that exists.
- registry: the reuse rung, a small committed index mapping feature to a previously approved mock-up.
- capture: the public-route Playwright waterfall, where a failure downgrades one rung rather than crashing the render.
- build: composes the resolved plan into scenes, emitting the generic card only when the plan explicitly says so.
Pair it with an HTML-to-video engine (HyperFrames or Remotion) plus GSAP for motion. Run capture and render in a render-only CI job with read-only repository permissions, since the pipeline needs no write access.