feat(skills): unify bgm-to-video flows into music-to-video

Replace bgm-to-video, bgm-to-video-new, bgm-to-video-refactor, and the
standalone beat-sync/montage skills with a single music-to-video skill.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Miao Yang
2026-06-23 21:33:01 +08:00
co-authored by Claude Opus 4.8
parent 0dcf914e14
commit a34d3dba4d
172 changed files with 1555 additions and 4198 deletions
@@ -37,6 +37,32 @@ function isCompositionRootOrMount(rawTag: string): boolean {
);
}
// Top-level CSS selectors (comma-split) in a stylesheet, skipping at-rule headers
// (@media/@keyframes/...) and keyframe stops. Heuristic — the lint layer has no
// full CSS parser, and rules elsewhere in this file scan CSS the same way.
function extractCssSelectors(css: string): string[] {
const out: string[] = [];
const noComments = css.replace(/\/\*[\s\S]*?\*\//g, "");
const ruleHeader = /([^{}]+)\{/g;
let m: RegExpExecArray | null;
while ((m = ruleHeader.exec(noComments)) !== null) {
const header = (m[1] ?? "").trim();
if (!header || header.startsWith("@")) continue;
for (const sel of header.split(",")) {
const s = sel.trim();
if (s) out.push(s);
}
}
return out;
}
// Class tokens in a selector's leftmost compound (before the first descendant /
// child / sibling combinator). `.frame .title` → ["frame"]; `.a.b > .c` → ["a","b"].
function leftmostCompoundClasses(selector: string): string[] {
const leftmost = selector.trim().split(/[\s>+~]+/)[0] ?? "";
return (leftmost.match(/\.([\w-]+)/g) ?? []).map((c) => c.slice(1));
}
export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding[]> = [
// invalid_capture_path — catches ../capture/ in src/href attributes and scripts.
// Sub-compositions live in compositions/ but are served relative to the project
@@ -576,4 +602,50 @@ export const compositionRules: Array<(ctx: LintContext) => HyperframeLintFinding
}
return findings;
},
// subcomposition_root_styled_by_class
// A sub-composition's <style> is scoped at render time to
// `[data-composition-id="<id>"] <selector>` so scenes inlined into one document
// can't leak styles into each other. A rule whose LEFTMOST selector is the ROOT
// element's own class (e.g. `.frame { ... }` on the same element that carries
// data-composition-id) therefore becomes a DESCENDANT selector that can never
// match the root — the whole scene renders unstyled (tiny text top-left, images
// at natural size). lint/validate/inspect evaluate the file in isolation (no
// scoping) and Studio previews each scene in its own iframe (no scoping), so the
// break is invisible until the composited MP4 render. Style the root via `#root`
// (the scoper special-cases the root id) and descendants via plain selectors,
// like the registry blocks — the runtime already scopes each scene by id, so a
// class namespace on the root is redundant.
({ rootTag, rootCompositionId, styles, options }) => {
if (!options.isSubComposition) return [];
if (isRegistrySourceFile(options.filePath)) return [];
if (!rootTag || !rootCompositionId) return [];
const rootClasses = (readAttr(rootTag.raw, "class") || "").split(/\s+/).filter(Boolean);
if (rootClasses.length === 0) return [];
const offenders: string[] = [];
for (const style of styles) {
for (const selector of extractCssSelectors(style.content)) {
const hitsRoot = leftmostCompoundClasses(selector).some((c) => rootClasses.includes(c));
if (hitsRoot && !offenders.includes(selector)) offenders.push(selector);
}
}
if (offenders.length === 0) return [];
const example = offenders.slice(0, 3).join(", ");
return [
{
code: "subcomposition_root_styled_by_class",
severity: "error",
message:
`Root element has class="${rootClasses.join(" ")}" and is styled by ${offenders.length} rule(s) keyed off that class (e.g. ${example}). ` +
`At render, every sub-composition rule is scoped to [data-composition-id="${rootCompositionId}"] <selector>, so a selector whose leftmost part is the ROOT's own class becomes a descendant selector that cannot match the root — the scene renders unstyled (tiny text top-left, full-size images). ` +
`lint/validate/inspect and Studio's per-frame iframe preview do not scope, so this passes every static check and looks correct in preview.`,
selector: example,
fixHint: `Give the root id="root" and style it with \`#root { ... }\` plus plain descendant selectors (\`.kicker\`, \`#hero\`) — the runtime already scopes each sub-composition by data-composition-id, so a class namespace on the root is redundant and breaks under scoping.`,
snippet: truncateSnippet(rootTag.raw),
},
];
},
];
-191
View File
@@ -1,191 +0,0 @@
---
name: bgm-to-video
description: >
Use when the user has a BGM / background-music track (audio file, or a video to pull
audio from) and wants a music-grounded, beat-synced HyperFrames video. This is the
template-driven path: a deterministic analyzer reads the beat, a Music Reader classifies
the track into sections and marks where each could be cut finer (beat type + mood, no
content), then a Director decides each section's groups (it alone sees the templates) and
matches each to a reverse-engineered Group Template from a catalog and adapts
it (binding copy, palette, and timing), falling back to free creative-coding when no
template fits, and a Builder realizes it as one paused-GSAP HyperFrames composition.
V1 is asset-free: typography, generative shader/geometry backgrounds, code-native
motion. "template" names the method (match-and-adapt), not a fixed look.
metadata:
{
"tags": "bgm, music, beat-sync, templates, group-template, creative-coding, typography, gsap, hyperframes, visual-plan",
}
---
# bgm-to-video — template-driven, music-grounded video
Input is a **BGM track**. Output is a beat-synced HyperFrames video where **music is the
spine; the visual for each group is chosen by matching a reverse-engineered template**,
not invented from scratch each time. When nothing matches, the Director free-composes —
the catalog is a head start, not a cage.
## Two layers
| Layer | Artifact | What it is | Used by |
| -------------------------- | --------------------------------- | ----------------------------------------------------------------------------- | -------- |
| **L0 · Motion Primitives** | `references/motion-primitives.md` | atoms: one anchor → one GSAP micro-move | Builder |
| **L1 · Group Templates** | `templates/<id>/` | a whole-group archetype (roles + timing + stop rule + exit), composed from L0 | Director |
The linchpin: the **Music Reader's per-group output** and a **template's match-face** are
the same schema — `GroupSignature` (`references/signature-schema.md`). Matching is then
mechanical.
## How templates get into the catalog
Templates are **reverse-engineered from golden-sample videos** by the
`bgm-golden_sample_reverse` skill (`reverse-to-template.md`): slice a group → beatgrid
(signature) → Gemini video analysis (roles/motion/transition) → a `card.json` (+ a
parameterized reference `index.html`), promoted into `templates/<id>/`.
## Pipeline
| # | Phase | Exec | Artifact | Detail |
| --- | ---------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 0 | init | Bash | `assets/bgm.mp3` | create project, place/extract BGM |
| 1 | analyze | Python | `audiomap.json` | deterministic beat / energy / roll / hard-stop analysis |
| 2 | read music | subagent | `music-read.json` | Music Reader → `sections[]` (a `GroupSignature` each) + `cut_candidates[]` (classify only; no group-count decision) |
| 3 | plan | subagent | `visual-plan.json` | Director → subdivide sections into groups (catalog-aware) + match a template per group + adapt; else free-compose |
| 4 | build | subagent | `index.html` | Builder → mount each group (fork template impl, or author from L0) on one timeline |
| 5 | verify | Bash | gate | lint + validate + inspect |
| 6 | render | Bash | `renders/video.mp4` | muxed video with BGM |
| 7 | finalize | subagent | repaired output | snapshot QA + one repair loop |
`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
## Step 0 — Init project + place BGM
```bash
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # extract from video first if needed
```
Optional style files at the project root: `frame.md`, `design.md` / `DESIGN.md`.
## Step 1 — Analyze the music
```bash
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
```
Writes the canonical timing source. Sections are NOT baked in.
## Step 2 — Read music (Music Reader → music-read.json)
Dispatch one subagent. Prompt = full contents of [`agents/music-reader.md`](agents/music-reader.md) + dispatch context:
```text
SKILL_DIR: <absolute path>
PROJECT_DIR: <absolute path>
AudioMap: <PROJECT_DIR>/audiomap.json
Signature schema: <SKILL_DIR>/references/signature-schema.md
Write music read to: <PROJECT_DIR>/music-read.json
```
The Music Reader **only classifies**: it cuts the track into **sections** (musical
macro-structure), writes a `GroupSignature` per section, and lists each section's
**`cut_candidates`** — the musically-legal places it _could_ be cut finer. It does **not**
decide how many groups a section becomes (that needs the catalog, which it can't see). No
copy, no fonts, no colors, no layout.
## Step 3 — Plan (Director → visual-plan.json)
Dispatch one subagent. Prompt = full contents of [`agents/director.md`](agents/director.md) + dispatch context:
```text
SKILL_DIR: <absolute path>
PROJECT_DIR: <absolute path>
User request / brief: <user's request and supplied copy>
AudioMap: <PROJECT_DIR>/audiomap.json
MusicRead: <PROJECT_DIR>/music-read.json
Template catalog: read EVERY <SKILL_DIR>/templates/*/card.json (status:"promoted")
Signature schema: <SKILL_DIR>/references/signature-schema.md
Template definition: <SKILL_DIR>/references/template-definition.md
Transition catalog: <SKILL_DIR>/references/transition-catalog.md
Visual plan contract: <SKILL_DIR>/references/visual-plan-contract.md
Motion primitives (for free-compose): <SKILL_DIR>/references/motion-primitives.md
Style files to read if present: <PROJECT_DIR>/frame.md, design.md, DESIGN.md
Write visual plan to: <PROJECT_DIR>/visual-plan.json
```
The Director first **subdivides each section into groups** by acting on its
`cut_candidates` (catalog-aware: keep a section whole when one template fits, split it when
a template would be stretched or it spans multiple gestures), then matches each group to a
promoted template, binds the template's params (copy it writes from the brief, palette from
mood, anchors from this group's beats), reconciles the stop rule to the group boundary,
plans `fast_cut` transitions, and free-composes any group with no match. It does **not**
write HTML/GSAP.
## Step 4 — Build (Builder → index.html)
Dispatch one subagent. Prompt = full contents of [`agents/builder.md`](agents/builder.md) + dispatch context:
```text
SKILL_DIR: <absolute path>
PROJECT_DIR: <absolute path>
AudioMap: <PROJECT_DIR>/audiomap.json
VisualPlan: <PROJECT_DIR>/visual-plan.json
Template reference impls: for each group with a templateRef, <SKILL_DIR>/templates/<templateRef>/index.html
Visual plan contract: <SKILL_DIR>/references/visual-plan-contract.md
Template definition: <SKILL_DIR>/references/template-definition.md
Motion primitives: <SKILL_DIR>/references/motion-primitives.md
Builder contract: <SKILL_DIR>/references/builder-contract.md
BGM path for HTML: assets/bgm.mp3
Write composition to: <PROJECT_DIR>/index.html
```
The Builder mounts each group as a gated sub-scene on ONE paused timeline: fork the
group's template reference impl and re-host its tweens at the group's absolute audio
seconds (or author from L0 primitives when free-composed), then apply the group→group
transitions.
## Step 5 — Verify gates
```bash
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . )
( cd "$PROJECT_DIR" && npx hyperframes inspect . )
```
Inspect: t=0, each group's `span_sec` start, each transition `at`, the final frame. On
failure → Step 7.
## Step 6 — Render
```bash
( cd "$PROJECT_DIR" && npx hyperframes render . -q draft -o renders/video.mp4 --fps 30 )
```
Expect video + audio, duration == `audiomap.audio.duration_sec`.
## Step 7 — Finalize / repair
Dispatch one subagent. Prompt = full contents of [`agents/finalize.md`](agents/finalize.md) + the contracts above + the verbatim gate-failure output. Finalize edits `index.html` only; if the plan is creatively wrong, return to Step 3.
## Resume table
| You have | Continue from |
| --------------------- | ------------- |
| `assets/bgm.mp3` only | Step 1 |
| `audiomap.json` | Step 2 |
| `music-read.json` | Step 3 |
| `visual-plan.json` | Step 4 |
| `index.html` | Step 5 |
| gates passed | Step 6 |
| a gate failed | Step 7 |
## Directory layout
```
bgm-to-video/
SKILL.md
agents/ music-reader.md · director.md · builder.md · finalize.md
references/ signature-schema.md · template-definition.md · transition-catalog.md
visual-plan-contract.md · motion-primitives.md (L0) · builder-contract.md
scripts/ analyze-beatgrid.py
templates/ <id>/ { card.json · index.html · README.md } ← the L1 catalog
```
-72
View File
@@ -1,72 +0,0 @@
# Builder (template-driven) — mount groups on one timeline
Turn `visual-plan.json` + `audiomap.json` into one renderable HyperFrames `index.html`.
Each group is a **gated sub-scene**: for a `templateRef` group, fork the template's
reference impl and re-host it; for a `free_design` group, author from L0 primitives. All
groups share **one paused GSAP timeline** at absolute audio seconds.
## Inputs
- `visual-plan.json` — groups (templateRef + params + role_bindings, or free_design) + transitions.
- `audiomap.json` — timing truth.
- **Template reference impls** — `templates/<templateRef>/index.html` for each matched group.
- `references/template-definition.md`, `visual-plan-contract.md`, `motion-primitives.md`,
`builder-contract.md`. Read `builder-contract.md` — the HyperFrames mechanics
(root `#stage`, the `<audio>` tag, the one paused timeline, the forbidden list,
seek-safety) are non-negotiable and unchanged.
Output: a single-file composition at the requested `index.html`.
## The core method: each group is a gated sub-scene
The whole video is ONE composition with ONE `#stage` and ONE paused timeline. Build it
group by group:
1. **One container per group** inside `#stage`:
`<div class="group" id="g1" style="position:absolute; inset:0;">…</div>`. Stable id.
2. **Gate visibility by the group's span.** A group is only visible during its
`span_sec`. Use 0ms `fast_cut` sets on the master timeline:
`tl.set("#g1",{autoAlpha:1},start); tl.set("#g1",{autoAlpha:0},end);` (and start hidden
at t=0 unless it's the first group). The transition between groups IS this hard cut.
3. **Re-host each group's animation at an OFFSET.** A template reference impl is a
standalone composition (its own 0-based timeline). You **inline its DOM + CSS + shader
into the group container** and **re-create its tweens on the master timeline shifted by
the group's `start`**: a tween the impl placed at `t` goes at `start + t`. Map the
impl's local reveal/hold/exit onto the group's real `role_bindings` seconds (e.g.
reveal on `role_bindings.message.reveal_at`, field breath on `field.surge_at`). Set the
group's element ids/uniform var names with a `g1_` prefix so multiple groups don't
collide.
4. **Fill the template's params.** Apply `visual-plan.json` `params` as the concrete
values (text content, palette → CSS vars / shader uniforms, flowSpeed, duration). You
may pass them as the impl's composition-variables OR hard-code them into the inlined
group — either way the rendered values must equal `params`.
5. **Free-design groups:** author the container from `motion-primitives.md` recipes, same
gating + offset rules.
> WebGL templates: give each group its own `<canvas>` + renderer inside its container; a
> continuous render loop is fine (the reference impls already do this and explain why it
> stays deterministic — all _visible_ state comes from timeline-driven uniforms). Gate the
> container with `autoAlpha`, not by tearing down the renderer.
## Transitions
`visual-plan.json.transitions` are all `fast_cut`: realize each as the 0ms visibility
swap at `at` (hide the outgoing group, show the incoming one on the same frame). No
crossfade, no tween. The cut is the transition.
## Timeline discipline (from builder-contract.md)
- Exactly one `gsap.timeline({ paused:true })`; register `window.__timelines["<compositionId>"] = tl;`; end with `tl.seek(0);`.
- All tween positions are absolute audio seconds from `audiomap.json` (offset per group as above).
- Hard hits / cuts / palette flips are 0ms `tl.set(...)`. Eased entrances 300–500ms. Lead a move that must _land_ on a beat by ~40–190ms.
- No `stagger`, timers, `requestAnimationFrame` for visual _state_, `Math.random`, `Date.now`, remote assets/fonts, infinite repeats, render-critical callbacks. Fake them deterministically (see builder-contract.md).
## Self-Check
- Passes `npx hyperframes lint .` and `npx hyperframes validate .`.
- `#stage` + `<audio id="bgm" data-timeline-role="music" ...>`; one paused timeline; duration == `audiomap.audio.duration_sec`.
- Each group is visible exactly across its `span_sec` and hidden outside it; t=0 is not accidentally blank.
- Each group's rendered text/palette equals its `visual-plan.json` `params`.
- Group→group cuts are 0ms and land on the `transitions[].at` second.
- Group ids/var names are namespaced; no two groups' elements or uniforms collide.
- Final frame is intentional; main text readable, not colliding.
-121
View File
@@ -1,121 +0,0 @@
# Director (template-driven) — match, adapt, transition
Turn the brief + `music-read.json` into `visual-plan.json`. For each **section**, decide
how finely to split it into **groups** (you own this call — you alone see the catalog),
then for each group **match a promoted Group Template and adapt it**; free-compose only
when nothing fits.
Your mantra: **music is the spine; a template is a head start, not a cage.**
## Inputs
- User brief / supplied copy — topic, mood, exact words to keep.
- `music-read.json` — `sections[]`: each is a `GroupSignature` over its whole span **plus**
a `cut_candidates[]` menu of musically-legal internal cut points. **There are no groups
yet — you create them** by choosing which candidates to act on.
- `audiomap.json` — timing truth (anchor seconds).
- **Template catalog** — read EVERY `templates/*/card.json` with `status:"promoted"`.
- `references/signature-schema.md`, `template-definition.md`, `transition-catalog.md`,
`visual-plan-contract.md`, `motion-primitives.md` (for free-compose).
- Style files if present: `frame.md` → `design.md` → `DESIGN.md`.
Read the contracts before writing. Output: one valid `visual-plan.json`, no commentary.
## Per section: decide its groups (subdivide)
You decide how many groups each section becomes, because the right granularity depends on
the **template native spans** in the catalog — which only you can see. A group's native
span ≈ the length of a card's `examples[].span_sec`.
1. **Try the section whole first.** Treat the section as one group (its `GroupSignature` is
already in `music-read.json`) and run the match below.
2. **Subdivide only if the whole-section fit is bad**, cutting at the section's
`cut_candidates[]`:
- **Pacing** — the best-matching card's native span is much shorter than the section
(the template would be stretched / leave dead air). Cut so each group ≈ a matchable
native span.
- **Gesture** — the section spans parts no single template or thesis covers well (e.g. a
busy opener + a closing lockup). Cut at the candidate(s) that separate them.
3. **How to cut.** Pick the **fewest, strongest** `cut_candidates` that fix the above; each
group's `span_sec` = consecutive cut points (plus the section ends). Keep every group
**≥ ~1 bar**. Derive each group's `GroupSignature` over its slice (signature-schema
derivation table) and **re-classify `structural_type` on that slice** — it may differ
from the section's.
4. **Don't over-cut.** If one template already fits the whole section's pacing, keep it
whole. A `void_breath` / `sustained_hold` / `hard_stop_freeze` section has no candidates
— never split it. Multiple templates across a section's groups are fine; cohesion is the
brand spine, not reuse.
## Per group: match → select → adapt
Run this on each group you produced above (the section itself when you kept it whole).
1. **Match.** Keep promoted cards where
`card.match.structural_type == group.structural_type`
**and** the group's `GroupSignature` satisfies **every** `card.match.requires`
predicate **and** `group.mood` overlaps `card.match.mood_fit`.
2. **Rank & select.** Order survivors by signature closeness to the card's `examples[]`
(and example count as a tiebreak); take the top → `templateRef`. If **no card
survives**, set `templateRef:null` and write a `free_design` (one visual thesis for the
group, built from `motion-primitives.md` — pick a density topology, name the
primitives).
3. **Adapt (bind the template).**
- Fill `params` (keys exactly from the card) — **copy you wrote** into the text slots,
**palette** from the brand spine, `flowSpeed`/etc. to taste, `duration` = the group's
span length.
- Fill `role_bindings` with this group's **real anchor seconds** (entry downbeat, surge
time, …) from its slice of the AudioMap — not the card's example times.
- **Reconcile the stop rule:** if the card's `exit_trigger` and the group's `span_sec`
end disagree, snap the boundary to the nearest AudioMap anchor and use that.
## Brand spine (unify the groups)
Set one `style`: one type family, a ≤4–6 swatch palette, ≤2 accents per frame, from the
brief's mood. Different templates per group are expected — the spine is what makes them
read as one piece. Pick the palette once; every group's `params.palette` draws from it.
## Write the copy (you own the words)
- Keep exact user words; else invent with taste, on the brief's mood.
- **Message vs texture:** a readable word holds ≥1 beat (headline 3–8, sentence 4–10),
stable + focal; a word held <1 beat is texture (strobe/grid/ticks). Never force a
message onto a sub-beat — demote it to texture.
- Place copy into the matched template's text params, or (free groups) onto the group's
anchors. Declare anchor + accumulate/stagger intent; leave micro-timing to the Builder.
- A closing `logo`/CTA lands on the final hit / hard stop and holds through trailing
silence.
## Transitions
One `transitions[]` entry per adjacent group pair. **`transition` is always `"fast_cut"`**
for now (decision #4): a 0ms hard cut at the boundary second. Do not emit richer
transitions yet (the interface exists for later — see `transition-catalog.md`).
## Direction stance
- **You own group count.** `music-read.json` gives sections + legal `cut_candidates`, not
groups — subdivide each section yourself (see above), because only you know the template
native spans. Keep a section whole when one template fits it; split it when a template
would otherwise be stretched or when it spans gestures no single template covers. Groups
in one section may use **different templates** — no reuse constraint; the brand spine
unifies them.
- One template (or one free thesis) per group — but the visual **system may change** at
each boundary; the brand spine unifies them.
- Trust the match: a `sustained_hold` group wants the held-message template's stillness,
not invented motion. Don't over-design a group the template already solves.
- Free-compose is a real fallback, not a failure — use it whenever the catalog has no
honest match, and write it as carefully as a matched group.
## Self-Check
- Every section became ≥1 group; each group entry carries its `section_id`, `span_sec`
drawn from the section's `cut_candidates` (or the whole section span), all groups in
order tiling `duration_s`. No group is < ~1 bar; no cut lands inside a roll.
- Each group's `GroupSignature` is derived over its own slice (or inherited from the
section when kept whole); its `structural_type` may differ from the section's.
- Every group has a `templateRef` (promoted, exists) **or** a `free_design`.
- For each `templateRef`: `match.requires` is actually satisfied by the group's signature;
`params` keys == the card's `params`; `role_bindings` use real AudioMap seconds.
- `style` brand spine is set and every `params.palette` is drawn from it.
- One `fast_cut` transition per boundary.
- `duration_s == audiomap.audio.duration_sec`.
-39
View File
@@ -1,39 +0,0 @@
# Finalize / Repair (template-driven)
Use after lint, validate, inspect, or render fails. You may edit `index.html` only.
## Inputs
- `audiomap.json`
- `visual-plan.json`
- current `index.html`
- `references/visual-plan-contract.md`
- `references/template-definition.md`
- `references/builder-contract.md`
- `references/motion-primitives.md`
- lint / validate / inspect / render output (verbatim)
- render quality target
Read the relevant contracts before repairing.
## Flow
1. Read the failure output first. Separate contract failures from visual issues.
2. Inspect important times: `t=0`, every group's `span_sec` start, every
`transitions[].at`, and the final frame.
3. Repair narrowly: blank/empty frames; a group visible outside its `span_sec` (or hidden
inside it); elements or uniforms colliding between groups (namespacing); invisible
elements; bad attrs; missing timeline registration; forbidden GSAP; obvious timing
misses; a group whose rendered text/palette doesn't match its `params`.
4. Re-run `npx hyperframes lint .`, `npx hyperframes validate .`, and inspect.
5. Render when gates pass.
## Rules
- Do not change duration or audio timing to hide sync issues.
- Do not redesign the concept during repair. If the plan is creatively wrong (wrong
template matched, wrong copy), return to the Director (Step 3) — don't patch around it.
- Keep each group's visibility gated to its `span_sec`; keep group→group cuts 0ms on the
`transitions[].at` second.
- Do not add remote assets, network fetches, timers, or nondeterminism.
- Prefer small CSS/GSAP fixes over structural rewrites.
-128
View File
@@ -1,128 +0,0 @@
# Music Reader (template-driven) — classify only
Turn `audiomap.json` into `music-read.json`: cut the track into **sections** (musical
macro-structure), write a `GroupSignature` for each section, and list the musically-legal
**cut candidates** inside each (the internal anchors the Director _may_ subdivide on). You
**classify and surface facts**; you do not design, and **you do not decide group count** —
how finely a section is split is the Director's call, because only the Director sees the
template catalog.
You are not choosing visuals, copy, fonts, colors, layout, or motifs. You answer, per
section: _what kind of beat is this_, _what mood_, and _where could this legally be cut
finer_. Everything else is the Director's job.
## Inputs
- `audiomap.json` — factual music data.
- `references/signature-schema.md` — the `GroupSignature` schema + controlled vocab +
derivation formulas + the `structural_type` classification rubric. **Read it first.**
## Output
Write exactly one valid JSON file to the requested path: `music-read.json`. No markdown,
no commentary.
```jsonc
{
"duration_s": 7.198, // == audiomap.audio.duration_sec
"bpm": 129.2,
"one_line": "A held recap card that breaks into a per-onset typography hit.",
"sections": [
{
// a section IS a GroupSignature over its whole span (so the Director can match it
// as one group if it chooses not to subdivide) + the legal cut points inside it.
"id": "s1",
"span_sec": [0.0, 7.198], // snapped to AudioMap anchors; sections tile the track
"structural_type": "per_onset_sequential", // the section's dominant archetype
"mood": ["hype"],
/* …every other GroupSignature field per references/signature-schema.md
(energy_level, density, onset_rate, onset_gap_bars, has_roll, entry, exit_trigger, …),
derived over the WHOLE section span … */
"cut_candidates": [
// internal anchors the Director MAY cut on — musically legal only. Empty for a
// single-gesture section. NEVER a point inside a rolls[] run.
{ "time": 3.692, "kind": "key_moment", "strength": "strong" },
{ "time": 5.759, "kind": "phrase", "strength": "medium" },
],
},
],
}
```
`sections[]` is an ordered list whose `span_sec` tile the whole track with no gaps or
overlaps (first starts at 0, last ends at `duration_s`). Each section is a full
`GroupSignature` (derived over its span) **plus** a `cut_candidates[]` menu. **There is no
`groups[]` here** — the Director creates groups in `visual-plan.json` by choosing which
cut candidates to act on.
## How to read (pipeline — run in order)
1. **Gestalt.** From `summary` / `tempo` / `audio.duration_sec` + the drum histogram +
roll count, write the `one_line` and note the density arc.
2. **Segment into sections.** Walk `energy_phases[]` in order and split the track where the
music genuinely changes state — at `hard_stops[]`, `SURGE`/`DROP` `key_moments`, the
start/end of a `rolls[]` run, an **onset desert** (a long gap in `events[]`), or a big
energy-level jump. Collapse adjacent phases that are really one gesture. Expect ~1–6
sections; a short clip may be one. **Snap every boundary to an AudioMap anchor**
(downbeat / hard_stop / phrase / key_moment / energy-phase edge), then **re-snap to the
nearest `beats_sec`** (key_moments / energy-phase edges are 1-second-resolution facts;
the beat grid is precise — tolerance ≤ ½ beat).
3. **Per section, build the `GroupSignature`** over the whole section span. Use the
derivation table in `signature-schema.md` for every objective field (`energy_level`,
`density`, `onset_rate`, `onset_gap_bars`, `has_steady_grid`, `span_bars`, `entry`),
classify `structural_type` (rubric, top-down first-match; `unclassified` + a `note` if
nothing fits), tag `mood` (1–3), and set `exit_trigger`. All from the audiomap — never
invented.
4. **Per section, list `cut_candidates[]`** — the internal anchors the Director _may_ cut
on. This is a **menu of musical facts, not a decision**: you do not pick how many groups,
only where a cut would be legal.
- **Include** each anchor that lies strictly inside the span: an internal `key_moment`
(mini SURGE/DROP), a mid-section `hard_stop`, the edge of a partial `rolls[]` run, a
`phrases[]` edge, or a clear onset-cluster gap (≥ ~1 bar between consecutive
`events[]`). Tag each `{time, kind, strength}` and snap its `time` to the nearest beat.
- **Exclude (illegal cuts):** any point **inside** a `rolls[]` run (a roll is one
cascade), and any candidate that would leave a fragment **< ~1 bar**.
- **Emit an empty list** for a single-gesture section (`void_breath` / `sustained_hold` /
`hard_stop_freeze`) — it must never be subdivided.
> The Director reads the catalog (template native spans + what matches) and decides which
> of these candidates to act on; an unused candidate costs nothing. Detecting where a cut
> is _legal_ is musical (yours); deciding where a cut is _useful_ is catalog-aware (theirs).
## Worked example — a section + its cut candidates
Section `s_final` = `[19.412, 30.0]`, `per_onset_sequential`, ~4.6 bars @ 103.4 bpm, with
a `hard_stop` at ~24s and a `SURGE` at ~26s inside it. You emit it as **one section**
carrying its whole-span `GroupSignature` plus:
```jsonc
"cut_candidates": [
{ "time": 23.963, "kind": "hard_stop", "strength": "strong" }, // snapped to the downbeat
{ "time": 26.215, "kind": "surge", "strength": "strong" },
]
```
You do **not** decide whether this becomes 1, 2, or 3 groups. The Director may keep it
whole (if one template fits), or cut at one/both candidates (e.g. a per-onset opener + a
closing lockup) — that is its catalog-aware call.
## Section boundaries are proposals
You propose section `span_sec`; the Director may nudge a boundary to fit a chosen
template's stop rule, then reconcile to the nearest anchor (decision #2). Because both of
you derive from the same audiomap, this rarely moves anything — but write the most
defensible audio boundary, not a guess.
## Self-Check
- `duration_s == audiomap.audio.duration_sec`; `sections[].span_sec` tile it with no
gap/overlap (first at 0, last at `duration_s`).
- Every section carries a full `GroupSignature` (every field traces to an audiomap value or
a span of it) **plus** a `cut_candidates[]` list (possibly empty).
- Every `cut_candidates[].time` sits on an AudioMap anchor re-snapped to the nearest beat;
none is inside a `rolls[]` run; none would leave a sub-1-bar fragment; single-gesture
sections (`void_breath` / `sustained_hold` / `hard_stop_freeze`) have an empty list.
- `structural_type`, `mood`, `exit_trigger.type` are controlled-vocab (or `unclassified`
with a note).
- **No `groups[]` and no group-count decision** anywhere — that is the Director's.
- No content, no fonts, no colors, no layout, no copy anywhere in the output.
@@ -1,143 +0,0 @@
# Builder Contract
This is the complete implementation contract for LLM-first BGM compositions. Builder
and Finalize must read it before editing `index.html`.
The timeline is seekable sheet music: one paused GSAP timeline, absolute audio-second
positions, deterministic elements, no browser-play-only tricks.
## Root Composition
The root is a real stage element, not `<html>`:
```html
<div
id="stage"
data-composition-id="bgm"
data-start="0"
data-duration="23.005"
data-width="1920"
data-height="1080"
></div>
```
- `data-composition-id` must equal the `window.__timelines` key.
- Use `data-duration`, not `data-composition-duration`.
- `data-width` / `data-height` define the frame.
- Root CSS must set explicit pixel `width` and `height`.
- Landscape 1920x1080 is default unless `visual-plan.json.canvas` requests otherwise.
## Audio
```html
<audio
id="bgm"
data-timeline-role="music"
src="assets/bgm.mp3"
data-start="0"
data-duration="23.005"
data-media-start="0"
data-volume="1.0"
></audio>
```
- Source HTML uses `data-duration`; emitting raw `data-end` triggers lint warnings.
- `data-timeline-role="music"` marks the BGM track.
- The file must exist beside `index.html` at `assets/bgm.mp3`.
## Timeline
- Exactly one render-critical `gsap.timeline({ paused: true })`.
- Register it: `window.__timelines["<compositionId>"] = tl;`.
- End the script with `tl.seek(0);`.
- Tween positions are absolute audio seconds from `audiomap.json`.
- Percentage keyframes only live inside a single tween's `keyframes`.
- `easeEach` belongs inside `keyframes`, never as a sibling tween prop.
## Timing Discipline
- Group-level cuts land on `visual-plan.json` `groups[].span_sec` boundaries (= the
`transitions[].at` seconds), snapped to nearby downbeats.
- Phrase moves use `audiomap.phrases[]`.
- Word entries and layout changes prefer `grid.downbeats_sec[]`.
- Micro accents use `grid.beats_sec[]` or selected `events[].t`.
- Rolls use `rolls[].start/end` and should feel continuous or cascading.
- Hard stops use `hard_stops[].t` and should visibly freeze, cut, or hold.
## Layout Before Animation
Build the most important static frame first:
- A scene container fills the stage.
- Use CSS grid/flex/padding for content layout.
- Use absolute positioning for decorative systems, overlays, masks, and generated
geometry.
- Keep title-safe padding. Do not let hero text touch the frame edge.
- Use `vmin`, `clamp`, or measured CSS to keep type readable across aspect choices.
Animate from hidden/offscreen states into the CSS end-state. The CSS end-state is the
truth.
## Seek-Safe Reveal
- Delayed elements are hidden until entrance and visible after seeking.
- Initial hidden state may be inline CSS or `gsap.set(..., {autoAlpha:0})` at time 0.
- Reveal with `fromTo` or paired `set` + motion tweens.
- Finite repeats only.
## Forbidden
`tl.play()`, `setTimeout`, `setInterval`, `requestAnimationFrame`, runtime network,
remote assets, remote fonts, `Math.random`, `Date.now`, `new Date`, `ScrollTrigger`,
`repeat:-1`, render-critical callbacks, `.call()`, `.addLabel()`, `.addPause()`.
## Discouraged
- `stagger:` does not serialize cleanly; expand multi-element moves into explicit
per-element tweens with offset positions.
- Google Fonts links fail in offline/sandboxed renders. Use system-safe stacks or
local `@font-face`.
- Out-of-alias font family names can trigger lint warnings.
## Faking the forbidden patterns
The bans still leave you every move the music wants — do them deterministically:
- **Instead of `stagger`:** schedule explicit per-element work at `t + i*step` — either
`delay: i*0.04` on each tween, or one `tl.set(el[i], props, eventTime[i])` per onset.
This serialises cleanly and lands each element on its own beat.
- **Instead of `Math.random`:** derive variation from the index —
`palette[(i*7 + step*3) % palette.length]`, a fixed coordinate/rotation table, or a
hand-keyed scrambled-string array. Looks random, stays seek-deterministic.
- **Instant text / number swaps:** `tl.set(el, { textContent: "…" }, T)` is allowed and is
the workhorse percussive move. Give the node `width: max-content` (or a fixed width) and
centre it so a longer word does not reflow the layout.
## CSS Values
Complex CSS strings for `clipPath`, `filter`, or transforms should be valid CSS in the
HTML source. If a serializer path requires raw passthrough, use the repo convention:
`"__raw:'inset(0 0% 0 0)'"`.
## Visual QA
- `t=0` is not blank unless intentional silence is specified.
- The first meaningful visual appears during the first section.
- Drop / surge has a visible hit within about 0.15s of the intended anchor.
- Dense sections show visual density, not just a single static word.
- Hard stop creates a readable hold or freeze.
- Final frame is intentional.
- Main text is readable and not colliding.
- Palette is coherent; define colors once through CSS variables or one palette block.
## Inspect Targets
When running `hyperframes inspect`, include:
- `0`
- every `visual-plan.json` `groups[].span_sec` start
- every `transitions[].at`
- strongest `DROP` / `SURGE` key moments
- every `hard_stops[].t`
- start/end of major `rolls[]`
- `duration - 0.2`
@@ -1,123 +0,0 @@
# Motion Primitives — recipe catalog for Builder
The atomic layer: one anchor → one micro-move. Group Templates (L1) are composed from
these; the Builder also reaches here directly when a group is free-composed. **Not a
fixed API** — they are creative-coding recipes.
One flat catalog. The **recipe** column tells you what to lift:
- **✓** — a runnable, lint-clean composition at `motion-primitives/<id>/index.html`. Open
it and lift the relevant tweens.
- **≈ `<id>`** — no separate file; use that existing recipe, it's the same idea.
- **—** — no standalone file. Implement it inline from the description + `builder-contract.md`;
these are one-liners (e.g. a 0ms `tl.set`) or moves a template realizes internally.
## Timing & latency (applies to every primitive)
Quantified from frame-accurate reverse engineering of beat-synced reels:
- **Hard hits are 0ms.** Cuts, palette flips, content swaps, freezes are `tl.set(...)`
with no duration — the percussion _is_ the motion. Easing a hit kills it.
- **Lead the anchor.** A move that must _land_ on a beat (a wipe covering the frame, a
count-up locking, two blocks colliding to centre) should **start ~40–190ms early** so it
completes ON the anchor. Reactive entrances — something appearing _because_ of the hit —
fire 0–45ms after.
- **Eased entrances: 300–500ms** (scale punch, slides, camera pushes). **Macro builds:
800–2000ms** spanning a whole roll / silence.
- **Magnitudes:** scale-punch entrance 0→1; weight pulse 1→1.06; hero fill up to 1→5;
chromatic split ~20px, resolve clean in ≤150ms.
- **Per-bar caps:** one accumulating element per audio hit (not a burst); a camera move at
most once per phrase, never per beat; a dense flip/strobe system runs ≤2–3s.
- **Tension-builds lock.** A count-up / sequential build / morph must _resolve on_ a
downbeat or hard_stop, never trail off mid-bar.
## Catalog
Each runnable recipe is self-contained and lint-clean: showcase chrome stripped,
system-font fallback, shared `../assets/gsap.min.js`, one paused timeline on
`window.__timelines["main"]`. To use one, read its `index.html` and lift the tweens.
| id | anchor | what it does | recipe |
| ------------------------ | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `01-hypercut_whip` | beat / hard_stop | fast whip-pan hard cut between frames | ✓ |
| `02-kinetic_letter_in` | downbeat / phrase | per-letter kinetic entrance | ✓ |
| `03-braam_punch` | drop / surge | big "braam" impact — scale + weight slam | ✓ |
| `04-chromatic_split` | snare / glitch / surge | RGB channel split / glitch on a word | ✓ |
| `05-mask_reveal` | section_start / downbeat | clip-path mask wipe reveal | ✓ |
| `07-screen_shake` | drop / crash / kick | camera/screen shake jitter | ✓ |
| `08-binary_decrypt` | roll / build | scramble→decode text (binary → word) | ✓ |
| `09-dolly_zoom` | phrase / build | vertigo dolly-zoom (scale vs perspective) | ✓ |
| `10-iris_open` | section_start / reveal | circular iris-open reveal | ✓ |
| `11-electric_arc` | accent / glitch | electric arc / lightning accent | ✓ |
| `12-neon_flicker` | hold / texture | neon-sign flicker | ✓ |
| `13-chrome_sweep` | downbeat / reveal | metallic specular sweep across text | ✓ |
| `15-slot_machine_reveal` | roll → downbeat | slot-machine spin-to-land character reveal | ✓ |
| `16-liquid_morph` | phrase / transition | liquid / blob morph | ✓ |
| `17-gooey_metaball` | build / drop | gooey metaball merge field | ✓ |
| `18-3d_card_flip` | downbeat / swap | 3D card flip (rotateY) | ✓ |
| `19-crash_zoom_in` | drop / surge | violent crash zoom-in | ✓ |
| `20-spotlight_sweep` | reveal / hold | spotlight / gradient sweep over text | ✓ |
| `21-outline_to_fill` | downbeat / reveal | stroke outline → solid fill | ✓ |
| `22-counting_punch` | roll → downbeat | number count-up that punches & locks | ✓ |
| `24-particle_burst` | drop / crash | particle explosion burst | ✓ |
| `25-radial_burst_lines` | drop / surge | radial speed-lines burst | ✓ |
| `26-pixel_dissolve` | transition / hard_stop | pixelated dissolve | ✓ |
| `27-datamosh_smear` | glitch / transition | datamosh / motion smear | ✓ |
| `28-text_wave_distort` | hold / texture | wavy text distortion | ✓ |
| `bg_flow_field` | energy / whole span (bed) | generative WebGL curl-noise flow-field **background bed** — palette-driven, breathes on the energy envelope; run it underneath and compose any foreground move over it | ✓ |
| `blur_resolve` | stop / final hold | blur-in to crisp focus, then blur-out on the cut | ✓ |
| `chromatic_pressure` | snare / glitch | RGB split / digital tension on a transient | ≈ `04-chromatic_split` |
| `color_grid_shuffle` | onset | grid of cells recoloured by a deterministic index per onset | — |
| `content_swap` | beat | 0ms swap of stacked nodes — the workhorse percussive move | ≈ `15-slot_machine_reveal` |
| `directional_fill` | beat / reveal | directional wipe-fill (scaleX) sweeping across bars | ✓ |
| `flash_cut` | drop / crash | full-frame flash masking a word/colour state change | ✓ |
| `freeze_hold` | hard_stop | freeze the moving system and hold it (desaturate + vignette) | — |
| `hard_cut` | beat / hard_stop | sample-accurate 0ms colour-block + word cut | ✓ |
| `mosaic_pack` | beat / build | scattered tiles fly in and pack into a grid | ✓ |
| `negative_space_hold` | silence / hard_stop / final hold | kill busy layers, hold one readable mark in empty space | — |
| `overlay_pop` | accent | badge / lower-third overlay pops in over a base | — |
| `palette_flip` | section change | same layout re-skins via 0ms palette-variable flips | ✓ |
| `staggered_exit` | phrase / transition | ordered cascade-out clearing the frame | ✓ |
| `staggered_reveal` | build | ordered cascade-in of a stack / list | — |
| `system_replace` | drop / regime change | hard-cut the entire visual system, then boot the new one | — |
| `text_spectral_rays` | phrase / sweep (hero text) | volumetric spectral light-rays cast by a wordmark toward a sweeping light cursor — grain + RGB-split; **WebGL hero-text system** | ✓ |
| `tile_mosaic` | build / reveal | grid of tiles revealed in a diagonal sweep, assembling a poster | ✓ |
| `typewriter_reveal` | roll / build | char/word type-on, explicit per-span set (no `stagger`) + caret | ✓ |
| `value_counter` | roll → downbeat | count-up that locks on a downbeat / hard_stop | ≈ `22-counting_punch` |
| `word_grid_burst` | onsets → downbeat | grid of words revealed per onset, refocus one on a downbeat | ✓ |
> **Template-private verbs.** Some templates declare motion verbs realized only inside their
> own impl — e.g. `held_lockup`, `anchor_pop_in`, `word_slot_cycle`, `per_line_color`,
> `scene_palette_flip`, `beat_jitter_shake`, `box_zoom_wipe` (split-anchor-word-slot),
> `motion-blur` (logo-split). Those live in the template's own `index.html` / README, not
> here. Promote one into this catalog only when a second template needs it.
## How to combine
- One dominant system per group; layer at most one texture recipe over one structural recipe.
- Structure on strong beats (cuts, camera, system_replace → downbeat / phrase / section_start);
texture on weak / syncopated hits (content_swap, typewriter letters, chromatic accents).
- A roll is an accumulation container — build during it, hard-cut to a clean layout on the
downbeat that ends it.
- `drop` ≠ `downbeat`: a downbeat is a cut within the regime; a drop is a regime change
(`system_replace`, total clear, element-count jump).
- Let silence remove density (`negative_space_hold`).
- **Background beds are a layer, not a move.** A bed (e.g. `bg_flow_field`) runs the whole
span on the **energy / phrase** channel, leaving the **beat anchors** free for the
foreground — so it composes cleanly _under_ any discrete primitive (text `content_swap`,
`hard_cut`, a held mark…). One bed at a time; when mounting into a group, merge the bed's
uniform tweens onto the group's master timeline (don't run a second timeline), bundle a
local `three`/WebGL (no CDN), and repaint via the timeline's `onUpdate` (no rAF).
- **WebGL "system" primitives come in two roles:** a **bed** (`bg_flow_field`, behind
everything) and a **hero-text treatment** (`text_spectral_rays`, which rasterizes the
wordmark and _is_ the hero). Use at most one of each; feed text/raster locally (no CDN
fonts), repaint via `onUpdate`.
- **`text_spectral_rays` renders its OWN wordmark — never give the word a second source.**
It draws the solid letters AND the rays from one glyph mask (perfectly registered). Do NOT
use it as a "rays-only" layer behind a separate DOM logo (or stack `content_swap` /
`chromatic_pressure` on the same word): the two fonts/positions won't match and you get a
doubled / ghosted wordmark — and deleting the shader's letter terms does not fix it (the
ray mask is still the second, misaligned copy). Let the shader be the wordmark; hide any
DOM logo (keep it only as an invisible layout spacer). If you move the word off
frame-center, move the light cursor's `y` by the same amount. Full recipe:
[`motion-primitives/text_spectral_rays/USAGE.md`](motion-primitives/text_spectral_rays/USAGE.md).
@@ -1,195 +0,0 @@
# GroupSignature — the shared schema (linchpin)
One schema, three producers:
- the **Music Reader** emits one `GroupSignature` per **section** (over its whole span);
- the **Director** derives one per **group** when it subdivides a section;
- a **template's match-face** declares which `GroupSignature`s it fits.
Because all speak this vocabulary, matching a group to a template is mechanical. **Do not
let them drift.** Every field here is derived from `audiomap.json` (fact) — never invented
— so it holds at runtime with no video.
## Two levels: sections → groups
Segmentation is split across two stages by who knows what:
1. **Sections** (Music Reader, catalog-blind) — the musical macro-structure: runs of one
gesture, snapped to real state-changes. Each section is a full `GroupSignature` over its
whole span **plus** a `cut_candidates[]` menu — the musically-legal internal anchors a
finer cut could land on. The Music Reader does **not** decide how many groups a section
becomes.
2. **Groups** (Director, catalog-aware) — the treatment units a template actually binds to.
The Director subdivides each section by acting on zero or more of its `cut_candidates`,
because the right granularity depends on template native spans only it can see. A
section kept whole is one group (== itself); a long / multi-gesture section becomes
several. The Director derives each group's `GroupSignature` over its own slice.
`sections[]` (in `music-read.json`) tile the **whole track** (first at 0, last at
`duration_s`, no gaps/overlaps). The Director's `groups[]` (in `visual-plan.json`) tile it
too; every group carries the `section_id` it came from, and a section's groups tile that
section's span.
A **template matches a `group`** (which may be a whole section) — the match-face below is
unchanged. **Multiple templates inside one section are fine** (the brand spine unifies
them, not template reuse).
```jsonc
"sections": [
{
// a GroupSignature over the whole section span (every field below) + a cut menu
"id": "s1",
"span_sec": [19.412, 30.0], // [start,end], snapped to AudioMap anchors (re-snapped to nearest beat)
"structural_type": "per_onset_sequential",
"mood": ["dark", "cinematic"],
// …all other GroupSignature fields, derived over the whole span…
"cut_candidates": [
// musically-legal internal cut points the Director MAY use; empty for a single
// gesture; NEVER inside a rolls[] run; never leaving a sub-1-bar fragment.
{ "time": 23.963, "kind": "hard_stop", "strength": "strong" },
{ "time": 26.215, "kind": "surge", "strength": "strong" },
],
},
]
```
## The object
```jsonc
{
"id": "g1", // group id within the track
"section_id": "s1", // the section this group lives in (its groups tile the section span)
"span_sec": [0.0, 4.017], // [start, end], snapped to AudioMap anchors
"span_bars": 2, // length in bars (rounded)
"structural_type": "sustained_hold", // controlled vocab — see rubric below
"mood": ["warm", "cinematic"], // controlled vocab, 1–3 tags
// ── objective audio facts (straight from audiomap) ──
"energy_level": "HIGH", // VOID | LOW | MEDIUM | HIGH (dominant phase)
"energy": 0.8, // 0–1, mean of the dominant phase
"density": "sparse", // sparse | medium | dense (audiomap fact)
"onset_rate": 1.0, // onsets / sec over the span
"onset_gap_bars": 2.05, // longest onset desert, in bars (key discriminator)
"has_steady_grid": true, // stable bpm + ≥2 downbeats present
"bpm": 129.2,
// ── roll lane (from audiomap rolls[] overlapping the span; false/null if none) ──
"has_roll": false, // any rolls[] entry overlaps the group
"roll_kind": null, // dominant roll kind: fill | accel-roll | sustained-fill
"roll_rate_per_min": 0, // hits/min of the dominant (longest) overlapping roll
"roll_count": 0, // rolls[] entries overlapping the span
// ── boundaries ──
"entry": { "anchor": "downbeat", "time": 0.093 },
"exit_trigger": { "type": "first_onset_reentry", "time": 4.017 },
}
```
## Field derivation (from audiomap — make this automatic)
| field | how to compute |
| --------------------------------- | -------------------------------------------------------------------------------------------- |
| `span_sec` | the group's [start,end]; snap each to nearest `downbeats_sec` / `hard_stops` / `phrase` edge |
| `span_bars` | `round((end-start) / bar_dur)`, where `bar_dur = beats_per_bar * 60/bpm` |
| `energy_level` / `energy` | the `energy_phases[]` block covering most of the span → its `level` / `energy` |
| `density` | dominant `energy_phases[].density` over the span |
| `onset_rate` | `count(events in span) / (end-start)` |
| `onset_gap_bars` | `max gap between consecutive events[].t inside the span` ÷ `bar_dur` |
| `has_steady_grid` | `tempo.n_bars >= 2` and bpm stable |
| `has_roll` / `roll_count` | any / count of `rolls[]` overlapping the span |
| `roll_kind` / `roll_rate_per_min` | `kind` / `rate_per_min` of the dominant (longest) overlapping roll |
| `entry` | first anchor at/after `start` (prefer `downbeat`) |
| `exit_trigger` | see exit-trigger rule below |
Worked example (group_1): max onset gap `3.971 − 0.163 = 3.808s`; `bar_dur =
4·(60/129.2) = 1.858s`; `onset_gap_bars = 3.808/1.858 = 2.05`. ✓
## exit_trigger rule (also the group boundary)
Pick the first that applies, snap its time to the nearest downbeat:
1. longest onset gap ≥ ~1.5 bars **and** an onset follows it → `first_onset_reentry`
(the held section ends when rhythm re-enters — group_1).
2. a terminal `hard_stops[]` in the span → `hard_stop`.
3. a `SURGE` into a denser phase at the end → `surge`.
4. otherwise → `downbeat` (next bar) or `end` (track end).
> Per decision #2: the Music Reader proposes the boundary; when a chosen template's
> stop rule disagrees, the **Director reconciles** to the nearest AudioMap anchor.
> They rarely conflict because both come from these same facts.
## Controlled vocabularies (SEED — grows as we reverse)
These lists are the dictionary both sides must use. Adding a value is a deliberate
catalog change, not an ad-hoc string.
### `structural_type`
| value | the music | seen in |
| ---------------------- | ----------------------------------------------------------- | ------------------ |
| `sustained_hold` | energy present but few/no onsets — a held pad/riser | group_1 |
| `per_onset_sequential` | discrete onsets drive one reveal each (typing/word-by-word) | group_2 (expected) |
| `roll_cascade` | a `rolls[]` run → continuous cascade / multiply | — |
| `dense_multiply` | HIGH + dense, no single message → field/grid/strobe | — |
| `void_breath` | VOID / silence dominant → clear & hold | — |
| `hard_stop_freeze` | terminal hard stop → freeze to negative space | — |
| `drop_regime_change` | SURGE into dense → system replace | — |
> `dense_multiply` is currently a **broad bucket** — three promoted templates live under
> it (`roll-flipbook-word-cycle`, `held-text-strobe-burst`, `poster-tile-mosaic`),
> disambiguated by their `match.requires` (a fast `sustained-fill` roll vs a tiny
> `onset_gap_bars` strobe vs a tessellating tile program). Candidate future subtypes:
> `held_strobe`, `tile_mosaic_program`. Split them out when a 4th example forces it.
### `structural_type` classification rubric (decision tree)
Run top-down, first match wins:
1. VOID dominant & `onset_rate ≈ 0` → `void_breath`
2. terminal `hard_stop` + freeze, little after → `hard_stop_freeze`
3. `rolls[]` spans most of the group → `roll_cascade`
4. `energy_level ≥ MEDIUM` & `density == sparse` & `onset_gap_bars ≥ 1.5` → `sustained_hold`
5. `density == dense` & `energy_level == HIGH` & no dominant readable mark → `dense_multiply`
6. onsets present, discrete, each plausibly one reveal → `per_onset_sequential`
7. `SURGE` into a denser phase → `drop_regime_change`
8. none fit cleanly → leave `structural_type: "unclassified"` and flag for a NEW type.
### `mood` (1–3 tags)
`warm` · `dark` · `hype` · `elegant` · `glitch` · `cinematic` · `playful` · `tense` ·
`dreamy` · `aggressive`. Derive from `energy_phases[].feel` (warm/heavy/bright/sparse)
- energy + the Gemini read's genre cues.
### `exit_trigger.type`
`first_onset_reentry` · `hard_stop` · `surge` · `downbeat` · `end`.
### role kinds (used by templates, see template-definition.md)
`message` (readable text) · `background` (field/texture) · `camera` · `asset` ·
`overlay` (grain/vignette/chrome).
### motion verbs (per role; each maps to an L0 primitive or a custom phrase)
`freeze_after_reveal` · `energy_envelope_breath` · `per_onset_pop` · `cascade` ·
`strobe` · `camera_push` · `hold` · `font_shuffle` (cycle typefaces on the beat) ·
`flipbook` (0ms word/glyph swap per 16th over a roll) · `scramble_decode` (scrambled →
locked phrase). Link the L0 id in the template's `uses_primitives`; a verb with no L0 id
is a custom phrase the impl defines.
> **Meta-templates** (a base + a program of beat-synced _operations_, e.g.
> `poster-tile-mosaic`) may declare an `operations` / `engine` block instead of role
> `motion` verbs — see template-definition.md extension fields.
## Self-check
- Every field traces to an `audiomap.json` value or a span of it.
- `structural_type`, `mood`, `exit_trigger.type`, role kinds, motion verbs are all from
the controlled vocab (or explicitly flagged as a proposed new value).
- `sections[]` (music-read) and the Director's `groups[]` (visual-plan) each tile the whole
track; every group's `section_id` names an existing section; a section's groups tile its
`span_sec`.
- The same object validates whether it came from the Music Reader (a section), the Director
(a group), or a template example.
@@ -1,156 +0,0 @@
# Template definition — what a Group Template IS
A Group Template is a reverse-engineered, reusable archetype for **one whole group** of
a BGM track. It lives at `templates/<id>/` and has three parts:
```
templates/<id>/
card.json ← the spec: match-face + build-face (this doc)
index.html ← the reference implementation (parameterized, asset-free)
README.md ← human notes + provenance + the source frames
```
A card has **two faces**:
- **match-face** — small, structured, in `GroupSignature` vocab. The Director reads it
to decide _does this template fit this group?_ Keep it concise (decision: simple).
- **build-face** — richer. Tells the Builder _how to realize it_: roles, fillable
params, the reference impl, the primitives used, the exit transition.
## `card.json` schema
```jsonc
{
// ── identity ──
"id": "held-message-living-field",
"name": "Held Message / Living Field",
"one_line": "A readable mark held dead still over a soft, color-shifting blurred field.",
"status": "draft", // draft (in reverse workspace) → promoted (in catalog)
// ── MATCH FACE (GroupSignature predicates — see signature-schema.md) ──
"match": {
"structural_type": "sustained_hold",
"requires": {
// predicates over a group's GroupSignature
"energy_level": ">=MEDIUM",
"density": "sparse",
"onset_gap_bars": ">=1.5",
"has_steady_grid": true,
},
"mood_fit": ["warm", "dark", "elegant", "cinematic"],
"span_bars": [2, 8], // typical extent
"exit_trigger": ["first_onset_reentry", "hard_stop"],
},
// examples = real reversed groups this template was mined from. Auto-filled from each
// sample's audiomap. More examples → more trustworthy `requires` thresholds.
"examples": [
{
"sample": "bgm_test_2",
"group": "g1",
"bpm": 129.2,
"energy": 0.8,
"density": "sparse",
"onset_gap_bars": 2.05,
"span_sec": [0.0, 4.017],
},
],
// ── BUILD FACE ──
"roles": {
"message": {
"kind": "message",
"motion": "freeze_after_reveal", // reveal on entry, then dead still
"anchor": "entry.downbeat",
"notes": "readable ≥ whole span; no per-element motion (there are no onsets)",
},
"field": {
"kind": "background",
"motion": "energy_envelope_breath", // brightness/chroma track the energy envelope
"anchor": "energy",
"notes": "the ONLY thing moving; peaks at the SURGE; settles dark for the hold",
},
// optional: "camera", "asset", "overlay"
},
"params": {
// fillable slots = composition-variables in index.html
"text": { "type": "string", "maps_to": "message.content" },
"palette": { "type": "object", "keys": ["bg", "colorLow", "colorMid", "colorHigh", "accent"] },
"flowSpeed": { "type": "number", "default": 1 },
"duration": { "type": "number", "from": "group.span_sec length" },
},
"reference_impl": "index.html",
"uses_primitives": ["blur_resolve", "negative_space_hold", "chromatic_pressure"],
// group→group exit. Default fast_cut for everything now (decision #4); the observed
// transition is recorded for later.
"transition_out": { "default": "fast_cut", "observed": "anticipation_glitch_cut" },
// ── provenance ──
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_1"],
"created": "fill at promotion time", // scripts can't call Date.now(); stamp by hand
}
```
### Required fields
`id`, `name`, `one_line`, `status`, `match` (`structural_type` + `requires` +
`mood_fit` + `exit_trigger`), `examples[]` (≥1), `roles` (≥1), `params`,
`reference_impl`, `transition_out`, `reversed_from`.
## Rules for each face
**match-face — keep it minimal.**
- `requires` predicates use simple operators: `">=X"`, `"<=X"`, `"==X"`, a literal, or a
list (any-of). Only constrain fields that actually distinguish this template.
- Don't encode creative taste here — that's the build-face. The match-face answers one
question: _does this group's signature fit?_
**build-face — whole-group, roles declared separately (decisions #1, #2).**
- One template covers the whole group (background + text together), but every moving
thing is its own `role` with its own `motion` + `anchor`, so roles can be factored
into composable role-templates later without rewriting cards.
- Each `role.motion` is a verb from the signature schema; each verb resolves to an L0
primitive id listed in `uses_primitives` (or a custom phrase the Builder can implement).
- `params` are exactly the composition-variables the reference impl exposes (so the
Builder fills them by passing `--variables`, no code edit needed for content/palette).
## Reference implementation (`index.html`)
- A HyperFrames composition (one paused GSAP timeline, deterministic, asset-free, passes
`lint` + `validate`).
- Exposes `params` as `data-composition-variables` (text + palette + speed + duration).
- A template may **bundle local assets** under `assets/` when its look genuinely needs
them (e.g. `held-text-strobe-burst` ships texture-mask PNGs + a local `gsap.min.js`).
Local bundled assets are allowed; remote assets / remote fonts are not.
## Extension fields (allowed beyond the required set)
Cards may carry extra fields when a template needs them. Promoted examples use:
- `beat_map` — script-side musical timing constants the impl reads (onset / roll seconds,
font / flip steps). Content lives in `params`; musical _timing_ lives here.
- `bundled_assets` — a note on what the impl ships under `assets/`.
- `base_template` / `operations` / `engine` / `program_format` / `program_data` —
**meta-templates**: one base look + a data-driven _program_ of beat-synced operations
(e.g. `poster-tile-mosaic`). The `program` param is the compose-by-data surface; the
operator code is fixed. Such a card may omit the standard `roles` motion-verbs.
- `provenance` — the source video / audiomap / video-read the template was reversed from.
- `examples[]` entries may carry extra audio facts (`roll`, `bursts_sec`,
`downbeats_sec`, …) beyond the required signature fields.
## Status lifecycle
`draft` (produced in the reverse workspace) → reviewed → `promoted` (copied into
`templates/<id>/`, added to the catalog). The Director only matches `promoted` cards.
## Worked example
The catalog ships five promoted templates (`held-message-living-field`,
`typewriter-phrase-keyword-shuffle`, `roll-flipbook-word-cycle`,
`held-text-strobe-burst`, `poster-tile-mosaic`) — each a real reversed group. Read any
`templates/<id>/card.json` for a filled-in reference.
@@ -1,54 +0,0 @@
# Transition Catalog (group → group)
Transitions between groups are L1 patterns, just like Group Templates. This catalog is
the interface; the Director picks a transition for each group boundary.
> **Decision #4: keep the interface, default EVERYTHING to `fast_cut` for now.** The
> reverse pipeline still _records_ the real observed transition on each template
> (`transition_out.observed`) so we can activate richer ones later — but the Director
> emits `fast_cut` for every boundary until we say otherwise.
## Entry schema
```jsonc
{
"id": "fast_cut",
"one_line": "Instant hard cut on the boundary downbeat. 0ms.",
"anchor": "boundary.downbeat", // which audio moment it lands on
"duration_ms": 0,
"mechanism": "tl.set(): kill group A, show group B on the same frame — no tween.",
"uses_primitives": ["hard_cut"], // L0 ids (bgm-motion-vocabulary.md)
"status": "active", // active | recorded (known but not yet emitted)
}
```
## Active
### `fast_cut` — DEFAULT for all boundaries
- **Anchor:** the boundary downbeat (the group's `exit_trigger.time`, snapped).
- **Mechanism:** 0ms `tl.set()` — hide group A, reveal group B on the same frame. No
crossfade, no tween. The cut _is_ the transition.
- **Why default:** zero-asset, never wrong, reads as decisive editing; lets us ship the
template pipeline before investing in bespoke transitions.
- **Primitives:** `hard_cut`.
## Recorded (known from reverses, NOT emitted yet)
These come out of the reverse pipeline as `transition_out.observed`. Kept here as the
backlog to activate once fast_cut-everything is working.
### `anticipation_glitch_cut` _(observed: group_1 → group_2)_
- A few-frame chromatic/noise glitch on the **pre-beat** (the onset just before the
boundary downbeat), impact landing on the downbeat. A "spring" that amplifies the
next group's entrance. Primitives: `chromatic_pressure` + `hard_cut`.
- Status: `recorded`. To activate: add `"status":"active"` and let the Director choose
it when a boundary's `exit_trigger.type == "first_onset_reentry"`.
## How the Director uses it (target)
For each adjacent group pair, set `transitions[]` entry `{ from, to, transition:
"fast_cut", at: boundary_time }`. Until further notice, `transition` is always
`fast_cut`. A template's `transition_out.observed` is metadata for the future, not an
instruction.
@@ -1,158 +0,0 @@
# Visual Plan Contract (template-driven)
The Director writes `visual-plan.json`. It is a build spec, not code. Unlike the
scene-based plan, this one is **group-driven**: the Director **creates the groups** by
subdividing each `music-read.json` section at its `cut_candidates` (catalog-aware — see
director.md), then writes one entry per group, each either bound to a **promoted Group
Template** or **free-composed**, plus the group→group transitions.
## Output shape
```jsonc
{
"compositionId": "bgm",
"duration_s": 7.198, // == audiomap.audio.duration_sec, exactly
"canvas": { "w": 1920, "h": 1080, "fps": 30 },
// ── brand spine: ONE identity across all groups, so different templates still read
// as one piece. The Director sets this from the brief's mood. ──
"style": {
"name": "warm cinematic recap",
"mood": "warm / cinematic",
"palette": ["#040406", "#100a2e", "#d23b5e", "#ffd9c2", "#ffb27a"],
"font": "system-safe stack or local @font-face",
"texture": "grain / light-leak",
},
// echoed from music-read.json (the source sections + cut_candidates the Director split).
// Groups that share a section may use DIFFERENT templates — no reuse rule; the brand
// spine unifies them.
"sections": [
{
"id": "s1",
"span_sec": [0.0, 7.198],
"structural_type": "sustained_hold",
"mood": ["warm", "cinematic"],
},
],
"groups": [
{
"id": "g1",
"section_id": "s1", // the section this group was cut from
"span_sec": [0.0, 4.017], // Director-chosen: between cut_candidates (or the whole section), reconciled to the stop rule
"structural_type": "sustained_hold",
"mood": ["warm", "cinematic"],
"templateRef": "held-message-living-field", // a promoted template id, or null
// params = the template's composition-variables, filled. Keys MUST match the
// template card's `params`. (Omitted when templateRef is null.)
"params": {
"kickerText": "PREVIOUSLY ON",
"heroText": "DUCKLIFE",
"palette": {
"bgColor": "#040406",
"colorLow": "#100a2e",
"colorMid": "#d23b5e",
"colorHigh": "#ffd9c2",
"accentColor": "#ffb27a",
},
"flowSpeed": 1,
"duration": 4.017,
},
// bind each template role to this group's real anchors (absolute audio seconds)
"role_bindings": {
"message": { "reveal_at": 0.093, "motion": "freeze_after_reveal" },
"field": { "drive": "energy_envelope", "surge_at": 1.0 },
},
// when templateRef is null, describe the free composition instead (uses L0):
"free_design": null,
// e.g. { "dominant_system": "per-onset typography", "layout": "...",
// "primitives": ["content_swap","scale_punch"], "density_topology": "accumulate" }
},
],
"transitions": [
{ "from": "g1", "to": "g2", "transition": "fast_cut", "at": 4.017 }, // default fast_cut
],
// the Director owns the words (see Copy rules). Texture vs message decided per item.
"copy": {
"headline": "DUCKLIFE",
"kickers": ["PREVIOUSLY ON"],
"taglineWords": [],
"keywords": [],
"ctaWords": [],
"logo": null,
},
"build_notes": ["one paused GSAP timeline", "no remote assets", "grain over every group"],
"avoid": ["generic slideshow", "tiny unreadable hero text"],
}
```
Required fields: `compositionId`, `duration_s`, `canvas`, `style`, `groups[]`,
`transitions[]`, `copy`, `build_notes[]`. Echo `sections[]` from music-read for
traceability; each group carries its `section_id`.
## Group rules
- **The Director creates groups by subdividing sections** (director.md): each group's
`span_sec` runs between chosen `cut_candidates` (or is the whole section), then is
**reconciled** to the chosen template's stop rule (snap to the nearest AudioMap anchor —
decision #2). Groups are in audio order; adjacent `span_sec` tile the timeline with no
gaps/overlaps; the last ends at `duration_s`; no group is < ~1 bar.
- **Each group carries its `section_id`** (the section it was cut from). Groups that share a
section may use **different templates** — match each independently; cohesion comes from
the brand spine, not template reuse.
- **Every group is either `templateRef` (a promoted id) or `free_design`** — never both,
never neither.
- **`params` keys must match the referenced card's `params`** exactly, so the Builder can
pass them straight to the reference impl's composition-variables.
- **`role_bindings` use real anchor seconds** from this group's slice of the AudioMap, not
the template's example times.
## Matching (how the Director picks a template — see template-definition.md)
For each group: keep promoted cards where `card.match.structural_type == group.structural_type`
**and** the group's `GroupSignature` satisfies every `card.match.requires` predicate
**and** `mood` overlaps `card.match.mood_fit`. Rank survivors by signature closeness /
example count; take the top. If none survive → `templateRef:null` + `free_design`
(compose from `motion-primitives.md`, one thesis for the group).
## Transitions
One entry per adjacent pair. **`transition` is always `"fast_cut"` for now**
(decision #4) — a 0ms hard cut at `at` (the boundary, = the earlier group's
`exit_trigger` time, snapped). The catalog interface allows richer transitions later; do
not emit them yet.
## Copy rules (Director owns the words)
- Keep any exact words the user supplied; otherwise invent with taste, on the brief's mood.
- **Message vs texture:** a word that must be read holds ≥1 beat, stable and focal; a word
held <1 beat is texture (strobe/ticks). Never force a message onto a sub-beat.
- Copy fills template `params` (or, for free groups, rides the group's anchors). Do not
hand-place every word's millisecond — declare the anchor + accumulate/stagger intent and
leave micro-timing to the Builder.
## Brand spine
One type family, a ≤4–6 swatch palette, ≤2 accents per frame, applied across every group.
Different templates per group are fine — the spine is what unifies them.
## Self-check
- `duration_s == audiomap.audio.duration_sec`; groups tile it exactly; no group < ~1 bar;
no group boundary lands inside a `rolls[]` run.
- Each group carries a `section_id` present in `sections[]`; its `span_sec` came from that
section's `cut_candidates` (or is the whole section); groups in one section may use
different templates.
- Every group resolves to a promoted `templateRef` **or** a `free_design`.
- Every `templateRef` exists under `templates/` and its `match.requires` is satisfied by
the group's signature.
- `params` keys == the card's `params`; `role_bindings` use real AudioMap seconds.
- One `transitions[]` entry per boundary, all `fast_cut`.
@@ -1,128 +0,0 @@
# Card Flyby · accelerating 3D deck cascade — `card-flyby`
A depth column of **N cards** rolls **forward** through perspective. On each landing
beat the next card **tumbles up into the front slot** and **wipes in** its solid colored
face (angled clip-path), the previous front card **tumbles forward + falls toward the
camera** on exit, and the cards behind **advance one slot**. Dwells **shrink card-to-card**,
so the deck reads as an **accelerating rush** into a **held final card**.
> **Origin — sandbox, not a golden-sample reverse.** Unlike the other catalog templates,
> this one was authored from the **`card-flyby` sandbox** composition (a Shader-Deck-style
> flyby), so there is **no source `audiomap.json` / Gemini read**. The match-face is a
> **hypothesis** about which music the look fits, and `card.json → examples[].synthetic`
> flags its cadence as design-intent. The first time this template is matched to a real
> reversed group, add that group as a real `examples[]` entry and tighten `requires`.
## Files
```
card-flyby/
card.json ← the spec (match-face + build-face) · status: promoted
index.html ← reference impl (parameterized GSAP; data-driven deck)
program.json ← the default 6-card deck + landing schedule (standalone, editable)
assets/gsap.min.js ← bundled GSAP (offline-safe)
renders/recreate.mp4 ← rendered proof @30fps (the default deck)
```
No fonts are bundled — the look uses a system grotesque stack (`"Inter", "Helvetica
Neue", Arial`). The original sandbox pulled Inter from Google Fonts + GSAP from a CDN
and used a grab-bag of clashing per-card hexes; this promoted impl **drops the remote
deps** (offline), makes the formerly-hardcoded deck **data-driven**, and replaces the
ad-hoc colors with a cohesive **`theme` palette system**.
## How it moves
The scene carries a **static yaw** (side tilt); the cards' own **`rotateX`** drives the
tumble. Depth comes from **perspective (Z translation)** plus aggressive `rotateX` on the
cards behind — the rear card lies almost flat (~84°), each step closer rotates more
upright, the front card is level (0°) and face-on. On exit a card continues _past_
upright into a face-down tumble (`rotX → -88°`) while dropping down + toward the lens.
| slot | role | rotX | what it is |
| --------- | ------- | ------- | ------------------------------------------------------- |
| `far` | back | 84° | a card just entered the column (invisible, opacity 0) |
| `s3`→`s1` | depth | 66°→22° | the rolling-forward column (opacity ramps in) |
| `s0` | front | 0° | upright, face-on — **wipes in its solid face here** |
| `exit` | leaving | −88° | tumbles forward + falls down + toward camera, fades out |
A card's pose is a pure function of how many slots it sits **behind the current front
card** (`poseForRel(rel)`), so the column stays correctly depth-sorted and **any card
count just works** (z-index is set instantly at each swap — CSS can't depth-sort
non-intersecting planes). The default deck is 6 cards over 6.0s.
## Timing (`beat_map` in `card.json` / `landings`)
Content lives in `cards`; musical **timing** lives in `landings` — **one beat per card**,
absolute audio seconds. The default schedule `[0.40, 1.70, 2.70, 3.45, 4.00, 4.40]`
**accelerates** (gaps `1.30 → 1.00 → 0.75 → 0.55 → 0.40`); the final card lands early
enough to hold ~1.6s before the cut. Each landing tween **leads its beat** by its own
duration (`dur_i = clamp(0.32 · gap_into_i, 0.12, 0.42)`) so the card arrives _on_ the
hit; the face wipe runs over the last ~85% of that window.
Omit `landings` and an accelerating schedule is **auto-derived** from the card count +
duration (geometric ~0.78× gap decay) — so a 3- or 9-card deck cascades correctly with
no hand timing.
## Themes (the look knob)
`theme` picks a **cohesive palette** — one temperature/saturation family, so any card
count reads as a _designed_ set (the deck cycles the ramp in order; each face also gets a
gentle top→bottom tonal gradient for depth). White-on-card stays AA at the card type
sizes. Set `theme` and you have a whole new look in one knob.
| `theme` | family |
| -------------------- | --------------------------------------------------------------------- |
| `aurora` _(default)_ | cool jewel arc — teal → ocean → indigo → violet → plum, on blue-black |
| `ember` | warm sunset arc — wine → brick → rust → amber → ochre → bronze |
| `mono` | sleek monochrome blue staircase (dark → mid) |
| `slate` | muted cool slate-grays — understated / editorial |
Add a palette by appending to the `THEMES` table in `index.html` (`bg` + `ink` + a
`colors[]` ramp).
## Parameters (swap freely)
- `theme` — palette preset: `aurora` | `ember` | `mono` | `slate` (default `aurora`).
- `bgColor` — override the radial field base. Empty → the theme's bg.
- `cards` — **JSON array** of `{ title, color? }`; `title` is the big centered hero (the
only copy on each card). Its length sets the deck depth. `color` is **optional** — omit
it and the card takes the next color from the theme ramp (cohesive by default); set it
to override one card. Empty → the built-in 6-card demo deck. (See `program.json`.)
- `landings` — **JSON array** of land beats (abs seconds), one per card. Empty → derived.
- `yaw` — static scene side-tilt in degrees (default `−12`; `0` = face-on).
Fill them with `--variables` (read inside the comp via `window.__hyperframes.getVariables()`):
```bash
npx hyperframes render card-flyby -f 30 --strict-variables \
--variables '{"theme":"ember","cards":"[{\"title\":\"BLACKOUT\"},{\"title\":\"THE HEIST\"}]","yaw":-8}'
```
## Match (when the Director should reach for it)
`structural_type: per_onset_sequential` — a **stream of discrete onsets that
accelerate** (a build into a downbeat) where you want to flash a **sequence of whole
cards** (titles / projects / posters / video tiles), one per hit, climaxing on a held
card. Discriminated from the typewriter / logo-sting `per_onset_sequential` templates by
revealing **whole cards** (not letters/words of one message) and by the **accelerating
cadence**. Put the card you want held longest on the strongest final hit. If the grid
goes quiet (`onset_gap_bars ≥ ~1.5`) this is the wrong template — use a hold template.
> Candidate finer `structural_type`: an `accel-roll` flavor of `roll_cascade` (the
> shrinking-dwell build) — flagged in `card.json` for catalog review, not yet a vocab
> value. Proposed motion verbs `deck_advance` / `wipe_reveal` / `tumble_fall` are
> likewise flagged.
## Verify
```bash
npx hyperframes lint card-flyby # clean (1 inherent window.__timelines note)
npx hyperframes validate card-flyby # no console errors · text passes WCAG AA
npx hyperframes render card-flyby -f 30
```
## Status
`promoted` — in the catalog, matchable by the Director. Because it is sandbox-origin (no
golden-sample provenance), the next reviewer pass should attach a **real reversed group**
as an `examples[]` entry and tighten `match.requires` against it.
@@ -1,158 +0,0 @@
{
"id": "card-flyby",
"name": "Card Flyby · accelerating 3D deck cascade",
"one_line": "A depth column of N cards rolls forward through perspective: on each landing beat the next card tumbles up into the front slot and WIPES in its solid colored face (angled clip-path), the previous front card tumbles forward + falls toward the camera on exit, and the cards behind advance one slot — dwells shrink card-to-card so the deck reads as an accelerating rush into a held final card.",
"status": "promoted",
"created": "2026-06-17",
"base_template": {
"primitive": "depth_card_column",
"notes": "A 3D deck of N cards stacked in a perspective depth column (slots s0=front … s3 + far=back, plus an exit pose). Each card is a CSS wireframe (always present, opacity tracks its slot) over a solid face — a gentle top→bottom tonal gradient (--c1/--c2) — revealed by an angled clip-path wipe (--wipe 0→1). The scene carries a static yaw; the cards' own rotateX drives the tumble. N is DATA (the `cards` array) — the slot engine is rel-based (a card's pose is a pure function of how many slots it sits behind the current front card), so 3 / 6 / 9 cards all 'just work'. COLOR is a `theme` (a cohesive palette ramp cycled across the deck), per-card overridable. Asset-free: wireframe + solid cards + system type, bundled GSAP."
},
"themes": {
"_": "Cohesive palette presets (the `theme` param). Each is ONE temperature/saturation family so any card count reads as a designed set — the deck cycles the ramp in order. White-on-card stays AA at the card type sizes. Per-card `color` still overrides.",
"aurora": "cool jewel arc — teal → ocean → indigo → violet → plum, on blue-black (DEFAULT)",
"ember": "warm sunset arc — wine → brick → rust → amber → ochre → bronze, on warm near-black",
"mono": "sleek monochrome blue staircase (dark → mid), on blue-black",
"slate": "muted cool slate-grays — understated / editorial, on cool charcoal"
},
"match": {
"structural_type": "per_onset_sequential",
"requires": {
"energy_level": ">=MEDIUM",
"has_steady_grid": true,
"density": ["medium", "dense"],
"onset_gap_bars": "<1.0"
},
"mood_fit": ["hype", "bold", "elegant", "cinematic", "playful"],
"span_bars": [2, 6],
"exit_trigger": ["surge", "downbeat", "hard_stop", "end"],
"notes": "Reach for this when a section has a STREAM of discrete onsets that ACCELERATE (gaps shrinking / a build into a downbeat) and you want to flash a SEQUENCE of items — a deck of titles, projects, posters, video tiles — one per hit, climaxing on a held card. Each card lands on one onset (per_onset_sequential), so it shares the structural_type with the typewriter / logo-sting templates; it is discriminated by being a SEQUENCE OF WHOLE CARDS (not letters/words of one message) and by the accelerating cadence. The strongest hit (final downbeat / surge) should carry the card you want held longest. Candidate finer type: an `accel-roll` flavor of `roll_cascade` (the shrinking-dwell build) — flagged for catalog review, not yet a vocab value. If the grid goes quiet (onset_gap_bars >= ~1.5) this is the wrong template — use a hold template."
},
"examples": [
{
"sample": "sandbox",
"group": "card-flyby-sandbox",
"synthetic": true,
"structural_type": "per_onset_sequential",
"energy_level": "HIGH",
"density": "dense",
"cards": 6,
"span_sec": [0.0, 6.0],
"landings_sec": [0.4, 1.7, 2.7, 3.45, 4.0, 4.4],
"landing_gaps_sec": [1.3, 1.0, 0.75, 0.55, 0.4],
"cadence": "accelerating (gaps shrink ~0.78× each card); final card holds ~1.6s",
"exit_trigger": { "type": "end", "time": 6.0 },
"note": "NOT reversed from a golden sample. This template was authored from the `card-flyby` SANDBOX composition (a Shader-Deck-style flyby), so these audio facts are the DESIGN-INTENT cadence (the hand-tuned landing schedule), not values derived from an `audiomap.json`. When this template is matched to a real group, `landings` is bound from that group's onset times (one per card) and the schedule re-derives — see beat_map."
}
],
"roles": {
"deck_card": {
"kind": "asset",
"motion": "deck_advance",
"anchor": "landings[]",
"notes": "Each of the N cards. On every landing beat the whole column advances one slot toward the front (far→s3→s2→s1→s0). A card's pose is a pure function of its slot-distance behind the front card (rel), so the deck stays correctly depth-sorted for any N. PROPOSED verb 'deck_advance' (per-onset one-slot forward roll of a stacked depth column; ~content_swap promoted to a 3D column)."
},
"front_face": {
"kind": "message",
"motion": "wipe_reveal",
"anchor": "landings[] + ~15% lead",
"notes": "As the landing card rolls into s0 (upright, rotX 0), its SOLID colored face — a big CENTERED hero title + a small play glyph — is revealed by an angled clip-path wipe sweeping upper-left→lower-right (--wipe 0→1, ~0.72° diagonal). The title is the only copy on the face (no eyebrow tag / no meta footer). ~05-mask_reveal."
},
"exit_card": {
"kind": "asset",
"motion": "tumble_fall",
"anchor": "landings[] (the OUTGOING front card)",
"notes": "When a new card lands, the previous front card continues FORWARD past upright into a face-down tumble (rotX → -88°) while dropping DOWN and toward the camera (y +620, z +420, scale 1.10) and fading out. PROPOSED verb 'tumble_fall' (forward over-rotate + fall toward lens). Reverse of the incoming roll."
},
"field": {
"kind": "background",
"motion": "hold",
"anchor": "none",
"notes": "A static radial-gradient field behind the deck (default near-black #06070d). Dead still the whole span; the only motion is the deck. negative_space_hold."
}
},
"params": {
"theme": {
"type": "string",
"maps_to": "palette (see themes)",
"default": "aurora",
"notes": "Palette preset: aurora | ember | mono | slate. Sets the field bg + the cohesive card-color ramp the deck cycles + the ink. The fastest knob for a whole new look."
},
"bgColor": {
"type": "color",
"maps_to": "field.color (radial gradient base)",
"default": "",
"notes": "Override the field background. Empty = the theme's bg. The radial centre/edge are derived from it."
},
"cards": {
"type": "string",
"maps_to": "deck (engine.cards)",
"default": "",
"notes": "JSON array of card objects { title, color? }. `title` is the big centered hero (the only required field). Its length sets N (the deck depth). `color` is OPTIONAL — omit it and the card takes the next color from the theme ramp (cohesive by default); set it to override one card. Empty = the built-in 6-card demo deck. THIS is the compose-by-data surface for content: add / drop / reorder cards — no code edit."
},
"landings": {
"type": "string",
"maps_to": "beat_map.landings (engine.landings)",
"default": "",
"notes": "JSON array of absolute audio seconds — ONE landing beat per card (length must equal `cards` length). Empty = an accelerating schedule auto-derived from the card count + duration. Bind these from the matched group's onset times so each card lands on a hit."
},
"yaw": {
"type": "number",
"maps_to": "scene.rotateY (deg)",
"default": -12,
"notes": "Static side-tilt of the whole deck. 0 = face-on; negative = scene rotated so the deck reads from the left."
}
},
"beat_map": {
"comment": "Musical TIMING lives here; content lives in `cards`. All times are ABSOLUTE audio seconds. One landing per card; per-card transition duration is derived from the gap into each landing (faster as the cadence accelerates).",
"landings": [0.4, 1.7, 2.7, 3.45, 4.0, 4.4],
"landings_notes": "one per card, in deck order. Bind from the matched group's onset times. The schedule should ACCELERATE (gaps shrinking) for the signature build; the final card lands early enough to HOLD a beat before the cut. If omitted at build time, an accelerating schedule is generated from card count + duration.",
"transition_dur_rule": "dur_i = clamp(0.32 * gap_into_i, 0.12, 0.42); each landing tween starts at landing - dur (leads the beat) so the card arrives ON the hit; the face wipe runs over the last ~85% of that window.",
"duration": 6.0,
"exit_note": "the final card rolls in and HOLDS front-and-center to the end (6.0s); the source then hard-cuts to the next group (fast_cut)."
},
"engine": {
"model": "data deck + rel-based slot column. The deck (`cards`) and the landing beats (`landings`) are DATA; the slot poses (s0..far + exit) and the per-landing orchestration are fixed code. `poseForRel(rel)` maps a card's slot-distance behind the current front card to a pose, so the column is always correctly depth-sorted and any N works. z-index is set instantly at each swap (CSS can't depth-sort non-intersecting planes). Compose by editing the `cards` / `landings` DATA — never the slot/orchestration code.",
"compose_by": ["theme", "cards", "landings", "yaw", "bgColor"],
"extend": "recolor the whole deck via `theme` (cohesive ramp) or one card via its `color`; more cards = more `cards` entries (+ matching `landings`); change the read angle via `yaw`. Add a palette = add an entry to the THEMES table (bg + ink + a colors[] ramp). To change the deck LOOK (slot depths, card size, wipe angle) edit the SLOT table / CSS, not the program."
},
"program_format": {
"_": "`cards` is a JSON array of card objects; `landings` is a JSON array of absolute audio seconds, one per card (same length as `cards`).",
"card": {
"title": "string — the big CENTERED hero title (the only copy on the face)",
"color": "string? — OPTIONAL solid face color (CSS color). Omit = next color from the theme ramp."
},
"landings": "number[] — abs seconds, one landing beat per card, in deck order (accelerating cadence recommended)"
},
"reference_impl": "index.html",
"program_data": "program.json (the default 6-card deck + landing schedule as standalone, agent-editable data)",
"uses_primitives": [
"18-3d_card_flip",
"05-mask_reveal",
"09-dolly_zoom",
"content_swap",
"negative_space_hold"
],
"uses_primitives_notes": "deck_advance / wipe_reveal / tumble_fall are PROPOSED custom phrases the impl defines (a per-onset one-slot forward roll of a stacked 3D depth column; an angled clip-path face reveal; a forward over-rotate + fall toward the lens). 18-3d_card_flip (#18) backs the 3D card transforms; 05-mask_reveal (#05) backs the angled clip-path wipe; 09-dolly_zoom (#09) is the perspective/depth feel; content_swap is the per-onset advance generalized to a depth column; negative_space_hold backs the static field.",
"bundled_assets": "assets/gsap.min.js (offline GSAP). No fonts bundled — uses a system grotesque stack ('Inter', 'Helvetica Neue', Arial). No remote assets.",
"transition_out": { "default": "fast_cut", "observed": "fast_cut" },
"reversed_from": [],
"origin": "sandbox",
"provenance": {
"source": "bgm-golden-sample-reverse/gorup-by-group/card-flyby (Shader-Deck-style horizontal card-flyby SANDBOX)",
"note": "Hand-authored design study, NOT reverse-engineered from a golden-sample group — there is no source audiomap / Gemini read. The match-face is therefore a HYPOTHESIS (which music this look fits), not a measured signature; `examples[].synthetic = true` flags the cadence as design-intent. The original sandbox is asset-free but used remote Google-Fonts Inter + a CDN GSAP AND a grab-bag of clashing per-card hexes; this promoted impl drops the remote deps (system fonts + bundled GSAP), makes the deck data-driven (`cards` / `landings`), and replaces the ad-hoc colors with a cohesive `theme` palette system (per-card color optional). Promote-time review should add a REAL example (and tighten `requires`) the first time this template is matched to an actual reversed group."
}
}
@@ -1,51 +0,0 @@
# Held Message / Living Field
The first promoted Group Template. Reverse-engineered from **group_1** of the golden
sample `bgm_test_2` (the "PREVIOUSLY ON / DUCKLIFE" recap card). Chinese name the user
uses: 静止文字 · 活背景.
In `visual-plan-contract.md` / motion terms it is the **macro-stable + micro-volatile
hold**: the message is frozen, the blurred field carries all the motion.
## When the Director picks it (match-face)
A group whose `GroupSignature` is **heavy-but-sparse with an onset desert**:
`energy_level >= MEDIUM`, `density == sparse`, `onset_gap_bars >= 1.5`, steady grid.
Mood fit: warm / dark / elegant / cinematic. See `card.json`.
The hold ends at the **first onset re-entry** (or a hard stop), snapped to the next
downbeat — that is both the group boundary and the template's stop rule.
## What it renders (build-face)
- **message** (text) — `freeze_after_reveal`: a held title block (mark + title +
tagline). Reveal (blur+scale settle, brief per-letter entrance) then dead still for the
whole span. Three slots: `markText` (big) + `titleText` + `tagText`.
- **field** (background) — `energy_envelope_breath`: a real-time WebGL flow field
(fbm + curl noise). Colorful chromatic light-leak at entry, breathes up on the SURGE,
then settles dark with a central glow for the hold.
## Files
- `card.json` — the spec (match-face + build-face).
- `index.html` — the **generic `webgl-textures-playground`** reference implementation
(asset-free, CDN three.js + GSAP, one paused timeline; passes lint + validate).
Composition-variables == the card's `params`: `markText`, `titleText`, `tagText`,
`bgColor/colorLow/colorMid/colorHigh/accentColor`, `flowSpeed`. The group_1 DUCKLIFE
recap (kicker + hero, the warm light-leak settle) is one parameterization of this engine.
## Params → recolor / re-text
```bash
npx hyperframes render --variables '{
"markText":"DUCKLIFE","titleText":"PREVIOUSLY ON","tagText":"",
"colorLow":"#100a2e","colorMid":"#d23b5e","colorHigh":"#ffd9c2","accentColor":"#ffb27a"
}'
```
## Provenance
Reversed via `skills/bgm-golden_sample_reverse/reverse-to-template.md` from
`bgm-golden-sample-reverse/gorup-by-group/group_1` (audiomap + Gemini analysis). The
reference impl here is the generic `group_1/webgl-textures-playground` (the user's chosen
canonical impl); the DUCKLIFE-specific `recreate-webgl` was an earlier parameterization.
@@ -1,66 +0,0 @@
{
"id": "held-message-living-field",
"name": "Held Message / Living Field",
"one_line": "A readable mark held dead still over a soft, color-shifting blurred field.",
"status": "promoted",
"created": "2026-06-17",
"match": {
"structural_type": "sustained_hold",
"requires": {
"energy_level": ">=MEDIUM",
"density": "sparse",
"onset_gap_bars": ">=1.5",
"has_steady_grid": true
},
"mood_fit": ["warm", "dark", "elegant", "cinematic"],
"span_bars": [2, 8],
"exit_trigger": ["first_onset_reentry", "hard_stop"]
},
"examples": [
{
"sample": "bgm_test_2",
"group": "g1",
"bpm": 129.2,
"energy": 0.8,
"density": "sparse",
"onset_gap_bars": 2.05,
"span_sec": [0.0, 4.017]
}
],
"roles": {
"message": {
"kind": "message",
"motion": "freeze_after_reveal",
"anchor": "entry.downbeat",
"notes": "a held title block (mark + title + tagline); reveal (blur+scale settle, brief per-letter entrance) then dead still for the whole span — no ongoing motion, there are no onsets"
},
"field": {
"kind": "background",
"motion": "energy_envelope_breath",
"anchor": "energy",
"notes": "the only thing moving; colorful chromatic light-leak at entry, breathes up on the SURGE, then a black mask settles it to near-black with a central glow for the hold"
}
},
"params": {
"markText": { "type": "string", "maps_to": "message.mark", "default": "HF" },
"titleText": { "type": "string", "maps_to": "message.title", "default": "HYPERFRAMES" },
"tagText": { "type": "string", "maps_to": "message.tag", "default": "HTML · SHADERS · MP4" },
"palette": {
"type": "object",
"keys": ["bgColor", "colorLow", "colorMid", "colorHigh", "accentColor"]
},
"flowSpeed": { "type": "number", "default": 1 },
"duration": { "type": "number", "from": "group.span length" }
},
"reference_impl": "index.html (generic webgl-textures-playground; the group_1 DUCKLIFE recreate is one parameterization)",
"uses_primitives": ["blur_resolve", "negative_space_hold", "chromatic_pressure", "hard_cut"],
"transition_out": { "default": "fast_cut", "observed": "anticipation_glitch_cut" },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_1"]
}
@@ -1,168 +0,0 @@
# held-text-strobe-burst (group template)
A reusable HyperFrames template for the **Held Text / Strobe Burst** pattern: a word
held **dead still** in the center while its letterforms **flip through texture-filled
frames** every ~3 frames, in short bursts pinned to a drum roll / fill. The default
(and primary) look is the **Texture-Flip** technique — there is no shader and no video.
All state lives on one paused GSAP timeline → deterministic and seek-safe.
Reversed from `../gruop_4.mp4` (see `../gruop_4.bg-flicker.gemini-analysis.md`, burst 2 —
the "III" glyph whose interior style-transfers per beat). Sibling of **Held Message /
Living Field** (`webgl-textures-playground`): message holds, background carries the
motion — but here it _strobes_ in beat-quantized hits instead of breathing.
> Render at **24 fps** so the 0.125 s jumps land every 3 frames (the original cadence).
## The technique (Texture-Flip, foreground)
The word's letters are a **window**: `background-image: <solid-fill>, <texture-url>`
with `background-blend-mode: multiply`, clipped to the text (`background-clip: text`).
So each letter shows a **texture PNG tinted by a per-frame fill color**, over a solid
per-frame **background color**. N such frames are stacked as full-frame layers; the
strobe flips which one is visible (`tl.set(opacity)`, 0 ms — seek-safe). The texture
fills the whole letterform (`line-height ≥ 1` keeps the glyph inside the background-paint
box — with `line-height < 1` the cap tops/bottoms overflow it and leave untextured slivers).
A **persistent base** holds the word in a solid color on the idle (black) plate, so it
never disappears — it is the anchor. The **base-template default plan flickers
continuously across the whole clip and never stops**, so the idle base only shows if your
plan leaves gaps (e.g. the gruop_4 two-burst variant).
Three things change per beat: **texture** (material), **fill** (foreground tint),
**bg** (frame background). All snap to the strobe grid.
---
## What beat matches this template
The discriminator the Director uses — the **opposite** of a held pad (busy, not empty):
| Signature field | Strobe Burst wants | Why |
| ----------------- | ---------------------------------- | --------------------------------------------------------------- |
| `density` | **dense** | a strobe needs many hits to flip on |
| `energy_level` | **≥ MEDIUM** (≥ HIGH in the burst) | flat-out hits, not a breath |
| `onset_gap_bars` | **≤ ~0.5 bar** | no onset deserts — a hit every fraction of a beat |
| `has_rolls` | **true** | a `rolls[]` run (accel-roll → SURGE, or a fill) is the _engine_ |
| `has_steady_grid` | true | jumps must quantize to a stable grid |
| `exit_trigger` | `hard_stop` or `surge` | the burst cuts clean to black, then the next section enters |
| `span_bars` | 1–2 (each burst ~0.4–0.7 s) | a strobe that runs > 2–3 s tires the eye |
**Heuristic:** a high-hits/min roll inside a `dense` phase is a strobe-burst candidate.
Pin one burst per roll/fill; bound it by the `hard_stop` / `SURGE` that follows.
**gruop_4 facts that fired it** (from `../audiomap.json`):
- BPM 129; downbeat 1.254; grid 0.743 / 1.254 / 1.718 / 2.183.
- rolls: `0.09–0.79 accel-roll →SURGE`, `1.21–1.65 fill →DROP`, `1.93–3.00 accel-roll →SURGE`.
- `hard_stop` @ 2 s; SURGE@1 (+0.21), DROP@2 (−0.28), SURGE@3 (+0.78).
- Two bursts: **1.125–1.542 s** and **2.042–2.708 s**, jumps every 0.125 s.
- Burst 1 starts ~2 frames _before_ downbeat 1.254 (lead the anchor); burst 2 opens on
the 2 s `hard_stop` + 1.93 accel-roll, ends 1 frame before the 2.76 snare.
---
## How to change it
Everything is a **composition variable** — fill with `--variables` (no code edit).
### 1. The word (instant)
`markText` — the held word (always on screen; box never moves). `fontStyle`:
`display` (Impact, bold condensed caps) or `serif` (Georgia italic). `markScale`
(0.3–2) sizes it.
### 2. The texture frames — `frames` (the core content)
A JSON array of texture-flip frames, cycled by strobe-step index:
```jsonc
[
{ "texture": "tiles-138", "bg": "#ff70b0", "fill": "#f0a020", "ink": "#2a0f1d" },
{ "texture": "lava", "bg": "#101127", "fill": "#ff5a2c" },
{ "texture": "onyx", "bg": "#e8e2d6", "fill": "#3a3a44" },
// texture = file name (no .png) from assets/texture-mask-text/masks/ (66 available)
]
```
- **Replace the texture image** → change `texture` (66 masks bundled: `tiles-138`,
`lava`, `onyx`, `marble-016`, `wood-066`, `concrete`, `metal-041-a`, `bricks-075-a`,
`grass-005`, `snow-015`, …). List them: `ls assets/texture-mask-text/masks/ | sed 's/\.png$//'`.
- **Replace the foreground color** → change `fill` (multiplied INTO the texture inside
the letters: light fill = bright/clear glyph, dark = moody, `#ffffff` = texture's own
color). `ink` is optional (UI/decor color).
- **Replace the frame background** → change `bg` (solid color behind the word that beat).
- Empty `frames` → the built-in 7-frame texture-flip set.
`idleColor` / `idleInk` set the between-burst plate (default white word on black).
`decor: yes` adds the blueprint grid + crop border per frame.
### 3. Match the changes to the beat — `strobePlan` (the core timing knob)
A JSON array of bursts; the template fires a **0 ms flip** at every jump time, cycling
`frames` by a global step counter, and cuts back to the idle base at each `end` (unless
the burst runs to the composition end → no terminal black, so the default never stops).
**Default (base template): one continuous burst the whole clip** — flicker, no stops:
```jsonc
[{ "start": 0, "end": 3, "step": 0.125 }] // jump every 0.125 s, 0 → duration
```
**gruop_4-faithful variant** (two bursts pinned to the rolls, black gaps between):
```jsonc
[
{ "start": 1.125, "end": 1.542, "step": 0.125 }, // jump every 0.125 s
{
"start": 2.042,
"end": 2.708,
"jumps": [
2.042,
2.167, // OR list exact times
2.292,
2.417,
2.5,
2.625,
],
},
]
```
**Building `strobePlan` from an AudioMap:**
1. **Find the roll(s).** Each `rolls[]` entry (or dense onset cluster) → one burst.
2. **Burst start = lead the anchor.** Open ~40–190 ms _before_ the kick/downbeat that
launches the roll, so the first flip lands _on_ the hit (gruop_4 burst 1 leads 1.254
by ~85 ms → start 1.125).
3. **Jumps = the grid the roll plays.** A 449/min hi-hat roll ≈ every 0.125 s →
`step:0.125`. Irregular roll → list the actual `events[].t` as `jumps[]` so every
flip sits on a real onset.
4. **Burst end = the stop.** End on the `hard_stop` / last snare / `SURGE` snapped to the
next anchor; the template cuts to the held-word-on-black base there.
5. **Order `frames` for accents.** Put the highest-contrast texture/bg on the index that
lands on the downbeat/kick; a near-black `bg` frame reads as a 1–2 frame blink-off.
Rule of thumb (`motion-primitives.md`): hard hits are **0 ms** (all flips are `tl.set`,
never tweened) and a dense strobe runs **≤ 2–3 s** — keep bursts short, let the
`hard_stop` clear them.
---
## Files
- `index.html` — reference implementation (Texture-Flip default + beat-matched plan).
`lint`: 0 errors (2 cosmetic warnings — `invalid_composition_variables_declaration`,
shared with the base template; and `Impact` font, carried from texture-flip, Arial
fallback). `validate`: 0 errors (the 5 WCAG 1:1 warnings are intrinsic to
`background-clip:text` — the checker can't read texture-filled glyphs).
- `assets/` — `gsap.min.js` + `texture-mask-text/masks/*.png` (66), copied from
`../texture-flip` so the template is self-contained.
- `card.json` — draft template card. `meta.json` — name / dims / 24 fps / 3 s.
- `renders/proof.mp4` — proof render of the built-in config.
## Provenance
Reversed from `bgm-golden-sample-reverse/gorup-by-group/group_4` (`gruop_4.mp4`,
`audiomap.json`, `gruop_4.bg-flicker.gemini-analysis.md`). Texture-Flip technique +
assets from `group_4/texture-flip`. Timeline/overlay shape scaffolded on
`group_1/webgl-textures-playground`.
@@ -1,99 +0,0 @@
{
"id": "held-text-strobe-burst",
"name": "Held Text / Strobe Burst",
"one_line": "A dead-still word whose letters flip through texture-filled frames (texture-clipped fill + per-frame tint + bg color) every ~3 frames, in short bursts pinned to a roll.",
"status": "promoted",
"created": "2026-06-17",
"match": {
"structural_type": "dense_multiply",
"requires": {
"energy_level": ">=MEDIUM",
"density": "dense",
"onset_gap_bars": "<=0.5",
"has_steady_grid": true,
"has_roll": true
},
"mood_fit": ["hype", "glitch", "aggressive", "playful"],
"span_bars": [1, 2],
"exit_trigger": ["hard_stop", "surge"],
"notes": "Candidate dedicated structural_type `held_strobe` (held message + strobe field). Using `dense_multiply` (rubric: dense+HIGH → field/grid/strobe) until the type list grows."
},
"examples": [
{
"sample": "bgm_test_2",
"group": "g4",
"bpm": 129,
"energy": 0.5,
"density": "dense",
"onset_gap_bars": 0.23,
"span_sec": [0.0, 3.01],
"bursts_sec": [
[1.125, 1.542],
[2.042, 2.708]
],
"burst_drivers": "accel-roll 1.93-3.00 (→SURGE) + fill 1.21-1.65 (→DROP); jumps every ~0.125s (3f@24fps)"
}
],
"roles": {
"message": {
"kind": "message",
"motion": "hold",
"anchor": "entry.downbeat",
"notes": "the held anchor: word box locked (no x/y/scale), always on screen. Its FILL flips per strobe step — each letterform is a texture PNG (background-clip:text) × a multiply tint (the foreground 'color'). Between bursts it falls back to a solid idleInk word on idle plate. This is the Texture-Flip technique reversed from gruop_4 burst 2."
},
"field": {
"kind": "background",
"motion": "strobe",
"anchor": "roll",
"notes": "per-frame solid bg color behind the word, hard-set (0ms) on each roll-grid subdivision via a stacked opacity flip-book. Base-template default flickers continuously across the whole clip; cuts back to idleColor (clean black) only at a burst end that is < composition end (so multi-burst plans get black gaps, the continuous default never stops)."
}
},
"params": {
"markText": { "type": "string", "maps_to": "message.content", "default": "NAMSHI" },
"fontStyle": {
"type": "select",
"maps_to": "message.font",
"options": ["display", "serif"],
"default": "display"
},
"markScale": { "type": "number", "maps_to": "message.scale", "default": 1 },
"idleColor": { "type": "color", "maps_to": "field.idle_bg", "default": "#000000" },
"idleInk": { "type": "color", "maps_to": "message.idle_ink", "default": "#ffffff" },
"frames": {
"type": "string",
"maps_to": "strobe.frames",
"notes": "JSON [{texture,bg,fill,ink?,pos?}]; texture = file under assets/texture-mask-text/masks/ (66 available). Empty = built-in texture-flip set. Cycled by strobe-step index."
},
"strobePlan": {
"type": "string",
"maps_to": "field.plan",
"notes": "JSON array of bursts {start,end,step|jumps[]}; built from the audiomap. Empty = built-in CONTINUOUS plan [{start:0,end:duration,step:0.125}] (base-template default: flicker the whole clip, never stop). gruop_4-faithful two-burst look = [{start:1.125,end:1.542,step:0.125},{start:2.042,end:2.708,step:0.125}]."
},
"decor": {
"type": "select",
"options": ["no", "yes"],
"default": "no",
"notes": "blueprint grid + crop border per frame"
},
"duration": { "type": "number", "from": "group.span_sec length" }
},
"reference_impl": "index.html",
"bundled_assets": "assets/ (gsap.min.js + texture-mask-text/masks/*.png ×66), copied from ../texture-flip",
"uses_primitives": [
"content_swap",
"hard_cut",
"palette_flip",
"system_replace",
"negative_space_hold",
"flash_cut"
],
"transition_out": { "default": "fast_cut", "observed": "hard_cut_to_black" },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_4"]
}
@@ -1,96 +0,0 @@
# Intro Kinetic Cascade · editorial phrase cascade with icon climax — `intro-kinetic-cascade`
A spoken / anchored line laid out as a sequence of big **editorial phrases** — each a
stacked poster with one enlarged accent **hero word** — revealed **word-by-word** on its
anchors, **hard cut-out** between phrases, climaxing on a phrase that **slides in** with a
**swappable, ringing icon** (bell / cursor / sparkle / … or any emoji / SVG).
> **Origin — a VO launch-video intro, adapted for the catalog.** Internalized from
> `act0-intro-bell` (the voiceover intro of the Timeline-Editor launch video). Its reveal
> times are **transcript word onsets**, so in origin it is **narration-driven**, not a
> beat-reversed musical group — bind `phrases[].times` to audio onsets to use it
> beat-driven. The original's Lottie bell + Google-Fonts Inter/Playfair + CDN GSAP are
> dropped here for an **offline** build, and the bell is now a **swappable icon**.
## Files
```
intro-kinetic-cascade/
card.json ← the spec (match-face + build-face) · status: promoted
index.html ← reference impl (parameterized GSAP; data-driven phrases + icon)
program.json ← the default act0 phrases + climax (standalone, editable)
assets/gsap.min.js ← bundled GSAP (offline-safe)
renders/recreate.mp4 ← rendered proof @30fps (default light + bell)
```
No fonts bundled — system grotesque stack (`"Inter","Helvetica Neue",Arial`); the serif
hero falls back `Playfair Display → Georgia` (drop a Playfair woff2 + `@font-face` for the
exact source face). Icons are **inline SVG** (no Lottie). No remote assets.
## How it moves
Each **phrase** is a vertically-centered, left-aligned stack of lines — a small word, a
HUGE accent **hero word**, a closing line — with per-line `size` + `x` indent for the
editorial diagonal. Words **fade in one-by-one** on their anchors, the phrase holds, then
**hard cuts out**. The finale **climax** slides in from offscreen-right and **holds**,
carrying the ringing icon.
| stage | what | anchor |
| --------------- | -------------------------------------------------------------- | ------------------- |
| phrase reveal | words fade in within a held poster (hero line big + accent) | `phrases[].times[]` |
| cut-out | phrase opacity → 0 (hard) | `out − 0.10` |
| climax slide-in | finale lockup slides x 1400→0, holds to end | `climax.in` |
| icon ring | glyph pops (scale 0.4→1) + damped wiggle + two expanding rings | `climax.iconAt` |
## The icon knob (match it to the scene)
`icon` picks the ringing climax glyph. Built-in inline-SVG library:
`bell` (timing/alerts) · `cursor` (a click/UI) · `sparkle` (AI/magic) · `bolt` (speed) ·
`play` (video) · `check` (done) · `heart` (like) · `star` (featured)
…or pass an **emoji** (`"🔔"`, `"⚡️"`), a raw **`<svg>…</svg>`** string, or `"none"` for a
pure-text climax. The pop + ring emphasis is generic, so any glyph "rings". The `{icon}`
token in `climax.text` marks where it lands.
## Themes
`theme` = `light` (default — the act0 editorial look), `dark`, or `bold`. Each is an
AA-tuned palette (field bg + ink + a hero-accent ramp incl. a `"gradient"` sweep).
## Parameters (swap freely)
- `theme` — `light` | `dark` | `bold` (default `light`).
- `icon` — climax glyph: a library name, an emoji, a raw `<svg>`, or `none` (default `bell`).
- `phrases` — **JSON array** of `{ lines:[{text,size,x,hero?,accent?,font?}], out, times? }`.
`times` (per word, reading order) = the VO/onset anchors; omit → auto-spread across the
phrase. Empty → the built-in 3-phrase act0 intro.
- `climax` — **JSON object** `{ text, in, iconAt, hold, size }`; `text` embeds `{icon}`.
Empty → the built-in `timing is {icon} tricky.`
Fill with `--variables` (read via `window.__hyperframes.getVariables()`):
```bash
npx hyperframes render intro-kinetic-cascade -f 30 --strict-variables \
--variables '{"theme":"dark","icon":"sparkle","climax":"{\"text\":\"editing just got {icon} magic.\",\"in\":3.79,\"iconAt\":4.9,\"hold\":1.3,\"size\":150}"}'
```
## Aligning to a track (VO or beat)
- Precise sync: set each phrase's `times` to the word onset seconds (a transcript for VO,
or `audiomap` onsets for a beat). Put the key word of each phrase on the strongest hit;
land the climax icon on a downbeat / surge.
- Quick layout: drop `times` and the engine auto-spreads each phrase's words evenly.
## Verify
```bash
npx hyperframes lint intro-kinetic-cascade # clean
npx hyperframes validate intro-kinetic-cascade # no console errors · text passes WCAG AA
npx hyperframes render intro-kinetic-cascade -f 30
```
## Status
`promoted` — in the catalog, matchable by the Director. VO-origin: when first matched to a
real musical group, add that group as an `examples[]` entry and tighten `match.requires`.
@@ -1,164 +0,0 @@
{
"id": "intro-kinetic-cascade",
"name": "Intro Kinetic Cascade · editorial phrase cascade with icon climax",
"one_line": "A spoken/anchored line laid out as a sequence of big editorial PHRASES — each a stacked poster with one enlarged accent HERO word — revealed word-by-word on its anchors, hard cut-out between phrases, climaxing on a phrase that SLIDES in with a swappable, ringing ICON (bell / cursor / sparkle / … or any emoji / SVG).",
"status": "promoted",
"created": "2026-06-17",
"base_template": {
"primitive": "editorial_phrase_cascade",
"notes": "A narration/anchor-driven kinetic-typography intro. Each PHRASE is a vertically-centered, left-aligned stack of lines (small word / BIG accent hero word / closing words) with per-line size + indent for an editorial diagonal composition. Words reveal one-by-one on their anchors (VO word-times OR audio onsets), the phrase holds, then HARD cuts out before the next. The finale is a CLIMAX phrase that slides in from offscreen-right and HOLDS, carrying a swappable inline ICON that pops + rings. Phrase count, words-per-line, and the icon are all DATA, so any sentence + any scene icon 'just works'. Asset-free: system type, inline-SVG icon library, bundled GSAP."
},
"themes": {
"_": "Palette presets (the `theme` param). Accents are AA-tuned on each bg. ink = body/closing words; accents[] = hero words (cycled per phrase); 'gradient' = animated sweep between gradFrom/gradTo.",
"light": "editorial light — near-white field, near-black ink, deep green / ocean / sweep accents (DEFAULT; the act0 look)",
"dark": "dark field, off-white ink, vivid green / cyan / sweep accents",
"bold": "deep-navy field, white ink, amber / pink / sweep accents"
},
"icons": {
"_": "The climax ICON is its own knob (`icon`) so it can match the scene. Built-in inline-SVG library (asset-free, fill follows the text color); or pass an emoji, a raw <svg>…</svg> string, or 'none' for a pure-text climax. The pop + ring + wiggle emphasis is generic, so any glyph 'rings'.",
"library": ["bell", "cursor", "sparkle", "bolt", "play", "heart", "check", "star"],
"examples": "bell → timing/alerts · cursor → a click/UI · sparkle → AI/magic · bolt → speed · play → video · check → done · heart → like · star → featured"
},
"match": {
"structural_type": "per_onset_sequential",
"requires": {
"energy_level": ">=MEDIUM",
"has_steady_grid": true,
"density": ["medium", "dense"]
},
"mood_fit": ["bold", "elegant", "playful", "hype", "cinematic"],
"span_bars": [2, 8],
"exit_trigger": ["downbeat", "surge", "hard_stop", "end"],
"notes": "Reach for this for an INTRO / opening statement: a short narrated or anchored line you want to land word-by-word as big editorial type, climaxing on one keyword + icon. Each word reveal lands on one anchor (per_onset_sequential), so it shares the structural_type with the typewriter / logo-sting templates; it is discriminated by laying the line out as a SEQUENCE OF WHOLE PHRASES (big mixed-size posters with a colored hero word, hard-cut between) and by a slide-in ICON climax — not one typed message, not a card deck. ORIGIN is VO-driven (reveal times come from a transcript); in a beat context bind `phrases[].times` to onset seconds instead. If there is no readable line to speak/anchor (pure abstract field) this is the wrong template."
},
"examples": [
{
"sample": "timeline-launch-video",
"group": "act0-intro-bell",
"vo_origin": true,
"structural_type": "per_onset_sequential",
"energy_level": "MEDIUM",
"density": "medium",
"phrases": 3,
"span_sec": [0.0, 6.2],
"line": "If you've EVER used AI / for VIDEO editing before, / you KNOW that / timing is 🔔 tricky.",
"word_times_sec": [0.14, 0.3, 0.55, 0.87, 1.06, 1.36, 1.58, 1.92, 2.48, 3.06, 3.3, 3.54],
"climax": { "text": "timing is {icon} tricky.", "in": 3.79, "iconAt": 4.9, "icon": "bell" },
"exit_trigger": { "type": "end", "time": 6.2 },
"note": "Reversed from the VO intro `act0-intro-bell` (golden_sample_reverse/.../timeline-launch-video). Reveal times are VO WORD onsets (a transcript), not audiomap musical onsets — so the cadence is real but its driver is narration. The original used a Lottie bell + Google-Fonts Inter/Playfair + CDN GSAP; this promoted impl is offline (system type + bundled GSAP) and the bell is an inline-SVG library icon (now swappable per scene). Bind `times` to audio onsets to use it beat-driven."
}
],
"roles": {
"phrase": {
"kind": "message",
"motion": "word_cascade_reveal",
"anchor": "phrases[].times[]",
"notes": "Each phrase is a stacked editorial poster, vertically centered. Its words fade in one-by-one on their anchor times (explicit `times`, else auto-spread across the phrase), the phrase holds, then HARD cuts out (opacity→0) at `out`. PROPOSED verb 'word_cascade_reveal' (per-anchor word fade within a held poster). ~typewriter_reveal."
},
"hero": {
"kind": "message",
"motion": "accent_blowup",
"anchor": "phrases[].times[] (the hero line's word)",
"notes": "One line per phrase is the HERO — much larger (≈500px) and colored from the theme accent ramp (cycled per phrase), optionally serif-italic ('ever') or an animated 'gradient' sweep ('know'). Carries the key word of each phrase. PROPOSED verb 'accent_blowup'."
},
"climax": {
"kind": "message",
"motion": "slide_in_lockup",
"anchor": "climax.in",
"notes": "The finale phrase SLIDES in from offscreen-right (x 1400→0, power3.out) and HOLDS to the end (it does NOT cut out). Mixed body + one inline icon. PROPOSED verb 'slide_in_lockup'."
},
"icon": {
"kind": "asset",
"motion": "icon_ring",
"anchor": "climax.iconAt",
"notes": "A swappable inline glyph in the climax (the {icon} token): pops in (scale 0.4→1, back.out), does a damped ring-wiggle (rotation), and emits two expanding rings. Resolves `icon` to a library SVG, a custom <svg>, an emoji/text glyph, or nothing. PROPOSED verb 'icon_ring'. ~radial_burst_lines for the rings."
},
"field": {
"kind": "background",
"motion": "hold",
"anchor": "none",
"notes": "A flat solid field (theme bg). Dead still; only the type moves. negative_space_hold."
}
},
"params": {
"theme": {
"type": "string",
"maps_to": "palette (see themes)",
"default": "light",
"notes": "Palette preset: light | dark | bold. Sets bg + ink + the hero accent ramp."
},
"icon": {
"type": "string",
"maps_to": "climax.{icon} token (see icons)",
"default": "bell",
"notes": "The ringing climax icon — MATCH IT TO THE SCENE. A library name (bell|cursor|sparkle|bolt|play|heart|check|star), an emoji, a raw <svg>…</svg> string, or 'none' (pure-text climax)."
},
"phrases": {
"type": "string",
"maps_to": "engine.phrases",
"default": "",
"notes": "JSON array of phrase objects { lines:[{text,size,x,hero?,accent?,font?}], out, times? }. `times` (per word, reading order) = the VO/onset anchors; omit to auto-spread. Empty = the built-in 3-phrase act0 intro."
},
"climax": {
"type": "string",
"maps_to": "engine.climax",
"default": "",
"notes": "JSON object { text, in, iconAt, hold, size }. `text` embeds {icon} where the icon rings. Empty = the built-in 'timing is {icon} tricky.'"
}
},
"engine": {
"model": "data phrases + climax + icon + theme. The phrase posters, the climax lockup, the icon library, and the palette themes are fixed code; WHAT they say + WHEN (the anchors) + WHICH icon + WHICH palette are DATA. Word anchors are explicit `times` (VO word-times or audio onsets) or auto-spread across each phrase. Compose by editing the `phrases` / `climax` / `icon` / `theme` DATA — never the engine.",
"compose_by": ["theme", "icon", "phrases", "climax"],
"extend": "add a palette = a THEMES entry (bg + ink + accents + gradFrom/gradTo); add an icon = an ICONS entry (an inline-SVG path); restyle a phrase via line size/x/hero/accent/font. To rebuild the motion (slide direction, ring count) edit the timeline, not the data."
},
"program_format": {
"_": "`phrases` is a JSON array; `climax` is a JSON object. Times are absolute seconds (VO word onsets, or audio onsets in a beat context).",
"phrase": {
"lines": "[{ text, size(px), x(indent px), hero?(bool → big accent line), accent?('#hex'|'gradient'), font?('display'|'serif') }]",
"out": "number — seconds the phrase cuts out",
"times": "number[]? — per-WORD reveal seconds, reading order across all lines; omit → auto-spread evenly across the phrase",
"start": "number? — first-word time when `times` omitted (default = previous phrase `out`)"
},
"climax": {
"text": "string — words + a {icon} token where the icon rings",
"in": "number — slide-in start",
"iconAt": "number — when the icon pops + rings",
"hold": "number — tail hold after the ring (sets total duration = iconAt + hold)",
"size": "number — word size px (the icon scales from it)"
}
},
"reference_impl": "index.html",
"program_data": "program.json (the default act0 phrases + climax as standalone, agent-editable data)",
"uses_primitives": [
"typewriter_reveal",
"content_swap",
"kinetic_letter_in",
"radial_burst_lines",
"negative_space_hold"
],
"uses_primitives_notes": "word_cascade_reveal / accent_blowup / slide_in_lockup / icon_ring are PROPOSED custom phrases the impl defines (per-anchor word fade in a held poster; an enlarged accent hero word; an offscreen slide-in finale; an icon pop + ring-wiggle + expanding rings). typewriter_reveal backs the per-word reveal; content_swap the hard cut-out between phrases; radial_burst_lines the rings; negative_space_hold the static field.",
"bundled_assets": "assets/gsap.min.js (offline GSAP). No fonts bundled — system stack ('Inter','Helvetica Neue',Arial; serif hero falls back Playfair→Georgia). Icons are inline SVG (no Lottie). No remote assets.",
"transition_out": { "default": "fast_cut", "observed": "fast_cut" },
"reversed_from": [
"golden_sample_reverse/templates/intro-kinetic-cascade",
"golden_sample_reverse/hyperframes-selected/timeline-launch-video/compositions/act0-intro-bell.html"
],
"origin": "vo-launch-intro",
"provenance": {
"source": "act0-intro-bell — the VO intro of the Timeline-Editor launch video (timeline-launch-video).",
"note": "VO/narration-driven in origin (reveal times = transcript word onsets), NOT a beat-reversed musical group — so the match-face is a reasonable hypothesis for the BGM Director, and reveal times should be bound to audio onsets when used beat-driven. Adapted for the catalog: dropped the remote deps (Lottie bell + Google-Fonts Inter/Playfair + CDN GSAP) for an offline build (system type + bundled GSAP + inline-SVG icons), parameterized the content (phrases/climax) and palette (themes), and made the climax icon a swappable, scene-matched knob. First time it is matched to a real musical group, add that group as an example and tighten requires."
}
}
@@ -1,85 +0,0 @@
# Logo Split / Lockup Pulse — `logo-split-lockup-pulse`
A short, beat-locked **logo/brand sting**. A two-part mark sits joined at center,
**splits left↔right** to open a gap, **grows a center word-lockup one word per onset**
(the key word lands on the downbeat surge), **snap-closes** on a hit, then **pulses**
with the roll/hihat bed before a fast cut.
Reversed from **group_7** of the golden sample — the **Lille — World Design Capital
2020** sting (left radial spark `☀` + `lille 2020` + right cloud `☁`, on a flat green
field).
## Files
```
group_7_template/
card.json ← the spec (match-face + build-face) · status: draft
index.html ← reference impl (parameterized GSAP; inlined motion-blur snippet)
assets/gsap.min.js ← bundled GSAP (offline-safe)
assets/fredoka-700.woff2 ← bundled heavy rounded face (@font-face "Lockup")
renders/recreate.mp4 + renders/stills/ ← rendered proof @24fps
```
## What it covers (provenance — group_7, 24fps, BPM 92.3)
The marks move on a FEW discrete anchors only — the sustained hi-hat fill (f17–f86) is
texture, **not** a motion driver. Left + right brackets always move **together** (mirrored).
| stage | frames | time | what | beat |
| -------------- | ------- | ---------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| seed | f2 | 0.083s | joined bracket pair (full-outside / empty-middle) blooms in at center | f2 perc onset |
| split + word 1 | f3–f6 | 0.13–0.25s | brackets **glide apart** to the full lockup width (held); `lille` eases into the gap | f6 onset |
| word 2 | f24 | 1.000s | `2020` eases into the reserved space (brackets already open) | **SURGE@1s / downbeat f24-25** |
| hold | f24–f49 | 1.0–2.08s | `lille 2020` static | hi-hat fill bed (texture) |
| snap-close | f50 | 2.083s | 1-frame hard cut: words vanish, brackets weld back together (impact streak via blur) | after f47 snare |
| see-saw | f51–f63 | 2.13–2.63s | welded unit damped vertical bounce + building see-saw tilt (spark UP / cloud DOWN), settling high+tilted | **f51 / f55 / f58 / f63** (hi-hats) |
| exit | f70 | 2.917s | source hard-cuts to the next group (live footage) | `fast_cut` (near f71 kick) |
Corrections baked in vs earlier reads: the close is a **1-frame hard snap** (not a
squeeze); after it the weld does a **damped vertical bounce + a rigid see-saw tilt**
(left-spark up / right-cloud down — one rigid unit rotating, **not** a scale-pulse and
**not** per-side independent), beat-synced and decaying; the marks **pre-open to full
width** (so word1 floats in wide brackets); the marks are **big enough to wrap the text**
(~2.5–3× letter height, ~140° spark fan), each with its mass on the **outer** side.
## Silkiness (what makes the motion fluid, not stiff)
- **Velocity motion blur** (inlined registry `motion-blur` snippet) on the two brackets —
a one-sided SVG ghost trail proportional to speed, so the fast split-glide and the
snap-impact read smooth instead of as hard frame jumps. Clears at rest.
- **Smooth, slightly longer eases** (`expo.out` split, `power3.out` word reveals,
`power2.out` recoil) — no poppy `back.out`/elastic. Timing anchors are unchanged.
- A **gentle hold-drift** (`sine.inOut`) so the weld isn't dead-frozen.
## Parameters (swap freely)
- `bgColor` / `markColor` / `textColor` — palette (defaults: green `#249b5f`, cream `#e7e3dd`).
- `leftMark` / `rightMark` — **inline SVG** for each side. Empty → the default spark / cloud.
Pass **two related SVGs**, or **the two halves of one logo** (left half + right half).
Keep each mark's mass on its **outer** side so the pair reads as brackets framing the text.
- `word1..word4` — the lockup words, revealed one per onset and accumulating. Supports
**1, 2, or 3+ words**; put the key word on the strongest beat. Empty slots are skipped.
## Adaptivity (`beat_map` in `index.html`)
Content lives in `params`; musical **timing** lives in the `beat_map` constants
(`ENTRY`, `SPLIT`, `WORD_ONSETS[]`, `CLOSE`, `DUR`) — filled from the matched group's
`audiomap.json`. The impl **measures each word at build time** and pre-opens the brackets
to the full lockup width, so any word count / length re-centers correctly. More words →
add `WORD_ONSETS` entries. The marks deliberately do **not** animate on the hi-hat bed.
## Verify
```bash
npx hyperframes lint group_7_template # clean (1 inherent window.__timelines note)
npx hyperframes validate group_7_template # no console errors
npx hyperframes render group_7_template -f 24
```
## Status
`draft` — in the reverse workspace. Promote per `reverse-to-template.md` Step 9 (copy to
`skills/bgm-to-video/templates/logo-split-lockup-pulse/`, set
`status:"promoted"`, stamp `created`) once reviewed. Proposed new motion verbs
(`split_open`, `snap_close`, `per_onset_pulse`) and the shared `per_onset_sequential`
structural_type are flagged in `card.json` for catalog review.
@@ -1,145 +0,0 @@
{
"id": "logo-split-lockup-pulse",
"name": "Logo Split / Lockup Pulse",
"one_line": "A two-part mark sits joined at center, splits left↔right to open a gap, grows a center word-lockup one word per onset (key word lands on the downbeat surge), then snap-closes on a hit and pulses with the beat.",
"status": "promoted",
"match": {
"structural_type": "per_onset_sequential",
"requires": {
"has_steady_grid": true,
"onset_rate": ">=2.0",
"onset_gap_bars": "<1.0",
"density": ["medium", "dense"],
"has_roll": true,
"span_bars": "<=4"
},
"mood_fit": ["playful", "hype", "elegant", "cinematic", "tense"],
"span_bars": [1, 4],
"exit_trigger": ["downbeat", "surge", "hard_stop", "end"],
"notes": "A short logo/brand sting, not a typed sentence. Discriminated from typewriter-phrase-keyword-shuffle by density (dense, not sparse/medium-only) + has_roll:true (a sustained-fill hihat bed it consumes as a PULSE, not a cascade) + the left/right bracketing-mark roles. Reveals are still per-onset (split -> word -> word), so the structural_type is shared, but the build-face is the logo lockup, not text typing. The KEY content word should be placed on the strongest hit (downbeat / SURGE). If the grid goes quiet (onset_gap_bars >= ~1.5) this is the wrong template — use a hold template."
},
"examples": [
{
"sample": "group_7",
"group": "g7-logo-sting",
"bpm": 92.3,
"structural_type": "per_onset_sequential",
"energy_level": "HIGH",
"energy": 0.89,
"density": "dense",
"onset_rate": 5.65,
"onset_gap_bars": 0.14,
"has_steady_grid": true,
"has_roll": true,
"roll_kind": "sustained-fill",
"roll_rate_per_min": 351,
"span_sec": [0.083, 2.917],
"span_bars": 1,
"entry": { "anchor": "onset", "time": 0.083 },
"exit_trigger": { "type": "downbeat", "time": 2.917 },
"downbeats_sec": [1.045, 3.646],
"surge_sec": 1.0,
"mood": ["playful", "hype", "elegant"],
"brand": "Lille — World Design Capital 2020 (left radial spark + 'lille 2020' + right cloud)"
}
],
"roles": {
"left_mark": {
"kind": "asset",
"motion": "split_open",
"anchor": "entry.onset + split.onset",
"notes": "Left BRACKET of the logo (group_7: a radial spark; mass on the OUTER/left side, opening toward the text — see one_line). Appears joined at center on the entry onset (f2), then GLIDES left to the FULL lockup width on the split onset (f6) — fast launch + expo.out settle, smoothed by velocity motion blur. Holds open; does NOT track each word. PROPOSED verb 'split_open' (paired symmetric translate; reverse = 'snap_close')."
},
"right_mark": {
"kind": "asset",
"motion": "split_open",
"anchor": "entry.onset + split.onset",
"notes": "Right BRACKET (group_7: a cloud / backwards-3 swirl; mass OUTER/right, opening toward the text). Mirrors left_mark exactly — same beats, same offset (the two always correspond / move together). Pre-opens to the full width so even word1 alone floats in wide-open brackets (faithful: the marks barely move when more words fill in)."
},
"lockup": {
"kind": "message",
"motion": "per_onset_pop",
"anchor": "entry.word_onsets",
"notes": "1..N words ACCUMULATING one per onset into the reserved center space (not replace). Each word eases in with a soft stretch (scaleX 0.58->1, ~0.24s power3.out — smooth, NO poppy overshoot). The KEY word sits on the downbeat/SURGE (group_7: 'lille'@0.25 then '2020'@1.0 on SURGE@1s)."
},
"close": {
"kind": "asset",
"motion": "snap_close",
"anchor": "close.onset",
"notes": "On a key hit (group_7: f50 / 2.083s) the lockup snap-closes: words HARD-CUT to gone (0ms, no squash) AND both brackets teleport back together in the SAME frame — the teleport reads as an impact streak through the motion blur. PROPOSED verb 'snap_close'."
},
"seesaw": {
"kind": "asset",
"motion": "seesaw_bounce",
"anchor": "post_close.onsets",
"notes": "After the snap the welded brackets do a DAMPED VERTICAL SPRING + a rigid SEE-SAW TILT (rotation +deg = left-spark UP / right-cloud DOWN), beat-synced to the hi-hat hits after the snap (group_7: f51 slam-down lowest, f55 up-rebound, f58 dip, f63 flick). Amplitude decays; the unit settles slightly HIGH and TILTED (spark up/cloud down) into the f70 cut. ~95% vertical translate + a building rotation. NOT a scale-pulse, NOT per-side independent — it's one rigid unit rotating. PROPOSED verb 'seesaw_bounce'."
},
"background": {
"kind": "background",
"motion": "hold",
"anchor": "none",
"notes": "Flat solid color, dead still the whole span (group_7: green #249b5f). No color change. Optional energy_envelope_breath add-on, not required."
}
},
"params": {
"bgColor": { "type": "color", "maps_to": "background.color", "default": "#249b5f" },
"markColor": {
"type": "color",
"maps_to": "left_mark + right_mark stroke/fill",
"default": "#e7e3dd"
},
"textColor": { "type": "color", "maps_to": "lockup.words color", "default": "#e7e3dd" },
"leftMark": {
"type": "string",
"maps_to": "left_mark.svg",
"notes": "inline SVG (or one half of a single logo). Empty = the default radial spark. Keep the mass on the OUTER side so it reads as a bracket."
},
"rightMark": {
"type": "string",
"maps_to": "right_mark.svg",
"notes": "inline SVG (or the other half). Empty = the default cloud/3 swirl. Mass on the OUTER side."
},
"word1": {
"type": "string",
"maps_to": "lockup.word[0]",
"optional": true,
"default": "lille"
},
"word2": { "type": "string", "maps_to": "lockup.word[1]", "optional": true, "default": "2020" },
"word3": { "type": "string", "maps_to": "lockup.word[2]", "optional": true, "default": "" },
"word4": { "type": "string", "maps_to": "lockup.word[3]", "optional": true, "default": "" }
},
"beat_map": {
"comment": "Script-side musical timing constants in index.html, filled from <group>.audiomap.json. Content lives in params; musical timing lives here. All times are ABSOLUTE audio seconds. The marks move on these DISCRETE anchors only — NOT on the sustained hi-hat fill (texture).",
"entry_onset": 0.083,
"split_onset": 0.25,
"word_onsets": [0.25, 1.0],
"word_onsets_notes": "one per non-empty word, in order; word_onsets[0] doubles as the split. Add more entries for 3+ words. The strongest hit (here 1.0 = SURGE@1s downbeat) should carry the key word.",
"close_onset": 2.083,
"seesaw_onsets": [2.125, 2.292, 2.417, 2.625],
"seesaw_note": "f51/f55/f58/f63 — welded unit damped vertical bounce + see-saw tilt (left up/right down), decaying, settling high+tilted to the cut. These ARE beat-synced (the one place after the snap that tracks the hi-hats).",
"duration": 2.875,
"exit_note": "logo holds/drifts to 2.875 (f69) then the source hard-cuts to the next group at f70 (2.917, near f71 kick)"
},
"reference_impl": "index.html",
"uses_primitives": [
"radial_burst_lines",
"kinetic_letter_in",
"motion-blur",
"negative_space_hold"
],
"uses_primitives_notes": "split_open / snap_close / settle_drift are proposed custom phrases the impl defines (paired symmetric translate, 0ms collapse, slow drift). radial_burst_lines (#25) backs the default left spark; kinetic_letter_in (#02) backs the word stretch-pop. SILKINESS comes from the registry 'motion-blur' snippet (velocity-driven SVG ghost trail) attached to the marks + expo/power eases over longer durations — NOT from extra keyframes.",
"bundled_assets": "assets/gsap.min.js (offline GSAP), assets/fredoka-700.woff2 (heavy rounded face for the words — declared @font-face 'Lockup'). The motion-blur snippet is inlined in index.html (no external file).",
"transition_out": { "default": "fast_cut", "observed": "fast_cut" },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_7"],
"created": "2026-06-17"
}
@@ -1,190 +0,0 @@
# Poster-Tile Mosaic · 3 beat-synced operations
> Reverse-engineered from **group_5** of the golden sample (the Namshi poster-grid scene).
> `structural_type: dense_multiply` · status: **draft**
**ONE base template, THREE operations.** The base is a packed **mosaic of
DIFFERENT-sized tiles** — **not** a uniform grid: tall / wide / small colored boxes
that tessellate to fill the frame **with no overlap** (thin seams only), exactly like
the source's 错落 wall. **Asset-free**: a tile is a colored box with a text label.
"Adding a box" = a new image; "changing a box color" = a new asset / recolor. Three
interchangeable, beat-synced operations act on that one mosaic:
| op | what it does | what moves | source span |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------- |
| **A · staggerInOut** | pop different-sized tiles in one-per-onset (top-right→bottom-left waterfall) until they pack the frame → hold on a downbeat → pop them out one-per-onset | transform + opacity (per tile) | 0.58–2.08s (f14–f50) |
| **B · holdRecolor** | snap the whole wall on at once, **lock positions**, recolor the grid as a unit on each beat | background color (per tile, 0ms) | 2.37–2.91s (f57–f70) |
| **C · snakeFill+overlay** | reveal tiles along a **snake path** to fill → recolor whole grid on the hard-stop → pop overlay "cutouts" on top, one-per-onset | reveal + one swap + overlay pops | 3.0–5.5s (f72–f137) |
```
group_5_template/
index.html ← asset-free reference impl: mosaic + 3 operators + program runner
program.json ← the default group_5 score as standalone, agent-editable DATA
card.json ← the spec: base template, operators, program_format, match signature
assets/gsap.min.js ← vendored (offline-safe lint/validate/render)
renders/ ← group_5_recreate(.mp4 / _audio.mp4) + custom_demo.mp4 (a remixed program)
README.md ← this file
```
This is the answer to _"is it one base template used three ways?"_ — **yes.** The
implementation makes that literal: the same `tiles[]` mosaic is built once (by a
deterministic binary-split packer) and reused by all three operations; only the
**scheduling** differs. (Gemini's pass called the three "different systems" —
frame-by-frame inspection disproved that; see `card.json` provenance.)
---
## 1. How it beat-syncs (from `group_5.audiomap.json`)
**Nothing is on a timer.** Every move is a GSAP tween/`set` at an absolute audio
second from the analysis. Track facts: **BPM 129.2**, 4/4, downbeats **1.324 (f32) /
3.181 (f76) / 5.039 (f121)**, **hard_stop @ 4.0s** (largest energy drop, Δ-0.67).
The score is the **PROGRAM** — a data array of operator steps ([`program.json`](program.json),
mirrored inline as `DEFAULT_PROGRAM` in §3):
```jsonc
[
{
"op": "staggerInOut", // build → hold → exit
"enter": [0.23, 0.37, 0.46, 0.6, 0.7, 0.84, 0.91, 1.07, 1.14, 1.28], // 10 onsets → 10 tiles
"hold": 1.324, // downbeat f32
"exit": [1.37, 1.51, 1.62, 1.74, 1.83, 1.97, 2.07],
}, // staggered out (ends f50)
{
"op": "holdRecolor",
"on": 2.35,
"onTheme": 1, // snap on, lock, recolor
"recolor": [2.42, 2.53, 2.81, 2.93],
"themes": [2, 3, 1, 2],
"off": 2.98,
},
{
"op": "snakeFillOverlay", // fill → swap → overlay
"fill": [3.04, 3.181, 3.44, 3.65, 3.79, 3.9], // 3.181 = downbeat f76 (accel)
"swap": 4.0,
"swapTheme": 4, // hard_stop "一键换装"
"overlay": [4.11, 4.34, 4.48, 4.81, 4.97, 5.25, 5.48],
}, // 7 onsets → 7 cutouts
]
```
**The rule of thumb:** structure (the build, the downbeat hold, the hard-stop swap)
leans on the strong grid; texture (per-onset reveals, per-beat recolors) rides the
dense onset stream in between.
---
## 2. Why _this beat_ → _this template_ (the matching intuition)
Reach for the tile-wall when the audiomap shows:
1. **A steady grid** (`has_steady_grid: true`) — you need downbeats to pin the
build/hold/swap structure to.
2. **A dense, continuous onset stream** (`onset_gap_bars ≤ 0.5`) — _a hit available
for every tile move_. group_5 is wall-to-wall snares/hihats; that's what lets one
tile enter (or recolor, or fill) per onset.
3. **Distinct sub-phases you want to articulate differently** — an accumulate stretch,
a held/rolling stretch, then a fill-and-drop. The three operations map onto exactly
that shape: **build → recolor-on-roll → fill-then-drop**.
4. **A hard-stop / big DROP** mid-section — op C uses it for the full-grid "一键换装"
recolor (`swap`), the single most dramatic beat in the scene.
Put plainly: **"steady grid + dense onsets + 2–3 contrasting sub-phases + a hard-stop"
is the fingerprint.** When you see it, you have a hit for every box you want to place,
recolor, or stack.
---
## 3. Usage
### Render with defaults (the group_5 recreation)
```bash
cd group_5_template
npx hyperframes lint . && npx hyperframes validate .
npx hyperframes render . -f 24 -o renders/group_5_recreate.mp4
# beat-matched proof (mux the original BGM):
ffmpeg -y -i renders/group_5_recreate.mp4 -i ../group_5.wav -c:v copy -c:a aac -shortest renders/group_5_recreate_audio.mp4
```
### Change the mosaic & labels (content only — no code edit)
```bash
npx hyperframes render . --variables '{
"tiles": 16, "bands": 4, "gap": 6,
"labels": "NEW,DROP,SALE,40% OFF,SHOP,NOW",
"bgColor": "#111111"
}'
```
- **tiles** = how many different-sized boxes the packer tessellates the frame into.
- **bands** = how many horizontal row-bands the snake fill (OP C) sweeps through.
- **gap** = seam thickness (0 = truly edge-to-edge, no seams).
- The waterfall enter order, the snake path, and the per-onset mappings all adapt to
the resulting mosaic automatically.
- **labels** is a comma list, cycled across tiles. **showText:false** hides labels for
a pure color-block look.
### Recompose freely — compose by DATA, not code (the whole point)
The three operators (`staggerInOut`, `holdRecolor`, `snakeFillOverlay`) are **pure,
parameterized, order-independent** functions over the one shared mosaic. What runs — in
what order, on which beats — is a **data PROGRAM** (an array of `{op, ...beats}` steps).
The default group_5 score lives in [`program.json`](program.json) and inline as
`DEFAULT_PROGRAM` (§3); the runner (§7) just dispatches `OPS[step.op](step)`.
So you recompose **without touching operator code** — pass a `program` JSON string:
```bash
# Run ONE operator solo (just the snake-fill + overlay)
npx hyperframes render . --variables '{"program":"[{\"op\":\"snakeFillOverlay\",\"fill\":[0.3,0.8,1.3,1.8,2.3],\"swap\":2.8,\"swapTheme\":4,\"overlay\":[3.0,3.4,3.8,4.2]}]"}'
# REORDER + retime: recolor first, then build, then fill (B → A → C)
npx hyperframes render . --variables '{"program":"[{\"op\":\"holdRecolor\",\"on\":0.3,\"onTheme\":2,\"recolor\":[0.8,1.3,1.8],\"themes\":[3,1,4],\"off\":2.1},{\"op\":\"staggerInOut\",\"enter\":[2.4,2.6,2.8,3.0,3.2,3.4],\"exit\":[3.8,4.0,4.2]},{\"op\":\"snakeFillOverlay\",\"fill\":[4.4,4.7,5.0,5.3],\"swap\":5.4,\"overlay\":[5.5,5.65]}]"}'
# REPEAT an operator (build, exit, build again)
npx hyperframes render . --variables '{"program":"[{\"op\":\"staggerInOut\",\"enter\":[0.2,0.5,0.8,1.1],\"exit\":[1.5,1.8,2.1]},{\"op\":\"staggerInOut\",\"theme\":2,\"enter\":[2.5,2.8,3.1,3.4]}]"}'
```
Each step's fields are documented in [`card.json`](card.json) → `program_format`. An
agent composes by emitting this JSON (op names + beats) — it never edits JS. Steps
combine freely, reorder, repeat, or run solo; every operator re-shows tiles from hidden
and sets its own theme, so any sequence is safe.
> **Empty `program` = the built-in group_5 score.** Keep `program.json` and
> `DEFAULT_PROGRAM` in sync — `program.json` is the canonical, copy-pasteable data.
### Re-fit the beat to a different group (the part that changes per track)
Copy the new group's `audiomap.json` onset/downbeat seconds into the step beat lists
(in `program.json` / `DEFAULT_PROGRAM`). Each list grows or shrinks freely — more onsets
→ more tile moves; `beatAt()` distributes any tile count across any beat list. For a
longer/shorter piece, also set `DUR` and the root `data-duration` to the new span.
Add palettes to `THEMES`, faces to `FONTS`, more overlay slots are auto-built from the
program's hungriest `overlay` list — every move stays keyed to an audio second, so it
renders identically every time. Want a new move? add a function + an `OPS` key (§6) and
the program can call it by name.
> **Deterministic / asset-free:** only colored boxes + generic font stacks, no remote
> assets, no `Math.random` (scatter uses a deterministic index hash), no timers.
> See `references/builder-contract.md`. Lints clean (0 errors, 0 warnings); validates
> with no console errors.
---
## 4. Provenance
- **Source:** `bgm-golden-sample-reverse/gorup-by-group/group_5/group_5.mp4`
- **Audio:** `group_5.audiomap.json` (from `scripts/analyze-beatgrid.py`)
- **Video read:** `group_5.gemini-analysis.md` (Gemini 3 Pro) **corrected by
frame-by-frame inspection** — Gemini mislabeled op B as a zero-gap two-row _banner_
and concluded the three phases were "different systems." Pulling real frames at each
onset proved B is the **same tile-wall recolored as a unit** (green→blue→pink), and
that A/B/C share one asset family and one grid paradigm — i.e. one base template,
three operations. Trust frames over sparse sampling for per-frame detail.
- **Open question for promotion:** the source omits an intro flourish (a green "III"
glyph transition, 0–0.58s) that this template skips; decide whether to ship it as an
optional pre-roll role. Also consider varying the per-phase grid _gap_ (the source
loosens the gap in op A, tightens it in B/C) as an operation parameter.
@@ -1,150 +0,0 @@
{
"id": "poster-tile-mosaic",
"name": "Poster-Tile Mosaic · 3 beat-synced operations",
"one_line": "ONE base template — a packed MOSAIC of DIFFERENT-sized colored tiles (asset-free: color + label) that tessellate to fill the frame with no overlap — driven by three interchangeable beat-synced operations: staggered enter/exit, locked global-recolor, and snake-fill + overlay.",
"status": "promoted",
"created": "2026-06-17",
"base_template": {
"primitive": "tile_mosaic",
"notes": "A packed mosaic of DIFFERENT-sized absolutely-positioned tiles (NOT a uniform grid): tall / wide / small boxes that tessellate to fill the frame with no overlap (thin seams only) — the source's 错落 wall. Built by a deterministic recursive binary-split packer (split the largest region along its longer side; ratio is a fixed function of the step index). A tile = a colored box + a text label (stands in for an image; no assets). 'Add a box' = a new image; 'change a box color' = a new asset / recolor. All three operations below act on this one mosaic — that is the whole point: same tiles, different rhythmic scheduling."
},
"operations": {
"A_staggerInOut": {
"intent": "build the mosaic by popping DIFFERENT-sized tiles in one-per-onset (top-right→bottom-left waterfall) until they pack the frame with no overlap, hold on a downbeat, then pop them out one-per-onset",
"anchors": "enter[] = onsets; hold = downbeat; exit[] = onsets",
"what_moves": "transform + opacity per tile (scatter-jitter slide-in, drop-out); tiles vary in size and tessellate — they do NOT overlap",
"source_span_sec": [0.58, 2.08],
"source_frames_24": [14, 50]
},
"B_holdRecolor": {
"intent": "snap the whole wall on at once, LOCK positions, recolor the entire grid as one unit on each beat",
"anchors": "on = onset; recolor[] = snares (one palette swap each); off = onset",
"what_moves": "background color of every tile (0ms set — a recolor is a hit, not a fade). Positions never change.",
"source_span_sec": [2.37, 2.91],
"source_frames_24": [57, 70]
},
"C_snakeFillOverlay": {
"intent": "reveal tiles along a snake path to fill the grid, recolor the whole grid on the hard-stop, then pop overlay 'cutouts' on top one-per-onset",
"anchors": "fill[] = onsets (incl. a downbeat accel); swap = hard_stop; overlay[] = onsets",
"snake_path": "top row L→R, then bottom row R→L, repeating per row pair",
"what_moves": "per-tile reveal (opacity+scale) along the path; one full-grid palette swap on the hard-stop; overlay elements pop in and HOLD (no exit)",
"source_span_sec": [3.0, 5.5],
"source_frames_24": [72, 137]
}
},
"match": {
"structural_type": "dense_multiply",
"requires": {
"energy_level": ">=MEDIUM",
"density": "dense",
"onset_gap_bars": "<=0.5",
"has_steady_grid": true
},
"mood_fit": ["hype", "playful", "fashion", "retail", "bold"],
"span_bars": [1, 3],
"exit_trigger": ["hard_stop", "surge", "freeze"],
"notes": "This is a META-template: a wall + a pluggable list of operations. Reach for it when a section has many discrete, individually-placeable onsets (a hit for every tile move) AND distinct sub-phases you want to articulate differently — accumulate, hold-and-flash, then fill-and-stack. The three ops map naturally onto: build → recolor-on-roll → fill-then-drop."
},
"examples": [
{
"sample": "bgm_test_2",
"group": "g5",
"bpm": 129.2,
"downbeats_sec": [1.324, 3.181, 5.039],
"hard_stop_sec": 4.0,
"span_sec": [0.0, 5.75],
"program": "A_staggerInOut(0.58-2.08) → B_holdRecolor(2.37-2.91) → C_snakeFillOverlay(3.0-5.5, swap@4.0)"
}
],
"params": {
"bgColor": { "type": "color", "maps_to": "stage.background", "default": "#e9e9e9" },
"tiles": {
"type": "number",
"maps_to": "mosaic.tile_count",
"default": 12,
"notes": "number of boxes the packer tessellates the frame into"
},
"bands": {
"type": "number",
"maps_to": "mosaic.snake_bands",
"default": 3,
"notes": "horizontal row-bands the snake fill (OP C) sweeps through"
},
"gap": { "type": "number", "maps_to": "mosaic.seam_px", "default": 10 },
"showText": { "type": "boolean", "maps_to": "tile.label_visible", "default": true },
"labels": {
"type": "string",
"maps_to": "tile.labels",
"notes": "comma list, one per tile (cycled)"
},
"program": {
"type": "string",
"maps_to": "engine.program",
"default": "",
"notes": "JSON array of operator steps (see program_format). Empty = built-in group_5 score. THIS is the compose-by-data surface: reorder/drop/repeat steps, no code edit."
}
},
"engine": {
"model": "operators + program-as-data. The 3 operators (§6 of index.html) are pure, parameterized, order-independent functions over ONE shared mosaic. A PROGRAM (data) lists which run, in what order, on which beats; §7 dispatches it. Compose by editing DATA (the PROGRAM array, the `program` variable, or program.json) — never the operator code. Steps combine freely, repeat, and run solo.",
"operators": ["staggerInOut", "holdRecolor", "snakeFillOverlay"],
"dispatch": "OPS[step.op](step) for each step in PROGRAM",
"extend": "add an operator = add a function + an OPS key; the program can then call it by name"
},
"program_format": {
"_": "A program is a JSON array of steps. Each step = { op, ...fields }. Beats are absolute audio seconds. Themes are indices into THEMES[]. order = 'waterfall' | 'snake' | 'index' | [explicit tile-index array].",
"staggerInOut": {
"enter": "number[] — onset per tile (distributed if count != tiles); reveal in `order`",
"exit": "number[]? — onset per tile to drop out; omit to leave the wall standing",
"hold": "number? — documentary downbeat the full wall lands on (no tween)",
"theme": "number? — THEMES index dressed at reveal (default 0)",
"order": "string|array? — reveal order (default 'waterfall' = top-right→bottom-left)"
},
"holdRecolor": {
"on": "number — all tiles snap on at once here",
"onTheme": "number? — THEMES index on snap-on (default 0)",
"recolor": "number[]? — beats at which the WHOLE wall recolors as a unit",
"themes": "number[]? — THEMES index applied at each recolor beat (cycled)",
"off": "number? — clear the wall here; omit to hold it"
},
"snakeFillOverlay": {
"fill": "number[] — reveal anchors; tiles distributed across them in `order`",
"baseTheme": "number? — THEMES index for the fill (default 0)",
"swap": "number? — beat for a full-grid recolor (the hard-stop 一键换装)",
"swapTheme": "number? — THEMES index for the swap (default 4)",
"overlay": "number[]? — one cutout pops per beat, holds to the end",
"order": "string|array? — fill order (default 'snake')"
}
},
"reference_impl": "index.html",
"program_data": "program.json (the default group_5 score as standalone, agent-editable data)",
"uses_primitives": [
"tile_mosaic",
"mosaic_pack",
"staggered_reveal",
"staggered_exit",
"palette_flip",
"color_grid_shuffle",
"directional_fill",
"system_replace",
"content_swap",
"overlay_pop",
"freeze_hold"
],
"transition_out": { "default": "fast_cut", "observed": ["freeze", "hold_on_final_collage"] },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_5"],
"provenance": {
"video": "group_5.mp4",
"audiomap": "group_5.audiomap.json (scripts/analyze-beatgrid.py)",
"video_read": "group_5.gemini-analysis.md (Gemini 3 Pro) corrected by frame-by-frame inspection — Gemini mislabeled op B as a zero-gap banner and called the three a 'different systems'; pulled frames proved B is the same tile-wall recolored as a unit, and all three share one asset family / grid paradigm."
}
}
@@ -1,150 +0,0 @@
# Roll-Driven Flipbook (Word Cycle → Optional Lock)
> Reverse-engineered from **gruop_3** of the golden sample (the fast word-flicker scene).
> `structural_type: dense_multiply` · status: **draft**
A general **fast word-flipbook**: a hi-hat **roll** drives a centred word that flips every
16th-note, cycling a word list to _fill the roll_. **On demand**, when a phrase is wanted,
the flicker resolves (scramble-decode) and **locks** into a final line. Background is pure
black (the original's rotating 3D shape / glitch field is an optional add-on role).
```
gruop_3_template/
index.html ← parameterized, asset-free reference impl (1 paused GSAP timeline)
card.json ← the spec: match-face + build-face
README.md ← this file
```
---
## 1. How it beat-syncs
Track facts (from `gruop_3.audiomap.json`): **BPM 129.2**, 4/4. The defining audio event
is a **sustained-fill hi-hat roll** — in the source at 3.71–6.66s, 21 hits, ~407 hits/min
— i.e. roughly a hit every **16th-note** (`60/129.2/4 = 0.116s`). That roll is the
flicker's clock.
**Timing is scene-relative** (rebased so content starts at ~0 — a template carries no dead
pre-roll; the source's 3.71s offset is removed):
| phase | what happens | scene time |
| ------------------------- | ----------------------------------------------------------------------------------------------------- | -------------- |
| **A — flicker** | a centred word hard-swaps every **0.116s** (16th-note), cycling the word list, **filling** the window | `0.10 → 2.19s` |
| **— clear** | the flicker clears (negative-space breath) | `~2.2s` |
| **B — lock** _(optional)_ | a scrambled line decodes left→right and locks the phrase | `2.33 → 3.33s` |
| **— hold** | the locked phrase holds to the end | `→ 3.8s` |
The flicker rate is **roll-level**, ~4× faster than the per-onset rate — that's what makes
words _flicker_ instead of _read one at a time_.
> **Why duration isn't hard-coded.** Scene length is read from the root `data-duration`
> attribute (single source — `3.8s` here). The flicker length isn't a magic number either
> — it's `round((flipEnd − flipStart) / 16th)`, so it **auto-fills whatever window you
> give it**. Change the beat → the flipbook re-fits.
---
## 2. When you reach for this template (the matching signal)
The Music Reader emits a `GroupSignature`; **the single tell for this template is a fast
`rolls[]` entry** (`sustained-fill`, hundreds of hits/min). A roll means:
- the music is giving you a **dense grid of evenly-spaced slots** (16th-notes), and
- there's **no single readable message** to hold — it's energy/texture.
So you fill the grid with a **rapidly-cycling word flipbook** (`dense_multiply`). If a
**SURGE / downbeat follows** the roll, that's your cue to **lock** the flicker into a
final phrase (the optional resolve).
### The contrast that makes the choice mechanical
Same track, three groups, three different onset _rates_ → three different templates:
| group | audio signature | rate | → template | text behaviour |
| ------ | ------------------------------------ | --------------- | ----------------------------------- | ---------------------------- |
| g1 | onset **desert** (`gap ≥1.5 bar`) | ~0 | `held-message-living-field` | text frozen, field moves |
| g2 | **continuous onsets** (`gap <1 bar`) | ~3/s | `typewriter-phrase-keyword-shuffle` | one word **per onset** |
| **g3** | a **sustained-fill roll** | **~7/s (16th)** | **`roll-flipbook-word-cycle`** | words **flicker** (many/sec) |
Read it as a rate ladder: **no onsets → hold · onsets → type one word each · a roll →
flicker many words.** When the audiomap shows a roll, you reach for _this_ card.
---
## 3. Usage
### Render with defaults (the gruop_3 recreation)
```bash
cd gruop_3_template
npx hyperframes lint && npx hyperframes validate
npx hyperframes render -f 24 -o renders/out.mp4
```
### Change the words / lock phrase (content only — no code edit)
```bash
# flicker a different list, lock a different phrase
npx hyperframes render --variables '{
"flipWords":"Ship,Iterate,Measure,Repeat",
"resolveText":"build in public",
"accentColor":"#39e6a0"
}'
# PURE FLICKER — no lock. Empty resolveText → the last cycled word just holds.
npx hyperframes render --variables '{"resolveText":""}'
```
- **`flipWords`** is cycled to fill the roll, however many you give (1 → N). More words →
fewer repeats; fewer words → more loops. The fill count follows the beat, not the list.
- **`resolveText` empty → pure flicker** (on-demand lock: only set it when you want a
phrase to land). `periodChar` empty → no accent dot.
### Re-fit to a different beat (the part that changes per track)
Two edits, both single-sourced. Timing is **scene-relative** — map your roll onto the
scene start (subtract the roll's absolute offset) so there's no dead pre-roll:
1. **Scene length** — set `data-duration` on `#root` in the HTML to your scene span.
2. **The `BEAT` block** at the top of the script:
```js
var BEAT = {
bpm: <tempo.bpm>, // sets the 16th-note flip step automatically
flipStart: 0.10, // small lead-in (keep near 0 — no dead air)
flipEnd: 0.10 + <rollLen>, // rollLen = audiomap rolls[].end − rolls[].start
resolveStart: flipEnd + ~0.14, // short clear; only used if a lock phrase is set
resolveLock: resolveStart + ~1, // place just before a downbeat in your track
};
// then set data-duration ≈ resolveLock + ~0.5 (hold)
```
That's it — the number of word-swaps, the decode step count, and the final hold all
derive from these + `data-duration`. No other timing constants to touch.
---
## 4. Implementation notes (why it's built this way)
- **Everything is a 0ms `tl.set(autoAlpha)` on a pre-built node** (content*swap flipbook).
The scramble is a \_second* flipbook whose frames are progressively-resolved strings,
baked deterministically at build time.
- **Avoided:** GSAP `tl.set({textContent})` and tween `onUpdate` — both silently fail
under the seek-by-frame renderer (verified: they render black). Also avoided animating
`scale` on a `translate(-50%,-50%)`-centred node (GSAP clobbers the centering) — layers
are **grid-centred** instead.
- **Final-frame gotcha:** a `set` placed at the timeline's _last instant_ is dropped by
the renderer, so the resolve locks slightly before the end and a no-op `tl.set(stack,
{opacity:1}, DUR)` extends the timeline so the held phrase renders to the end.
- Deterministic / asset-free: generic font stacks, no `Math.random`, no timers.
## 5. Provenance
- **Source:** `bgm-golden-sample-reverse/gorup-by-group/gruop_3/gruop_3.mp4`
- **Audio:** `gruop_3.audiomap.json` (from `scripts/analyze-beatgrid.py`)
- **Video read:** `gruop_3.gemini-analysis.md` (Gemini 3 Pro) **confirmed by frame-by-frame
inspection** — Gemini's word list (Design → … → Event Management, 2 loops) and the
decode-to-"everything you need." resolve both checked out against real frames.
- **Open for promotion:** identify the source's actual typefaces if a pixel-exact match
is wanted (this impl reproduces the _mechanism_ with a generic bold sans), and decide
whether to ship the rotating-3D / glitch background as a second role.
@@ -1,111 +0,0 @@
{
"id": "roll-flipbook-word-cycle",
"name": "Roll-Driven Flipbook (Word Cycle → Optional Lock)",
"one_line": "A hi-hat roll drives a centred word that flips every 16th-note through a word list; optionally the flicker resolves and locks into a final phrase.",
"status": "promoted",
"match": {
"structural_type": "dense_multiply",
"requires": {
"has_roll": true,
"roll_rate_per_min": ">=300",
"roll_kind": "sustained-fill",
"energy_level": ">=MEDIUM",
"density": ["medium", "dense"]
},
"mood_fit": ["hype", "glitch", "aggressive", "tense", "playful"],
"span_bars": [1, 4],
"exit_trigger": ["surge", "downbeat", "hard_stop"],
"notes": "The ONE signal that triggers this template is a fast sustained-fill rolls[] entry in the audiomap (hundreds of hits/min, ~16th-note). A roll = a dense grid of slots with no single readable message → fill it with a rapidly-cycling word flipbook. Contrast held-message (onset desert → freeze) and typewriter-phrase (continuous onsets → one word per onset): here the RATE is roll-level (≈4× faster than onsets), so words flicker, they don't read one-at-a-time. The lock-to-phrase resolve is OPTIONAL."
},
"examples": [
{
"sample": "gruop_3",
"group": "g3-flicker-lock",
"bpm": 129.2,
"structural_type": "dense_multiply",
"energy_level": "HIGH",
"energy": 0.9,
"density": "dense",
"roll": {
"start": 3.71,
"end": 6.66,
"hits": 21,
"rate_per_min": 407,
"kind": "sustained-fill",
"drum": "hihat"
},
"has_steady_grid": true,
"span_sec": [3.32, 6.966],
"span_bars": 2,
"entry": { "anchor": "roll", "time": 3.625 },
"exit_trigger": { "type": "surge", "time": 6.966 },
"mood": ["hype", "glitch"]
}
],
"roles": {
"word_flicker": {
"kind": "message",
"motion": "flipbook",
"anchor": "roll.16th_grid",
"notes": "PROPOSED motion verb. A centred word that hard-swaps (0ms) every 16th-note, cycling the word list to FILL the roll window. Word count auto-derives from (rollEnd-rollStart)/16th. The typographic field IS the percussion."
},
"lock_phrase": {
"kind": "message",
"motion": "scramble_decode",
"anchor": "surge + next_downbeat",
"notes": "PROPOSED motion verb. OPTIONAL. On the SURGE after the roll, the flicker clears and a scrambled line decodes left→right, locking the final phrase on the next downbeat. Empty resolveText → skip; the last flicker word just holds (locks) instead."
},
"background": {
"kind": "background",
"motion": "hold",
"anchor": "none",
"notes": "Pure black in this reference impl (per the reverse brief). The original gruop_3 layered a rotating 3D shape + glitch field here — an OPTIONAL add-on role, not required by the structural type."
}
},
"params": {
"bgColor": { "type": "color", "maps_to": "background.color" },
"textColor": { "type": "color", "maps_to": "word_flicker.color + lock_phrase.color" },
"accentColor": { "type": "color", "maps_to": "lock_phrase.trailing_accent" },
"flipWords": {
"type": "string",
"maps_to": "word_flicker.words",
"note": "comma-separated; cycled to fill the roll"
},
"resolveText": {
"type": "string",
"maps_to": "lock_phrase.content",
"optional": true,
"note": "EMPTY = pure flicker, no lock"
},
"periodChar": { "type": "string", "maps_to": "lock_phrase.trailing_accent", "optional": true }
},
"beat_map": {
"comment": "Script-side BEAT block in index.html. SCENE-RELATIVE (starts at ~0, no dead pre-roll) — the source's absolute roll at 3.71s is rebased to flipStart. Duration is single-sourced from data-duration; the flipbook AUTO-FILLS the flicker window.",
"bpm": 129.2,
"flip_step_derived": "60/bpm/4 (16th-note) = 0.116s",
"flipStart": 0.1,
"flipEnd": 2.19,
"fill_roll": true,
"resolveStart": 2.33,
"resolveLock": 3.33,
"duration": "from data-duration (3.8 here)",
"source_roll_absolute": {
"start": 3.71,
"end": 6.66,
"note": "rebased: subtract ~3.6s offset to remove the pre-roll"
}
},
"reference_impl": "index.html",
"uses_primitives": ["content_swap", "word_grid_burst", "negative_space_hold", "value_counter"],
"transition_out": { "default": "fast_cut", "observed": "clear_then_decode_lock" },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/gruop_3"],
"created": "2026-06-17"
}
@@ -1,246 +0,0 @@
# Split-Anchor Word-Slot · 5 beat-synced operators
> Reverse-engineered from **group_6** of the golden sample (the "studio contre courant" kinetic-type scene).
> `structural_type: per_onset_sequential` · status: **draft**
**ONE base lockup, FIVE operators.** The base is a kinetic-typography **lockup**: a
**held left anchor column** of `R` rows (fixed words) beside a **torn-paper word-SLOT
box** on the right. `R` is data (the `anchors` comma-list length) — pass 2, 3, or 4
words and the geometry follows. Asset-free: just text + colored boxes. Five
interchangeable, beat-synced operators act on that one lockup:
| op | what it does | what moves | source span |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------ |
| **lockup** | pop the `R` left anchor words in one-per-beat → reveal the empty slot box | per-word pop-in + box scale-in | 0.13–0.50s (f3–f12) |
| **slot** | swap a word-GROUP into the box: lines slide in per beat → hold → slide out (omit `exit` to hold). per-line color via `colors[]` | per-line textContent + slide/fade | 1.0–1.83s (f24–f44) & 2.04–2.75s (f49–f66) |
| **bg** | flip the WHOLE scene to another theme on a beat (bg + anchor ink + box fill + slot ink invert, 0ms) | colors of root/box/anchors/lines | f83 (blue→green) |
| **shake** | global per-beat jitter of the whole lockup (x/y + rotation), one jolt per beat | transform of `#lockup` | 2.16–4.18s (f52–f100) |
| **expand** | EXIT wipe: fade text → zoom the slot box until it fills the frame | text fade + box scale→30× | 4.30–4.79s (f100–f114) |
```
group_6_template/
index.html ← asset-free reference impl: lockup + 5 operators + program runner
program.json ← the default group_6 score as standalone, agent-editable DATA
card.json ← the spec: base template, operators, program_format, match signature
assets/gsap.min.js ← vendored (offline-safe lint/validate/render)
renders/ ← group_6_recreate(.mp4 / _audio.mp4) + custom_demo.mp4
README.md ← this file
```
This answers the brief directly: **the fixed structure is a template; the content is
data.** Different words compose into the same lockup; the row count and the number of
background flips are program parameters; every move is keyed to a beat, so a new track
matches by swapping the beat numbers.
---
## 1. How it beat-syncs (from `../audiomap.json`)
**Nothing is on a timer.** Every move is a GSAP tween/`set` at an absolute audio second
from the analysis. Track facts: **~92 BPM**, 4/4, downbeats **2.322 (f56) / 4.923
(f118)**, a **sustained hihat fill 2.16–4.18s (f52–f100, 14 hits)**. The beat tracker is
only confident after 2.3s (the front is a VOID lead-in), so the early anchor pops ride
the onset list, not the grid.
The score is the **PROGRAM** — a data array of operator steps
([`program.json`](program.json), mirrored inline as `DEFAULT_PROGRAM` in §3 of
`index.html`):
```jsonc
[
{ "op": "lockup", "enter": [0.125, 0.333, 0.5], "box": 0.292, "theme": 0 }, // name locks in
{
"op": "slot",
"words": ["I bring", "ideas", "to life"], // group 1 in→out
"enter": [1.0, 1.167, 1.292],
"exit": [1.667, 1.75, 1.833],
},
{
"op": "slot",
"words": ["you", "wanna", "see?"], // group 2, colored
"enter": [2.042, 2.208, 2.375],
"exit": [2.75, 2.75, 2.75],
"colors": [0, 1, 1],
},
{
"op": "shake",
"amp": 15,
"rot": 1.7,
"settle": 0.13, // ride the hihat fill
"beats": [2.16, 2.3, 2.44, 2.62, 2.76, 2.88, 3.06, 3.27, 3.41, 3.53, 3.71, 3.85, 4.09, 4.18],
},
{ "op": "bg", "at": 3.458, "theme": 1 }, // blue → green (f83)
{ "op": "expand", "fade": 4.3, "at": 4.667, "to": 4.792 }, // zoom-wipe into f118
]
```
**Rule of thumb:** structure (the lock-in, the palette flip, the zoom-wipe) leans on the
strong downbeats; texture (per-word slot pops, the shake) rides the dense onset stream in
between.
---
## 2. Why _this beat_ → _this template_ (the matching intuition)
Reach for the anchor-slot lockup when the audiomap shows:
1. **A held idea + a stream of discrete onsets** — something to anchor on the left (a
name / brand) and a hit for every word you pop on the right (`onset_gap_bars ≤ 1`).
2. **A dense run (roll / hihat fill)** to ride a **shake** on — group_6's f52–f100 fill
is exactly the "jitter the whole thing" stretch.
3. **A strong downbeat to wipe out into** — the **expand** zoom lands its black-out one
beat _before_ the f118 downbeat kick, so the next group "punches" in on the beat.
4. **Optional: one or two key hits to invert the palette** — schedule a `bg` flip on each.
Put plainly: **"a held name + per-onset words + one roll + a downbeat exit"** is the
fingerprint.
---
## 3. Usage
### Render with defaults (the group_6 recreation)
```bash
cd group_6_template
npx hyperframes lint . && npx hyperframes validate .
npx hyperframes render . -f 24 -o renders/group_6_recreate.mp4
# beat-matched proof (mux the original BGM):
ffmpeg -y -i renders/group_6_recreate.mp4 -i ../group_6.wav -c:v copy -c:a aac -shortest renders/group_6_recreate_audio.mp4
```
### Change the words (content only — no code edit)
```bash
# 2-row lockup, different phrase
npx hyperframes render . --variables '{
"anchors": "make,it",
"program": "[{\"op\":\"lockup\",\"enter\":[0.1,0.4],\"box\":0.3},{\"op\":\"slot\",\"words\":[\"move\",\"fast\"],\"enter\":[1.0,1.3],\"exit\":[1.9,1.9]},{\"op\":\"expand\",\"fade\":2.2,\"at\":2.5,\"to\":2.7}]"
}'
```
- **anchors** is a comma list — one word per row. Its length sets `R` (rows): 2 / 3 / 4.
- The slot box auto-sizes to the widest word-group; the slot operator distributes any
word count across its `enter` / `exit` beat lists.
- **showText:false** hides all glyphs for a pure block/box look.
### Background changes once or twice (a parameter, on the beat)
```bash
# change TWICE: blue → green at 2.0s, green → ink at 3.6s
npx hyperframes render . --variables '{"program":"[{\"op\":\"lockup\",\"enter\":[0.1,0.3,0.5]},{\"op\":\"bg\",\"at\":2.0,\"theme\":1},{\"op\":\"bg\",\"at\":3.6,\"theme\":2},{\"op\":\"expand\",\"fade\":4.5,\"at\":4.8,\"to\":5.0}]"}'
```
`bg` is just another step — schedule **zero, one, or two** of them on whatever beats the
music gives you.
### Recompose freely — compose by DATA, not code (the whole point)
The five operators (`lockup`, `slot`, `bg`, `shake`, `expand`) are **pure, parameterized
functions** that write tweens at absolute audio seconds onto one shared timeline. They
are **order-independent and may overlap** (the `shake` runs _under_ the slot cycles and
the bg flip). What runs — on which beats — is the **PROGRAM** (a `{op, ...beats}` array).
So you recompose **without touching operator code**:
```bash
# Repeat the slot op three times (three word-groups), no shake, no bg flip
npx hyperframes render . --variables '{"program":"[{\"op\":\"lockup\",\"enter\":[0.1,0.3,0.5]},{\"op\":\"slot\",\"words\":[\"one\",\"two\",\"three\"],\"enter\":[1.0,1.2,1.4],\"exit\":[1.8,1.8,1.8]},{\"op\":\"slot\",\"words\":[\"four\",\"five\",\"six\"],\"enter\":[2.2,2.4,2.6],\"exit\":[3.0,3.0,3.0],\"colors\":[2,3,0]},{\"op\":\"slot\",\"words\":[\"seven\",\"eight\",\"nine\"],\"enter\":[3.4,3.6,3.8]},{\"op\":\"expand\",\"fade\":4.6,\"at\":4.9,\"to\":5.1}]"}'
```
Each step's fields are documented in [`card.json`](card.json) → `program_format`. An
agent composes by emitting this JSON (op names + beats) — it never edits JS.
> **Empty `program` = the built-in group_6 score.** Keep `program.json` and
> `DEFAULT_PROGRAM` in sync — `program.json` is the canonical, copy-pasteable data.
### Re-fit the beat to a different group (the part that changes per track)
Copy the new group's `audiomap.json` onset / downbeat seconds into the step beat lists.
Each list grows or shrinks freely — more onsets → more word pops; `beatAt()` distributes
any count across any beat list. For a longer / shorter piece set `DUR` and the root
`data-duration` to the new span. Add palettes to `THEMES`, accent colors to `ACCENTS`.
> **Deterministic / asset-free:** text + colored boxes only, no remote assets, no
> `Math.random` (shake uses a deterministic index hash), no timers. Lints clean,
> validates with no console errors.
---
## 4. Provenance
- **Source:** `bgm-golden-sample-reverse/gorup-by-group/group_6/group_6.mp4`
- **Audio:** `audiomap.json` (from `skills/bgm-to-video-new/scripts/analyze-beatgrid.py`)
- **Video read:** `group_6.gemini-analysis.md` (Gemini 3 Pro, 24fps) cross-checked by
frame-by-frame contact sheets. Both agreed this is **kinetic typography, not an image
grid** — left held `studio / contre / courant`; the right box cycled `I bring / ideas /
to life` then the colored `you / wanna / see?`; a one-frame blue→green palette flip at
f83; a global shake riding the f52–f100 hihat fill; and a box zoom-wipe to black at
f112–f114 leading into the f118 downbeat.
- **Corrections to the original read:** it is the **right slot box** (not a "left box")
that zooms out, and the text is **masked / faded** under the zoom, not a soft dissolve.
### Tuning pass — Gemini 24fps side-by-side (`renders/sidebyside_*`)
A second pass rendered the recreate, stacked it beside the source (`renders/sidebyside_src-vs-recreate_v3.mp4`), and had Gemini 3 Pro grade the diff frame-by-frame
(`renders/sidebyside_v3.gemini-analysis.md`). The source reads as **acid/brutalist
collage with strong physical inertia**; v1 read as flat/linear UI motion. Applied:
1. **Constant lean** — the whole lockup rests at `BASE_TILT -3.5°`, the slot box leans
`+2.6°` more. The source is never axis-aligned.
2. **Punchy easing + faux motion-blur** — slot words WHIP in from the right on `expo.out`
with a `scaleX` stretch (1.6→1) that fakes horizontal motion blur; exit arcs down-left
on `power3.in`. (Was a uniform, mechanical slide.)
3. **Faux-extended type** — inner `.t` span at `scaleX(1.12)` + weight 900 + tight
tracking approximates a Druk-Wide / Monument-Extended face, asset-free. Bigger size,
raised position (the lockup sits high-center).
4. **Per-line torn TAPES (not one box)** — this was the biggest "soul" gap (flagged in
both Gemini passes + frame inspection). Each slot line is now its **own tape**: a
white card sized to _its_ word (kills the dead space a shared box left behind narrow
lines), with its own micro-rotation, a stair `margin-left` offset, a torn `clip-path`,
and a drop shadow → a brutalist tape collage. The backing `#slotbox` is transparent
during word phases (tapes sit straight on the colour field), and `bg` turns it into a
solid torn card for the empty state + the expand zoom target.
5. **Brighter palette** — electric azure `#0a84ff` + lime/acid green `#5cf03a`.
6. **Stronger shake** — `amp 26px · rot 2.4° · back.out(3)` recoil around the base tilt.
(Verified rendering by diffing adjacent shake-window frames — Gemini's v3 claim that
the recreate was "static" was a low-res / anchoring misread.)
7. **Two-stage expand** — stage A grows the torn mass to ~half-frame (decelerating,
`power2.out`) so the swell is _visible_ like the source (its mass is still only
~half-frame at f113); stage B then swallows the frame (`power2.in` + blur) and flattens
to the solid black-out at ~f115, one beat before the f118 downbeat. (A single big-scale
tween covered the frame far too early, because a large rest box hits full cover at a low
scale.)
### Fix pass — review of the rendered cut
Three concrete defects spotted on playback, all fixed:
1. **Slot box covered the held words** (`courant`→`couran`, `make`→`mak`). Root cause: the
faux-extend `scaleX` does **not** change an element's _layout_ width, so (a) the anchor
glyphs rendered 12% wider than their layout box and overflowed RIGHT under the box, and
(b) the slot tapes (GSAP `scaleX` from centre) bled 6% LEFT back over the anchors — the
two overflows collided in the gap. Fixed three ways: anchors are **left-aligned** with
each row's width **pinned to its measured scaled width** (`getBoundingClientRect`), the
slot tapes scale from **`transform-origin: 0% 50%`** (rightward only). With the overflow
tamed, `#slotbox margin-left` is the **press knob**: a small **negative** value (`-0.12em`)
gives the source's tight collage TUCK — the tapes lightly press the tail of the longest
anchor (`courant`'s `t` sits right at the tape edge) while every glyph stays legible. Use
`0` for a clean kiss, more negative for a heavier tuck (too negative = white-on-white over
the glyph; a tape with a contrasting `boxInk` can press further).
2. **Slot words overflowed their tape** (`bring`→`brin`) — the faux-extend `scaleX(1.12)`
stretched only the text, not the tape background. Fixed: slot tapes carry the extend on
the **line's GSAP `scaleX`** (the background stretches _with_ the text), `.sline .t` is
reset to `scaleX(1)`, plus more right padding — the word always fits the strip.
3. **Final box was one clean block** — it should be a torn **collage of stacked, offset
rectangles**. Fixed: the box is now **three sibling `.card` layers** (each its own
offset + rotation + torn `clip-path`); they're transparent during word phases and turn
black for the empty box + the expand zoom, scaling as one while staying staggered.
- **Open questions for promotion:** (1) expose `tear` (clip-path roughness), `tilt` /
`boxTilt`, and the per-line stair offsets as params; (2) bundle a real Extended-Black
font under `assets/` for an exact type match (currently faked with `scaleX`); (3) `shake`
could auto-derive `beats` from the overlapping `rolls[]` span; (4) real motion blur isn't
available in-engine — the `scaleX` squash + expand `blur()` only approximate it; (5) the
source briefly shows an empty WHITE box before the first words / between groups — the
per-line-tape model drops that (the colour field is bare until a tape whips in), a minor
trade for killing the dead space.
File diff suppressed because one or more lines are too long
@@ -1,178 +0,0 @@
{
"id": "split-anchor-word-slot",
"name": "Split-Anchor Word-Slot · beat-synced kinetic typography",
"one_line": "ONE base lockup — a HELD left anchor column of R rows (fixed words) beside a torn-paper word-SLOT box on the right — driven by five interchangeable beat-synced operators: anchor lock-in, slot word-group cycle (in/out, per-line color), full-scene background flip, global per-beat jitter, and a box-zoom exit wipe. R (rows) and the number of background flips are data, so 2/3/4 rows and 0/1/2 flips all 'just work'.",
"status": "promoted",
"created": "2026-06-17",
"base_template": {
"primitive": "anchor_slot_lockup",
"notes": "A two-column kinetic-typography lockup. LEFT = an 'anchor' column of R held words (one per row, fixed for the whole group). RIGHT = a torn-paper 'slot' box (a colored card with a faint offset second sheet) holding up to R stacked text lines. R is derived from the `anchors` comma-list length; the box pre-builds maxRows line nodes from the program, so 2/3/4 rows follow the data with no code edit. A slot 'word-group' = the lines the box currently shows; cycling = swapping that group in/out. Asset-free: text + colored boxes only. All five operators below act on this one lockup — same DOM, different rhythmic scheduling."
},
"operations": {
"lockup": {
"intent": "establish the held stage: pop the R left anchor words in (one per beat) and reveal the empty slot box",
"anchors": "enter[] = onsets (one per anchor row, distributed); box = beat the empty box appears",
"what_moves": "per-anchor pop-in (autoAlpha + y + scale); box scale-in. Anchors then hold for the whole group.",
"source_span_sec": [0.125, 0.5],
"source_frames_24": [3, 12]
},
"slot": {
"intent": "one word-GROUP cycle inside the box — lines slide in one-per-beat, hold, then slide out (omit exit to hold)",
"anchors": "enter[] = onsets (per line); exit[] = onsets (per line, or all equal for a one-shot clear)",
"what_moves": "per-line textContent set + slide/fade in, slide/fade out. `colors[]` tints individual lines (ACCENTS index) for the multi-color look; else the theme's boxInk.",
"repeatable": true,
"source_groups": [
{
"words": ["I bring", "ideas", "to life"],
"span_sec": [1.0, 1.833],
"frames_24": [24, 44]
},
{
"words": ["you", "wanna", "see?"],
"span_sec": [2.042, 2.75],
"frames_24": [49, 66],
"colors": "blue/green/green"
}
]
},
"bg": {
"intent": "flip the whole scene to another theme on a beat (stage bg + anchor ink + box fill + slot ink invert as one 0ms hit)",
"anchors": "at = beat",
"what_moves": "backgroundColor of root + box + sheet; color of anchors + slot lines. Schedule 0/1/2 of these = background changes none / once / twice.",
"source_span_sec": [3.458, 3.458],
"source_frames_24": [83, 83],
"source_flip": "blue scene (theme 0) → green scene (theme 1)"
},
"shake": {
"intent": "global per-beat jitter of the whole lockup (x/y translate + rotation), one jolt per beat — rides a dense onset run / roll",
"anchors": "beats[] = onsets (the source's 14-hit hihat fill)",
"what_moves": "transform of #lockup (anchors + box together); each jolt is a deterministic index-hashed offset that eases back to 0 by `settle`. Runs UNDER slot/bg (overlapping ops are fine — absolute-second scheduling).",
"source_span_sec": [2.16, 4.18],
"source_frames_24": [52, 100]
},
"expand": {
"intent": "the EXIT transition — fade the text out, reset the lockup transform, then ZOOM the slot box until it fills the frame (a color wipe into the next group)",
"anchors": "fade = beat text starts fading; at = box zoom start; to = box fills the frame",
"what_moves": "anchors + slot lines fade to 0; clip-path/rotation cleared; #slotbox scales to 30× (covers 1920×1080) ending opaque full-frame. Lands the black-out just before the next downbeat kick.",
"source_span_sec": [4.3, 4.792],
"source_frames_24": [100, 115]
}
},
"match": {
"structural_type": "per_onset_sequential",
"requires": {
"energy_level": ">=MEDIUM",
"has_steady_grid": true,
"onset_gap_bars": "<=1.0"
},
"mood_fit": ["hype", "playful", "bold", "elegant"],
"span_bars": [2, 4],
"exit_trigger": ["surge", "downbeat", "hard_stop"],
"notes": "Reach for this when the section is short, has a held idea (a brand / name to anchor on the left) and a stream of discrete onsets to pop separate words on, PLUS at least one dense run (roll / hihat fill) to ride a shake on and a strong downbeat to wipe out into. The five ops map onto: lock the name → cycle a couple of word-groups per beat → invert the palette on a key hit → jitter through the busy bit → zoom-wipe on the downbeat. Variable R (rows) and 0/1/2 bg flips are data, so it fits 2/3/4-line lockups and either a single or double color shift."
},
"examples": [
{
"sample": "bgm-golden-sample-reverse",
"group": "group_6",
"bpm": 92,
"downbeats_sec": [2.322, 4.923],
"roll_sec": [2.16, 4.18],
"roll_kind": "sustained-fill",
"span_sec": [0.0, 5.41],
"rows": 3,
"bg_flips": 1,
"program": "lockup(0.125-0.5) → slot:'I bring/ideas/to life'(1.0-1.833) → slot:'you/wanna/see?'(2.042-2.75) → shake(2.16-4.18) → bg→green(3.458) → expand(4.3-4.792)"
}
],
"params": {
"bgColor": {
"type": "color",
"maps_to": "stage.background (theme 0 bg)",
"default": "#0a84ff"
},
"anchors": {
"type": "string",
"maps_to": "lockup.left_column",
"default": "studio,contre,courant",
"notes": "comma list — ONE word per row; its length sets R (rows). 2/3/4 words = 2/3/4 rows."
},
"theme": {
"type": "number",
"maps_to": "scene.base_theme",
"default": 0,
"notes": "THEMES index for the opening scene"
},
"showText": {
"type": "boolean",
"maps_to": "text.visible",
"default": true,
"notes": "false = blocks/box only, no glyphs"
},
"program": {
"type": "string",
"maps_to": "engine.program",
"default": "",
"notes": "JSON array of operator steps (see program_format). Empty = built-in group_6 score. THIS is the compose-by-data surface: reorder/drop/repeat steps, swap beats, add bg flips — no code edit."
}
},
"engine": {
"model": "operators + program-as-data (identical to poster-tile-mosaic). The 5 operators (§6 of index.html) are pure, parameterized functions that write GSAP tweens at ABSOLUTE audio seconds onto ONE paused timeline — so they are order-independent and may overlap (shake runs under slot/bg). A PROGRAM (data) lists which ops run on which beats; §7 dispatches OPS[step.op](step). Compose by editing DATA (the PROGRAM array, the `program` variable, or program.json) — never the operator code.",
"operators": ["lockup", "slot", "bg", "shake", "expand"],
"dispatch": "OPS[step.op](step) for each step in PROGRAM",
"extend": "add an operator = add a function + an OPS key; the program can then call it by name. Add themes to THEMES / accent colors to ACCENTS."
},
"program_format": {
"_": "A program is a JSON array of steps. Each step = { op, ...fields }. Beats are absolute audio seconds. theme = index into THEMES[]; colors[] = indices into ACCENTS[]. Rows (R) come from the `anchors` variable; the slot box auto-sizes to the widest word-group.",
"lockup": {
"enter": "number[] — one onset per anchor row (distributed if count != R); per-word pop-in",
"box": "number? — beat the empty slot box appears (default = last enter)",
"theme": "number? — THEMES index for the opening scene (default = base theme)"
},
"slot": {
"words": "string[] — the lines this cycle shows in the box (<= maxRows)",
"enter": "number[] — onset per line; slide/fade in",
"exit": "number[]? — onset per line to slide out; omit to HOLD the group. Equal values = a one-shot whole-group clear.",
"colors": "number[]? — ACCENTS index per line (the multi-color look); omit = theme boxInk",
"theme": "number? — THEMES index whose boxInk colors the lines (default = base theme)",
"dir": "string? — 'up' (default) | 'down' slide direction on enter"
},
"bg": {
"at": "number — beat the whole scene flips (0ms invert)",
"theme": "number — THEMES index to flip to. Add a 2nd `bg` step to change twice."
},
"shake": {
"beats": "number[] — one jolt per beat (ride a roll / dense onset run)",
"amp": "number? — translate amplitude px (default 14)",
"rot": "number? — rotation amplitude deg (default 1.5)",
"settle": "number? — seconds each jolt eases back to rest (default 0.12)"
},
"expand": {
"fade": "number — beat the text starts fading out",
"at": "number — beat the box-zoom starts",
"to": "number? — beat the box fills the frame (default at + 0.15)",
"theme": "number? — recolor the box at zoom start (default = keep current)"
}
},
"reference_impl": "index.html",
"program_data": "program.json (the default group_6 score as standalone, agent-editable data)",
"uses_primitives": [
"held_lockup",
"anchor_pop_in",
"word_slot_cycle",
"per_line_color",
"scene_palette_flip",
"beat_jitter_shake",
"box_zoom_wipe",
"freeze_hold"
],
"transition_out": {
"default": "fast_cut",
"observed": ["box_zoom_wipe", "anticipation_zoom_to_black_into_downbeat"]
},
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_6"],
"provenance": {
"video": "group_6.mp4",
"audiomap": "audiomap.json (scripts/analyze-beatgrid.py — ~92 BPM, downbeats 2.322/4.923, sustained hihat fill 2.16-4.18s)",
"video_read": "group_6.gemini-analysis.md (Gemini 3 Pro 24fps) cross-checked by frame-by-frame contact sheets. Both agreed: NOT an image grid — pure kinetic typography. Left held 'studio/contre/courant'; right box cycled 'I bring/ideas/to life' then colored 'you/wanna/see?'; blue→green hard flip at f83; global shake on the hihat fill; box zoom-wipe to black at f112-114 into the f118 downbeat. (User's original read was correct except: it is the RIGHT slot box, not a 'left box', that zooms; and the text is masked/faded out, not a soft dissolve.)"
}
}
@@ -1,186 +0,0 @@
# Typewriter Phrase / Keyword Font-Shuffle
> Reverse-engineered from **group_2** of the golden sample (the "growth through creativity." scene).
> `structural_type: per_onset_sequential` · status: **draft**
Words type in **one-per-onset** to spell a short phrase; then **one keyword** cycles
through a library of typefaces **on the beat** while the rest of the line holds dead
still. Background is pure black (the original's glitch field is an optional add-on role).
```
templates/typewriter-phrase-keyword-shuffle/
index.html ← parameterized, asset-free reference impl (1 paused GSAP timeline)
card.json ← the spec: match-face + build-face
README.md ← this file
```
---
## 1. How it beat-syncs (from `group_2.audiomap.json`)
The whole scene is nailed to the audiomap. **Nothing is on a timer** — every move is a
GSAP tween/`set` at an absolute audio-second taken straight from the analysis.
Track facts: **BPM 129.2**, 4/4, `bar_dur = 4·(60/129.2) = 1.858s`. Every move rides a
**hi-hat onset** from `audiomap.events[]` (this scene is the quiet pre-drop build — low
energy, but the hats tick continuously).
### Phase A — spell-out (typewriter, accumulating)
One word pops in per onset and **stays** (it does not replace the previous word):
| visual | audiomap anchor | `audiomap` field |
| ----------------------------- | ---------------- | ---------------- |
| `growth` pops | **0.557s** hihat | `events[1].t` |
| `through` pops | **0.906s** hihat | `events[2].t` |
| `creativity` pops (base face) | **1.231s** hihat | `events[3].t` |
| orange `.` punches in | **1.440s** hihat | `events[4].t` |
→ in the impl: `LEAD_ONSETS = [0.557, 0.906]`, `KEY_ONSET = 1.231`, `PERIOD_ONSET = 1.440`.
Each is a `fromTo(autoAlpha 0→1, scale .92→1)` ~100ms reactive pop landing on the onset.
### Phase B — keyword font-shuffle (on the beat, 0ms hard swaps)
Once the phrase is set, **only `creativity`** changes — it flips typeface on each
following onset; `growth through` and the `.` stay locked in the base face:
| visual | audiomap anchor | font preset |
| --------------------------------------- | ---------------- | ----------- |
| → upright serif | **1.904s** hihat | `FONTS[1]` |
| → heavy serif | **2.392s** hihat | `FONTS[2]` |
| → italic serif | **2.624s** hihat | `FONTS[3]` |
| → back to base bold sans, then **HOLD** | **3.088s** hihat | `FONTS[0]` |
→ in the impl: `SHUFFLE = [{t,font}, …]`. Each row is a `tl.set(keyEl, fontProps(i), t)`
— **0ms**, because a font flip is a percussive hit (the contract's `content_swap` rule:
easing a hit kills it).
### Phase C — exit
Scene ends at **3.85s**, just before the **3.855s kick** (`events[11]`, the first
`MEDIUM`→`HIGH` SURGE / drop). The phrase locks; the drop is where the _next_ group's
regime change begins. `exit_trigger: surge` (snapped to downbeat `3.808`).
> **The rule of thumb:** structure (word entries, the final lock) leans on the strong
> grid; texture (the per-beat font flips) rides the syncopated hi-hats in between.
---
## 2. Why _this beat_ → _this template_ (the matching intuition)
This is the important part. When the Music Reader emits a `GroupSignature` and you (or
the Director) look at the audiomap, **these are the tells that should make you reach for
this template:**
1. **A steady grid is present.** `has_steady_grid: true` — stable BPM, ≥2 downbeats.
Without a reliable grid you can't put one word per beat.
2. **The onset stream is CONTINUOUS, not a desert.** `onset_gap_bars: 0.28` (≪ 1 bar) —
the hi-hats keep ticking ~every 0.3–0.5s. This is the single biggest discriminator.
It means: _there is a hit available for every move you want to make_ — one per word on
the way in, then one per font-flip after.
3. **Discrete, individually-placeable onsets.** Each `events[]` entry is a clean
weak/syncopated hit → rubric step 6 → `per_onset_sequential`. Each onset can carry
exactly one reveal.
4. **A run of onsets at the head you can map to words** (Phase A) **+ a continuing tick
afterward** (Phase B). That two-part shape — _accumulate, then animate-in-place_ — is
what this template is built around.
5. **It ends on a SURGE/drop** (or hard*stop). The build resolves into something bigger,
so the scene's job is to \_fill the pre-drop bars with readable, rhythmic typography*.
Put plainly: **"steady grid + a continuous hi-hat stream + low-energy pre-drop build +
ends on a drop" is the fingerprint.** The moment you see that in the audiomap, this
template fits — you have a hit for every word and a hit for every font change.
### The contrast that makes it click
The exact same track, one group earlier (group_1), is the **opposite** signature and
wants the **opposite** template:
| | `held-message-living-field` (group_1) | `typewriter-phrase-keyword-shuffle` (group_2) |
| ----------------- | ------------------------------------- | --------------------------------------------- |
| `structural_type` | `sustained_hold` | `per_onset_sequential` |
| `onset_gap_bars` | **≥ 1.5** (onset _desert_) | **< 1.0** (continuous) |
| energy gate | `energy_level ≥ MEDIUM` | not gated (low is fine) |
| what moves | the **background** (text frozen) | the **text** (per onset / per beat) |
| because… | no onsets → nothing to hit → hold | onsets everywhere → hit everything |
So the decision is mechanical: **onset desert → hold the message; continuous onset
stream → type it / shuffle it.** Same `match.requires` predicates both sides read; see
`card.json`.
---
## 3. Usage
### Render with defaults (the group_2 recreation)
```bash
cd templates/typewriter-phrase-keyword-shuffle # or this folder
npx hyperframes lint && npx hyperframes validate
npx hyperframes render -f 24 -o renders/out.mp4
```
### Change the words (content only — no code edit)
`params` are `data-composition-variables`; fill them with `--variables`:
```bash
npx hyperframes render --variables '{
"lead1":"built", "lead2":"for", "lead3":"",
"keyword":"speed", "periodChar":".",
"accentColor":"#39e6a0"
}'
```
- **Lead words are 1–3 and optional.** Leave `lead2`/`lead3` empty to ship a 1- or
2-word lead (`""` is skipped, the line rebuilds and re-centers automatically). The
**keyword** is always the last, shuffling word.
- **`periodChar`** empty → no trailing accent dot.
### Re-fit the beat to a different group (the part that changes per track)
Content lives in `--variables`; **musical timing lives in the script** (`index.html`,
section `// 3. BEAT MAP`). When you reuse this template on a _new_ group, copy the new
group's `audiomap.json` numbers in:
```js
var LEAD_ONSETS = [ … ]; // one events[].t per lead word, in order
var KEY_ONSET = … ; // events[].t where the keyword types in
var PERIOD_ONSET = … ; // events[].t for the accent char (or remove)
var SHUFFLE = [ // one row per font-flip — add as MANY as the beat has
{ t: <events[].t or beats_sec[]>, font: <index into FONTS[]> },
…
];
var DUR = <scene end, just before the next drop/hard_stop>;
```
**You can have more (or fewer) flips than group_2's four.** `SHUFFLE` is just a list —
add a row for every beat you want a change on. Re-use a `font` index to repeat a face,
or walk new indices for a longer cycle.
### Preset more fonts
The keyword cycles the **`FONTS[]` preset library** (top of the script). It ships **8**
offline-safe faces (bold sans · upright serif · heavy serif · italic serif · monospace ·
condensed sans · light sans-italic · bold serif-italic). `FONTS[0]` is the **base** face
shared with the lead words. Add entries freely — every `{ family, weight, style }` is
valid; `fontProps(i)` wraps the index so `SHUFFLE` can point anywhere. More beats →
preset more faces and walk through them.
> **Deterministic / asset-free:** only generic font stacks (no remote/Google fonts), no
> `Math.random`, no timers — every flip is keyed to an audio second, so it renders
> identically every time. See `references/builder-contract.md`.
---
## 4. Provenance
- **Source:** `bgm-golden-sample-reverse/gorup-by-group/group_2/group_2.mp4`
- **Audio:** `group_2.audiomap.json` (from `scripts/analyze-beatgrid.py`)
- **Video read:** `group_2_text-only.gemini-analysis.md` (Gemini 3 Pro) **corrected by
frame-by-frame inspection** — the Gemini pass reported the keyword as static; pulling
real frames at each onset proved it shuffles typeface. Trust frames over sparse
sampling for per-frame detail.
- **Open question for promotion:** identify the _actual_ typefaces in the source if a
pixel-exact match is wanted (this impl reproduces the _mechanism_ with generic faces),
and decide whether to ship the glitch-field background as a second role.
@@ -1,95 +0,0 @@
{
"id": "typewriter-phrase-keyword-shuffle",
"name": "Typewriter Phrase / Keyword Font-Shuffle",
"one_line": "Words type in one-per-onset to spell a phrase, then one keyword cycles typefaces on the beat while everything else holds dead still.",
"status": "promoted",
"match": {
"structural_type": "per_onset_sequential",
"requires": {
"has_steady_grid": true,
"onset_rate": ">=1.5",
"onset_gap_bars": "<1.0",
"density": ["sparse", "medium"]
},
"mood_fit": ["hype", "glitch", "tense", "cinematic", "playful"],
"span_bars": [1, 4],
"exit_trigger": ["surge", "hard_stop", "downbeat"],
"notes": "Deliberately NOT gated on energy_level — the discriminator is a steady grid with a CONTINUOUS onset stream (no desert). This is the inverse of held-message-living-field, which requires onset_gap_bars >= 1.5 (an onset desert) and energy >= MEDIUM. If the grid goes quiet (gap >= ~1.5 bars), use a hold template instead."
},
"examples": [
{
"sample": "group_2",
"group": "g2-text-scene",
"bpm": 129.2,
"structural_type": "per_onset_sequential",
"energy_level": "VOID",
"energy": 0.13,
"density": "sparse",
"onset_rate": 2.89,
"onset_gap_bars": 0.28,
"has_steady_grid": true,
"span_sec": [0.0, 3.808],
"span_bars": 2,
"entry": { "anchor": "onset", "time": 0.046 },
"exit_trigger": { "type": "surge", "time": 3.808 },
"mood": ["tense", "cinematic"]
}
],
"roles": {
"lead_phrase": {
"kind": "message",
"motion": "per_onset_pop",
"anchor": "entry.onsets",
"notes": "1-3 words; one word pops in per hi-hat onset and ACCUMULATES (typewriter, not replace), then holds. group_2: growth@0.557 · through@0.906."
},
"keyword": {
"kind": "message",
"motion": "font_shuffle",
"anchor": "beats_after_phrase",
"notes": "PROPOSED NEW motion verb. The final word types in (base face) then cycles through the FONTS[] preset library on each subsequent beat/onset — 0ms hard swaps; holds the base face between flips and after the last one. group_2: types @1.231, period @1.440, shuffles @1.904/2.392/2.624/3.088."
},
"background": {
"kind": "background",
"motion": "hold",
"anchor": "none",
"notes": "Pure black in this reference impl (per the reverse brief). The original group_2 layered a glitch/strobe/RGB-split field here (motion: strobe / energy_envelope_breath) — an OPTIONAL add-on role, not required by the structural type."
}
},
"params": {
"bgColor": { "type": "color", "maps_to": "background.color" },
"textColor": { "type": "color", "maps_to": "lead_phrase.color + keyword.color" },
"accentColor": { "type": "color", "maps_to": "keyword.trailing_accent" },
"lead1": { "type": "string", "maps_to": "lead_phrase.word[0]", "optional": true },
"lead2": { "type": "string", "maps_to": "lead_phrase.word[1]", "optional": true },
"lead3": { "type": "string", "maps_to": "lead_phrase.word[2]", "optional": true },
"keyword": { "type": "string", "maps_to": "keyword.content" },
"periodChar": { "type": "string", "maps_to": "keyword.trailing_accent", "optional": true }
},
"beat_map": {
"comment": "Script-side constants in index.html, filled from <group>.audiomap.json. Content lives in params; musical timing lives here.",
"lead_onsets": [0.557, 0.906],
"keyword_onset": 1.231,
"period_onset": 1.44,
"shuffle": [
{ "t": 1.904, "font": 1 },
{ "t": 2.392, "font": 2 },
{ "t": 2.624, "font": 3 },
{ "t": 3.088, "font": 0 }
],
"duration": 3.85,
"font_presets": 8
},
"reference_impl": "index.html",
"uses_primitives": ["typewriter_reveal", "content_swap", "negative_space_hold"],
"transition_out": { "default": "fast_cut", "observed": "surge_drop_cut" },
"reversed_from": ["bgm-golden-sample-reverse/gorup-by-group/group_2"],
"created": "2026-06-17"
}
@@ -48,15 +48,17 @@ So `<template>` is not just a wrapper — it is the **transport container**. If
<template>
<!-- EVERYTHING the runtime needs goes here: styles, markup, scripts -->
<style>
.chart-root {
/* Root: style by #root, never a class. (At render the CSS is scoped to
data-composition-id, so a class on the root stops matching — see Pitfall 3.) */
#root {
position: absolute;
inset: 0;
color: #fff;
}
/* ... */
/* .label, #bar, … — descendants, plain selectors */
</style>
<div class="chart-root" data-composition-id="data-chart" data-width="1920" data-height="1080">
<div id="root" data-composition-id="data-chart" data-width="1920" data-height="1080">
<!-- sub-composition markup -->
</div>
@@ -83,23 +85,23 @@ Contrast with **standalone** compositions, which put the root directly in `<body
<!-- ❌ WRONG — looks normal, ships catastrophically broken -->
<head>
<style>
.chart-root { font-size: 88px; ... }
#root { font-size: 88px; ... }
</style>
</head>
<body>
<template>
<div class="chart-root" ...>...</div>
<div id="root" data-composition-id="data-chart" ...>...</div>
</template>
</body>
<!-- ✅ RIGHT — styles are inside the template -->
<!-- ✅ RIGHT — styles are inside the template, root styled by #root (see Pitfall 3) -->
<head></head>
<body>
<template>
<style>
.chart-root { font-size: 88px; ... }
#root { font-size: 88px; ... }
</style>
<div class="chart-root" ...>...</div>
<div id="root" data-composition-id="data-chart" ...>...</div>
</template>
</body>
```
@@ -133,6 +135,36 @@ Contrast with **standalone** compositions, which put the root directly in `<body
**Symptom:** the render logs `Sub-composition timelines not registered after 45000ms: <host-id>` for every mismatched slot, waits 45s per scene, then captures static initial-state frames (so the video is full-length but no animation plays).
### Pitfall 3 — Styling the root by a class instead of `#root`
```html
<!-- ❌ WRONG — class on the root, stylesheet keyed off it -->
<template>
<style>
.frame { position: absolute; inset: 0; background: #faf9f5; }
.frame .title { font-size: 120px; }
</style>
<div id="root" class="frame" data-composition-id="03-scene" ...>
<div class="title">…</div>
</div>
</template>
<!-- ✅ RIGHT — root styled by #root, descendants by plain selectors -->
<template>
<style>
#root { position: absolute; inset: 0; background: #faf9f5; }
.title { font-size: 120px; }
</style>
<div id="root" data-composition-id="03-scene" ...>
<div class="title">…</div>
</div>
</template>
```
**Why this happens:** when sub-compositions are inlined into one composited render, the compiler **scopes each file's CSS to its own `data-composition-id`** so scenes can't leak styles into each other — every rule `S` becomes `[data-composition-id="<id>"] S` (a _descendant_ selector). A rule whose leftmost selector is the **root's own class** (`.frame`) therefore becomes `[data-composition-id="<id>"] .frame`, which cannot match the root (the root _is_ the scoped element, not a descendant of it), so **every `.frame…` rule silently drops**. `#root` is special-cased by the scoper and keeps matching the root; plain descendant selectors (`.title`) match normally. The per-scene class namespace is also just redundant — the `data-composition-id` scope already isolates each scene's styles.
**Symptom:** _identical_ to Pitfall 1 — tiny unstyled text in the top-left, images at natural size, inline styles (e.g. a card background) the only thing surviving. The trap: this passes `lint`/`validate`/`inspect` (they evaluate the file in isolation, unscoped) **and looks perfect in `preview`** (Studio mounts each scene in its own iframe, also unscoped) — it only breaks in the composited MP4 render. Lint rule `subcomposition_root_styled_by_class` flags it; the registry blocks (e.g. `apple-money-count`) model the `#root` pattern.
### Verification checklist before render
```bash
@@ -145,9 +177,14 @@ grep -n "<style\|<script\|<template" compositions/<scene>.html
grep "data-composition-id" index.html
grep "data-composition-id\|__timelines\[" compositions/<scene>.html
# → all three strings must match exactly per scene
# 3) the root is styled by #root, not by a class on the data-composition-id element
grep -n 'data-composition-id=' compositions/<scene>.html
# → that element should NOT also carry a class="…" that the <style> keys off
# (e.g. `.frame { … }`); scoping drops it. Style the root via #root. See Pitfall 3.
```
For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these two pitfalls.
For the runtime end-to-end check (a fast `snapshot` pass + per-scene frame eyeball), see the **Visual smoke test** step in `hyperframes-cli`'s Minimum Completion Gate — that is the only gate that catches these three pitfalls.
## What HyperFrames Does With the Sub-Composition
-324
View File
@@ -1,324 +0,0 @@
---
name: montage
description: >
Author a beat-synced HyperFrames montage from a folder of photos/videos and a
music track — cut each segment on the music's beats and duck the music under
any clip that carries its own audio. Use when the user has (or wants) a music
track and a set of image/video assets and asks for a "montage", "music video",
"photo montage", "beat-synced" / "cut to the beat" / "rhythmic" edit, or a
slideshow driven by the music. Closes the loop from the `hyperframes beats`
CLI output to a finished composition. Docs-only recipe — no engine/runtime
changes; it builds entirely on the shipped `beats` CLI and the core
media/volume contract.
metadata:
{ "tags": "montage, beats, beat-synced, music-video, photo-montage, volume-ducking, crossfade" }
---
# montage — beat-synced montage authoring recipe
A **beat-synced montage** cuts one segment per asset on a steady beat cadence so the picture changes _feel_ the music, and ducks the background music under any clip that brings its own sound. This skill closes the loop that `hyperframes beats` (detection) and Studio beat-snapping (manual) leave open: given a folder of assets + `beats/<audio>.json`, place the cuts on beats and duck the music under each video clip.
**Read `/hyperframes-core` first** for the base composition contract (clips, tracks, `data-*` attributes, the seekable timeline). This recipe only covers what is specific to beat-driven montage: consuming the beats file, segment placement, crossfade exits, and music ducking. It introduces **no new commands** and touches **no engine/runtime code**.
## When to use this skill
Use it when the user has a music track and a set of assets and asks for any of:
- a "montage", "photo montage", "music video", or "highlight reel";
- a "beat-synced", "cut to the beat", or "rhythmic" edit;
- a slideshow/recap whose pacing should follow the music.
Do **not** use it for narrative voiceover pieces (the cadence is the speech, not the music) — that stays in `/general-video` / `/product-launch-video`. If there is no music track at all, there is nothing to sync to; ask first.
## Prerequisites
1. **One music track**, mounted as the music `<audio>`: `data-timeline-role="music"` (the `beats` CLI keys off this — or an id matching `music` / `bgm` / `soundtrack`). This is the track the montage cuts against.
2. **Assets on disk** — photos (`<img>`) and/or video clips. Video clips that carry audible sound get a sibling `<audio>` per the core media contract (see Step 4).
You need the music file present before detecting beats; the assets can be wired in either before or after.
## The loop
### Step 1 — Detect beats, read `beats/<audio>.json`
Run the shipped CLI from the project root (it spawns headless Chrome, so ensure `npx hyperframes browser ensure` first if no browser is on disk):
```bash
npx hyperframes beats # analyzes the music track in ./index.html
npx hyperframes beats --json # same, but prints { ok, file, count, bpm } as JSON
```
The command finds the music `<audio>` (first element with `data-timeline-role="music"`, else the first id matching `music|bgm|soundtrack`), detects beats, and writes:
```
beats/<audio>.json
```
The file is versioned and self-describing — **one `{ time, strength }` per beat**:
```jsonc
{
"version": 1,
"audio": "assets/bgm/track.mp3",
"beats": [
{ "time": 0.523, "strength": 0.62 },
{ "time": 1.014, "strength": 0.81 },
{ "time": 1.505, "strength": 0.43 },
// …
],
}
```
Read it at build time (the composition must stay deterministic — read the file **offline**, bake the chosen times into the HTML/timeline; never fetch it at render time):
```js
// build-time helper (runs once when authoring, NOT in the composition)
const { beats } = JSON.parse(fs.readFileSync("beats/assets/bgm/track.mp3.json", "utf8"));
// beats: Array<{ time: number, strength: number }>
```
> **0 beats is not an error to bake.** The CLI refuses to _write_ a 0-beat file (a silent/ambient track yields nothing), so a missing file means re-run detection or pick a different track.
### Step 2 — Place one segment per asset on a beat cadence
Pick a cadence — **one segment every Nth beat** — so segment boundaries land exactly on beats. `N` sets the pace:
| Cadence (every Nth beat) | Vibe | Typical BPM × N |
| ------------------------ | ------------------- | ----------------------- |
| every 1 beat | frenetic / intro | fast cuts, ≤ ~0.5s each |
| every 2 beats | energetic default | ~1s each at 120 BPM |
| every 4 beats | relaxed / cinematic | ~2s each at 120 BPM |
Then for asset `i`, assign the segment `[beats[i * N].time, beats[(i + 1) * N].time]`. Use `strength` to bias _which_ beats you cut on (cut on the strongest beats), to drop a segment on a long musical rest, or to land a hero asset on the strongest beat in the track.
```js
// build-time: turn beats + assets into concrete clip times
const N = 2; // every 2nd beat
const slots = assets
.map((asset, i) => {
const startBeat = beats[i * N];
const endBeat = beats[(i + 1) * N];
if (!startBeat || !endBeat) return null; // ran out of beats → stop
return {
asset,
start: Number(startBeat.time.toFixed(3)),
duration: Number((endBeat.time - startBeat.time).toFixed(3)),
};
})
.filter(Boolean);
const totalDuration = Number(slots[slots.length - 1].start + slots[slots.length - 1].duration);
```
Each slot becomes a `.clip` with those exact `data-start` / `data-duration`, all inside one composition whose `data-duration` is `totalDuration`. Consecutive `data-start` values are the **clip boundaries** the crossfade rule in Step 3 keys off.
### Step 3 — Crossfade segments (with the required hard kill)
Between segments, crossfade the outgoing segment's content to `opacity: 0` ending _at_ the next segment's start boundary, then **immediately hard-kill** it with a `tl.set(..., { opacity: 0 }, boundary)` at that same time.
This pair is **required**, not stylistic. The `gsap_exit_missing_hard_kill` lint rule fires whenever a GSAP exit tween (a `.to`/`.fromTo` ending in a hidden state — `opacity: 0`, `autoAlpha: 0`, `visibility: "hidden"`, or `display: "none"`) lands on a clip start boundary without a matching `tl.set`. Non-linear seeking can otherwise stop _after_ the fade and leave stale, half-visible state from the previous segment bleeding through the cut.
```js
// segment A ends at boundary B (the next segment's data-start)
tl.to("#seg-a", { opacity: 0, duration: 0.4, ease: "power2.out" }, B - 0.4);
tl.set("#seg-a", { opacity: 0 }, B); // ← the required hard kill
```
Rules of thumb:
- Animate **`opacity`** (or `autoAlpha`) for crossfades — never `visibility`/`display` on a `.clip` element (that trips `gsap_animates_clip_element`; the framework owns clip visibility).
- The hard kill must use the **same hidden state** the exit tween lands in and sit at the **same time** as the boundary (within 0.05s).
- The **final** segment has no successor boundary, so its closing fade needs no hard kill.
### Step 4 — Duck `#bgm` under each video clip, lift the clip's own `<audio>`
When a segment is a **video clip with its own sound**, duck the music under it so the clip's audio is audible, then lift the music back when the clip ends. Per the core media/volume contract, automate `volume` **on the timeline** (the runtime probes the timeline's volume keyframes and applies them identically in preview and render); `data-volume` is only the static baseline for elements no tween touches.
```js
// clip spans [clipStart, clipEnd]; music baseline is data-volume="0.9"
tl.to("#bgm", { volume: 0.15, duration: 0.3, ease: "power1.inOut" }, clipStart); // duck
tl.to("#bgm", { volume: 0.9, duration: 0.3, ease: "power1.inOut" }, clipEnd - 0.3); // lift
```
Wire the clip's sound the standard way: a muted `<video>` for the picture plus a sibling `<audio>` (same `src`, same timing) carrying the sound at `data-volume="1"`. Photo segments and silent B-roll duck nothing — leave the music at its baseline.
```html
<!-- video clip WITH sound: muted <video> for picture + sibling <audio> for sound -->
<video
class="clip"
id="seg-2-video"
src="assets/clip-2.mp4"
muted
playsinline
data-start="3"
data-duration="3"
data-track-index="2"
></video>
<audio
id="seg-2-audio"
src="assets/clip-2.mp4"
data-start="3"
data-duration="3"
data-track-index="3"
data-volume="1"
></audio>
```
## Worked example
A 9-second, 3-segment montage over a music bed. Beats land every ~1.5s, so every-2nd-beat gives 3s segments at boundaries **3.0s** and **6.0s**. Segment 2 is a video clip with its own audio, so the music ducks under it. This file passes `npx hyperframes lint` with 0 errors once the referenced asset files exist (the `assets/*` paths are placeholders — drop your own media in; lint treats missing local media as errors, not warnings).
```html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Beat-synced montage</title>
</head>
<body style="margin: 0">
<div
data-composition-id="montage"
data-start="0"
data-duration="9"
data-width="1920"
data-height="1080"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden; background: #0a0a0a"
>
<!-- Music bed: a direct child of the root composition (the media contract —
media is never nested in a sub-comp/wrapper). data-timeline-role="music"
is what `hyperframes beats` targets; data-volume="0.9" is the static
baseline the timeline automates. -->
<audio
id="bgm"
src="assets/bgm/track.mp3"
data-start="0"
data-duration="9"
data-track-index="0"
data-volume="0.9"
data-timeline-role="music"
></audio>
<!-- Segment 1 — photo, beats[0] → beats[2] (0.0s → 3.0s) -->
<section
class="clip"
id="seg-1"
data-start="0"
data-duration="3"
data-track-index="1"
style="position: absolute; inset: 0"
>
<img
id="seg-1-img"
src="assets/clip-1.jpg"
alt=""
style="width: 100%; height: 100%; object-fit: cover"
/>
<h2
id="seg-1-cap"
style="position: absolute; left: 80px; bottom: 80px; margin: 0; font-family: sans-serif; font-size: 64px; color: #fff"
>
Sunrise
</h2>
</section>
<!-- Segment 2 — video clip WITH its own audio, beats[2] → beats[4] (3.0s → 6.0s) -->
<video
class="clip"
id="seg-2-video"
src="assets/clip-2.mp4"
muted
playsinline
data-start="3"
data-duration="3"
data-track-index="2"
style="position: absolute; inset: 0; width: 100%; height: 100%; object-fit: cover"
></video>
<audio
id="seg-2-audio"
src="assets/clip-2.mp4"
data-start="3"
data-duration="3"
data-track-index="3"
data-volume="1"
></audio>
<!-- Segment 3 — photo, beats[4] → beats[6] (6.0s → 9.0s) -->
<section
class="clip"
id="seg-3"
data-start="6"
data-duration="3"
data-track-index="4"
style="position: absolute; inset: 0"
>
<img
id="seg-3-img"
src="assets/clip-3.jpg"
alt=""
style="width: 100%; height: 100%; object-fit: cover"
/>
<h2
id="seg-3-cap"
style="position: absolute; left: 80px; bottom: 80px; margin: 0; font-family: sans-serif; font-size: 64px; color: #fff"
>
Nightfall
</h2>
</section>
</div>
<script src="https://cdn.jsdelivr.net/npm/gsap@3/dist/gsap.min.js"></script>
<script>
window.__timelines = window.__timelines || {};
const tl = gsap.timeline({ paused: true });
window.__timelines["montage"] = tl;
// Segment starts land on every 2nd beat: 0.0, 3.0, 6.0. Each outgoing
// segment crossfades to opacity:0 at the next boundary (3.0, 6.0), so each
// fade-out gets a matching tl.set "hard kill" at that boundary — the
// gsap_exit_missing_hard_kill rule. The final segment's closing fade has no
// successor boundary, so it needs no hard kill.
// Segment 1 out → boundary 3.0
tl.to("#seg-1", { opacity: 0, duration: 0.4, ease: "power2.out" }, 2.6);
tl.set("#seg-1", { opacity: 0 }, 3.0);
// Segment 2 out → boundary 6.0
tl.to("#seg-2-video", { opacity: 0, duration: 0.4, ease: "power2.out" }, 5.6);
tl.set("#seg-2-video", { opacity: 0 }, 6.0);
// Final segment fades out at the end (no boundary → no hard kill).
tl.to("#seg-3", { opacity: 0, duration: 0.4, ease: "power2.out" }, 8.6);
// Duck #bgm under segment 2's video clip (it carries its own audio), then
// lift back to the data-volume="0.9" baseline. The runtime probes these
// volume keyframes and applies them identically in preview and render.
tl.to("#bgm", { volume: 0.15, duration: 0.3, ease: "power1.inOut" }, 3.0);
tl.to("#bgm", { volume: 0.9, duration: 0.3, ease: "power1.inOut" }, 5.7);
</script>
</body>
</html>
```
### What the example demonstrates
- **`data-timeline-role="music"`** on `#bgm` is the hook the `beats` CLI detects against — and `#bgm` is the duck target.
- **Segment boundaries (3.0, 6.0)** are the next clips' `data-start` values; the crossfade fade-outs end on them and each is followed by a `tl.set(..., { opacity: 0 }, boundary)` hard kill.
- **`opacity`** is animated for crossfades — never `visibility`/`display` on a `.clip` (the framework owns clip visibility).
- **`volume` is automated on the timeline**, not by swapping `data-volume`; `data-volume="0.9"` stays the static baseline the lift returns to.
- **The video clip's sound** rides a sibling `<audio>` (muted `<video>` for picture, `<audio>` for sound) — the core media contract.
## Validation
After authoring or editing a montage composition, run:
```bash
npx hyperframes lint # must report 0 error(s) — block on the hard-kill + clip-visibility rules
npx hyperframes validate # headless runtime check — catches missing assets / JS errors
```
Treat both as blockers. The two rules most likely to fire while iterating this recipe:
- `gsap_exit_missing_hard_kill` — a crossfade ends on a clip boundary without the matching `tl.set`. Add the hard kill (Step 3).
- `gsap_animates_clip_element` — you animated `visibility`/`display` on a `.clip`. Move that content into a child `<div>` and target that, or use `opacity`.
When the cut feels off, the fix is almost always the cadence (`N`) or which beats you cut on (favor `strength`) — not the animation. Re-read the beats file and rebake the segment times.
+189
View File
@@ -0,0 +1,189 @@
---
name: music-to-video
description: "Use when the user has a music track (an audio file, or a video to pull audio from) and wants a beat-synced HyperFrames video, calm to hard-hitting. The music drives everything: one analyzer reads it once, the orchestrator lays out the frames and fills a per-frame plan, and one sub-agent builds each frame. Typography and templates are the floor — a complete video needs zero assets — but any images or videos the user supplies are cut into the frames on the same beat grid (beat-cut / ken-burns). The genre (lyric video, slideshow, kinetic promo) falls out of the per-frame choices; the pipeline never branches on it."
---
# music-to-video — one music-grounded, beat-synced video workflow
Use this skill to turn a **music track** into a beat-synced HyperFrames video. You analyze the track once, lay out the frames, fill in a per-frame plan, and build each frame as a composition. The input is a music track plus optional user images or videos — there is **no narration and no website capture**. Typography and templates are the floor (a complete video needs zero assets); any media the user supplies is cut in on the same beat grid.
You are the **orchestrator**. Work in `videos/<project>/`. Run the steps in order and pass each **Gate** before moving on. Two steps need the user: **Step 3** (plan approval) and **Step 6** (render approval). Do every step yourself except **Step 4**, where you dispatch **one sub-agent per frame**. Keep design and motion rules out of this file — they live in `references/` and the `frame-worker` sub-agent.
`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos/<project-name>/`.
Workflow: Step 0 setup → `hyperframes.json` + `assets/bgm.mp3`; Step 1 analyze → `audiomap.json`; Step 2 skeleton → `STORYBOARD.md` (frames, groups `TBD`); Step 3 plan → complete `STORYBOARD.md` + `frame.md`; Step 4 build → `compositions/frames/NN-*.html`; Step 5 assemble → `index.html`; Step 6 render → `renders/video.mp4`.
## Two ideas that shape everything
- **One analyzer, and you trust it.** `analyze-beatgrid.py` is the only beat analyzer — never re-measure beats with another tool or by ear. Its energy / density / rolls / onsets / silences are always reliable. Its `bpm` and `beats_sec` are reliable **only when the music is genuinely rhythmic**; on calm music the grid is a metronome the tracker imposed, so pace by phrases and energy instead and never hard-cut to it. Deciding which case you're in is each frame's `pacing` (Step 2).
- **One frame = one file; groups live inside.** Step 2 cuts the track into **frames**, and each frame becomes one composition file `compositions/frames/NN-<frame_id>.html`, built by one frame-worker. A frame can subdivide into **groups** (each a template or a motion-primitives combo). Extra density goes *inside* a group, so **frame count tracks distinct treatments, not beats** — a fast track does not blow up the number of sub-agents.
---
## Step 0: Setup, BGM, and inputs
Goal: Create the HyperFrames project, set the music as the source, and note any user-supplied media.
Initialize only if `hyperframes.json` is missing. Name `<project>` from the brief in kebab-case, such as `midnight-drive-loop` — never a timestamp. The **music is the spine**: copy it to `assets/bgm.mp3` (extract the audio from a video first if the user handed you one). If the user supplied images or videos, stage them so frames can weave them in on the beat grid; if not, typography carries the whole video.
```bash
npx hyperframes init "videos/<project>" --non-interactive --skip-skills --example=blank
mkdir -p "$PROJECT_DIR/assets" "$PROJECT_DIR/renders"
cp "<user-music>" "$PROJECT_DIR/assets/bgm.mp3" # extract from a video first if needed
# only if the user gave you images/videos:
node <SKILL_DIR>/scripts/stage-assets.mjs --from <dir> --hyperframes "$PROJECT_DIR" --into public
```
The **brand** (font + palette) is chosen at Step 3, not here. Don't pick a genre or a track type up front — assets are just an optional ingredient, and the genre emerges from the per-frame choices.
**Gate:** `hyperframes.json` + `assets/bgm.mp3` exist; aspect / length / fps and (if any) the asset inventory are noted.
---
## Step 1: Analyze the music
Goal: Produce the one canonical timing analysis the whole video is built on.
`analyze-beatgrid.py` is the **only** beat analyzer — never re-measure beats with another tool or by ear. It reads the track once and writes `audiomap.json`: energy phases (level / density / feel), onsets + `onset_rate`, rolls, silences, `hard_stops`, `key_moments`, phrases, tempo / grid, and `audio.duration_sec`. It's deterministic — the same file always gives the same map. Most fields are reliable on any music; `bpm` and `beats_sec` are reliable only when the music is genuinely rhythmic, and judging that is the call you make at Step 2.
```bash
python3 <SKILL_DIR>/scripts/analyze-beatgrid.py "$PROJECT_DIR/assets/bgm.mp3" \
-o "$PROJECT_DIR/audiomap.json" --print
```
**Gate:** `audiomap.json` exists; `audio.duration_sec` is known.
---
## Step 2: Frame skeleton
Goal: Read the music and lay out the frames — the skeleton of `STORYBOARD.md`.
Read [`references/frame-skeleton.md`](references/frame-skeleton.md). Turn `audiomap.json` into the **skeleton** of `STORYBOARD.md` yourself — there is no intermediate JSON. Cut the track into **frames** at real musical changes (`hard_stops`, SURGE / DROP `key_moments`, the edges of a roll, a stretch with no onsets, a big energy jump), snapping every boundary to an audiomap anchor. For each frame set `span_sec`, `pacing` (the verdict from Step 1's trust call — `beat_cut` when the grid is real, `phrase_flow` when it's a metronome imposed on calm music), `mood`, and a one-line `feel` (the plain music situation Step 3 matches a template against). Only classify and lay out here: leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank — no templates, copy, color, or fonts. Expect ~1–6 frames.
**Gate:** frames tile the track (first at 0, last at `duration_s`); each carries `span_sec` + `pacing` + `mood` + `feel`; every `### Groups` is `TBD`; no content anywhere.
---
## Step 3: Plan (user-gated)
Goal: Turn the skeleton into an approved, complete `STORYBOARD.md`.
Read [`references/planning.md`](references/planning.md), [`storyboard-format.md`](references/storyboard-format.md), [`template-catalog.md`](references/template-catalog.md), [`motion-primitive-catalog.md`](references/motion-primitive-catalog.md), and [`montage.md`](references/montage.md) (only if the user supplied assets). Editing the same file in place, do two things:
1. **Pick the brand.** Choose one preset from `../hyperframes-creative/frame-presets/` using the table in `../hyperframes-creative/references/design-spec.md` (match the track's mood; **only its fonts and colors matter** — templates own composition). Copy it into `frame.md` **unmodified** and fill the frontmatter `style` (font + a ≤4–6 swatch palette) from it.
2. **Fill every frame.** Decide its groups and give each a treatment: a matched template from the catalog (with bound params and real audiomap anchors), a free-compose from the primitive catalog, or an asset treatment that **obeys `pacing`**. Write the copy. You own WHAT (template / primitives + content + anchors); the frame-worker owns HOW — **never write millisecond tweens into the storyboard**.
```bash
node <SKILL_DIR>/scripts/validate-plan.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--audiomap "$PROJECT_DIR/audiomap.json" --templates <SKILL_DIR>/references/templates
```
Fix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then show the user a frame-by-frame summary and iterate until they approve.
**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan.
---
## Step 4: Build frames
Goal: Build every frame as a self-contained composition file.
Create `compositions/frames/`. Read [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) and `../hyperframes-core/references/subagent-dispatch.md`. Dispatch **one frame-worker per frame**, in parallel where possible (otherwise in waves). Each worker gets exactly one frame and this context:
```text
PROJECT_DIR: <abs path>
frame_id: <NN-frame_id> # = the frame file stem, e.g. 02-f2; the composition id
Your block: the `## Frame N — <frame_id>` block in PROJECT_DIR/STORYBOARD.md
audiomap: PROJECT_DIR/audiomap.json
frame.md: PROJECT_DIR/frame.md
Materials: for each group, <SKILL_DIR>/references/templates/<id>/index.html (templates) and
<SKILL_DIR>/references/motion-primitives/<id>/ (free); staged assets/ (asset groups)
Contracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md
Canvas: <w>×<h> Pacing: <beat_cut|phrase_flow>
Write to: PROJECT_DIR/compositions/frames/<frame_id>.html
```
The worker forks the cited materials, converts every anchor to frame-local seconds (`local_t = track_t − span_sec[0]`), gates its groups with 0ms cuts, and writes one seek-safe frame file. **The worker never runs the `hyperframes` CLI** — those commands operate on the assembled project, which doesn't exist yet, so they'd report on the wrong files. The worker just writes to the contract and stops; you verify after assembly (Step 6). As each worker returns, you can confirm its file landed on disk.
**Gate:** every frame has its `compositions/frames/NN-*.html` on disk.
---
## Step 5: Assemble
Goal: Wire the built frames + BGM into the playable `index.html`.
`assemble-index.mjs` is deterministic — no subagent, no judgment. It references each frame file at its cumulative `data-start`, mounts `assets/bgm.mp3` on track 11, and hard-cuts frame → frame (frames tile the track with no gaps, so there is **no transition injector**).
```bash
node <SKILL_DIR>/scripts/assemble-index.mjs --storyboard "$PROJECT_DIR/STORYBOARD.md" \
--hyperframes "$PROJECT_DIR" --audiomap "$PROJECT_DIR/audiomap.json"
```
Fix any `✗` it reports — a missing or blank frame file means that worker wrote a partial file; re-dispatch it (Step 4) and re-assemble.
**Gate:** `index.html` exists; total duration == `audiomap.audio.duration_sec`.
---
## Step 6: Verify and render
Goal: Verify the assembled video, get user approval, and render the final MP4.
Run the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `lint` checks structure, `validate` runs headless Chrome (catching JS errors and missing assets), `inspect` snapshots frames.
```bash
( cd "$PROJECT_DIR" && npx hyperframes lint . && npx hyperframes validate . && npx hyperframes inspect . )
```
Inspect at `t=0`, each frame start, the strongest DROP / SURGE, every `hard_stops[].t`, and the final frame. On failure, make the **cheapest safe fix**: edit the offending `compositions/frames/NN-*.html` for a local issue; **re-dispatch that one frame-worker** only when a whole frame must be rebuilt; go back to Step 3 only if the plan is creatively wrong. Never change duration or audio timing to hide a sync issue. Once the gates pass, pause for user review, then render only on approval:
```bash
( cd "$PROJECT_DIR" && npx hyperframes render . -q draft -o renders/video.mp4 --fps 30 )
```
**Gate:** `lint` / `validate` / `inspect` passed; the user approved; `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.
---
## Resume table
| You have | Continue from |
| -------------------------- | ------------- |
| `assets/bgm.mp3` only | Step 1 |
| `audiomap.json` | Step 2 |
| `STORYBOARD.md` (skeleton) | Step 3 |
| `STORYBOARD.md` (complete) | Step 4 |
| all frame files | Step 5 |
| `index.html` | Step 6 |
## Quick Reference
**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the canvas once in the storyboard frontmatter (`canvas: { w, h, fps }`).
**Scripts** under `scripts/`: `analyze-beatgrid.py` (the one analyzer), `validate-plan.mjs` (plan check), `assemble-index.mjs` (index assembly), `stage-assets.mjs` (stage user media), `lib/storyboard.mjs` (vendored parser). Everything else is the `hyperframes` CLI.
| Read | When |
| ------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| [`references/frame-skeleton.md`](references/frame-skeleton.md) | Step 2: read the music, lay out the frames, set pacing |
| [`references/planning.md`](references/planning.md) · [`storyboard-format.md`](references/storyboard-format.md) | Step 3: pick the brand, fill each frame, write the plan |
| [`references/template-catalog.md`](references/template-catalog.md) | Step 3: pick a template per group |
| [`references/motion-primitive-catalog.md`](references/motion-primitive-catalog.md) | Step 3/4: L0 recipes for free-compose |
| [`references/montage.md`](references/montage.md) | Step 3/4: asset treatments (beat-cut / ken-burns) |
| [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) | Step 4: dispatch + build one frame |
| `../hyperframes-core/references/subagent-dispatch.md` | Step 4: dispatch sub-agents safely |
| `../hyperframes-creative/references/design-spec.md` | Step 3: pick the preset (the brand) |
## Directory layout
```
music-to-video/
SKILL.md
references/ frame-skeleton.md · planning.md · storyboard-format.md
template-catalog.md · motion-primitive-catalog.md · montage.md
templates/<id>/ { index.html (+ assets/ · program.json) } ← L1 catalog impls
motion-primitives/<id>/ { index.html } (+ shared assets/gsap.min.js) ← L0 catalog impls
scripts/ analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs
sub-agents/ frame-worker.md ← the one subagent (one per frame)
```
@@ -0,0 +1,94 @@
# Frame skeleton (Step 2) — read the music, lay out the frames
At Step 2 **you (the orchestrator)** read `audiomap.json` and write the **skeleton** of
`STORYBOARD.md` directly: cut the track into **frames** (one frame = one composition file =
one scene), and for each frame set its **span**, its **pacing** (does this stretch want hard
beat-cuts, or calm phrase/energy flow?), its **mood**, and a one-line **feel** note.
You **classify and lay out the spine only.** You do **not** pick templates, write copy, choose
colors/fonts, or decide a frame's groups — those are Step 3 (the plan fills each frame in
place). Leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank.
There is **no intermediate JSON** — the skeleton _is_ the start of `STORYBOARD.md`. Step 3
edits the same file.
## The trust boundary (read this first)
`audiomap.json` is one analyzer's output. Some fields are robust on **any** music; some are
reliable only when the music is **actually rhythmic**. This decides each frame's `pacing`:
| Field | Trust |
| --- | --- |
| `energy_phases[]` (level / energy / density / feel), `events[]` + `onset_rate`, `rolls[]` (and their **absence**), `silences[]`, `hard_stops[]`, `key_moments[]`, `phrases[]`, `audio.duration_sec` | **Always** — robust measurements |
| `tempo.bpm`, `grid.beats_sec` / `downbeats_sec` **precision** | **Only when the music is rhythmic.** On calm / sparse material the beat grid is a metronome the tracker *imposes* (often octave-doubled) — usually **more grid beats than real onsets**. Do **not** anchor cuts to it there. |
- **Grid is reliable** when: rolls present, and/or dense phases, and/or high `onset_rate` with a steady grid.
- **Grid is fictional** when: `rolls`≈0, mostly `sparse` phases, low `onset_rate` → pace by `phrases[]` + `energy_phases[]`, not beats.
## How to lay out frames (run in order)
1. **Gestalt.** From `summary` / `tempo` / `audio.duration_sec` + the roll count, write the
frontmatter `compositionId`, `duration_s` (== `audio.duration_sec`), `canvas`, and a
one-line read of the track's density arc.
2. **Cut into frames.** Walk `energy_phases[]` and split where the music genuinely changes
state — at `hard_stops[]`, `SURGE` / `DROP` `key_moments`, the start/end of a `rolls[]` run,
an **onset desert** (a long gap in `events[]`), or a big energy-level jump. Collapse adjacent
phases that are one gesture. Expect **~1–6 frames**; a short clip may be one.
**Snap every boundary to an audiomap anchor**, then re-snap to the nearest `beats_sec`
(tolerance ≤ ½ beat) **only when the grid is reliable**; on calm material snap to
`phrases[]` / `energy_phases[]` edges instead. Frames **tile the track** (first at 0, last
at `duration_s`, no gaps/overlaps).
3. **Per frame, set `pacing`** — the trust-boundary call:
- **`beat_cut`** — genuinely rhythmic: a roll present, **or** dense, **or** (clearly high `onset_rate` **and** a steady grid). Hard cuts / per-onset reveals may anchor to beats.
- **`phrase_flow`** — calm / sparse: `rolls`≈0, mostly sparse, low `onset_rate`. Do **not** anchor hard cuts to the grid; pace by `phrases[]` + the energy envelope (slow crossfades, long holds).
4. **Per frame, tag `mood`** (1–3 of: `warm` · `dark` · `hype` · `elegant` · `glitch` ·
`cinematic` · `playful` · `tense` · `dreamy` · `aggressive`) from `energy_phases[].feel` +
energy + any genre cue in the brief/title.
5. **Per frame, write a one-line `feel`** — the plain-language music situation Step 3 matches a
template against (e.g. "accelerating onset stream into a held downbeat", "calm held pad, one
onset desert", "fast sustained-fill roll, no readable message"). This is what the planner
reads against the catalog's **Reach for it when** — keep it concrete, drawn from the robust
fields, never invented.
## What the skeleton looks like
A valid `STORYBOARD.md` with the spine set and every frame's treatment left for Step 3
(full syntax in [`storyboard-format.md`](storyboard-format.md)):
```markdown
---
compositionId: bgm
duration_s: 30.0 # == audiomap.audio.duration_sec
canvas: { w: 1920, h: 1080, fps: 30 }
style: # blank — Step 3 fills it from the chosen frame.md preset
build_notes: ["one paused timeline per frame", "no remote assets"]
---
## Frame 1 — f1
- src: compositions/frames/01-f1.html
- duration: 7.198s # = span length; assembler sums these for cumulative data-start
- span_sec: [0.0, 7.198] # track seconds; frames tile the track
- pacing: beat_cut
- mood: [hype]
- feel: accelerating onset stream building into a held downbeat
### Groups
- TBD (Step 3)
## Frame 2 — f2
- src: compositions/frames/02-f2.html
- duration: 10.4s
- span_sec: [7.198, 17.598]
- pacing: phrase_flow
- mood: [warm, cinematic]
- feel: calm held pad, one long onset desert
### Groups
- TBD (Step 3)
```
## Self-check
- `duration_s == audiomap.audio.duration_sec`; frames tile the track gap-free (first at 0, last at `duration_s`).
- Every frame has `src` + `span_sec` + `duration` + `pacing` + `mood` + a one-line `feel`.
- `pacing` was set from the **robust** fields (energy / density / rolls / onset_rate), never from `bpm` / `beats_sec` alone.
- No frame boundary sits inside a `rolls[]` run or leaves a sub-1-bar fragment.
- Every frame's `### Groups` is `TBD (Step 3)`; `style` is blank. **No template, copy, color, or font anywhere.**
@@ -0,0 +1,55 @@
# Asset treatments — weaving user media onto the beat spine
When the user supplies images/videos, a group can be an **asset treatment** instead of a
typographic template/free-compose. Assets are an **additive ingredient on the same beat
spine** — never a separate pipeline. Typography/templates stay the floor: if no asset fits a
group, fall back to a template/free group (a complete video needs zero assets).
The planner (Step 3) picks the treatment and the clips + anchors (WHAT); the frame-worker
realizes it inside the frame file (HOW). **Obey the frame's `pacing`.**
## The three treatments
### `beat_cut` — one clip per anchor (only on a `beat_cut` frame)
The asset-driven analogue of a per-onset typographic group: cut to a new clip on each anchor
(the frame's beats/onsets from the audiomap). Each clip is a `class="clip"` element
(`<img>` for a photo, **muted** `<video>` for a motion clip) placed at its anchor with
`data-start`/`data-duration`/`data-track-index` per the core clip contract. Between clips,
crossfade the outgoing content to `opacity:0` ending **at** the next anchor, then immediately
**hard-kill** with a `tl.set(..., {opacity:0}, anchor)` — this pair is required (the
`gsap_exit_missing_hard_kill` lint rule; non-linear seeking otherwise bleeds stale frames).
Cut on the **strong** anchors; land a hero clip on a `key_moment`/downbeat.
### `ken_burns` — slow push on one clip (fits a `phrase_flow` frame)
For calm frames: one clip held over the span with a slow scale/translate push (e.g. scale
1.0→1.08 + a small drift) eased across the whole `span_sec` — paced by the frame, not by
beats. No hard cuts. Crossfade in/out at the frame edges. This is the right asset treatment
when the beat grid is unreliable (calm music).
### `bg_under_text` — clip dimmed behind a template/free group
A full-bleed clip dimmed ~30–50% as the background of a group whose foreground is a template
or free-compose typographic treatment. The text rides on the same anchors; the clip is the
bed. Use when the user wants their footage present but the message must stay readable.
## Rules
- **`pacing` decides the treatment**: `beat_cut` only on a `beat_cut` frame; on a
`phrase_flow` frame use `ken_burns` or a slow crossfade — **never** per-onset hard cuts on
the (unreliable) calm grid.
- **Clips are muted; the root owns audio.** Mount each `<video class="clip">` **muted**, as a
direct child of the frame root (never nested in another timed element, or the renderer
freezes it). The BGM is the only audio in v1.
- **Crossfades animate `opacity`/`autoAlpha`**, never `visibility`/`display` on a `.clip`
(the framework owns clip visibility — that trips `gsap_animates_clip_element`).
- **Backgrounds dim ~30–50%** so any foreground text stays legible.
- Anchors are **track seconds from `audiomap.json`**; the worker subtracts the frame start
to get frame-local time.
- Local staged assets only (`assets/` via `stage-assets.mjs`); never remote URLs.
## Deferred hook (not v1)
A clip that should play **its own sound** (interview cut, lyric clip) needs a sibling
`<audio>` mounted at the **root** by the assembler, with the BGM ducked under it (timeline
volume automation: `tl.to("#el-bgm",{volume:0.15,…},clipStart)` … `tl.to(…,{volume:0.9,…},
clipEnd)`). The frame-worker mounts no audio. Keep clips muted in v1; wire clip-audio +
ducking only when the user asks.
@@ -0,0 +1,95 @@
# Motion-primitive catalog — the free-compose menu
The atomic layer: one anchor → one micro-move. Templates ([`template-catalog.md`](template-catalog.md))
are built from these; when no template fits a group, the planner **free-composes** by naming
primitives from here, and the frame-worker realizes them. Two readers, one file:
- **Planner (Step 3)** — scan **what it does** + **anchor** to pick the primitives a free group rides. Selection only.
- **Frame-worker (Step 4)** — open the cited recipe and lift its tweens. Build only.
The **recipe** column says what to lift:
- **✓** — a runnable, lint-clean composition at `motion-primitives/<id>/index.html`. Open it and lift the tweens.
- **≈ `<id>`** — no separate file; use that recipe, it's the same idea.
- **—** — no file; implement inline from the description (a one-liner, e.g. a 0ms `tl.set`, or a move a template realizes internally).
## Timing & latency (applies to every primitive)
Quantified from frame-accurate reverse engineering of beat-synced reels:
- **Hard hits are 0ms.** Cuts, palette flips, content swaps, freezes are `tl.set(...)` with no duration — the percussion _is_ the motion. Easing a hit kills it.
- **Lead the anchor.** A move that must _land_ on a beat (a wipe covering the frame, a count-up locking, two blocks colliding) starts **~40–190ms early** so it completes ON the anchor. Reactive entrances (something appearing _because_ of the hit) fire 0–45ms after.
- **Eased entrances: 300–500ms** (scale punch, slides, camera pushes). **Macro builds: 800–2000ms** spanning a whole roll / silence.
- **Magnitudes:** scale-punch 0→1; weight pulse 1→1.06; hero fill up to 1→5; chromatic split ~20px, resolve clean in ≤150ms.
- **Per-bar caps:** one accumulating element per hit (not a burst); a camera move at most once per phrase, never per beat; a dense flip/strobe system runs ≤2–3s.
- **Tension-builds lock.** A count-up / sequential build / morph must _resolve on_ a downbeat or hard_stop, never trail off mid-bar.
## Catalog
Each runnable recipe is self-contained and lint-clean: showcase chrome stripped, system-font
fallback, shared `../assets/gsap.min.js`, one paused timeline on `window.__timelines["main"]`.
| id | anchor | what it does | recipe |
| -------------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| `hypercut-whip` | beat / hard_stop | fast whip-pan hard cut between frames | ✓ |
| `kinetic-letter-in` | downbeat / phrase | per-letter kinetic entrance | ✓ |
| `braam-punch` | drop / surge | big "braam" impact — scale + weight slam | ✓ |
| `chromatic-split` | snare / glitch / surge | RGB channel split / glitch on a word | ✓ |
| `mask-reveal` | section_start / downbeat | clip-path mask wipe reveal | ✓ |
| `screen-shake` | drop / crash / kick | camera / screen shake jitter | ✓ |
| `binary-decrypt` | roll / build | scramble→decode text (binary → word) | ✓ |
| `dolly-zoom` | phrase / build | vertigo dolly-zoom (scale vs perspective) | ✓ |
| `iris-open` | section_start / reveal | circular iris-open reveal | ✓ |
| `electric-arc` | accent / glitch | electric arc / lightning accent | ✓ |
| `neon-flicker` | hold / texture | neon-sign flicker | ✓ |
| `chrome-sweep` | downbeat / reveal | metallic specular sweep across text | ✓ |
| `slot-machine-reveal`| roll → downbeat | slot-machine spin-to-land character reveal | ✓ |
| `liquid-morph` | phrase / transition | liquid / blob morph | ✓ |
| `gooey-metaball` | build / drop | gooey metaball merge field | ✓ |
| `3d-card-flip` | downbeat / swap | 3D card flip (rotateY) | ✓ |
| `crash-zoom-in` | drop / surge | violent crash zoom-in | ✓ |
| `spotlight-sweep` | reveal / hold | spotlight / gradient sweep over text | ✓ |
| `outline-to-fill` | downbeat / reveal | stroke outline → solid fill | ✓ |
| `counting-punch` | roll → downbeat | number count-up that punches & locks | ✓ |
| `particle-burst` | drop / crash | particle explosion burst | ✓ |
| `radial-burst-lines` | drop / surge | radial speed-lines burst | ✓ |
| `pixel-dissolve` | transition / hard_stop | pixelated dissolve | ✓ |
| `datamosh-smear` | glitch / transition | datamosh / motion smear | ✓ |
| `text-wave-distort` | hold / texture | wavy text distortion | ✓ |
| `bg-flow-field` | energy / whole span (bed) | generative WebGL curl-noise flow-field **background bed** — palette-driven, breathes on the energy envelope; compose any foreground move over it | ✓ |
| `blur-resolve` | stop / final hold | blur-in to crisp focus, then blur-out on the cut | ✓ |
| `chromatic-pressure` | snare / glitch | RGB split / digital tension on a transient | ≈ `chromatic-split` |
| `color-grid-shuffle` | onset | grid of cells recoloured by a deterministic index per onset | — |
| `content-swap` | beat | 0ms swap of stacked nodes — the workhorse percussive move | ≈ `slot-machine-reveal` |
| `directional-fill` | beat / reveal | directional wipe-fill (scaleX) sweeping across bars | ✓ |
| `flash-cut` | drop / crash | full-frame flash masking a word / colour state change | ✓ |
| `freeze-hold` | hard_stop | freeze the moving system and hold it (desaturate + vignette) | — |
| `hard-cut` | beat / hard_stop | sample-accurate 0ms colour-block + word cut | ✓ |
| `mosaic-pack` | beat / build | scattered tiles fly in and pack into a grid | ✓ |
| `negative-space-hold`| silence / hard_stop / final hold | kill busy layers, hold one readable mark in empty space | — |
| `overlay-pop` | accent | badge / lower-third overlay pops in over a base | — |
| `palette-flip` | section change | same layout re-skins via 0ms palette-variable flips | ✓ |
| `staggered-exit` | phrase / transition | ordered cascade-out clearing the frame | ✓ |
| `staggered-reveal` | build | ordered cascade-in of a stack / list | — |
| `system-replace` | drop / regime change | hard-cut the entire visual system, then boot the new one | — |
| `text-spectral-rays` | phrase / sweep (hero text) | volumetric spectral light-rays cast by a wordmark toward a sweeping light cursor — grain + RGB-split; **WebGL hero-text system** | ✓ |
| `tile-mosaic` | build / reveal | grid of tiles revealed in a diagonal sweep, assembling a poster | ✓ |
| `typewriter-reveal` | roll / build | char / word type-on, explicit per-span set (no `stagger`) + caret | ✓ |
| `value-counter` | roll → downbeat | count-up that locks on a downbeat / hard_stop | ≈ `counting-punch` |
| `word-grid-burst` | onsets → downbeat | grid of words revealed per onset, refocus one on a downbeat | ✓ |
> **Template-private verbs.** Some templates declare moves realized only inside their own
> impl — `held_lockup`, `anchor_pop_in`, `word_slot_cycle`, `per_line_color`,
> `scene_palette_flip`, `beat_jitter_shake`, `box_zoom_wipe` (`split-anchor-word-slot`),
> `motion-blur` (`logo-split-lockup-pulse`). Those live in the template's `index.html`, not here.
## How to combine
- One dominant system per group; layer at most one texture recipe over one structural recipe.
- Structure on strong beats (cuts, camera, `system-replace` → downbeat / phrase / section_start); texture on weak / syncopated hits (`content-swap`, typewriter letters, chromatic accents).
- A roll is an accumulation container — build during it, hard-cut to a clean layout on the downbeat that ends it.
- `drop` ≠ `downbeat`: a downbeat is a cut within the regime; a drop is a regime change (`system-replace`, total clear, element-count jump).
- Let silence remove density (`negative-space-hold`).
- **Background beds are a layer, not a move.** A bed (`bg-flow-field`) runs the whole span on the **energy / phrase** channel, leaving the **beat anchors** free for the foreground — so it composes cleanly _under_ any discrete primitive. One bed at a time; merge the bed's uniform tweens onto the group's master timeline (don't run a second timeline), bundle a local `three`/WebGL (no CDN), repaint via the timeline's `onUpdate` (no rAF).
- **WebGL "system" primitives come in two roles:** a **bed** (`bg-flow-field`, behind everything) and a **hero-text treatment** (`text-spectral-rays`, which rasterizes the wordmark and _is_ the hero). Use at most one of each; feed text/raster locally (no CDN fonts), repaint via `onUpdate`.
- **`text-spectral-rays` renders its OWN wordmark — never give the word a second source.** It draws the solid letters AND the rays from one glyph mask (perfectly registered). Do NOT use it as a "rays-only" layer behind a separate DOM logo (or stack `content-swap` / `chromatic-pressure` on the same word): the two fonts/positions won't match and you get a doubled / ghosted wordmark — deleting the shader's letter terms does not fix it (the ray mask is still the second, misaligned copy). Let the shader be the wordmark; hide any DOM logo (keep it only as an invisible layout spacer). If you move the word off frame-center, move the light cursor's `y` by the same amount. Full recipe: [`motion-primitives/text-spectral-rays/USAGE.md`](motion-primitives/text-spectral-rays/USAGE.md).
@@ -1,6 +1,6 @@
# Using `text_spectral_rays` — it OWNS its wordmark
# Using `text-spectral-rays` — it OWNS its wordmark
`text_spectral_rays` is a **self-contained WebGL hero-text renderer**. From ONE rasterized
`text-spectral-rays` is a **self-contained WebGL hero-text renderer**. From ONE rasterized
glyph mask it draws **both** the solid wordmark **and** the spectral rays that emanate from
it. Letters and rays share the same mask, so they are always perfectly registered.
@@ -38,5 +38,5 @@ The ghost / doubled-wordmark artifact comes from splitting the word across two s
## Pairs with
A background bed (`bg_flow_field`) or **separate** supporting elements (tagline, CTA, rule)
A background bed (`bg-flow-field`) or **separate** supporting elements (tagline, CTA, rule)
— never a second treatment of its own word.
@@ -0,0 +1,100 @@
# Planning (Step 3) — pick the brand, fill every frame
At Step 3 **you (the orchestrator)** turn the Step-2 skeleton into a complete, approved
`STORYBOARD.md`. You edit the **same file** in place: pick the brand spine, then for each
frame decide its **groups**, give each group a treatment, bind real beat anchors, and write
the copy.
Your mantra: **music is the spine; a template is a head start, not a cage; typography is the
floor and assets are an optional ingredient on the same beat grid.**
**You own WHAT, not HOW.** You name the template / primitives, the content, the brand, the
anchor seconds, and the intent. The frame-worker (Step 4) decides HOW — micro-timing,
realization, intra-frame cuts. **Never write millisecond tweens into the storyboard.**
## Inputs
- The Step-2 skeleton already in `STORYBOARD.md` — frames with `span_sec` + `pacing` + `mood` + `feel`.
- `audiomap.json` — timing truth; read the real anchor seconds inside each frame's span.
- [`template-catalog.md`](template-catalog.md) — the template selection menu.
- [`motion-primitive-catalog.md`](motion-primitive-catalog.md) — the free-compose menu (L0 recipes).
- [`montage.md`](montage.md) — asset treatments (only if the user supplied images/videos).
- User brief / supplied copy — topic, mood, exact words to keep.
## Step A — pick the brand spine (one preset, unmodified)
The whole video shares one type family + palette. Pick **one ready-made preset** from
`../hyperframes-creative/frame-presets/` using the preset table in
`../hyperframes-creative/references/design-spec.md` — choose by the track's mood + the brief,
and **only its fonts + colors matter** (templates own composition + motion; the preset only
sets the look). Copy it in **unmodified**:
```bash
cp ../hyperframes-creative/frame-presets/<preset>/FRAME.md "$PROJECT_DIR/frame.md"
```
Then fill the storyboard frontmatter `style` from it: the `font` from its `typography:` and a
≤4–6 swatch `palette` from its `colors:`. **Quote the hex / family verbatim — never invent or
round.** Every group's palette params draw from this one palette; that unity is what makes
different templates read as one piece.
## Step B — per frame, decide its groups
A frame is usually **one group** (one template or one free composition spanning the frame).
Subdivide into 2+ groups **only when a single treatment can't cover the frame** — e.g. a busy
opener plus a closing lockup. When you split, cut at a **real audiomap anchor** inside the
frame's span (a `key_moment` / `phrase` edge / onset-cluster gap), **never inside a `rolls[]`
run**, and keep every group **≥ ~1 bar**. Density does **not** force more groups — a dense
frame is usually ONE group whose template absorbs the density internally (a meta-template like
`poster-tile-mosaic`). **Group count tracks distinct treatments, not beats.**
## Step C — per group, pick a treatment (exactly one of three)
### A. Match a template
Read [`template-catalog.md`](template-catalog.md). Match the group's `feel` + `mood` + `pacing`
to a template's **Reach for it when**; take the closest fit. Then bind it:
- Fill `params` (keys from the catalog entry) — your copy into text slots, palette from the brand spine, `duration` = the group's span length.
- Fill `role_bindings` with this group's **real anchor seconds** read from `audiomap.json` over its span (not example times).
- If the template's natural stop and the group's span end disagree, snap to the nearest anchor.
### B. Free-compose (no template fits)
Write a `free_design` — one visual thesis from [`motion-primitive-catalog.md`](motion-primitive-catalog.md)
(a dominant system + the named L0 primitives + a density topology) + `anchors` (the real
beat / onset seconds the moves ride). Free-compose is a **first-class** choice, written as
carefully as a matched group — never a failure.
### C. Asset treatment (only when the user supplied assets and they fit)
Make it an `asset` group ([`montage.md`](montage.md)). **Obey `pacing`:** on a `beat_cut`
frame use `beat_cut` (one clip per anchor) or `bg_under_text`; on a `phrase_flow` frame use
`ken_burns` or a slow crossfade — **never** per-onset hard cuts. Assets are additive: if none
fits a group, fall back to template / free (typography is the floor — a complete video needs
no assets).
## Copy (you own the words)
- Keep exact user words; else invent with taste, on the brief's mood.
- **Message vs texture:** a readable word holds ≥1 beat (headline 3–8, sentence 4–10), stable + focal; a word held <1 beat is texture (strobe / grid / ticks). Never force a message onto a sub-beat — demote it to texture.
- Place copy into the template's text params, onto a free group's anchors, or as an asset group's `overlay_copy`. Declare the anchor + accumulate / stagger intent; leave micro-timing to the worker.
- A closing logo / CTA lands on the final hit / hard stop and holds through trailing silence.
## Transitions (you do not emit them)
Everything is a **0ms hard cut** for now. **frame → frame** is owned by the assembler
(back-to-back files); adjacent `span_sec` already imply the cut. **group → group inside a
frame** is owned by the worker on its frame timeline; you only set each group's `span_sec`.
## Write + validate
Complete `STORYBOARD.md` ([`storyboard-format.md`](storyboard-format.md)), then run
`node scripts/validate-plan.mjs` and fix every `✗`. Show the user a frame-by-frame summary and
iterate until approved.
## Self-check
- `frame.md` is a verbatim copy of one preset; frontmatter `style.font` / `style.palette` are drawn from it (exact values).
- Every frame became ≥1 group; groups tile the frame span in order; no group < ~1 bar; no group boundary inside a `rolls[]` run.
- Each group is exactly one of template / free_design / asset.
- Template `params` keys match the catalog entry; `role_bindings` / `anchors` use real audiomap seconds.
- Asset treatments obey `pacing` (no `beat_cut` on a `phrase_flow` frame).
- Every group's palette draws from the one brand palette.
- `duration_s == audiomap.audio.duration_sec`; `validate-plan.mjs` passes.
@@ -0,0 +1,91 @@
# STORYBOARD.md format — frames → groups
`STORYBOARD.md` is the single reviewable plan the user approves at Step 3 and the **manual**
each frame-worker follows at Step 4. It is **hierarchical**: one block per **frame**, written
as a `## Frame N — <frame_id>` heading (the parser recognizes `Frame`). **One frame = one
scene = one composition file.** Inside each frame block are its **groups** (the treatment
units). The assembler reads the frame level (`duration` → `data-start`, `src`); the worker
reads its own frame block. A frame's **composition id = its `src` file stem**
(`compositions/frames/01-f1.html` → `01-f1`), which the worker uses as `data-composition-id`
and the `window.__timelines` key.
Step 2 writes the skeleton (frame fields, groups `TBD`); Step 3 fills the groups + brand. It
is a build spec, not code — the planner writes WHAT, the worker decides HOW. **Never write
millisecond tweens here.**
## File shape
YAML frontmatter (the video-wide spine) + one `## Frame N — <frame_id>` block per frame.
```markdown
---
compositionId: bgm
duration_s: 30.0 # == audiomap.audio.duration_sec, exactly
canvas: { w: 1920, h: 1080, fps: 30 }
style: # brand spine — from the chosen frame.md preset (Step 3)
font: "EB Garamond / Inter / JetBrains Mono" # the preset's typography, verbatim
palette: ["#FAF9F5", "#141413", "#CC785C", "#181715"] # ≤4–6 swatches from the preset's colors
assets: false # false, or a note like "assets/ has 6 user photos"
build_notes: ["one paused timeline per frame", "no remote assets"]
avoid: ["generic slideshow", "tiny unreadable hero text"]
---
## Frame 1 — f1
- src: compositions/frames/01-f1.html # worker writes here; assembler refs it; stem (01-f1) = composition id
- duration: 7.198s # = span length; the assembler reads this for cumulative data-start
- span_sec: [0.0, 7.198] # track seconds; frames tile the track
- pacing: beat_cut # beat_cut | phrase_flow (from the skeleton; obey it)
- mood: [hype]
- feel: accelerating onset stream into a held downbeat
### Groups
- **g1** — template: `intro-kinetic-cascade`
- span_sec: [0.0, 4.017] # frame-LOCAL build is 0-based; these are TRACK seconds (worker subtracts frame start)
- params: { theme: "light", icon: "bolt", phrases: "[…]", climax: "{…}" }
- role_bindings: { phrase: { times: [0.14, 0.55, 0.87] }, climax: { in: 3.79, iconAt: 4.9 } }
- copy: "GROWTH THROUGH CREATIVITY"
- **g2** — free_design
- span_sec: [4.017, 7.198]
- free_design: { dominant_system: "per-onset typography", primitives: ["content-swap", "braam-punch"], density_topology: "accumulate" }
- anchors: [4.10, 4.80, 5.50, 6.20] # onset seconds the reveals ride (from audiomap)
- copy: ["BUILD", "SHIP", "REPEAT"]
## Frame 2 — f2
…
```
## Frame block — required fields
| field | meaning |
| --- | --- |
| heading `## Frame N — <frame_id>` | `frame_id` matches the `src` stem; `N` = the 1-based index. |
| `src` | `compositions/frames/NN-<frame_id>.html` — where the worker writes; the assembler references it. Stem = `data-composition-id`. |
| `duration` | the frame span length in seconds (e.g. `7.198s`) — **required**; the assembler sums these for cumulative `data-start`. |
| `span_sec` | `[start, end]` track seconds. `duration = end − start`. |
| `pacing` | `beat_cut` \| `phrase_flow` — from the skeleton; the worker must obey (no hard-cut on `phrase_flow`). |
| `mood`, `feel` | from the skeleton; tone + the one-line music situation the planner matched against. |
| `### Groups` list | ≥1 group; groups tile the frame span in order. |
## Group entry — exactly one of three kinds
Every group is **template** OR **free_design** OR **asset** — never two, never none. All three
carry `span_sec` (track seconds, tiling the frame) and may carry `copy`.
- **template** — `template: <catalog id>` + `params` (keys from the catalog entry) + `role_bindings` (real audiomap anchor seconds) + `copy`.
- **free_design** — `free_design: { dominant_system, primitives: [catalog ids], density_topology }` + `anchors` (real beat / onset seconds) + `copy`.
- **asset** — `asset: { treatment, clips: [public/…], anchors?, overlay_copy? }`. `treatment` ∈ `beat_cut` (one clip per anchor — only on a `beat_cut` frame) | `ken_burns` (slow push — fits `phrase_flow`) | `bg_under_text` (clip dimmed behind a template / free group). See [`montage.md`](montage.md).
## Rules
- Frames tile the track (gap-free, first at 0, last at `duration_s`); a frame's groups tile its span; no group < ~1 bar; no group boundary inside a `rolls[]` run.
- `params` keys come from the template's [`template-catalog.md`](template-catalog.md) entry.
- All anchor seconds are **track seconds from `audiomap.json`** — the worker converts to frame-local by subtracting the frame start.
- A `phrase_flow` frame MUST NOT use `beat_cut` asset treatment or per-onset hard cuts.
- The brand `style` is set once; every group's palette draws from it.
- Reviewable prose-plus-data; keep it scannable. No GSAP, no millisecond timing.
## Self-check (the planner runs `validate-plan.mjs`)
- frontmatter has `compositionId`, `duration_s` (== audiomap), `canvas`, `style`.
- every frame has `span_sec` + `src` + positive `duration` + `pacing` + ≥1 group; frames tile the track.
- every group is exactly one of template / free_design / asset; template ids exist in the catalog; anchors are real audiomap seconds; `phrase_flow` frames have no `beat_cut`.
@@ -0,0 +1,70 @@
# Template catalog — the selection menu (Step 3)
Reverse-engineered, asset-free **group templates**. This file is the **only** thing the
planner reads to pick one — you do **not** open the template's `index.html` to choose. One
template realizes **one group** of a frame (a frame may stack several groups; the brand spine
unifies them).
**How to pick.** For each group, read its frame's `pacing` + `mood` + the one-line music
situation from the skeleton, then scan **Reach for it when** below and take the closest fit.
If nothing fits, **free-compose** from [`motion-primitive-catalog.md`](motion-primitive-catalog.md)
— that is a first-class choice, not a failure.
**Brand comes from `frame.md`, not the template.** Templates ship their own demo palette
(`theme` / `palette` / color params). Fill those params from the project's `frame.md` (the
chosen preset's colors + fonts) so every group reads as one piece — the template supplies the
**motion + layout**, the preset supplies the **look**.
**Params** are listed so you can fill content slots in the storyboard. Exact semantics +
defaults live in each template's `index.html` (`data-composition-variables`) — the frame-worker
reads those at build time; you only name the values.
Pacing tag: every template below is **beat_cut** except `held-message-living-field`
(**phrase_flow**). Never put a beat_cut template on a phrase_flow frame.
---
### card-flyby
- **What** — a depth column of cards rolls forward through perspective; each landing beat tumbles the next card into the front slot with a solid colored wipe, the old front falls toward camera, dwells shrink card-to-card so the deck accelerates into a held final card.
- **Reach for it when** — a stream of discrete onsets that **accelerate** (gaps shrinking / a build into a downbeat) and you want to flash a **sequence of items** — titles, projects, posters, tiles — one per hit, climaxing on a held card.
- **Params** — `theme`, `bgColor`, `cards`, `landings`, `yaw`
### held-message-living-field · phrase_flow
- **What** — a readable mark (logo / word / title) held dead still over a soft, color-shifting blurred field; only the field breathes.
- **Reach for it when** — a **calm / sparse** stretch with an onset desert — energy present but few or no onsets (a held pad or riser); you have one word or mark to hold and let breathe.
- **Params** — `markText`, `titleText`, `tagText`, `palette`, `flowSpeed`, `duration`
### held-text-strobe-burst
- **What** — a dead-still word whose letters flip through texture-filled frames (texture-clipped fill + per-frame tint + bg color) every ~3 frames, in short bursts pinned to a roll.
- **Reach for it when** — a **dense, hard-hitting roll / fill** and a single word you want to strobe through textures for a few bars. (Ships texture-mask PNGs under `assets/`.)
- **Params** — `markText`, `fontStyle`, `markScale`, `idleColor`, `idleInk`, `frames`, `strobePlan`, `decor`, `duration`
### intro-kinetic-cascade
- **What** — a line laid out as a sequence of big editorial **phrases** (each a stacked poster with one enlarged hero word), revealed word-by-word on its anchors, hard cut between phrases, climaxing on a phrase that slides in with a swappable ringing **icon** (bell / cursor / sparkle / emoji / SVG).
- **Reach for it when** — an **intro / opening statement**: a short line to land word-by-word as big type, climaxing on one keyword + an icon. Medium-or-more energy, steady grid.
- **Params** — `theme`, `icon`, `phrases`, `climax`
### logo-split-lockup-pulse
- **What** — a two-part mark joined at center splits left↔right to open a gap, grows a center word-lockup one word per onset (key word lands on the downbeat surge), snap-closes on a hit, then pulses with the beat.
- **Reach for it when** — a short **logo / brand sting** (not a typed sentence): fast dense onsets + a sustained roll bed to pulse on, with a left/right bracketing mark.
- **Params** — `bgColor`, `markColor`, `textColor`, `leftMark`, `rightMark`, `word1`, `word2`, `word3`, `word4`
### poster-tile-mosaic
- **What** — a packed **mosaic** of different-sized colored tiles that tessellate to fill the frame (no overlap), driven by interchangeable beat-synced operations: staggered enter/exit, locked global recolor, snake-fill + overlay.
- **Reach for it when** — many discrete, individually-placeable onsets (a hit for every tile move) with distinct sub-phases you want articulated differently (accumulate → recolor-on-roll → fill-then-drop). A dense section best held as **one** rich tile program rather than split.
- **Params** — `bgColor`, `tiles`, `bands`, `gap`, `showText`, `labels`, `program`
### roll-flipbook-word-cycle
- **What** — a hi-hat roll drives a centred word that flips every 16th-note through a word list; optionally the flicker resolves and locks into a final phrase.
- **Reach for it when** — a **fast sustained-fill roll** (hundreds of hits/min, ~16th-note) with no single readable message — fill the roll with a rapidly-cycling word flipbook.
- **Params** — `bgColor`, `textColor`, `accentColor`, `flipWords`, `resolveText`, `periodChar`
### split-anchor-word-slot
- **What** — a held left anchor column of fixed-word rows beside a torn-paper word-slot box on the right, driven by beat-synced operators: anchor lock-in, slot word-group cycle (in/out + per-line color), full-scene background flip, per-beat jitter, box-zoom exit wipe. Row count + number of flips are data.
- **Reach for it when** — a short section with a **held idea** (a brand / name to anchor on the left) **and** a stream of onsets popping separate words on the right, plus a dense run to ride a shake on and a strong downbeat to wipe out into.
- **Params** — `bgColor`, `anchors`, `theme`, `showText`, `program`
### typewriter-phrase-keyword-shuffle
- **What** — words type in one-per-onset to spell a phrase, then one keyword cycles typefaces on the beat while everything else holds dead still.
- **Reach for it when** — a steady grid with a **continuous onset stream** (no desert): a phrase to type out, then a keyword to shuffle. The inverse of `held-message-living-field` (which wants an onset desert).
- **Params** — `bgColor`, `textColor`, `accentColor`, `lead1`, `lead2`, `lead3`, `keyword`, `periodChar`

Some files were not shown because too many files have changed in this diff Show More