Imported from derek-zhuolin/interflow-video-cut (SKILL.md). Install upstream with npx skills add derek-zhuolin/interflow-video-cut. Copyright stays with the author.

Interflow Video Cut — 口播成片 Workflow

Interflow Video Cut converts a local video into a card-based composition: the agent designs the cards (timing + content), assembles one composition HTML, and renders it to MP4 via hyperframes.

Default authoring mode: clone-and-recompose, not free-design. Per card, start from a shipped fragment (references/styles/<key>.html); always swap the text + accent, and recompose its layout freely to serve the card's point — while holding the style's DNA fixed (fonts, theme palette, ornament, spacing scale, overflow guards). Cloning anchors the quality floor in the style's tokens, not in a frozen arrangement, so adjacent cards need not look identical. Hand-authoring from a blank file is the exception, only when content fits no reference.

CLI Resolution

vtake CLI (npx -y @notedit/vtake@latest) handles extract/transcribe; hyperframes (npx -y hyperframes@latest) renders. Both auto-download from npm. SKILL_DIR = this skill's dir (host injects it as "Base directory for this skill: …"); all references/… + scripts/… paths are relative to it.

Reference Map — read the right file at the right step

The workflow skeleton is below; the heavy detail lives in references/. Clone from the library, don't reinvent.

Loading discipline (progressive disclosure — read this first). Every file below is Level 3: it costs zero tokens until you open it, so open it only when you actually branch into its step, and read only the slice you need — not the whole file "to be safe." Concretely: (1) never pre-read these at the start of a run; pull each one at the moment its step arrives. (2) When a file is a catalog/matrix (DESIGN_INDEX.md, the resolution tables in render-strategy.md), read the chosen style's / ratio's row, not the entire matrix. (3) On the fast path — the user pre-approved a single known preset (e.g. says "默认 / glass-hud / 直接产") — skip render-strategy.md and DESIGN_INDEX.md entirely and go straight to that preset's recipe + the one style fragment it clones. Reading all four heavy refs on every run defeats the whole point of moving them out of SKILL.md.

Workflow

Interaction contract — 前置一次问全，然后无人值守跑完（ALL channels）

The user hands you a video to get back a finished film, not to babysit a pipeline. So the ONLY moment you ask the user anything is once, upfront (Step 3.5), in a single batched round — ratio / layout / style / 运镜 / card density. After they answer, you run the entire pipeline (transcribe → correct → storyboard → cards → assemble → render) autonomously to a finished MP4, with no further questions — so they can walk away and come back to a complete work. This ordering is identical on every invocation channel (手机 CLI, 飞书 bot, desktop) — the channel only changes the question transport (native AskUserQuestion vs plain-text), never the timing.

Rules:

• Front-load, don't drip. Never ask a question mid-pipeline that you could have asked in Step 3.5. The old flow asked visual direction at Step 7 (after transcribe) — that's the bug this contract fixes. Precompute everything askable from the file alone (metadata + color analysis) so the whole batch fires before any slow/mechanical step.
• Autonomous = render and deliver, not preview-and-wait. On the autonomous path you self-QA with snapshots (Step 10) and go straight to render (Step 11) — the user reviews the finished MP4 and asks for revisions after. Only drop into the interactive preview loop if the user explicitly says they want to watch/iterate live.
• Stop early only for a genuine blocker (missing file, ASR rate-limit, a contradiction in the request) — not for a preference you could have batched.
• If the user explicitly pre-answers in their opening message ("竖屏 glass 直接产") or says "你看着来/默认", skip Step 3.5's questions and proceed on those + the auto-recommendations.

1. Check Environment

npx -y @notedit/vtake@latest doctor
# confirm bundled assets:
ls "<SKILL_DIR>/assets/fonts" "<SKILL_DIR>/assets/vendor/gsap.min.js"

Required:

