HyperFrames Studio Conventions

This skill covers two things: how you talk with the owner about a film before touching files, and how you lay a project out so that anyone who opens it later in HyperFrames Studio (the owner on their own machine, a teammate, or you) sees a short, readable timeline instead of a wall of unlabeled rows. Studio draws one row per top-level element. A project built to these rules opens as a base row, one row per scene, one caption row and the audio rows; every part can be selected, trimmed, muted or moved on its own.

When to use

• The owner sends a message about a film in progress: a change ("make the title bigger"), a felt note ("the intro feels jolty"), a question ("why does the title jump?"), a hold ("don't change anything yet"), or an idea ("I want the ending to feel bigger").
• The owner asks for a new film, a new version, or a cutdown of an existing one.
• You are deciding where scenes, captions, overlays and audio go in index.html, or which track each one sits on.
• You need to check that captions and key content sit inside the safe zones for the frame size.

What you need

• Your computer set up for HyperFrames: run the check in references/computer-setup.md first.
• The project folder and its plan files: BRIEF.md, STORYBOARD.md, index.html, compositions/. Read npx hyperframes timeline --json to know what is on the timeline instead of opening every file.
• For the edit itself, the copyable creator-editing recipes in hyperframes-core; load it with skill_view. Never invent another form of an edit those recipes cover.
• For a new film's brief, pitch round and build, hyperframes.

Method

1. Read the message before you open a file

Decide what the owner is asking for:

The owner	You
names a change, however politely ("make the title bigger", "can you cut the third scene?")	Make it.
gives a felt note on the built film ("the intro feels jolty", "it doesn't go long enough")	Find the cause, change the measurable thing, say what the note meant and what moved, and record it in STORYBOARD.md (step 5).
asks a question and names no change ("why does the title jump?")	Answer it. Change nothing.
says don't change anything, hold, "just thinking", "let's talk"	Change no file, not even a fix you noticed. Offer it in words.
brings an idea for this film with no concrete change ("I want the ending to feel bigger")	Propose the change and add it to the plan. Change no composition file.
asks for a new film	Plan it (step 6).
approves a plan ("build it", "go")	Build what was approved.

A message that asks a question and names a change gets the answer and the change. Only when you cannot tell whether it asks for anything is it a conversation: a wrong answer costs one message, a wrong build costs a long run and a round of notes. Worked examples of each row are in references/conversation-examples.md.

2. Reply to a conversation, do not build

• Answer first, in plain words, in a few sentences.
• Ask only questions whose answer changes the film, each with a recommended answer and its trade-off ("30 seconds fits a feed; 60 leaves room for the demo"). Use clarify for a choice the owner must make.
• When there is an idea to shape: for a new film, offer directions using the pitch round in hyperframes; for an idea about this film, two or three options for the part named. Recommend one.
• End with the next step and the word that starts it ("Say build and I'll start").

3. Keep the plan in the project, not only in the chat

The next message may start a new session that cannot see this one. Add the plan to STORYBOARD.md the way a review round is recorded (step 5), and never overwrite locked frames. If the owner asked you to change nothing at all, write nothing: put the plan in the reply and offer to save it.

4. Lay out the timeline

Follow these four rules whenever you create or restructure index.html. A complete, lint-clean example with every kind of track is in references/timeline-layout.md.

1. Every scene is a sub-composition. The root composition holds only timed hosts, media and audio. Any scene with nested structure (a div with children, a title with a subtitle, a chart) is its own file loaded with data-composition-src (wiring in hyperframes-core, its sub-compositions reference). Nested markup left in the root does not get rows of its own; it hides inside one opaque row that cannot be trimmed or moved part by part, and lint warns nested_structure_needs_subcomposition. Author as if that warning were an error.
2. One caption track. All captions live on one track: a single sub-composition host with one data-track-index, marked data-track-kind="captions", carrying every caption group in order. Never one row per caption group, and never captions mixed onto a track with another kind. Word timing follows the caption_* lint rules; see media-use for transcripts and caption timing.
3. One element kind per track. Group by kind so each row is one thing the owner can select, mute or drag as a set:

Kind	data-track-kind
Base video / A-roll	video (from the tag)
Scenes, overlays, graphics	graphics
Captions	captions
Audio (voiceover, music, sound effects)	audio (from the tag)

Put data-track-kind on sub-composition hosts; <video> and <audio> get their kind from the tag. Give each kind its own data-track-index. The number is display only and never changes what renders on top: use CSS z-index for layering. 4. Safe zones. Rulers and safe-box overlays belong to Studio's preview pane, never inside the composition: do not add guide elements to the HTML. Both framings use the same two boxes (Premiere's defaults; in the open-source repo, ACTION_SAFE_PERCENT and TITLE_SAFE_PERCENT in packages/studio/src/utils/previewSafeMargins.ts):

