references/composition-and-verification.md
# Compose and verify the approved film
This guide ships with the customer skill. It needs no separate Recoup composition skill
or private example project. Preserve the approved bible, clip table, recording and Scribe
word timings; assembly does not authorize new generation, transcription or publication.
## Check the host before starting
The host needs Node.js 22 or later, HyperFrames **0.7.5**, FFmpeg/ffprobe, an available
Chromium-compatible rendering browser, and authorized access to the selected local media.
Browser checks and rendering must be possible in this host. Check the installed versions
and capabilities; do not claim a check passed because its command appears below.
Use only the host's already installed, reviewed tools. Do not download packages,
remote code, browser dependencies or additional skills during this workflow.
If a capability is missing, name it. The agent can prepare the timeline and review plan
from available approved inputs, but must label the unperformed checks and withhold a
verified-film claim. A hosted preset is a separate workflow, not an automatic substitute.
## Start from an empty composition
Use a new project directory, or reuse a tested project only after preserving its existing
work. Copy an already available, reviewed HyperFrames 0.7.5 blank template or
local harness. If none is available, prepare the clip manifest and edit plan,
report the missing composition environment, and stop before local execution.
Do not bootstrap a project or install dependencies to work around that limit.
Choose the approved aspect ratio. Keep automatic Whisper transcription and extra
skill installation disabled. Reuse `audio/scribe.json` from the approved recording.
Copy the selected clips into the new project's media directory and retain a manifest
mapping each copy to its approved source. Keep source masters unchanged. Set the canvas
dimensions and total duration from the approved film, including only an approved end card.
Replace every blank-template placeholder and remove its example media.
## Build the timeline in index.html
Use the scaffold's root `data-composition-id` and matching paused GSAP timeline in
`window.__timelines`. Keep one composition root with explicit `data-width`, `data-height`
and `data-duration`. A caption or visual animation must seek deterministically on that
timeline; avoid independent timers or autoplay that only works during live playback.
For every row of the active clip table:
- Put the video directly inside the root in `index.html`, with a unique ID and `class="clip"`.
Keep media out of nested sub-compositions or wrapper elements: the pinned runtime can
leave nested video blank even when automated checks pass.
- Set `src` to the actual selected clip; use explicit `data-start`, `data-duration`,
`data-media-start` for trimming, and `data-track-index`. All timing values are seconds.
Mute the generated clip's audio. Avoid overlaps on the same track unless deliberately
implemented and reviewed as a transition.
- Place captions on their own track, using the approved Scribe word windows. Do not
invent missing timings or silently change words to fit a line. Review lyric differences.
- Cover the complete recording. Retain approved still holds or transitions explicitly;
an accidental black frame is not a hold. Keep the approved visual identity and fonts.
This workflow muxes the unchanged song master after the picture render. Do not leave the
scaffold's example audio active or double the song by mixing it into both stages.
## Check and review before rendering
From the composition directory, run:
```bash
hyperframes lint .
hyperframes validate .
hyperframes inspect .
hyperframes snapshot . --at 0,1.5,4 --describe false
```
Replace the example snapshot times with this film's cuts, caption transitions, end frames
and ending. Inspect the resulting PNGs. `--describe false` disables optional automatic
Gemini analysis; a configured key must not silently submit film frames to another service.
These commands check different things: source structure, browser execution and contrast,
then layout over time. Record failures and fix them before final rendering. Intentional
overflow requires visual evidence, not simply suppression of the warning.
Review moving playback as well as snapshots, and obtain approval of the assembled edit.
Only then render the picture locally:
```bash
hyperframes render . --output renders/picture.mp4 --fps 30 --strict
```
Use the approved frame rate; 30 fps is an example. Keep this a local render; no cloud
upload or publication is implied. Record command/version, output and actual check results.
## Finish the actual deliverable
Mux the approved master with FFmpeg, using the main workflow's measured linear-gain
procedure. Do not normalize or trim the song to hide a timeline mismatch. Add silence
only for an approved end-card tail. Use ffprobe on the final MP4 to measure actual duration,
video continuity and the audio stream; listen to the result and inspect frames at cuts,
caption changes and known trouble spots. Watch movement and the ending.
Capture the inspection times, defects, corrections and final viewing approval. A successful
render, an audio stream or an automated check alone is not proof of visual quality,
faithful sound or synchronized captions. If playback, audio listening or browser inspection
was unavailable, say which review remains and deliver the artifact with that limitation.
## Version evidence
The commands and attributes above were checked against the published
[`hyperframes@0.7.5` package](https://registry.npmjs.org/hyperframes/-/hyperframes-0.7.5.tgz),
including its CLI command declarations, blank template and bundled composition/CLI guides.
Its npm integrity is
`sha512-VUmuyjU5R6DI3p/FFqA8usT5LqXEFAoA/4HOeEtrKZCbxE4TuKUsAY4ne6qBtbJqJwDFr1h3ZD6lPx85dmr8+w==`.
This is a static package inspection, not a film render or a hosted provider test.
The package link records provenance only; do not fetch or execute it from this workflow.
references/small-room-production.md
# Small Room: evidence and execution contract
Reviewed 2026-09-07. This record reconstructs the final build completed 2026-09-03;
it is not the generic Higgsfield Pipeline or the superseded v1 shot list.
## Evidence behind the sequence
Source records in the marketing workspace, under `content/small-room/`:
| Stage | Evidence |
|---|---|
| Song | `gen-song.mjs`, `audio/small-room-take1.json`, the 120.2-second WAV, `audio/scribe.json` |
| Bible and audit | `BIBLE.md`: Higgsfield character-design order, scene-engine audit, owner review choices; `SCRIPT.md` records bible approval |
| Character | `gen-character.mjs`, `gen-sheet.mjs`, `cast/IDENTITY.md` |
| Screen test | `gen-audition.mjs`, two five-second takes; take 1 copied to `cast/projectionist-locked-take.mp4` |
| Props then plates | `gen-props.mjs`, `gen-plates.mjs`; saved artifacts follow the character audition |
| Scene plan and stills | `SCRIPT.md`, `gen-scene.mjs`; shared style, identity and reference glossary |
| Revised clip plan | `SCRIPT.md` v2: 26 planned shots consolidated to 17 clips; `gen-endframes.mjs` |
| Final motion | `gen-motion.mjs`, selected `clips/*.json` and MP4s; these carry later fixes not present in every table cell |
| Edit | `video/index.html`, `video/package.json`, `video/mux.sh`, original and revised renders |
| Publication | `post.config.mjs`, `post-results.json`, marketing `posts-log.md` entries for 2026-09-03 |
These paths are provenance, not required files in an installed skill. The workflow and
settings needed for a new film are carried in this skill. Small Room's final film was
124.2 seconds: 120.2 seconds of song plus an approved four-second end card. The publication
ledger records $9.76 billed for that production. Neither figure is a new-project budget.
The old `SCRIPT.md` title and final build checklist still say draft / 26 shots; the current
v2 table, 17 selected clip files and final timeline establish what actually shipped.
The final motion generator also supersedes some v2 prose: M24 is locked off rather than a
push-in; C06, M12, M18, C23 and C26 reuse start images as end anchors. Small Room was not
an all-locked-camera film: other selected rows still use push-ins or a tilt.
## Generation settings used in the completed build
| Operation | Actual model / settings |
|---|---|
| Song | `minimax/music-3`, requested 120 seconds. For new songs use the owner's later `recoup-song` decision: Recoup API, maximum duration headroom, four approvals. |
| Transcription | ElevenLabs Scribe, saved word timestamps |
| Character, prop, location and scene stills | `meta/muse-image/text-to-image` and `meta/muse-image/edit`; PNG; scene frames 9:16, character panels 3:4, prop sheets 16:9 |
| Audition | `minimax/h3-max-turbo/image-to-video`, 5 seconds, 768P, `prompt_expansion_mode: disabled`; two takes, first selected |
| Scene motion | Same H3 Max Turbo model, 768P, 5–15-second integer requests; approved start image, optional end image, `prompt_expansion_mode: disabled` |
| Composition | HyperFrames 0.7.5, selected clips trimmed onto the song map, timed captions |
| Mux | FFmpeg, copy rendered video, song at −1 dB linear gain, AAC 256 kbps, silence through the approved end card |
The old Seedance test proposal was not the scene-generation path. There was no OmniHuman,
lip-sync pass, Soul training, recasting pass or separate narrator. Candidate/model options
left in generator code are not evidence that those options made the final film.
## Transport, capabilities and spend
For a new film, preserve the session's authorized providers, accounts and spend limits;
never copy a credential or private import path out of the old scripts.
Before paying for an audition or motion batch, verify the chosen route supports the actual
model and settings above. Name the route, model, take count and current quote in the spend
plan. Retain an approved budget on resume; extra takes beyond it need approval. Do not
silently substitute a different model and call it the Small Room configuration.
**Known Recoup route gap, verified against API implementation on 2026-09-07:**
`POST https://api.recoupable.dev/api/content/video` selects H3 Max (not Turbo), accepts
`balanced` / `quality` prompt expansion, and rejects `disabled`. Passing an invented `model`
field cannot select Turbo. If the session requires this route, report the mismatch and
resolve the model/route choice with the user before motion spend. Direct-provider access
is not automatically authorized by a requirement to match historical settings.
Sources: [video model](https://github.com/recoupable/api/blob/071ff9b6dd02fa338128b193713604dd989f5dc1/lib/content/video/generateVideo.ts),
[video validator](https://github.com/recoupable/api/blob/071ff9b6dd02fa338128b193713604dd989f5dc1/lib/content/video/validateCreateVideoBody.ts),
[image routing](https://github.com/recoupable/api/blob/071ff9b6dd02fa338128b193713604dd989f5dc1/lib/content/image/buildImageInput.ts).
Recheck before a new production; this is a dated capability snapshot. Historical promotional
rates have expired or may change, so get a fresh quote and distinguish reported spend from
estimates. Preserve provider request IDs and local artifacts when calls are slow; reconcile
uncertain submissions instead of duplicating them.
## Scribe compatibility checkpoint
Inspected against API release `090f988060407e343d65dfdc3387156fb7dec0a5` on
2026-10-20. The Small Room workflow still requires ElevenLabs Scribe word timestamps.
Neither inspected Recoup transcription path establishes that capability:
- `POST /api/content/transcribe` defaults to `fal-ai/whisper`. Its optional `model`
string is forwarded to the same Whisper-shaped input and `text`/`chunks` response
adapter; accepting a string does not prove Scribe compatibility.
- `POST /api/transcribe` calls OpenAI `whisper-1` and saves account/artist files.
It is not a Scribe route and can write account data.
Use an existing approved Scribe transcript for the exact recording or a separately
authorized Scribe operation with word timestamps. If neither is available, report the
capability gap before proceeding through timing-dependent production. Preserve the
required provider; do not relabel a Whisper transcript or invent a model override.
Adding a tested Scribe adapter to Recoup is API work, separate from these instructions.
Sources: [content adapter](https://github.com/recoupable/api/blob/090f988060407e343d65dfdc3387156fb7dec0a5/lib/content/transcribe/transcribeAudio.ts),
[content validator](https://github.com/recoupable/api/blob/090f988060407e343d65dfdc3387156fb7dec0a5/lib/content/transcribe/validateTranscribeAudioBody.ts),
[stored transcription adapter](https://github.com/recoupable/api/blob/090f988060407e343d65dfdc3387156fb7dec0a5/lib/transcribe/transcribeAudio.ts).
## Why the linked skills are adapted
Small Room used the character-design and scene-engine methods, plus shotlist-director's
shared style, reference glossary and sequence checks. Its artifact was a Markdown script
and its animation was H3 Max Turbo. The upstream shotlist skill's Seedance prompt grammar,
HTML interface, Soul/Elements setup and automatic 15-second envelopes were not used.
Its silent audition also did not require dialogue, a separate voice model or lip-sync.
Use the applicable methods without importing those unused production branches.
SKILL.md
---
name: recoup-music-video
description: Make a narrative music video using the Small Room workflow — approved song, story bible, scene audit, character audition, props, location plates, shot list, reviewed stills and end frames, motion, and verified edit. Use for "make a music video", "turn this song into a film", or "follow the Small Room workflow". Reuse approved audio; stops at the asset unless publishing is requested.
---
# Music video — the Small Room workflow
Follow the production sequence used to finish **SMALL ROOM / The Projectionist on
2026-09-03**. This is the combined workflow recorded in its bible, identity sheet,
final shot table, generators and render, not a ten-step procedure from one Higgsfield skill.
Read `references/small-room-production.md` for the evidence, final model settings and
historical-versus-current execution differences before selecting generation routes.
**Song → bible → scene audit → character and audition → props and plates → shot list →
reviewed stills → revised clip table and end frames → motion → verified edit.**
Start at the earliest unfinished step. Reuse approved artifacts and keep their approval
state in the project; do not regenerate the song or reopen unchanged decisions on resume.
Carry forward the user's visual direction. Reproduce the workflow, not Small Room's
protagonist, photoreal style, palette, plot, duration or exact number of shots.
## Supporting skills and precedence
The essential Small Room methods are included below; no external skill download
or private project checkout is required. Already installed, reviewed helpers may
assist at the relevant step. Do not fetch remote skill instructions, install
packages or run dependency/bootstrap commands as part of this workflow.
The Higgsfield character-design framework credits **@vavavinca**; the community
reference was OSideMedia/higgsfield-ai-prompt-skill at revision
`c0b73ab946df6658cca513db78bdc3909a655bfd`. This is attribution, not a load step.
| Stage | Accompanying skill | What this workflow takes from it |
|---|---|---|
| New song, only when needed | Already installed recoup-song, when available | Four approvals; Recoup API generation; maximum duration headroom |
| Bible and character audition | Included method; optional installed higgsfield-character-design | World-first bible, character sheet, screen test and identity lock |
| Story audit | Included method; optional installed higgsfield-scene-engine | Goal, obstacle, tactic, reversal and audience value shift |
| Shot list | Included method; optional installed higgsfield-shotlist-director | Global style, reference glossary, named prompts, tempo and monotony audits |
| Composition and verification | Bundled `references/composition-and-verification.md` | Pinned HyperFrames setup, HTML timeline, captions, lint, snapshots, render and inspection |
| Recoup authentication, when using its routes | Host-managed connection; optional installed recoup-platform-api-access | Verify the account and API contract without exposing credentials |
Small Room adapted these methods: its shot list was `SCRIPT.md`, its audition was silent,
and its scene motion was H3 Max Turbo. Do not import the linked skills' Seedance multi-cut
prompts, HTML shot-list deliverable, Soul training or dialogue audition as extra stages.
The finished bible supplies the visual identity for HyperFrames; do not choose a new style
while assembling the already approved film.
## 1. Approve the song and establish the actual timings
Use the exact approved recording and lyric sheet. If no song exists, follow `recoup-song`:
approve idea, genre, exact lyrics/prompt, then the paid request. Its current default is
maximum supported duration (300 seconds), allowing a natural ending. Do not copy Small Room's
historical 120-second request or generate another song merely to enter this workflow.
Save the master, generation ID and approved inputs under `audio/`. Measure the actual file
with ffprobe. Transcribe with **ElevenLabs Scribe**, retaining word timestamps in
`audio/scribe.json`; compare them with the approved lyrics and flag changes, omissions,
repeats and cutoff. Do not use Whisper for this workflow. Get the user's listening approval
before developing the film. An existing approval satisfies this gate.
First verify that the available transcription operation actually supports Scribe and
word timestamps. Recoup's generic transcription routes are not a Scribe substitute;
see `references/small-room-production.md` for the inspected route boundaries. An arbitrary
model override or a file renamed to `scribe.json` does not satisfy this requirement.
If Scribe access is unavailable, reuse an approved matching Scribe transcript or report
the missing capability before timing-dependent production. A separately connected Scribe
service requires its own authorized access and audio submission; do not extract credentials
from another connection or silently switch transcription providers.
The recording determines the film's musical runtime. A later end card has its own separately
approved duration. Do not truncate the song to a generic social-video target.
## 2. Write the story bible
Use the character-design method to write one project-level `BIBLE.md`, in this order:
1. **Premise:** an arguable claim, the counter-argument it must respect, and emotional promise.
2. **World:** physical, social, economic, ideological, historical and sensory rules, limited
to the detail this film needs.
3. **Character:** thematic role, external/internal goals, psychological/moral needs, wound,
spark, silhouette, contradiction and relevant relationships. World before casting.
4. **Story spine:** causal beats connected by consequences, with a turning point and ending.
5. **Style:** palette, lighting, materials, proportions, camera language, wardrobe, props,
continuity and forbidden elements. Derive it from the approved song and user direction.
Record the audio source and measured length. Propose missing creative choices explicitly.
The bible is a reviewable file, not only prose scattered through the conversation.
## 3. Audit the story, then approve the bible
Run the scene-engine audit inside `BIBLE.md` before any character or scene generation:
- **Goal:** the lead's fixed objective; each scene must contribute to it.
- **Obstacle:** what threatens that goal or its current stage, and at what scale.
- **Tactic:** the action taken with available knowledge; a failed attempt must teach something.
- **Reversal:** at least one turn against expectation in each resolved sequence.
- **Value shift:** how that reversal changes the audience's judgment of the character.
Name the weakest point and offer a minimal fix and a fuller alternative. Apply the user's
choice, present the revised bible, and obtain approval. A plot turn without an audience
reassessment is not enough. Preserve approval for unchanged decisions; approve affected
revisions before they propagate into paid assets.
## 4. Design, audition and lock the character
Use **Muse Image** for the candidate stills and reference edits. Build character sheets on
plain grey, then separate face and body references: front/back wardrobe, face close-up and
needed angles; include mouth-open/closed variants when relevant. Present the candidates and
let the user select the character before motion testing.
**Decide the medium here, because it decides the motion model.** A photoreal cast animates with
H3 Max i2v from Muse start stills (the Small Room pipeline). A stylized or animated cast can
instead go to Seedance 2.5 with the sheets as references, one take per song section: Seedance's
input filter (through fal) rejects every photoreal face of any origin but accepts a stylized one
and holds it across shots. Cast photoreal from the user's references first, approve, then
re-render every asset in one style string. Recipe, prompt architecture and costs live in
`references/stylized-motion.md`.
Stage a **silent five-second screen test** of an actual demanding beat from the film,
using **H3 Max Turbo** at the settings in the production reference. It must prove the
character can act with gaze, posture and hands. Small Room tested looking from a failing
lamp to the projector, deciding, and beginning a hand movement; derive this film's test
from its own bible. Use the agreed audition take count, review the motion, and obtain the
user's choice before locking a winner.
Save the selected take and reference roster in `cast/`, with `cast/IDENTITY.md` containing:
- one appearance paragraph reused verbatim in every applicable still prompt;
- one movement sentence reused in applicable motion prompts;
- each reference's role and the state it preserves.
Appearance belongs in still prompts; motion prompts describe action and the movement lock.
Use the face plus at most two other relevant references per scene still, as Small Room did.
When identity drifts, inspect the reference selection before rewriting the character.
## 5. Build props, then empty location plates
Create prop sheets on grey before the scene stills. Lock relevant dimensions, construction,
orientation and state changes; derive variants as edits of the approved prop.
Then make empty location masters in `plates/`. Derive dark/lit/transformed versions as edits
of the same room, preserving geometry. Review and approve props and plates before combining
them with the character. State each reference's role; character, prop and location must
agree on the film's material and visual style. Do not automatically make extra camera-angle
plates for every location.
## 6. Write the song map and connected shot list
Use the shotlist-director method in **`SCRIPT.md`**. Include:
- the first-frame visual hook and the film's premise as readable action;
- song sections anchored to the measured word timings;
- one global style prefix from the bible and the locked identity paragraph;
- an `@`-glossary mapping character, prop, plate and state references to real files;
- per-row ID, song window, duration, story beat, framing, camera move, references, start
state, intended end state, still prompt, motion and caption.
Start with the picture: no opening logo, title card or fade. The song supplies the voice;
do not introduce a separate narrator or an on-camera singing requirement.
Check that the windows cover the complete recording with no gaps or overlaps. Read the
framing and camera columns together: avoid three consecutive shots with the same size and
move. Vary scale and purpose, not merely duration. Show the table for approval before
scene still generation.
## 7. Generate and review scene stills
Use Muse edits of the approved references, with this prompt assembly:
`global style + identity (when present) + location lock + framing + scene state + continuity`
Attach face first when present, then the relevant plate and prop, with at most three
references. An approved earlier shot may supply a more precise location/state reference.
Keep reference roles explicit. Save the exact prompts, reference assignments and results.
Review a contact sheet and individual detail crops with the user before scene motion.
Check identity, hands, prop count/scale/orientation, lighting, background figures, stray
text and the physical cause of every effect. Fix the still first when the flaw is already
visible there. Feed corrections back into the bible's continuity rules and affected rows.
## 8. Revise the clip table and approve end frames
After still review, combine adjacent beats when **one camera setup can cover a continuous
unit of action within the model's duration limit**. Preserve the lyric windows. Split when
framing, location or action cannot be staged coherently together. Small Room changed from
26 planned shots to **17 final clips**; that count is evidence, not a target for every film.
For each clip, assign its approved start still. When a planned change needs an end frame,
make it as an **edit of that start still with the same camera position and framing**.
Only change the intended state. Show start and end side by side before motion spend.
For a held state, Small Room sometimes reused the start as its end anchor; some rows used
no end frame. Do not require a newly generated end frame for every clip.
Mark the revised table as current and archive superseded rows/stills. The active table,
render timeline and generation manifest must agree. Do not let an old build checklist
silently restore the superseded shot count.
## 9. Test the interpolation, then generate and review motion
Generate **one representative start/end clip first**. Small Room used the opening M01,
13 seconds, to test the interpolation. Review it before the scene batch.
Use **MiniMax H3 Max Turbo**, 768P, integer durations 5–15 seconds and
`prompt_expansion_mode: disabled`, subject to the verified route and approved spend scope
in `references/small-room-production.md`. Request enough clip duration for the assigned
window, then trim in the edit.
Motion prompt = row action + applicable movement lock + locked camera or named camera move
+ project-specific continuity exclusions. Do not re-describe appearance. Omit character
movement/face clauses from shots with no visible character. Preserve prop geometry and
light states explicitly where those are at risk.
Inspect motion and extracted frames for face drift, extra limbs, invented light/objects,
unintended camera moves and continuity errors. Keep useful takes; correct only failed
rows within the approved retry budget. If a shot keeps failing, revise or remove it and
update the table rather than repeatedly spending on the same broken action. Small Room
removed C14 and extended M12 while preserving the song timeline. Save kept and rejected
takes separately, along with model, prompt, start/end refs and requested/measured durations.
## 10. Assemble, inspect, render and deliver
Use **HyperFrames 0.7.5**, the version used by Small Room. If a tested local video harness
is available, reuse its structure and fonts; Small Room used the LETAL XLUG harness. Clear
its old media, captions, copy and timing. Otherwise use an already available, reviewed
blank template for the same pinned version. If none is available, prepare the edit
plan and report the missing local rendering capability; do not install a harness.
Read the bundled `references/composition-and-verification.md` for that setup and the
required host capabilities. Keep automatic Whisper transcription and extra skill installation
disabled when scaffolding; preserve the approved Scribe timings and existing host setup.
Place the selected clips at the approved song windows, mute clip audio, and add captions
from the timestamped transcript. Use unique media IDs and explicit start/duration values.
Flag transcription-versus-lyric differences for the user; Small Room's written-word caption
override was explicit, not permission to silently alter captions in future films.
Run lint, validate and inspect, then snapshot important moments and caption transitions:
```bash
hyperframes lint .
hyperframes validate .
hyperframes inspect .
hyperframes snapshot --at <review-times> --describe false .
```
Review those images before rendering. Render the film, mux the approved master with FFmpeg
using **measured linear gain**, and measure the finished audio again. Small Room used
−1 dB; calculate this film's gain from its own measured levels. Keep the master unchanged;
do not apply `loudnorm`. If an end card is approved, append its duration explicitly and
pad only the card's audio tail with silence.
Read frames back from the finished MP4 at cuts, captions and previously troublesome shots;
check the actual movement as well as frame appearance. Confirm full song coverage,
continuous video, caption timing and the ending. A render completing is not a visual pass.
Record what was inspected and any unresolved defects. Return the playable film, measured
duration, source artifacts and actual cost when reported; label estimates as estimates.
Obtain the user's final viewing approval.
Finish at the approved asset. Publishing requires a separate user request naming the destination
and account, an authorized publishing connection, and verification of the resulting post. Video
approval alone does not authorize publication.