{"id":"4501bb55-9680-4a90-8cf8-ee2f523a0d69","entityType":"agent","slug":"clawhub-heygen-com-music-to-video","name":"music-to-video","canonicalUrl":"https://www.xpersona.co/agent/clawhub-heygen-com-music-to-video","canonicalPath":"/agent/clawhub-heygen-com-music-to-video","generatedAt":"2026-10-10T05:41:10.170Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:28:08.435Z","emptyReason":null},"description":"Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.","descriptionLabel":"Source description","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 2.2K downloads reported by the source. Last updated 10/9/2026.","installCommand":"clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:music-to-video","sourceUrl":"https://clawhub.ai/heygen-com/music-to-video","homepage":"https://clawhub.ai/heygen-com/skills/music-to-video","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/heygen-com/music-to-video","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/heygen-com/skills/music-to-video","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":67,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"music-to-video technical dossier on Xpersona with agent coverage, OPENCLEW support, and live trust metadata."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:28:08.435Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:28:08.435Z","emptyReason":null},"stars":null,"forks":null,"downloads":2217,"packageName":null,"latestVersion":"1.0.25","tractionLabel":"2.2K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:28:08.435Z","emptyReason":null},"lastUpdatedAt":"2026-10-09T17:28:08.435Z","lastCrawledAt":"2026-10-09T17:28:08.435Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-10T17:28:08.435Z","lastVerifiedAt":null,"highlights":[{"version":"1.0.25","createdAt":"2026-10-07T07:31:07.609Z","changelog":"Synced from 4fcad1e (main)","fileCount":104,"zipByteSize":218585},{"version":"1.0.24","createdAt":"2026-10-04T19:32:47.766Z","changelog":"Synced from 0c3e244 (main)","fileCount":104,"zipByteSize":218534},{"version":"1.0.23","createdAt":"2026-10-04T19:19:52.748Z","changelog":"Synced from 173103d (main)","fileCount":104,"zipByteSize":218522},{"version":"1.0.22","createdAt":"2026-10-04T13:09:22.666Z","changelog":"Synced from 69a2169 (main)","fileCount":104,"zipByteSize":218592},{"version":"1.0.21","createdAt":"2026-10-02T14:32:58.326Z","changelog":"Synced from 9465048 (main)","fileCount":104,"zipByteSize":218554},{"version":"1.0.20","createdAt":"2026-10-02T00:12:47.204Z","changelog":"Synced from 37f30b1 (main)","fileCount":104,"zipByteSize":218505},{"version":"1.0.19","createdAt":"2026-09-27T21:22:31.761Z","changelog":"Synced from ff6e210 (main)","fileCount":104,"zipByteSize":218492},{"version":"1.0.18","createdAt":"2026-09-19T05:09:10.971Z","changelog":"Synced from 1a9668b (main)","fileCount":104,"zipByteSize":218776}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:music-to-video","setupComplexity":"low","setupSteps":["Install using `clawhub skill install s17fpgb0p797dzkbtbrxw5x1hh89qs64:music-to-video` in an isolated environment before connecting it to live workloads.","No published capability contract is available yet, so validate auth and request/response behavior manually.","Review the upstream CLAWHUB listing at https://clawhub.ai/heygen-com/music-to-video before using production credentials."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T05:41:10.165Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-heygen-com-music-to-video/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-09T17:28:08.435Z","emptyReason":null},"readme":"Skill: music-to-video\n\nOwner: heygen-com\n\nSummary: Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.\n\nTags: latest:1.0.25\n\nVersion history:\n\nv1.0.25 | 2026-10-07T07:31:07.609Z | user\n\nSynced from 4fcad1e (main)\n\nv1.0.24 | 2026-10-04T19:32:47.766Z | user\n\nSynced from 0c3e244 (main)\n\nv1.0.23 | 2026-10-04T19:19:52.748Z | user\n\nSynced from 173103d (main)\n\nv1.0.22 | 2026-10-04T13:09:22.666Z | user\n\nSynced from 69a2169 (main)\n\nv1.0.21 | 2026-10-02T14:32:58.326Z | user\n\nSynced from 9465048 (main)\n\nv1.0.20 | 2026-10-02T00:12:47.204Z | user\n\nSynced from 37f30b1 (main)\n\nv1.0.19 | 2026-09-27T21:22:31.761Z | user\n\nSynced from ff6e210 (main)\n\nv1.0.18 | 2026-09-19T05:09:10.971Z | user\n\nSynced from 1a9668b (main)\n\nv1.0.17 | 2026-09-19T03:23:06.154Z | user\n\nSynced from 2db126d (main)\n\nv1.0.16 | 2026-09-19T00:59:31.050Z | user\n\nSynced from f297653 (main)\n\nv1.0.15 | 2026-09-14T01:46:03.465Z | user\n\nSynced from f059a6e (main)\n\nv1.0.14 | 2026-09-14T01:26:28.593Z | user\n\nSynced from 95bea16 (main)\n\nv1.0.13 | 2026-09-10T03:25:27.077Z | user\n\nSynced from 0f8eb89 (main)\n\nv1.0.12 | 2026-08-21T03:10:01.246Z | user\n\nSynced from efc2e19 (main)\n\nv1.0.11 | 2026-08-18T01:48:19.626Z | user\n\nSynced from f8a1e2d (main)\n\nv1.0.10 | 2026-07-28T11:29:39.125Z | user\n\nSynced from d287e52 (main)\n\nv1.0.9 | 2026-07-20T15:22:22.670Z | user\n\nSynced from 6ad738b (main)\n\nv1.0.8 | 2026-07-15T13:24:25.956Z | user\n\nSynced from b9be0b2 (main)\n\nv1.0.7 | 2026-07-10T22:50:11.806Z | user\n\nSynced from 00d059b (main)\n\nv1.0.6 | 2026-07-10T05:17:31.018Z | user\n\nSynced from dda09c8 (main)\n\nv1.0.5 | 2026-07-08T18:01:31.363Z | user\n\nSynced from 17b8527 (main)\n\nv1.0.4 | 2026-07-08T17:32:53.498Z | user\n\nSynced from 81884a7 (main)\n\nv1.0.3 | 2026-07-08T08:40:28.203Z | user\n\nSynced from 6192ed4 (main)\n\nv1.0.2 | 2026-07-07T20:28:51.138Z | user\n\nSynced from 7286b00 (main)\n\nv1.0.1 | 2026-07-07T18:58:48.351Z | user\n\nSynced from 5fe9573 (main)\n\nv1.0.0 | 2026-07-01T11:06:51.358Z | user\n\nOfficial HyperFrames skills from heygen-com/hyperframes\n\nArchive index:\n\nArchive v1.0.25: 104 files, 218585 bytes\n\nFiles: references/frame-skeleton.md (6584b), references/montage.md (3269b), references/motion-primitive-catalog.md (9885b), references/motion-primitives/3d-card-flip/index.html (1278b), references/motion-primitives/3d-card-flip/scene.html (3393b), references/motion-primitives/assets/gsap.min.js (72927b), references/motion-primitives/bg-flow-field/index.html (1274b), references/motion-primitives/bg-flow-field/scene.html (11328b), references/motion-primitives/binary-decrypt/index.html (1310b), references/motion-primitives/binary-decrypt/scene.html (2711b), references/motion-primitives/blur-resolve/index.html (1272b), references/motion-primitives/blur-resolve/scene.html (1688b), references/motion-primitives/braam-punch/index.html (1276b), references/motion-primitives/braam-punch/scene.html (2728b), references/motion-primitives/chromatic-split/index.html (1284b), references/motion-primitives/chromatic-split/scene.html (3481b), references/motion-primitives/chrome-sweep/index.html (1278b), references/motion-primitives/chrome-sweep/scene.html (1824b), references/motion-primitives/counting-punch/index.html (1310b), references/motion-primitives/counting-punch/scene.html (3214b), references/motion-primitives/crash-zoom-in/index.html (1280b), references/motion-primitives/crash-zoom-in/scene.html (3386b), references/motion-primitives/datamosh-smear/index.html (1341b), references/motion-primitives/datamosh-smear/scene.html (3503b), references/motion-primitives/directional-fill/index.html (1284b), references/motion-primitives/directional-fill/scene.html (2773b), references/motion-primitives/dolly-zoom/index.html (1274b), references/motion-primitives/dolly-zoom/scene.html (3278b), references/motion-primitives/electric-arc/index.html (1306b), references/motion-primitives/electric-arc/scene.html (3263b), references/motion-primitives/flash-cut/index.html (1270b), references/motion-primitives/flash-cut/scene.html (3146b), references/motion-primitives/gooey-metaball/index.html (1310b), references/motion-primitives/gooey-metaball/scene.html (4918b), references/motion-primitives/hard-cut/index.html (1264b), references/motion-primitives/hard-cut/scene.html (2708b), references/motion-primitives/hypercut-whip/index.html (1280b), references/motion-primitives/hypercut-whip/scene.html (1229b), references/motion-primitives/iris-open/index.html (1272b), references/motion-primitives/iris-open/scene.html (2015b), references/motion-primitives/kinetic-letter-in/index.html (1288b), references/motion-primitives/kinetic-letter-in/scene.html (1764b), references/motion-primitives/liquid-morph/index.html (1278b), references/motion-primitives/liquid-morph/scene.html (2992b), references/motion-primitives/mask-reveal/index.html (1276b), references/motion-primitives/mask-reveal/scene.html (2086b), references/motion-primitives/mosaic-pack/index.html (1274b), references/motion-primitives/mosaic-pack/scene.html (2829b), references/motion-primitives/neon-flicker/index.html (1278b), references/motion-primitives/neon-flicker/scene.html (1979b), references/motion-primitives/outline-to-fill/index.html (1284b), references/motion-primitives/outline-to-fill/scene.html (2282b), references/motion-primitives/palette-flip/index.html (1276b), references/motion-primitives/palette-flip/scene.html (2824b), references/motion-primitives/particle-burst/index.html (1282b), references/motion-primitives/particle-burst/scene.html (3185b), references/motion-primitives/pixel-dissolve/index.html (1282b), references/motion-primitives/pixel-dissolve/scene.html (2645b), references/motion-primitives/radial-burst-lines/index.html (1290b), references/motion-primitives/radial-burst-lines/scene.html (3742b), references/motion-primitives/screen-shake/index.html (1278b), references/motion-primitives/screen-shake/scene.html (2197b), references/motion-primitives/slot-machine-reveal/index.html (1292b), references/motion-primitives/slot-machine-reveal/scene.html (2820b), references/motion-primitives/spotlight-sweep/index.html (1284b), references/motion-primitives/spotlight-sweep/scene.html (3009b), references/motion-primitives/staggered-exit/index.html (1276b), references/motion-primitives/staggered-exit/scene.html (2413b), references/motion-primitives/text-spectral-rays/index.html (1276b), references/motion-primitives/text-spectral-rays/scene.html (11504b), references/motion-primitives/text-spectral-rays/USAGE.md (2401b), references/motion-primitives/text-wave-distort/index.html (1316b), references/motion-primitives/text-wave-distort/scene.html (2999b), references/motion-primitives/tile-mosaic/index.html (1274b), references/motion-primitives/tile-mosaic/scene.html (3063b), references/motion-primitives/typewriter-reveal/index.html (1286b), references/motion-primitives/typewriter-reveal/scene.html (2634b), references/motion-primitives/word-grid-burst/index.html (1282b), references/motion-primitives/word-grid-burst/scene.html (2707b), references/planning.md (6194b)\n\nFile v1.0.25:SKILL.md\n\n---\nname: music-to-video\ndescription: \"Turn a music track (an audio file, a video to pull audio from, or a track generated from a mood brief) into a beat-synced video — lyric video, slideshow, or kinetic promo. The music drives all pacing; any user-supplied images/videos are cut onto the same beat grid, and a complete video needs zero assets. Narrated pieces → the input-matched workflow (see /hyperframes). Unclear → /hyperframes.\"\n---\n\n**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.\n\n> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update music-to-video`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.\n\n# music-to-video — one music-grounded, beat-synced video workflow\n\nUse 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.\n\nYou are the **orchestrator**. Work in `videos//`. 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) — both are checkpoint gates per `../hyperframes/references/brief-contract.md` (read it before Step 0): in autonomous mode, post the Step 3 summary as a heads-up and proceed; Step 6 render approval is still asked, as the one kept question. 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.\n\n`SKILL_DIR` = this skill directory. `PROJECT_DIR` = `videos//`.\n\nWorkflow: 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`.\n\n## Two ideas that shape everything\n\n- **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).\n- **One frame = one file; groups live inside.** Step 2 cuts the track into **frames**, and each frame becomes one composition file `compositions/frames/NN-.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.\n\n---\n\n## Step 0: Setup, BGM, and inputs\n\nGoal: Establish the music source, create the HyperFrames project, and note any user-supplied media.\n\n**The brief starts at the intent layer.** Opening rule, in order: **(1)** `BRIEF.md` exists → read it and ask nothing it answers — its `flow`/`storyboard` derive the mode (brief contract § 1). **(2)** No `BRIEF.md` but the project exists → resume from what's on disk; never re-interrogate. **(3)** A fresh creation request that arrived here directly → read `/hyperframes` and run its intent layer (`references/intent-interview.md`): it confirms this route's must-haves (the music source, destination → aspect — `../hyperframes/references/routes/music-to-video.md`) and announces what stays deferred — brand and genre are chosen at Step 3 by design. Write `BRIEF.md` immediately after init (never before — `init` refuses a non-empty directory) and record the preference-backed answers (`brief-format.md`). Edit requests skip all of this.\n\nThe **music is the spine** — establish one track before anything else. This skill is tuned for **fast, high-energy BGM**: a strong beat grid drives the cuts (calm tracks work, but pace by phrase rather than beat). If the user supplied audio — a music file, or a video to pull audio from — use it. Otherwise choose the mood from the request and generate a track through `/media-use` (`audio/references/bgm.md`); when the host app provides its own music tool, use that. Before the first authenticated provider action, run `npx hyperframes auth status` and relay its output verbatim. If signed out, apply one branch:\n\n- **Collaborative:** wait for sign-in or an explicit choice to continue offline with the local provider.\n- **Autonomous:** state the status and continue through the available local provider.\n\nIf no offline provider can satisfy the required music capability, surface the blocker. Never write keys into a per-repo `.env`. Auth ownership and offline fallbacks live in `/media-use` `references/setup-providers.md` § Providers. The resulting track lands at `assets/bgm.mp3`. Stage supplied images or videos so frames can use them on the beat grid; otherwise typography carries the video.\n\n**Lyric videos:** for lyrics synced to the vocals, get word/line timing by transcribing the track via `/media-use`, or ask the user for the lyrics text and place lines on the beat grid.\n\nInitialize only if `hyperframes.json` is missing. Name `` from the brief in kebab-case, such as `midnight-drive-loop` — never a timestamp. `init` checks the installed skills against the latest on GitHub and updates the global set if any are out of date.\n\n```bash\nnpx hyperframes init \"videos/\" --non-interactive --example=blank --skill=music-to-video\nmkdir -p \"$PROJECT_DIR/assets\" \"$PROJECT_DIR/renders\"\ncp \"\" \"$PROJECT_DIR/assets/bgm.mp3\" # extract from a video first if needed\n# only if the user gave you images/videos:\nnode /scripts/stage-assets.mjs --from --hyperframes \"$PROJECT_DIR\" --into public\n```\n\nThe **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.\n\n**Gate:** `hyperframes.json` + `assets/bgm.mp3` exist; aspect / length / fps and (if any) the asset inventory are noted.\n\n---\n\n## Step 1: Analyze the music\n\nGoal: Produce the one canonical timing analysis the whole video is built on.\n\n`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.\n\nPrerequisites: Python 3 with `librosa`, `numpy`, and `soundfile` available. If import fails, install them into the active Python environment before running the analyzer:\n\n```bash\npython3 -m pip install librosa numpy soundfile\n```\n\n```bash\npython3 /scripts/analyze-beatgrid.py \"$PROJECT_DIR/assets/bgm.mp3\" \\\n -o \"$PROJECT_DIR/audiomap.json\" --print\n```\n\n**Gate:** `audiomap.json` exists; `audio.duration_sec` is known.\n\n---\n\n## Step 2: Frame skeleton (structure only)\n\nGoal: Read the music and lay out the frames — the skeleton of `STORYBOARD.md`.\n\nRead [`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.\n\n**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.\n\n---\n\n## Step 3: Fill the plan (user-gated)\n\nGoal: Turn the skeleton into an approved, complete `STORYBOARD.md`.\n\nRead [`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:\n\n1. **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.\n2. **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`**. **Before you free-compose a named look, search the live catalog for it**: for every look, effect, treatment or transition the user asked for — \"CRT scanlines\", \"glitch\", \"film grain\", \"shimmer sweep\" — run `npx hyperframes catalog --query \"\" --json` and read the top results. `template-catalog.md` and `motion-primitive-catalog.md` list only this skill's own local materials; the search ranks the whole hosted registry (~400 blocks and components) and needs **nothing installed** — no project, no prior `add`, no account. Free-compose a look only after a search for it came back with nothing that fits. Write the copy. You own WHAT (template / primitives + content + anchors); the frame-worker owns HOW — **never write millisecond tweens into the storyboard**.\n\n```bash\nnode /scripts/validate-plan.mjs --storyboard \"$PROJECT_DIR/STORYBOARD.md\" \\\n --audiomap \"$PROJECT_DIR/audiomap.json\" --templates /references/templates\n```\n\nFix every `✗` (hard errors: duration mismatch, frames not tiling the track, a missing `src`); warnings are best-effort. Then present the frame-by-frame summary in chat as a proposal (`../hyperframes/references/review-loop.md` § 1) and iterate on the user's replies until they approve; for `storyboard: yes`, also write it as `storyboard.html` (`../hyperframes-creative/references/storyboard-recipe.md` § 3) for them to open. In autonomous mode this is a checkpoint gate: post the summary as a heads-up and proceed (the `validate-plan.mjs` pass is a quality gate and still blocks).\n\n**Gate:** `frame.md` is a verbatim preset copy; `validate-plan.mjs` exits 0; the user approved the plan (autonomous: the summary was posted as a heads-up).\n\n---\n\n## Step 4: Build frames from the plan\n\nGoal: Build every frame as a self-contained composition file.\n\nCreate `compositions/frames/`. Read [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) and `../hyperframes/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:\n\n```text\nPROJECT_DIR: \nframe_id: # = the frame file stem, e.g. 02-f2; the composition id\nYour block: the `## Frame N — ` block in PROJECT_DIR/STORYBOARD.md\naudiomap: PROJECT_DIR/audiomap.json\nframe.md: PROJECT_DIR/frame.md\nMaterials: for each group, /references/templates//index.html (templates) and\n /references/motion-primitives// (free); staged assets/ (asset groups)\nContracts: ../hyperframes-core/references/sub-compositions.md + determinism-rules.md\nCanvas: × Pacing: \nWrite to: PROJECT_DIR/compositions/frames/.html\n```\n\nThe 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.\n\n**Gate:** every frame has its `compositions/frames/NN-*.html` on disk.\n\n---\n\n## Step 5: Assemble\n\nGoal: Wire the built frames + BGM into the playable `index.html`.\n\n`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**).\n\n```bash\nnode /scripts/assemble-index.mjs --storyboard \"$PROJECT_DIR/STORYBOARD.md\" \\\n --hyperframes \"$PROJECT_DIR\" --audiomap \"$PROJECT_DIR/audiomap.json\"\n```\n\nFix any `✗` it reports — a missing or blank frame file means that worker wrote a partial file; re-dispatch it (Step 4) and re-assemble.\n\n**Gate:** `index.html` exists; total duration == `audiomap.audio.duration_sec`.\n\n---\n\n## Step 6: Verify and render\n\nGoal: Verify the assembled video, get user approval, and render the final MP4.\n\nRun the CLI on the **assembled project** — that's the correct unit (the per-frame workers couldn't run it). `check` runs structural lint and the headless-browser runtime, layout, motion, and contrast gate in one pass; `--snapshots` also emits the review frames.\n\n```bash\n( cd \"$PROJECT_DIR\" && npx hyperframes check . --snapshots )\n```\n\nInspect 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** yourself: edit the offending `compositions/frames/NN-*.html`. Never change duration or audio timing to hide a sync issue. Once the gates pass, open the final Studio preview (`( cd \"$PROJECT_DIR\" && npx hyperframes preview --background )`) and pause for user review — render now, or what changes? Render only on approval (autonomous mode: the same, as the one kept question), then deliver the MP4 with the contact sheet:\n\n```bash\n( cd \"$PROJECT_DIR\" && npx hyperframes render . --skill=music-to-video -q draft -o renders/video.mp4 --fps 30 )\n```\n\n**Gate:** `check` passed and the snapshots were inspected; the user approved (autonomous: checks passed and the delivery includes the contact sheet); `renders/video.mp4` exists with audio, duration == `audiomap.audio.duration_sec`. The final reply states the MP4 path and duration.\n\n---\n\n## Resume table\n\n| You have | Continue from |\n| -------------------------- | ------------- |\n| `assets/bgm.mp3` only | Step 1 |\n| `audiomap.json` | Step 2 |\n| `STORYBOARD.md` (skeleton) | Step 3 |\n| `STORYBOARD.md` (complete) | Step 4 |\n| all frame files | Step 5 |\n| `index.html` | Step 6 |\n\n## Quick Reference\n\n**Formats:** landscape `1920x1080` by default; portrait `1080x1920`; square `1080x1080`. Set the canvas once in the storyboard frontmatter (`canvas: { w, h, fps }`).\n\n**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.\n\n| Read | When |\n| -------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |\n| [`references/frame-skeleton.md`](references/frame-skeleton.md) | Step 2: read the music, lay out the frames, set pacing |\n| [`references/planning.md`](references/planning.md) · [`storyboard-format.md`](references/storyboard-format.md) | Step 3: pick the brand, fill each frame, write the plan |\n| [`references/template-catalog.md`](references/template-catalog.md) | Step 3: pick a template per group |\n| [`references/motion-primitive-catalog.md`](references/motion-primitive-catalog.md) | Step 3/4: L0 recipes for free-compose |\n| [`references/montage.md`](references/montage.md) | Step 3/4: asset treatments (beat-cut / ken-burns) |\n| [`sub-agents/frame-worker.md`](sub-agents/frame-worker.md) | Step 4: dispatch + build one frame |\n| `../hyperframes/references/subagent-dispatch.md` | Step 4: dispatch sub-agents safely |\n| `../hyperframes-creative/references/design-spec.md` | Step 3: pick the preset (the brand) |\n\n## Directory layout\n\n```\nmusic-to-video/\n SKILL.md\n references/ frame-skeleton.md · planning.md · storyboard-format.md\n template-catalog.md · motion-primitive-catalog.md · montage.md\n templates// { index.html (+ assets/ · program.json) } ← L1 catalog impls\n motion-primitives// { index.html (mounts the scene), scene.html (the sub-composition) } (+ ../assets/gsap.min.js shared by recipes) ← L0 catalog impls\n scripts/ analyze-beatgrid.py · assemble-index.mjs · validate-plan.mjs · stage-assets.mjs · lib/storyboard.mjs\n sub-agents/ frame-worker.md ← the one subagent (one per frame)\n```\n\nFile v1.0.25:_meta.json\n\n{\n \"ownerId\": \"kn77d06grj6xqp3dqwkk4bavhn89pegt\",\n \"slug\": \"music-to-video\",\n \"version\": \"1.0.25\",\n \"publishedAt\": 1791358267609\n}\n\nFile v1.0.25:references/frame-skeleton.md\n\n# Frame skeleton (Step 2) — read the music, lay out the frames\n\nAt Step 2 **you (the orchestrator)** read `audiomap.json` and write the **skeleton** of\n`STORYBOARD.md` directly: cut the track into **frames** (one frame = one composition file =\none scene), and for each frame set its **span**, its **pacing** (does this stretch want hard\nbeat-cuts, or calm phrase/energy flow?), its **mood**, and a one-line **feel** note.\n\nYou **classify and lay out the spine only.** You do **not** pick templates, write copy, choose\ncolors/fonts, or decide a frame's groups — those are Step 3 (the plan fills each frame in\nplace). Leave every frame's `### Groups` as `TBD (Step 3)` and the frontmatter `style` blank.\n\nThere is **no intermediate JSON** — the skeleton _is_ the start of `STORYBOARD.md`. Step 3\nedits the same file.\n\n## The trust boundary (read this first)\n\n`audiomap.json` is one analyzer's output. Some fields are robust on **any** music; some are\nreliable only when the music is **actually rhythmic**. This decides each frame's `pacing`:\n\n| Field | Trust |\n| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `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 |\n| `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. |\n\n- **Grid is reliable** when: rolls present, and/or dense phases, and/or high `onset_rate` with a steady grid.\n- **Grid is fictional** when: `rolls`≈0, mostly `sparse` phases, low `onset_rate` → pace by `phrases[]` + `energy_phases[]`, not beats.\n\n## How to lay out frames (run in order)\n\n1. **Gestalt.** From `summary` / `tempo` / `audio.duration_sec` + the roll count, write the\n frontmatter `compositionId`, `duration_s` (== `audio.duration_sec`), `canvas`, and a\n one-line read of the track's density arc.\n2. **Cut into frames.** Walk `energy_phases[]` and split where the music genuinely changes\n state — at `hard_stops[]`, `SURGE` / `DROP` `key_moments`, the start/end of a `rolls[]` run,\n an **onset desert** (a long gap in `events[]`), or a big energy-level jump. Collapse adjacent\n phases that are one gesture. Expect **~1–6 frames**; a short clip may be one.\n **Snap every boundary to an audiomap anchor**, then re-snap to the nearest `beats_sec`\n (tolerance ≤ ½ beat) **only when the grid is reliable**; on calm material snap to\n `phrases[]` / `energy_phases[]` edges instead. Frames **tile the track** (first at 0, last\n at `duration_s`, no gaps/overlaps).\n3. **Per frame, set `pacing`** — the trust-boundary call:\n - **`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.\n - **`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).\n4. **Per frame, tag `mood`** (1–3 of: `warm` · `dark` · `hype` · `elegant` · `glitch` ·\n `cinematic` · `playful` · `tense` · `dreamy` · `aggressive`) from `energy_phases[].feel` +\n energy + any genre cue in the brief/title.\n5. **Per frame, write a one-line `feel`** — the plain-language music situation Step 3 matches a\n template against (e.g. \"accelerating onset stream into a held downbeat\", \"calm held pad, one\n onset desert\", \"fast sustained-fill roll, no readable message\"). This is what the planner\n reads against the catalog's **Reach for it when** — keep it concrete, drawn from the robust\n fields, never invented.\n\n## What the skeleton looks like\n\nA valid `STORYBOARD.md` with the spine set and every frame's treatment left for Step 3\n(full syntax in [`storyboard-format.md`](storyboard-format.md)):\n\n```markdown\n---\ncompositionId: bgm\nduration_s: 30.0 # == audiomap.audio.duration_sec\ncanvas: { w: 1920, h: 1080, fps: 30 }\nstyle: # blank — Step 3 fills it from the chosen frame.md preset\nbuild_notes: [\"one paused timeline per frame\", \"no remote assets\"]\n---\n\n## Frame 1 — f1\n\n- src: compositions/frames/01-f1.html\n- duration: 7.198s # = span length; assembler sums these for cumulative data-start\n- span_sec: [0.0, 7.198] # track seconds; frames tile the track\n- pacing: beat_cut\n- mood: [hype]\n- feel: accelerating onset stream building into a held downbeat\n\n### Groups\n\n- TBD (Step 3)\n\n## Frame 2 — f2\n\n- src: compositions/frames/02-f2.html\n- duration: 10.4s\n- span_sec: [7.198, 17.598]\n- pacing: phrase_flow\n- mood: [warm, cinematic]\n- feel: calm held pad, one long onset desert\n\n### Groups\n\n- TBD (Step 3)\n```\n\n## Self-check\n\n- `duration_s == audiomap.audio.duration_sec`; frames tile the track gap-free (first at 0, last at `duration_s`).\n- Every frame has `src` + `span_sec` + `duration` + `pacing` + `mood` + a one-line `feel`.\n- `pacing` was set from the **robust** fields (energy / density / rolls / onset_rate), never from `bpm` / `beats_sec` alone.\n- No frame boundary sits inside a `rolls[]` run or leaves a sub-1-bar fragment.\n- Every frame's `### Groups` is `TBD (Step 3)`; `style` is blank. **No template, copy, color, or font anywhere.**\n\nFile v1.0.25:references/montage.md\n\n# Asset treatments — weaving user media onto the beat spine\n\nWhen the user supplies images/videos, a group can be an **asset treatment** instead of a\ntypographic template/free-compose. Assets are an **additive ingredient on the same beat\nspine** — never a separate pipeline. Typography/templates stay the floor: if no asset fits a\ngroup, fall back to a template/free group (a complete video needs zero assets).\n\nThe planner (Step 3) picks the treatment and the clips + anchors (WHAT); the frame-worker\nrealizes it inside the frame file (HOW). **Obey the frame's `pacing`.**\n\n## The three treatments\n\n### `beat_cut` — one clip per anchor (only on a `beat_cut` frame)\n\nThe asset-driven analogue of a per-onset typographic group: cut to a new clip on each anchor\n(the frame's beats/onsets from the audiomap). Each clip is a `class=\"clip\"` element\n(`` for a photo, **muted** `