Box	Share of the frame	Inset on every edge	1920 by 1080	1080 by 1920	1080 by 1080
Action-safe	90%	5%	x 96 to 1824, y 54 to 1026	x 54 to 1026, y 96 to 1824	54 to 1026 both ways
Title-safe	80%	10%	x 192 to 1728, y 108 to 972	x 108 to 972, y 192 to 1728	108 to 972 both ways

Everything visible stays inside action-safe; captions and key content stay inside title-safe. Two-up and 50/50 layouts keep each half's content inside title-safe. When a caption track runs, keep other content above about 83% of the height (900 px on a 1080-tall frame, 1600 px on a 1920-tall frame) so it never collides with the captions; npx hyperframes check --caption-zone "x0=0;y0=.82;x1=1;y1=1" flags text that enters the band.

5. Record notes rounds in STORYBOARD.md

Above the first ## Frame heading (anything after the last frame leaks into that frame's section):

• ## Changes from v1 (then v2, v3): the owner's notes, verbatim, with what you changed.
• ## Still open: questions not yet answered.
• ## Locked: what the owner has confirmed. Build only what is locked. Bump the version each round and revise only the frames the notes name. When the build lands, the compositions are the truth: regenerate the timing table from index.html (and the transcript when there is voiceover), update STORYBOARD.md to match, and state the final length.

6. A new film: plan, storyboard, build

The HyperFrames launch films (https://github.com/heygen-com/hyperframes-launches) were made in this order:

Step	Owner
1. Brief	hyperframes, its intent interview. Inside an existing project only a follow-on to the same film stays: a new version or a cutdown, same route and aspect. Ask its must-have questions, skip init, never overwrite BRIEF.md or STORYBOARD.md, add a new dated section to each, and say so in the reply. A film with a different route or aspect starts a new project, and the reply says so.
2. Directions	hyperframes, the pitch round
3. Storyboard	hyperframes, the storyboard and review loop (see also hyperframes-creative)
4. Build	hyperframes, the production loop, with hyperframes-core for structure
5. Notes	step 5 above, then hyperframes' review loop

What the launch films add for a product launch (where the chosen arc says otherwise, the arc wins):

• Real footage of the launched product. Ask for a screen recording in the brief unless the run captures it itself (a site from its URL), and hold its slot with a labelled placeholder until it arrives. Never approximate the launched product's UI. A third-party tool shown as context (a chat app, an editor) is rebuilt faithfully from a capture.
• One world. The same window or canvas continues across beats. Scrub every cut (snapshots either side of it): whatever persists must not jump.
• Cursors and scrolled content leave through the window or frame edge, not by fading mid-frame.
• Close on the command or the address, with the logo landing in footage that is still moving.
• State the runtime at every version. Running past the target is the owner's call, not yours.

Output

• For a conversation: the answer, the options with a recommendation, and the next step, with nothing changed on disk (or the plan saved to STORYBOARD.md when the owner did not forbid writing).
• For a change: the edited files, one line per change saying what moved and why, and the new runtime.
• For a layout pass: index.html with one host per scene, one caption host, kind-grouped tracks, and the timeline output pasted into your note:

video (1)     a-roll 0-12s
graphics (2)  el-title 0.5-3.5s, el-stat 6-10s
captions (1)  el-captions 0-12s
audio (2)     music 0-12s vol=0.3, sfx-whoosh-stat 5.9-6.2s

Checks before you finish

• Your reply matches the row in step 1: no file changed for a question, a hold or an idea.
• npx hyperframes lint shows no findings, including no nested_structure_needs_subcomposition warnings.
• npx hyperframes timeline shows one base video row, one row per scene host, exactly one caption row and the audio rows, each kind on its own track index.
• Snapshots at caption and title moments (looked at with vision_analyze) show text inside title-safe and nothing colliding with the caption band.
• STORYBOARD.md records the round (changes, still open, locked) and the stated runtime.

Pitfalls

• Editing on a question. "Why does the title jump?" is not "fix the title". Answer, then offer the fix.
• A fix you noticed during a hold. The owner said not to change anything. Mention it; do not make it.
• One row per caption group. Twenty caption rows bury the timeline. One host, every group inside.
• Using track numbers for layering. Track index is a display lane; a clip on track 5 is not in front of track 1. Use z-index.
• Guides in the composition. Safe-box overlays added to the HTML render into the video.
• Approximating the product. A hand-drawn imitation of the launched product's UI reads as fake. Use the real recording or capture, or hold the slot.
• Plans that live only in chat. The next session cannot see them. Write the round into STORYBOARD.md.