Skip to content

World's first open-source, agentic video production system. 12 production pipelines, 100+ tools, 700+ agent skill and production-knowledge files. Turn your AI coding assistant into a full video production studio.

docs(atelier): recognize HyperFrames as natively bespoke

calesthioc4d897521304
diff --git a/skills/meta/bespoke-composition.md b/skills/meta/bespoke-composition.md
index 04b692b6..c2cadf9b 100644
--- a/skills/meta/bespoke-composition.md
+++ b/skills/meta/bespoke-composition.md
@@ -14,7 +14,7 @@ need so that what you build is correct, and distinct.
## When to use this skill (authoring mode is a proposal decision)
-OpenMontage now separates three orthogonal axes, all locked at proposal:
+OpenMontage separates three orthogonal axes, all locked at proposal:
- `renderer_family` — creative grammar
- `render_runtime` — technical engine (remotion / hyperframes / ffmpeg)
@@ -26,8 +26,16 @@ output, localization variants, quick drafts, low-stakes internal clips — place
sameness is fine and bespoke cost is unjustified. Present the choice to the user at proposal and
log it in `decision_log` (`category: "composition_mode"`), the same way you present runtime.
-If atelier is chosen, the stock scene-type catalog, the `hyperframes-registry` blocks, fixtures,
-and any finished component are **off-limits** — they are frozen looks and reintroduce sameness.
+### Atelier and the two runtimes
+
+The two runtimes treat "bespoke" differently — read this before assuming the doctrine maps the same way to both:
+
+- **Remotion** ships a `cut.type` registry of stock scenes (`text_card`, `stat_card`, `bar_chart`, …) dispatched by the `Explainer`/`CinematicRenderer` compositions. That's the templated default. **Atelier mode is the escape hatch** — `composition_mode: "atelier"` routes the render to `_render_via_atelier` and bypasses the registry entirely, so the agent hand-writes its own React composition under `projects/<slug>/`.
+- **HyperFrames is inherently atelier.** There is no cut-schema in HF — every composition is a hand-authored `index.html` with `data-*` timing attributes and a GSAP timeline you wrote. The registry (`hyperframes add`) is a *block* registry (grain overlays, transitions) — it's optional inputs to your composition, not a scene catalog dispatching the whole render. **When `render_runtime: "hyperframes"` is chosen, the piece is already atelier-style; `composition_mode: "atelier"` is implicit.** The principles in this skill (art direction, scene distinctness, no hero-component spine, distinctness review) apply equally. Render via `hyperframes_compose` (or `npx hyperframes render` for hand-authored compositions — see section 5).
+
+So: if `render_runtime == "remotion"` and the piece is hero work, log a `composition_mode: "atelier"` decision. If `render_runtime == "hyperframes"`, atelier is the default behavior and you don't need to argue for it; this skill still routes you through the same principles before you write the composition.
+
+If atelier is in play (either runtime), the stock Remotion `cut.type` catalog, `hyperframes-registry` finished blocks consumed as scenes (vs as raw inputs), fixtures, and any pre-baked creative component are **off-limits** — they are frozen looks and reintroduce sameness.
## The construction route
@@ -82,19 +90,49 @@ Reach for **principle** skills, never finished animations:
- The HyperFrames `references/motion-principles.md` — easing as emotion, timing as weight.
### 3. Reach for a richer vocabulary only when the concept demands it
-Most scenes are Remotion primitives. Escalate when the *idea* needs it, not by default:
-`gsap-*` (kinetic typography via SplitText, shape morph via MorphSVG, curved motion via
-MotionPath, line-draw via DrawSVG, custom easing), `threejs-*` (3D), `d3-viz` (data-driven
-custom charts — build the chart by hand; do **not** drop in the stock `bar_chart`/`line_chart`),
-`manim-*` (math), `canvas-procedural-animation` (particles/weather).
+
+**On Remotion** — most scenes are Remotion primitives. Escalate when the *idea* needs it, not
+by default: `gsap-*` (kinetic typography via SplitText, shape morph via MorphSVG, curved
+motion via MotionPath, line-draw via DrawSVG, custom easing), `threejs-*` (3D), `d3-viz`
+(data-driven custom charts — build the chart by hand; do **not** drop in the stock
+`bar_chart`/`line_chart`), `manim-*` (math), `canvas-procedural-animation` (particles/weather).
+
+**On HyperFrames** — the vocabulary lives in `/hyperframes-animation`: 36+ atomic motion
+**rules** (`kinetic-beat-slam`, `3d-text-depth-layers`, `motion-blur-streak`,
+`physics-press-reaction`, `multi-phase-camera`, `depth-of-field-blur`, …), 15+ scene
+**blueprints** (`kinetic-type-beats`, `comparison-split`, `dataviz-countup`,
+`constellation-hub`, `ticker-takeover`, `device-surface-showcase`, …), 16 **transition**
+families (`css-distortion`, `css-destruction`, `css-radial`, `css-light`, `css-mechanical`,
+…), and **7 runtime adapters** under one composition: GSAP default, plus Lottie, Three.js,
+Anime.js, CSS keyframes, WAAPI, and TypeGPU (GPU compute). The headline capability is
+`adapters/html-in-canvas-patterns.md` — capture live HTML/CSS as a GPU texture and render
+through WebGL/Three.js for cinematic bloom, shatter, liquid, portal effects. Use it for 1–3
+hero beats per video, not every beat. **Compose 2–4 distinct atomic rules per beat** and use
+**at least 3 different easings across the piece** — that's the doctrine baked into the
+animation skill, not optional polish.
+
+For HF creative direction (palette/type/narration/beat planning) read `/hyperframes-creative`.
+For HF assets (TTS/BGM/SFX/transcription/background-removal) read `/hyperframes-media` or
+`/media-use`. For HF CLI workflow (init/lint/validate/inspect/snapshot/beats/render) read
+`/hyperframes-cli`. The `/hyperframes` router skill maps it all.
### 4. Get the engine mechanics right — the gotcha codex
This is the only place you "reuse": the engine's solved problems. These are facts about how
-Remotion works, not looks. Study `.agents/skills/remotion-best-practices` (19 rule files:
-timing, transitions, text-animations, transparent video, fonts, audio, sequencing, measuring
-text). You may also read the stock components in `remotion-composer/src/components/` **as a
+the framework works, not looks.
+
+**For Remotion**, study `.agents/skills/remotion-best-practices` (19 rule files: timing,
+transitions, text-animations, transparent video, fonts, audio, sequencing, measuring text).
+You may also read the stock components in `remotion-composer/src/components/` **as a
mechanics codex — to learn idioms, never to import or imitate a look.**
+**For HyperFrames**, the composition contract is in `/hyperframes-core` (the `data-*`
+timing attributes — `data-start`, `data-duration`, `data-track-index` — plus the
+mandatory `class="clip"`, `data-composition-id`, `window.__timelines` registration, sub-
+composition mounts). Run `npx hyperframes lint && npx hyperframes validate` after every
+change — they catch missing root attrs, missing clip ids, GSAP-target unresolved, overlapping
+tweens, and contrast failures before render. Use `npx hyperframes snapshot . --at <times>`
+to spot-check beats visually before committing to a full render.
+
Recurring mechanics that bite if you don't know them:
- **Determinism**: no `Math.random()` / `Date.now()` per frame — use Remotion `random(seed)` or a
seeded helper, or particles/easing flicker across the render.
@@ -105,7 +143,14 @@ Recurring mechanics that bite if you don't know them:
public dir and reference via `staticFile`. Mirror the `resolveAsset` helper.
- **GSAP-in-Remotion**: use a `paused` timeline and `.seek(frame/fps)` — never `requestAnimationFrame`
— so frames render deterministically.
-- **Fonts**: `loadFont()` from `@remotion/google-fonts/<Name>` at module scope, once.
+- **Fonts (Remotion)**: `loadFont()` from `@remotion/google-fonts/<Name>` at module scope, once.
+- **HF data-* contract**: every timed element needs `data-start`, `data-duration`,
+ `data-track-index`, AND `class="clip"` — without `clip` the framework won't manage
+ visibility and your element will be onscreen the whole timeline. Root `<body>` needs
+ `data-composition-id`, `data-start="0"`, `data-duration`, `data-width`, `data-height`.
+ Every timeline must be `gsap.timeline({ paused: true })` and registered as
+ `window.__timelines["<composition-id>"]`. Use stable `id` attributes on clips and on
+ GSAP targets — `nth-of-type` selectors are flaky at validate time.
- **Captions vs on-screen text — pick one role, never both for the same content.** Decide
once per piece, before authoring: are captions adding meaning the spoken words can't carry
(a number, a name, a translation, a quote attribution), OR are they accessibility subtitles
@@ -114,26 +159,30 @@ Recurring mechanics that bite if you don't know them:
amateurish even when the rest of the scene is beautiful. Empty `captions=[]` in props, or
scope captions only to scenes where the on-screen text differs from what's being said.
-### 5. Render through the atelier path (project-local, throwaway)
-Bespoke scenes are **throwaway and project-local** — they never enter the shared `src/` registry.
+### 5. Render through the runtime-appropriate bespoke path
+Bespoke compositions are **throwaway and project-local** — they never enter any shared registry.
-- Author under `remotion-composer/projects/<slug>/` (gitignored). It needs its own Remotion entry
- (`index.tsx` + a `Root` registering only this composition) so it reuses the composer's
- `node_modules` and stays out of the global `Root.tsx`. The entry MUST live under
- `remotion-composer/` for the bundler to resolve `remotion`.
-- Keep media in a small per-project public dir and pass it as `public_dir` so renders don't copy
- the bloated shared `public/`.
-- Render via `video_compose` `operation="render"` with:
+#### Remotion atelier path
+- Author under `projects/<slug>/` (gitignored). The render tool auto-stages your `.tsx`/`.ts`
+ source into `remotion-composer/projects/<slug>/` via mtime-skip copy so webpack can resolve
+ `node_modules` — your source-of-truth stays under `projects/`.
+- Scaffold with `python scripts/scaffold_atelier_project.py <slug>` — emits engine
+ plumbing only (entry / Root / blank `Composition.tsx` / `art-direction.md` / props
+ template / README). Zero creative content; the placeholder is a deliberately ugly black
+ screen so the post-render review correctly refuses to ship the scaffold unauthored.
+- Keep media in `projects/<slug>/public/` and pass that as `bespoke.public_dir`.
+- Render via `video_compose` `operation="render"`:
```json
edit_decisions = {
"render_runtime": "remotion",
"composition_mode": "atelier",
"bespoke": {
- "entry": "remotion-composer/projects/<slug>/index.tsx",
+ "entry": "projects/<slug>/index.tsx",
"composition_id": "<id registered in that entry's Root>",
- "props_path": "<absolute path to props.json>",
- "public_dir": "<absolute path to the project's public dir>",
+ "props_path": "<absolute path to artifacts/props.json>",
+ "public_dir": "<absolute path to projects/<slug>/public/>",
+ "art_direction": "<short note or path to art-direction.md — REQUIRED>",
"scale": 0.5, // 0.5 for a fast draft; drop for the 1080p final
"crf": 18, // crisp final
"concurrency": 8
@@ -142,6 +191,26 @@ edit_decisions = {
```
No `asset_manifest` or `cuts` are required in atelier mode — the composition owns its own assets.
+The tool's `_run_atelier_checks` fails the render if any source file imports from the stock
+registry (`src/components`, `src/Explainer`, etc.), and warns if `art_direction` is missing.
+
+#### HyperFrames path
+- Scaffold with `npx hyperframes init <slug>` (run from `projects/`). HF init generates
+ `index.html`, `meta.json`, `package.json`, and a per-project `CLAUDE.md` that auto-routes
+ the agent into `/hyperframes` — so the next session knows exactly which sub-skills to load.
+- Author `index.html` by hand. Every clip needs `class="clip"` + the three `data-*` timing
+ attrs + a stable `id`. Mount sub-compositions via `data-composition-src` once the timeline
+ on one file grows past 4 clips (the lint catches density).
+- For music-driven pieces, run `npx hyperframes beats .` after dropping the track in
+ `assets/` — it emits `beats/<audio>.json` with `{time, strength}` per beat so the agent
+ can land scenes on real drops (not guesses).
+- Verify before render: `npx hyperframes lint . && npx hyperframes validate . && npx hyperframes snapshot . --at <times>`.
+ Snapshot is HF's native visual-spotcheck (contact-sheet of PNG frames at chosen
+ timestamps) — use it the same way an atelier `final_review.visual_spotcheck` would.
+- **Render**: `npx hyperframes render . --output renders/<name>.mp4`.
+ > Known gap (F13): `hyperframes_compose.render` currently requires `edit_decisions.cuts[]`
+ > from the templated path. For hand-authored HF compositions it errors; call `npx` directly
+ > until the tool grows a bespoke branch.
## Guardrails so this doesn't backfire
@@ -158,14 +227,30 @@ No `asset_manifest` or `cuts` are required in atelier mode — the composition o
for approval BEFORE generating assets, then a footage/asset checkpoint, then a first-render
checkpoint. Do not batch-generate ahead of sign-off.
-## Worked precedent (for the *workflow*, not the look)
+## Worked precedents (for the *workflow*, not the look)
+
+Two reference pieces — one per runtime — to study **processes**, never visual languages:
+
+- **Remotion atelier** — Phantom Reach explainer (`projects/phantom-reach-explainer/`):
+ Playwright-captured app footage with a PII-blur layer → per-sentence TTS stitched with
+ silence beats → free Pixabay music → hand-authored Remotion scenes (custom intro,
+ score-ring, agentic flow, CTA) on a one-off violet theme.
+ Compound Snowball (`projects/compound-snowball/`) and Library of Alexandria
+ (`projects/alexandria-fire/`) are two more — three Remotion atelier pieces, three
+ completely different visual languages.
+
+- **HyperFrames** — `in-a-hurry` (`projects/in-a-hurry/`): a music-driven kinetic-typography
+ piece using the new HF 0.7 `beats` command to lock scene timing to real drops. Exercises
+ **5 categories** of `/hyperframes-animation`: `kinetic-beat-slam`, `3d-text-depth-layers`
+ (stacked extrusion), `motion-blur-streak` (echo-ghost trails), `transitions/css-distortion`
+ (chromatic-aberration RGB-split), and `adapters/html-in-canvas-patterns` (Three.js +
+ UnrealBloom on a hero punchline). Each beat uses a distinct easing (`expo.out`,
+ `back.out(2)`, `circ.out`, `sine.inOut`).
-The first atelier piece was the Phantom Reach explainer (`projects/phantom-reach-explainer/`):
-Playwright-captured app footage with a PII-blur layer → per-sentence TTS stitched with silence
-beats → free Pixabay music → hand-authored Remotion scenes (custom intro, score-ring, agentic
-flow, CTA) on a one-off violet theme. Study its **process** (capture → timing → props builder →
-bespoke scenes → render). **Do not reproduce its visual language** — the next piece must look
-nothing like it. That is the whole point.
+**Do not reproduce any of their visual languages** — the next piece must look nothing like
+any of them. That is the whole point. Study only the *process* (decisions, ordering, gates,
+verification).
See also: `skills/meta/animation-runtime-selector.md` (runtime + library routing),
-`AGENT_GUIDE.md` → "Composition Authoring Mode".
+`AGENT_GUIDE.md` → "Composition Authoring Mode", `/hyperframes` (the HF router and
+capability map).