Broll Story

B-roll Story (avatar doing an activity)

The action / demonstration counterpart of the broll skills. Where broll-generator synthesizes presenter-free B-roll and broll-finder finds real footage, broll-story puts OUR avatar on screen DOING something — a silent, voice-over-ready clip where the focus is the action, not the dialogue (the avatar may be speaking, but it's off-screen narration, so there is no lip-sync). Think ALF grabbing the camcorder, or a full-body shot of the presenter showing a place, taking calls and scheduling on screen, seen from behind, cooking, building — optionally interacting with invented side-characters.

It is an orchestrator over two existing skills: gpt-image-2 (one storyboard sheet) → seedance-2 (animate it) → muted clip.

Inputs (gather what's missing)

Prerequisites

• gpt-image-2 ready (shared Replicate token) — produces the sheet.
• higgsfield CLI installed + authenticated with credits (higgsfield account status) — runs seedance.
• ffmpeg on PATH — mutes the clip.

Pipeline

short script + avatar ref + ratio
  │
1 AGENT authors the Phase-1 storyboard prompt (6 panels) following gpt-image-2's
  │      prompts/storyboard_framework.md — adapted to broll-story, NOT simplified
  │      -> <slug>.board.txt
  │
2 make_broll_story.py:
  │   gpt-image-2 generate_image.py  -> ONE 6-panel storyboard sheet (the ratio's grid)
  │   seedance-2  (baseline storyboard→movie prompt via prompt_tools.py, verbatim)
  │               -> 8s 720p video, same ratio
  │   ffmpeg -an  -> MUTED clip in <avatar>/broll/story/<NNN>_<slug>.mp4 + manifest.json
  │
3 hand off to avatar-reel-composer as a broll scene (broll_source: existing)

Hard rules (do not break)

• 6 panels, ONE storyboard image. A single composite sheet for the requested ratio (16:9 → 3 columns × 2 rows; 9:16 → 2 columns × 3 rows).
• Follow the baseline prompts verbatim, do NOT simplify them. Author the storyboard image prompt by following gpt-image-2's storyboard framework (~/.cursor/skills/gpt-image-2/prompts/storyboard_framework.md, sections A–H). The seedance animation prompt is the baseline storyboard→movie one-liner produced by prompt_tools.py storyboard — the script uses it as-is. "no simplifiques los baseline prompts."
• Do not tie the panels to 8 seconds. "no necesitas especificar en la imagen del storyboard que los paneles deban calzar en 8 segundos, eso lo determina el skill automáticamente … preocúpate que la historia esté bien representada en la imagen y no de su duración especificada." The storyboard may carry the framework's own timecodes (even 15s/30s); seedance compresses the whole board into the requested 8s. Representing the story well in the 6 panels matters; the storyboard's stated duration does not.
• Silent output, no audio requests. "No le pidas a seedance-2 sonidos ni voces específicas porque el resultado estará muteado." The clip is muted; the avatar's voice is laid on later as voice-over by avatar-reel-composer.
• No lip-sync / no talking-head. Seedance cannot lip-sync without an audio reference, and these segments are not about what is said — write panels around what the avatar is DOING (action, blocking, camera changes), not dialogue.

Workflow

1 — Author the storyboard prompt (the creative step)

Follow gpt-image-2's storyboard framework (Phase 1, sections A–H), not simplified, adapted to broll-story:

• Subject: the avatar performing ONE activity across 6 beats (setup → do the thing → a small turn/interaction → result). Drive every panel with action, not dialogue.
• Character DNA: describe the avatar from --avatar-ref and demand identical identity/wardrobe across all panels. Invented side-characters are welcome — give each a distinct, consistent description.
• Shot variety (this is the point): first-person / POV, over-the-shoulder, from behind, full-body wide showing the whole action, inserts/close-ups of what the hands do, camera changes between panels. Never a centered talking-head.
• Grid for 6 panels: 16:9 → 3×2; 9:16 → 2×3 (flip the grid for vertical, per the framework).
• Save the prompt to <slug>.board.txt. See REFERENCE.md for a broll-story Phase-1 template and worked examples.

2 — Generate + animate + mute (the mechanical step)

python3 .cursor/skills/broll-story/scripts/make_broll_story.py \
  --prompt-file <slug>.board.txt \
  --avatar-ref <avatar>/refs/<hero>.png \
  --ratio 9:16 --slug <slug> --avatar-dir <avatar> \
  --script "the short VO line for this beat (manifest only)"

It writes <avatar>/broll/story/<NNN>_<slug>.mp4 (muted) + a manifest.json entry and prints a JSON summary. Useful flags: --sheet PATH (reuse an existing sheet, skip image gen), --resolution, --duration (default 8), --panels 1-3 (animate a sub-range), --keep-audio (rare). QA the printed sheet before trusting the clip; re-author the prompt and re-run if a panel is off.

3 — Hand off to avatar-reel-composer

Drop the clip into a storyboard broll scene; the composer lays the avatar's single master narration over it in sync:

{ "id": "s3", "type": "broll", "broll_source": "existing",
  "broll_clip": "doki-monster/broll/story/001_doki-show-office.mp4",
  "text": "the contiguous slice of the narration spoken over this beat" }

Notes / troubleshooting

• Story longer than one clip? Seedance is ≤15s and best ≤8s. For a longer beat, make ONE sheet and animate it once at 8s; if a sequence truly needs more time, split the script into two broll-story calls (two sheets) rather than one long clip.
• ip_detected / blocked — a photoreal human face in the sheet can trip seedance. Keep invented side-characters stylized to match the avatar; re-run.
• Session expired / out of credits — higgsfield auth login / top up, then re-run (the sheet is cached in the work folder; pass --sheet to skip image gen).

Additional resources

• broll-story Phase-1 template, per-ratio grids, examples: REFERENCE.md
• gpt-image-2 storyboard framework (verbatim baseline): ~/.cursor/skills/gpt-image-2/prompts/storyboard_framework.md
• seedance-2 storyboard→video framework + baseline one-liner: ~/.cursor/skills/seedance-2/prompts/storyboard_video_framework.md
• Consumer: avatar-reel-composer (broll_source: existing). Siblings: broll-generator (synthetic, presenter-free), broll-finder (real footage).