• ffmpeg / ffprobe (system)
• python3 (stdlib only) — for scripts/auto-style.py, the auto style-match by video color in Step 7.0
• <SKILL_DIR>/assets/fonts/*.woff2, <SKILL_DIR>/assets/vendor/gsap.min.js (bundled inside this skill, staged to work dir in Step 9)

Optional:

• ELEVEN_API_KEY — set → vtake transcribe hits ElevenLabs directly (no rate limit). Unset → proxy https://vtake.app/api/transcribe (3 req/min/IP; override via VTAKE_TRANSCRIBE_ENDPOINT).

Strongly recommended on macOS for hyperframes render:

export PRODUCER_BROWSER_GPU_MODE=hardware

2. Create a Work Directory

VIDEO_PATH="/absolute/path/input.mp4"
WORK_DIR=".interflow-video-work/$(basename "$VIDEO_PATH" | sed 's/\.[^.]*$//')"
mkdir -p "$WORK_DIR"

3. Extract Audio and Metadata

npx -y @notedit/vtake@latest extract "$VIDEO_PATH" --out-dir "$WORK_DIR"

Outputs: metadata.json (duration, width, height, fps) + audio.mp3.

3.5 Upfront Consultation — ask EVERYTHING here, once (then go autonomous)

This is the single user-interaction gate. Everything askable is decidable from the file alone — no transcript needed yet — so ask it all now, before the slow steps, then run the rest untouched (per the Interaction contract above).

Precompute first (file-only, cheap):

python3 "<SKILL_DIR>/scripts/auto-style.py" "$VIDEO_PATH" --json
# → {"mode","temp","recommend":[...],"recommend_cn":[...]}  → recommendedStyle

• recommendedRatio from metadata.json aspect (≥1.5→16:9 · ≤0.7→9:16 · else 4:5). iPhone .MOV caveat: ffprobe may report a rotated 1920×1080 that displays as portrait — check stream_side_data=rotation before trusting the aspect.
• autoCount from duration × assumed-medium density (Step 6 math) — label it "约 N 张"; you refine the exact count after the transcript exists. Good enough to ask.

Then ask ONE batched round — the 5 visual questions. Use the best channel (native AskUserQuestion; else the plain-text template). The 5 visual questions

• resolution tables live in references/render-strategy.md (read its question call now).

Record all 5 answers in working memory: ratio / layout / style / rhythm / cardDensity. These drive Steps 6, 7, 8 — do not re-ask any of them later. (Channels without a native question tool: post the plain-text batch as one message, parse the reply, proceed. Same timing on every channel.)

If the user already stated preferences in their opening message, or said "默认/auto/你看着来", skip the questions and use those + the auto-recommendations. After this gate, you do not pause again until the finished MP4 (Step 12) — unless a genuine blocker appears.

4. Transcribe (provider-aware: 火山 Seed ASR or ElevenLabs)

Both produce the same transcript.json shape ({ segments, words, raw }, word- level timestamps in seconds) — the rest of the pipeline doesn't care which ran.

if [ -n "$VOLC_ASR_API_KEY" ]; then
  # 火山引擎 Seed ASR 2.0 — 中文友好、便宜、词级时间戳。Key 走 env（不进 git）。
  node "$SKILL_DIR/scripts/transcribe.js" --audio "$WORK_DIR/audio.mp3" --out-dir "$WORK_DIR"
else
  # fallback: ElevenLabs via vtake (proxy mode works key-free, 3 req/min/IP)
  npx -y @notedit/vtake@latest transcribe "$WORK_DIR/audio.mp3" --out-dir "$WORK_DIR" --asr elevenlabs
fi

Output: transcript.json with { segments, words, raw }.

Two ASR providers, pick by env:

• 火山 Seed ASR (VOLC_ASR_API_KEY set) — async submit (base64 audio, no public URL needed); transcribe.js resamples to 16k mono first, polls, and emits the same shape. Optional: VOLC_ASR_RESOURCE_ID (default volc.seedasr.auc), VOLC_ASR_MODEL (default bigmodel). Re-convert a saved result without re- billing: node transcribe.js --from-result volcengine_result.json --out-dir "$WORK_DIR".
• ElevenLabs (no VOLC_ASR_API_KEY) — vtake proxy mode runs key-free out of the box (zero model download) and only hits the rate limit below. There is no local/whisper path.

Rate limiting (proxy mode only — no ELEVEN_API_KEY): the server allows 3 requests per minute per IP. If you see an error starting with rate_limited: or service_busy:, do not auto-retry — stop and tell the user how many seconds to wait (the message includes the retry hint), then resume from this step when they ask again.

Note — this skill is additive only. It decorates a take (cards over video); it does NOT 去口水词 / 去气口 / 去废话. It assumes a reasonably clean recording. If a raw 口播 has lots of 口水词 / 卡顿 / 重说, those stay in the footage and get baked under your cards — clean it first with whatever editor you prefer, then feed the cleaned video here. (Automatic rough-cut is no longer wired into this pipeline.)

5. Correct Transcript

Read transcript.json and fix obvious ASR errors:

• Homophones, product names, technical terms, punctuation
• Preserve all start / end timestamps
• Prefer editing segments[].text only
• Edit individual words[].word only for clear one-to-one replacements

6. Draft a Lightweight Storyboard (in chat)

No CLI involved. Read transcript.json + metadata.json and design cards directly. storyboard.json is an agent-internal planning artifact — no vtake CLI command consumes it; it exists so you can think clearly about timing and content before writing each card's HTML. Keep the shape consistent with the example below so the same outline can drive the composition you author in Step 9:

{
  "schemaVersion": 3,
  "composition": {
    "fps": 30,
    "width": 1080,
    "height": 1920,
    "durationSeconds": 121.2,
    "layout": "portrait",
    "themeId": "noir",
    "seed": 42,
    "background": { "key": "dark-particles", "accent": "#7aa2ff", "opacity": 0.9 }
  },
  "videoTrack": {
    "sourcePath": "input-video.mp4",
    "startSec": 0,
    "endSec": 121.2,
    "bounds": { "x": 0, "y": 0, "width": 1080, "height": 1920 }
  },
  "subtitles": { "enabled": false },
  "cards": [
    {
      "id": "card-01",
      "intent": "Hook with the speaker's anxious midnight question",
      "startSec": 0.5,
      "endSec": 13.0,
      "accentIndex": 0,
      "zone": "fullscreen",
      "beat": "kinetic",
      "contentHints": {
        "kicker": "AN HONEST QUESTION",
        "title": "晚上 11 点的灵魂提问",
        "detail": "客户六十秒语音：「人民币会升值，我的美金保单是不是亏惨了？」"
      }
    }
  ]
}

Required Card fields:

Composition-level background (optional) — a moving atmosphere layer behind the cards / above the video. { key, accent, opacity }; key ∈ backgrounds 库 (dark-particles / starfield / aurora / grid-hud / mesh-gradient) 或 curve:<曲线>（曲线氛围底——氛围归这层，不是前景斜字）。build-timeline.py 自动注入 <canvas> + draw(t) 钩子（Step 9 记得 cp backgrounds.js + curve-atmosphere.js 进 vendor/）。选择在 Step 7「背景层」问题里决定（见 render-strategy.md）。全闭式 draw(t)、 seek 安全。

Five zone values (resolve to card-host pixel bounds in Step 9; full bounds table in references/composition-assembly.md): fullscreen (whole canvas — hero / big numbers) · whiteboard-area (40px inset or portrait bottom-45% — dense data) · lower-third (bottom 30% — annotate over video) · side-panel (landscape right-42% / portrait bottom-40% — data beside video) · video-overlay (full canvas, mostly-transparent card — overlay on full-bleed video). Video bounds are set once (videoTrack.bounds); "moving" video between cards = GSAP tweens on #video-wrap (Step 9).

冲击自动分配（pipeline 全自动 — drafting 时执行，用户不手选）。 扫描修正后的 transcript，命中信号就自动分配 impact，按优先级取最强 ≤3 个（预算硬约束， 超了 build-timeline.py 会 WARN），其余一律回落 transitions.dev 丝滑 kit： ① 认知翻转（"但其实/真相是/大家都错了"）→ break 卡 transition: shatter + 下一张 word-slam 立新观点（优先级最高）；② 开场 hook / 全片最强主张 → beat: "slam"；③ 情绪爆点 / 章节硬切 → flash-cut 或 punch + 可选 videoPunch 踩在重音音节上；④ 命令 / 代码 / 工具名 → type-on。 完整信号表 + Style × impact 准入矩阵（歸藏 clean 家族哪些慎用）见 references/impact-motion.md。

No prescribed roles or arc — cards emerge from what the video says (all quotes, all data, open on a number or a story; let the transcript drive). But when the transcript argues or explains (a mechanism, cause→effect, this-vs-that, setup→payoff — you can say "first… which causes… which is why… so…" across the cards), reach for references/narrative-progression.md: 4 arcs that sequence the cards + stage each card's reveal so motion carries the logic, all in beat/transition/data-anim (no new style). Skip it for a flat list of independent takeaways — those stay平铺.

Card boundaries — one intent per card ("let the transcript drive" ≠ "cut anywhere"). A boundary belongs where the speaker pivots to a new idea; a card spans the stretch between two boundaries. Signals: topic shift ("…now here's what works" = new card) · argument unit (a setup→proof→payoff >~20s = 2–3 cards, one per move) · distinct claim/number/comparison (each its own card, no 4-facts data-dump) · emphasis/repetition (repeated phrase / "the key point" = its own beat) · shot change (face→screen-share→prop). The math below sets how many; these set where. Disagree → trust the intents; never split one idea or fuse two to hit a number.

How many takeaways? — auto-infer from duration + density. No fixed upper limit. Floor is fixed: minimum 5 cards.

Step 1 — base pace by duration (natural sec/card for medium density):

Step 2 — density multiplier: High density (many numbers / distinct claims / staccato) × 0.7 · Medium (mixed data + narrative) × 1.0 · Low (slow narrative, one idea over many sentences) × 1.4.

Step 3 — compute:

cardCount = max(5, round(videoSec / (basePace × densityMultiplier)))

Always sanity-check against content: the math gives a starting count, but the actual intents decide the final count.

Speaker presence — keep the talking head on screen (unless the user wants a faceless explainer): cards annotate, they don't replace. Default = full-bleed/ large-PIP speaker on opening + closing cards, ≥ small PIP/side-panel where the speaker makes a personal point; data-heavy cards can go full-card briefly.

Distill, don't transcribe — a card is information design. The #1 failure is pasting a spoken sentence onto a card; a headline is a rewrite (same meaning, ⅓ the words, point surfaced). Gate every card: (1) one intent, one sentence — can't → split; (2) headline ≠ quote — ~14-char title, demote the explanation to a small detail line; (3) no two cards make the same point — merge/reframe overlaps; (4) shape follows content — comparison→two-column, number→big figure+label, list→stacked rows, quote→large centered. Reject & rewrite if: title > ~14 中文字, detail is a verbatim clause, or the card is "the next sentence" not "the next idea".

Final card — append a customizable brand outro (card-cta). After all content cards, append one fullscreen outro card (contentHints: recap + purpose) and extend composition.durationSeconds by ~3.5s to match its endSec. Lead with a recap / payoff line rewritten from what the video said (the earned content beat, not a logo flash) + a one-line purpose / 延伸 under the wordmark. Re-theme it to the composition's style (reuse --bg/--ink/ --accent-0, swap mark/wordmark/tagline; keep the entrance choreography) — a clashing fixed outro is a defect. Ships the Interflow club sign-off (Interflow

• Interflow AI 出品); for an outside creator swap/drop the brand, no hard-sell CTA, strip AI-jargon (赋能/闭环/leverage…). Full template + JSON + entrance choreography: references/card-contract.md.

7. Resolve Render Strategy (from the Step 3.5 answers — do NOT ask again)

The visual system — ratio / layout / style / 运镜 / density — was already chosen by the user in Step 3.5. This step is pure resolution: turn those stored answers into concrete canvas size, frame, theme palette, and per-card bounds. No questions here (front-load contract).

What this step does with the stored answers:

• Resolve canvas from ratio (16:9→1920×1080 landscape · 9:16→1080×1920 portrait · 4:5→1080×1350 portrait).
• Map style → a specific style key and auto-pick the frame from the layout × style matrix; resolve rhythm (fixed vs dynamic videoBounds).
• Refine cardCount: in 3.5 you used assumed-medium density for the "约 N" label; now the transcript exists, so apply the real density multiplier (Step 6) and let the actual intents set the final count.
• Conditional follow-up already handled in 3.5: if style ∈ {glass / nebula-glass / spatial / geom}, the curve-foreground (5b) and dark-background (5c) micro-questions fire as part of the upfront gate (the user is still there right after picking style) — not here. By Step 7 they're already answered.

→ The full resolution detail — the canvas / frame / bounds tables, theme palettes, day/night style map, 留白, camera rhythm, the storyboard render contract, AND (for reference) the original question call + plain-text fallback — is in references/render-strategy.md. Read only the slice for your resolved ratio/style. (Its "ask" machinery is what Step 3.5 invokes; here you read the resolution tables.)

State back what's locked in one sentence (ratio + canvas size, layout, primary style + any sibling accent styles, frame, final cardCount, rhythm), then proceed.

8. Write Each Card's HTML

Clone-first (the default). For each card:

1. cp "$SKILL_DIR/references/styles/<styleKey>.html" "$WORK_DIR/public/cards/<card-id>.html" — <styleKey> is the card's styleKey if set, else the film's primary style (see the style-family note in Step 7: most cards use the primary; accent cards may pull a tonally-compatible sibling).
2. Rename the fragment's data-card-id="ref-<key>" to this card's <card-id> (update the scoped <style> selectors + element ids).
3. Swap the placeholder copy for this card's real contentHints, set the accent to the card's accentIndex.
4. Compose, don't just fill — but hold the style's DNA. The floor is the style's design tokens (fonts, theme palette / var(--accent-N), ornament, spacing scale) + the overflow guards — keep those fixed. Within that envelope you're free to recompose the fragment to serve this card's point: promote/demote emphasis, switch stacked ↔ two-column, move the panel (bottom / centered / side), drop an unused slot, let shape follow content. Two adjacent cards should NOT be structurally identical when their content differs. Off-limits: re-picking fonts, off-theme color, foreign ornament, breaking overflow safety. Over a talking head, keep the speaker's face clear (a deliberate full-dim statement beat is the rare exception). Full guidance in references/card-contract.md.

Authoring a fragment from a blank file is the exception. Animations are declared, not coded — use data-anim-* attributes only; never write <script> in a card. The composition index.html is the only place a <script> (the GSAP block) lives.

Give each graphic card ONE crafted motion moment (transitions.dev kit — the default, not optional). A card that's just static text on video is the failure this is here to fix. As you fill each card, reach for the content-matched component effect: a number → digit-flip, a list → lines-reveal, an emphasis word → blur-swap/shimmer, a chip → badge-pop, a ✓ → check-draw, a this→that swap → icon-swap; topic shifts between cards → page/reveal handoffs. Add the right <span class="digit"> / .line / .icon-from hooks the effect needs (see the kit). One effect per card + its beat — never stack three (恰到好处). Talking-head/face-is-the-point cards may stay calm; the kit serves the graphic cards. Full default-by-content table + required HTML/CSS per kind + the curve map: references/transitions-dev-motion.md.

结构化内容 → 抬一个视觉组件 (clean 家族). When a card's content hits a structured shape — a trend, a ratio breakdown, a single hero number, an analogy (X≈Y), a black-box, an A+B=C equation, a spectrum, an iceberg, a two-way comparison, or a terminal/chat/code mock — don't free-design it: pick the component via the content→组件 table in references/components/components.md, copy its <!-- COMP:<key> --> block from components-gallery.html, fill real content, and scope its guizang-clean.css classes into the card (same as cloning a clean fragment). These are 归藏-family members — they already encode the 字号字重 + 间距 discipline, so don't hand-tweak their font/spacing values. clean 家族 only.

简洁排版类·歸藏家族 cards (swiss / minimal / terminal / editorial-print / pastel-aura): before composing, read references/styles/guizang-dna.md — these share one DNA (字号字重耦合 + 预设调色板 + 组件库 guizang-clean.css)。配色只能取 预设表（禁自定义 hex，accent 经 --accent），组件用 .stat-card/.callout/ .pipeline/.timeline-v/.bar-chart/.kicker/.meta/.mark，一片一支柱永不混。 写完每张 clean 卡跑一遍校验：

node "$SKILL_DIR/scripts/validate-clean-card.mjs" "$WORK_DIR/public/cards/<card-id>.html"

应 PASS（无 hard fail）；交付前对照 guizang-checklist.md 过 P0。

→ The complete Step 8 — the card HTML contract + hard rules (lint), the canvas-atmosphere exception, NON-NEGOTIABLE overflow safety, portrait mobile-first sizing, the silky motion philosophy, the full data-anim kinds table, and the card-cta brand-outro template — is in references/card-contract.md. Read it once before your first card — the overflow safety + contract hard-rules are mandatory; the data-anim table and the card-cta template are lookups, jump to them only when you actually need them (don't re-read the whole file per card).

9. Assemble the Composition HTML

Stage the assets and write $WORK_DIR/public/index.html:

# SKILL_DIR is injected by the host ("Base directory for this skill: …")
SKILL_DIR="<SKILL_DIR>"

mkdir -p "$WORK_DIR/public/fonts" "$WORK_DIR/public/vendor" "$WORK_DIR/public/cards"
cp -n "$SKILL_DIR/assets/fonts/"*            "$WORK_DIR/public/fonts/"
cp -n "$SKILL_DIR/assets/vendor/gsap.min.js" "$WORK_DIR/public/vendor/"
# if storyboard.composition.background is set, stage the background-layer libs
# (build-timeline.py injects the <canvas> + draw(t) hook automatically):
cp -n "$SKILL_DIR/references/backgrounds/backgrounds.js"        "$WORK_DIR/public/vendor/"
cp -n "$SKILL_DIR/references/curve-motion/curve-atmosphere.js"  "$WORK_DIR/public/vendor/"
# copy the STATIC composition shell — do NOT retype it
cp "$SKILL_DIR/references/composition-shell.html" "$WORK_DIR/public/index.html"
# stage the input video so the composition can reference it by relative path
ln -f "$VIDEO_PATH" "$WORK_DIR/public/input-video.mp4" 2>/dev/null \
  || cp "$VIDEO_PATH" "$WORK_DIR/public/input-video.mp4"

Then fill the shell — do not regenerate it. index.html is the copied composition-shell.html (already has #stage / #video-wrap / card-host structure + @font-face + GSAP runtime). Edit only these slots:

1. The 6 {{...}} tokens at the top: {{BG}} {{TEXT}} {{ACCENT_0..4}} (from the chosen themeId palette), {{DURATION}} (= composition.durationSeconds), {{FPS}}, {{WIDTH}}, {{HEIGHT}}. The tokens appear in a few places each — a sed pass replaces all at once, e.g. sed -i '' -e 's/{{DURATION}}/121.2/g' -e 's/{{FPS}}/30/g' … "$WORK_DIR/public/index.html". (sed -i '' is macOS/BSD; on Linux use sed -i with no ''.)

2. .video-wrapper initial left/top/width/height — set to card-01's layout bounds.

3. The two INJECT-* markers — do NOT hand-author these. Run the generator; it reads storyboard.json + public/cards/*.html and fills both the card-host divs and the full GSAP timeline (enter / drift / exit, with data-anim attributes compiled via the cheat sheet, times quantized, data-track-index increasing, drift repeats finite):

   python3 "$SKILL_DIR/scripts/build-timeline.py" --work "$WORK_DIR"   # add --slip 0.55 to tune

   Idempotent — re-run after editing any card / the storyboard; it re-injects between its BEGIN/END sentinels. Run it AFTER Step 8 (cards exist) and AFTER the sed fill; read its stderr timing warnings. What it leaves to you: #video-wrap reframes for dynamic (起伏运镜) rhythm — add "videoBounds": {left,top,width,height} (+ optional "videoClass": "video-wrapper pip") to a card in storyboard.json and it emits the reframe tween at that card's slip; cards without videoBounds keep the video put (calm default).

Hand-authoring the timeline is the exception — only for a one-off motion the cheat sheet can't express (then stop re-running the script, it overwrites). Else declare motion as data-anim-* (Step 8) and let the generator compile it.

→ The Step 9 reference detail — the GSAP statement cheat sheet, card-timing validation (overlap is intentional), the video framing reference per layout, the HyperFrames layout/animation QA rules, the hard-won gotchas (read before assembling), and the fixed card-cta GSAP block — is in references/composition-assembly.md.

10. QA — autonomous-default: snapshot self-QA → render → deliver

Default (autonomous path): do NOT open the interactive preview or wait for approval. The user front-loaded their choices in Step 3.5 and walked away to get a finished film. So self-QA with single-frame snapshots (cheap — one per card moment), fix any overflow/placement issues you see, then go straight to Step 11 (render) and deliver the MP4. The user reviews the finished work and asks for revisions after — that's when you iterate.

cd "$WORK_DIR"
# self-QA: one snapshot per card beat (cheap; NOT a render)
npx hyperframes snapshot public --at 5 --describe false   # writes public/snapshots/frame-…png

Interactive path (only if the user explicitly asked to watch/iterate live): start the live studio and share the URL — it opens instantly, plays/scrubs in real time, and hot-reloads on every edit.

cd "$WORK_DIR"
npx hyperframes preview public --no-open
# prints e.g. "Studio  http://localhost:3002" (auto-picks the next free
# port if taken). Share that URL with the user.

Interactive loop (only when the user opted to watch live):

1. Assemble / edit the composition (Step 9).
2. Run hyperframes preview (once — it stays up and hot-reloads). Give the user the localhost URL.
3. User reviews in the browser → requests changes → you edit the HTML → user just refreshes / re-scrubs. No render in this loop.
4. Only when the user explicitly approves do you move to Step 11 (render). Do not render proactively just to "check" — snapshots (hyperframes snapshot) cover your own static QA without a full render.

Autonomous default does the opposite: no preview server, no waiting — snapshot-QA then render directly (the user is away). Use the interactive loop ONLY when they said they want to iterate live.

For YOUR OWN spot-checks during building, use single-frame snapshots (cheap), not renders:

npx hyperframes snapshot public --at 5 --describe false   # writes public/snapshots/frame-…png

Pass --describe false to silence the built-in Gemini QA (prints GEMINI_API_KEY not set, skipping otherwise). Frames write to the real path public/snapshots/frame-*.png (not snap-*.png). Under zsh an unmatched glob hard-errors (nomatch → exit 1) — guard loops with setopt +o nomatch.

Manage preview servers: hyperframes preview --list / hyperframes preview --kill-all.

Headless / cron runs (no desktop): skip the interactive preview and go straight to Step 11, using snapshots for QA.

11. Render to MP4 (autonomous default — render once snapshots pass; or after live approval)

cd "$WORK_DIR"
PRODUCER_BROWSER_GPU_MODE=hardware npx hyperframes render public \
  -o output.mp4 \
  --fps 60   # 60 for spring/motion-heavy comps — matches the live preview's fluidity

Render at --fps 60, not 30. The live preview plays via the browser's rAF (~60fps) so spring/back.* overshoot looks buttery; a 30fps render samples the same motion at half the temporal resolution and the springs read as slightly stepped — the #1 reason "the MP4 feels stiffer than the preview". The easing is identical; only the sampling differs. Use 30 only for static/calm talking-head cuts where file size matters.

hyperframes render <dir> reads <dir>/index.html and produces the MP4. The flag PRODUCER_BROWSER_GPU_MODE=hardware (or --browser-gpu) is strongly recommended on macOS — software-only Chrome rendering times out on most laptops.

For a sanity check before the full render, capture a single frame at a specific timestamp:

npx hyperframes snapshot public --at 5 --out snapshot-5s.png --describe false

12. Report Results

Tell the user: work dir path · key artifacts (storyboard.json, public/cards/*.html, public/index.html, output.mp4) · ASR provider · card count + how you chose them (1 sentence) · any missing keys / quality caveats. Don't delete the work directory unless asked.