Files
hyperframes/skills/website-to-hyperframes/scripts
ukimsanov 0a60427fdf fix(skill): move music fetch from Step 5 to Step 3 (beats align to track structure)
User flag: music selection in Step 5 was the wrong timing. Music has
structural moments (builds, peaks, drops, fills) that the video's
rhythm should honor — a build at 22s wants beat N to land at 22s.
With Step-5 fetch, the storyboard wrote beat timing BLIND to the
actual track, then Step 5 produced a structural mismatch.

SFX timing was already correct (per-beat punctuation, decided in
storyboard, fetched in build with full beat context). Only music
needed the move.

New flow:
  Step 2 (yes/no/auto) → Step 3 Music Fetch (search + pick + add +
  inspect + record sparkline+peaks in STORYBOARD.md) → Step 3
  beat-timing AWARE of track structure → Step 4 (no-op for music)
  → Step 5 (just wire the already-on-disk file)

Changes:

step-3-storyboard.md:
- New ## Music Fetch section between PACING and Technique-pick.
  6 sub-steps: describe mood → search catalog → pick (collaborative
  or auto by score) → music add (downloads + prints LUFS/peaks/
  sparkline) → record in Global Direction → time beats against
  structure (build@22s → schedule reveal at 22s, etc.).
- Global Direction template adds:
    **Music file:** assets/music/<id>.<ext>
    **Music direction:** mood + volume rule
    **Music structure:** sparkline + peak + duration + suggested trim
- Updated the existing "Music direction details" subsection to
  reference Step 2 Q5 + background-music.md (renamed from
  "Underscore/music direction").

step-4-vo.md:
- Replaced "Music (storyboard-driven, decided in Step 2)" section
  with "Music (already fetched in Step 3 — verify timing only)".
  Explicitly: do NOT re-fetch or re-ask here. Step 4 may align VO
  start to music's quiet intro if relevant.

step-5-build.md:
- Background music paragraph: "track is already on disk from Step 3
  Music Fetch; do NOT re-fetch or re-search here. Just wire as a
  BGM <audio> on track lane 11 with data-volume per storyboard."

w2h-prep.mjs:
- New BGM detection block (after voice auto-detect). Parses
  STORYBOARD.md for `**Music file:** <path>` line; falls back to
  auto-detect from `assets/music/` (single-file or alphabetical with
  warning when >1). Emits `bgm_path` field in group_spec.json,
  which assemble-index.mjs already consumes (line 289).
- Smoke-verified end-to-end: storyboard with Music file line →
  bgm_path: "assets/music/<id>.mp3" in group_spec.

This closes the loop that was missing: music decision → fetch →
analysis → beat timing → group_spec → assembler → final video.
2026-06-11 17:35:15 -07:00
..