hyperframes-showreel

End-to-end pipeline from real footage to a delivered HyperFrames showreel. HyperFrames
is used only through its public CLI (npx hyperframes …); none of its skills or code
is vendored here. Last verified with HyperFrames 0.8.72 (2026-09-24) — a data point,
not a pin.

Ground rules

• Footage-only rule — every process shown on screen comes from real footage. No AI
  insert may depict a process that has no footage; if there is no recording of it, the
  beat is cut from the script.
• Screen-blend FX rule — Veo output is used only as an additive FX layer: rendered
  on a black background and composited with mix-blend-mode: screen over the footage
  (light, particles, flares, scan lines). It never replaces a shot.

Pipeline

1. Footage sampling — contact sheets of every source (ffmpeg -i src.mov -vf "fps=1/2,scale=480:-2,tile=6x6" sheet_%02d.png); note sensitive regions and usable moments with timecodes.
2. Edit script — acts, shots, source timecodes, on-screen copy, FX layer map. Every shot names its source clip and in/out.
3. Clip cutting with redaction baked in — one call per clip via the footage-redaction skill (crop / delogo / timed blur in source-frame coordinates), then contact-sheet verification of every clip.
4. Generated composition, pass 1 — a generator script turns the shot table into index.html + one scene sub-composition per act, with provisional scene durations and a temp track or none. See references/generator-pattern.md.
5. Optional Veo FX layers — black-background renders (e.g. veo-showreel-production-kit + veo-generator), screen-blended per the rule above.
6. npx hyperframes check and snapshots — check must report 0 errors; npx hyperframes snapshot --at <t1>,<t2>,… at scene midpoints to verify framing.
7. Preview and user review — npx hyperframes preview; the user approves the picture before music is fitted.
8. Music, punches, generation pass 2 — cut the music with music-edit-to-length (listen-before-lock), pick hits with beat-sync-video, then regenerate the composition: re-run the generator with scene starts from _edit.json (downbeats_video, a boundary on each drop), punches from _hits.json, and root duration = the edit's duration.
9. Delivery render — npx hyperframes render . -o ../export/showreel_v1.mp4 --fps 30 --quality delivery --video-frame-format png.
10. Export QA — the gate below; a render is not "done" until it passes.
11. Upload — copy the export (and its subtitles) to the agreed share; record the location next to the file.

Music skills not installed? Step 8's music skills ship in
@blackbelt-technology/pi-dashboard-music-production
(pi install npm:@blackbelt-technology/pi-dashboard-music-production). Without them,
continue with the unedited music track and no punches: set the root duration to the
track length and skip the pass-2 punch step.

Pitfalls

• (a) Install scope. Default: follow the upstream installer —
  npx hyperframes skills update installs into the universal store ~/.agents/skills,
  which pi reads; the router installs further workflows there lazily. Only when the user
  wants project-only scope: after every init, init --skill or skills update
  (including the router's lazy workflow installs), copy the directories just
  installed into the user project's .pi/skills/. Do not modify the global store by
  default — it is machine-wide, other projects may use it, and the router re-installs
  into it anyway. Warn that project and global copies may then coexist at different
  versions. Remove global copies only after the user explicitly confirms (ask_user)
  that no other project uses them, and only the directories and lock entries that call
  just created. Never apply this to the dashboard repository's own .pi/skills.
• (b) Blend on the wrapper. mix-blend-mode and any opacity go on the FX wrapper
  (.fxw); never put opacity on a wrapper whose inner video carries the blend — the
  blend then composites against the wrapper, not the footage.
• (c) Audio needs an id. Every <audio> element needs an id, or the render is silent.
• (d) Never hand-edit generated files. Composition HTML is generated; change the
  generator and re-run it (and check).
• (e) Flash snapshots. A snapshot landing exactly on a flash tween looks washed
  out — expected; snapshot a few frames later before judging.

Export QA gate

ffprobe -v error -show_entries stream=codec_type,codec_name,width,height,r_frame_rate:format=duration -of json export/showreel_v1.mp4
ffmpeg -hide_banner -i export/showreel_v1.mp4 -af loudnorm=print_format=json -f null - 2>&1 | tail -12
ffmpeg -v error -ss <drop_t> -i export/showreel_v1.mp4 -vf "fps=8,scale=480:-2,tile=8x1" -frames:v 1 qa_drop_strip.png
ffmpeg -v error -sseof -4 -i export/showreel_v1.mp4 -vf "fps=2,scale=480:-2,tile=8x1" -frames:v 1 qa_end_strip.png

Pass criteria:

• one video + one audio stream; resolution and fps as specified; duration equals the
  music edit's duration ±0.1 s;
• integrated loudness (input_i) and true peak (input_tp) reported; note the platform
  target (−14 LUFS integrated for web platforms, true peak ≤ −1 dBTP) and whether a
  final loudnorm pass is needed;
• frame strips at the drop and at the end card inspected: the drop cut lands on the
  beat, the end card holds with the logo fully visible, no redaction leak.