Reel builder

<objective> End-to-end reel generator. Input: topic OR research brief OR pre-written script. Output: a single MP4 file with stitched video shots + background music + optional captions, plus the individual components (shots, music, script) for reuse.

This skill orchestrates:

1. viral-text (or user-supplied script) → 3-shot screenplay with timed captions
2. video-prompt --execute → N video shots via the chosen provider (Veo 3.1 / Sora 2 / Kling 3.0 / Runway Gen-4)
3. music-prompt --execute → 1 music track via Suno / Stable Audio / ElevenLabs Music / Lyria 3 Pro
4. common/style-library/video/ (12 directorial styles) and common/style-library/music/ (12 genre presets)
5. ffmpeg → concat shots, mix music, burn captions

Use when the user wants a finished reel, not just video prompts. Without --execute, returns assembled prompts; with --execute, generates the MP4.

This skill does NOT:

• Add a voiceover / TTS narrator (out of scope for v1 — would need ducking/mixing logic; planned v2.4.0)
• Composite multi-track edits beyond hard cuts (no dissolves, no transitions other than concat)
• Beat-sync shots to music BPM (would need BPM detection; planned later)
• Post to platforms — that is post-publisher, which takes this skill's output directory (the final.mp4) as its input
• Run editing software (Premiere / DaVinci / CapCut) — uses ffmpeg only </objective>

ROLE

Topic / research / script → build 1-4 shot screenplay with timing → resolve video style (directorial anchor) + music style (genre preset) → generate shots in parallel (async polling) + music in parallel → ffmpeg concat → ffmpeg audio mix → optional caption burn-in → print final paths.

PIPELINE

1. Resolve input source:

   • --script-file <path>: read pre-written script with shot timing markers and captions (skip step 2)
   • --research <path>: read brief, extract key facts, condense into a 15-30 sec hook+payoff narrative
   • --topic "<text>": invoke viral-text to draft a hook+beats+payoff script (~80-150 words)

2. Plan shots — see references/shot-planning.md:

   • Default: 3 shots × 5 sec = 15 sec total (TikTok / Reels sweet spot)
   • Single-shot mode: 1 shot × 8 sec (Veo 3.1 max) — for atmospheric / one-take pieces
   • Each shot has: index, screenplay line (action description), camera/composition note, dialogue or VO line (optional)
   • Shot 1 always carries the hook (must land in first 1-2 sec)

3. Resolve video style — see references/style-resolution.md:

   • --style <id>: load common/style-library/video/<id>.md. Use the Shot anchor (per-shot prompt fragment) block.
   • --style auto: pick from library based on topic/tone + pacing requirements.
   • Same anchor APPENDED to every shot's prompt. ONE style for the whole reel.

4. Resolve music style — see references/music-pairing.md:

   • --music-style <id>: load common/style-library/music/<id>.md. Use the Suno Style box + meta-tag stacks if Suno selected; or the Lyria field-driven block if Lyria; or the ElevenLabs prompt if Eleven.
   • --music-style auto: pick from library based on video style (each video style has a "Suggested music style" field — start there) + tempo requirement.
   • One music track for the whole reel.

5. Pick providers — see references/model-picker.md:

   • Video: --video-provider auto|veo-3-1|veo-3-1-fast|veo-3-1-lite|kling-3|runway-gen-4-5|fal-video. Auto-pick by style requirements.
   • Music: --music-provider auto|suno-v5-5|stable-audio-2-5|eleven-music|lyria-3-pro. Auto by genre/instrumental.

6. Build per-shot video prompts via the shared chain — DO NOT hand-write prompts per shot. Instead, spawn ONE Agent with the canonical SYSTEM_PROMPT at ../common/video-prompt-library/system-prompt.md:

   • Load the SYSTEM_PROMPT verbatim from that file.
   • Fill buildUserMessage(opts) per the shape in the same file:
     • Mode: i2v (default — when carousel slides / poster frames are present) or t2v (script-from-scratch).
     • For i2v: pass each source frame's image_url + a one-line summary of the in-image overlay text per shot (the LLM uses it to choose which one motion fits the slide's rhetoric, then strips it from the output prompt).
     • For t2v: pass the screenplay beats per shot.
     • Always pass the character-identity marker (8-15 words) and the resolved video-style entry.
   • The Agent returns ONE JSON object {"shots":[{"index":N,"prompt":"...","kwargs":{...}}]} — all N shots in a single call. Per-shot subagent calls break identity consistency, just like in the carousel chain.
   • Append each shots[i].prompt + shots[i].kwargs to plan.json (single canonical path, overwrite — don't proliferate plan-v1.json).

   The SYSTEM_PROMPT encodes the full discipline: i2v 11 rules (2-sentence cap, 80-word cap, single motion verb, identity front-loading, global lock sentence verbatim, no rhetorical adjectives, no punitive labels, contact-motion subject-anchored not target-anchored, etc.) and the t2v cinematic template. The human-readable rationale + worked before/after examples live in the sibling video-prompt skill's i2v-prompting reference document (at ../video-prompt/references/). When the two files conflict, the SYSTEM_PROMPT wins — that doc is the rationale, not the authority.

7. Build music prompt based on music-style library entry:

   • Suno: Style of Music box + Lyrics box (instrumental: empty/structured-tags-only)
   • Lyria: prompt + key + BPM + (optional lyrics)
   • Eleven: single prompt with bracketed cues + duration
   • Stable Audio: free-text instrumental composition

8. Estimate cost — sum video shots + music. Confirm batch if >$0.10 and not --yes.

9. Execute in parallel:

   • Video shots: parallelism N (default 2 — video calls are 30-90s each, more concurrency stresses rate limits)
   • Music: 1 call running concurrently
   • All async via JobHandle + poll-with-timeout
   • Manifest updated after each completion

10. ffmpeg stitch (only if all shots succeeded; partial failures stop here for safety):

    • Concat N shots in order: ffmpeg -f concat -c copy → shots-concat.mp4
    • Mix music: replace audio track with music.mp3, fade-out 0.5s at end → with-music.mp4
    • (If --captions on) Burn captions via drawtext filter per timed entry → final.mp4

11. Output:

    ./generated/reel/<slug>/
      final.mp4           # the finished reel (15s typically)
      shots/
        shot-1.mp4
        shot-2.mp4
        shot-3.mp4
      music.mp3
      script.md           # screenplay + captions + shot prompts
      manifest.json       # for --resume
      style-used.md       # video style + music style snapshot
    

    stdout last lines:

    Reel: ./generated/reel/<slug>/final.mp4
    Components: ./generated/reel/<slug>/{shots/, music.mp3, script.md}
    

MODES

Input

• reel-builder --topic "<text>" — draft script then generate
• reel-builder --research <path> — ingest research brief, derive script
• reel-builder --script-file <path> — use pre-written screenplay (see references/shot-planning.md for format)

Structure

• --shots N — 1-5, default 3
• --shot-duration S — seconds per shot, default 5 (cap per-provider varies: Veo 8s, Sora 10s, Kling 8s)
• --aspect vertical|square|horizontal — 9:16 / 1:1 / 16:9, default vertical
• --captions on|off — burn timed captions via ffmpeg drawtext, default on

Style

• --style auto|<library-id> — video directorial style (see common/style-library/video/_index.md)
• --music-style auto|<library-id> — music genre preset (see common/style-library/music/_index.md)
• --style-mod "<override>" — append tweak to video anchor

Providers

• --video-provider auto|veo-3-1|veo-3-1-fast|veo-3-1-lite|kling-3|runway-gen-4-5|fal-video — video API
• --music-provider auto|suno-v5-5|stable-audio-2-5|eleven-music|lyria-3-pro — music API
• --video-instrumental on|off — for music: pure instrumental (default on for reels — voiceover is out of scope v1)

Execution

• --execute — actually generate (else returns plan + prompts)
• --output <dir> — custom output path
• --parallelism N — concurrent shot calls (default 2, max 4)
• --yes — skip cost confirmation
• --resume — pick up from manifest

Inspection

• --prompts-only — assemble script + per-shot prompts + music prompt, save to script.md, exit
• --cost-only — print total estimated cost, exit
• --check — validate env vars + library files + ffmpeg available

ffmpeg gating

• If ffmpeg is not detected on PATH:
  • With --execute: still generates shots + music, then prints the ffmpeg concat command for the user to run manually.
  • --check: reports the missing binary and the manual install command (brew install ffmpeg / apt-get install ffmpeg).
• SKILLS_SKIP_FFMPEG=1: don't attempt ffmpeg even if installed. Outputs stay separate.

REFERENCES (load on demand)

File	When to load
references/shot-planning.md	Step 2 — shot count templates, timing, screenplay format, dialogue rules
references/style-resolution.md	Step 3 — directorial style auto-pick, Inspired by vs anchor, override semantics
references/music-pairing.md	Step 4-7 — music genre auto-pick from video style, BPM matching, instrumental rules, per-provider prompt mapping
references/model-picker.md	Step 5 — video + music provider decision trees, capability matrix, cost preview
references/ffmpeg-stitch.md	Step 10 — concat, audio mix, fade-out, burn-in caption filter syntax, ffmpeg gating
references/captions.md	Caption writing — placement, line length, timing, accessibility
references/troubleshoot.md	When shots fail, music doesn't match, ffmpeg errors, sync issues

EXAMPLES

See examples/before-after.md — 3 calibration runs: 3-shot vertical reel from a topic with Suno music (Veo 3.1 + Suno v5.5), 1-shot atmospheric reel with Stable Audio (Sora 2 + Stable Audio), 4-shot product reel from research brief with Kling 3.0 + Lyria 3 Pro.

CONSTRAINTS

• One video provider for all shots. Mixing Veo / Sora / Kling across shots breaks the look. Lock per-reel.

• One music track per reel. Not one per shot. The music plays under the whole sequence.

• Music duration ≥ total video duration. ffmpeg -shortest clips music to video length, so generate music a bit longer than reel. Default: reel_duration + 2s of music.

• No voiceover / TTS in v1. If the user asks "narrate this", suggest pasting voiceover separately via ElevenLabs TTS UI + manual mix. Voiceover orchestration with ducking is v2.4.0+.

• Hard cuts only. ffmpeg concat does straight cuts. No dissolves / wipes / fancy transitions.

• First 1-2 seconds carry the hook. Reel feeds scroll fast — if the opening doesn't land, audience leaves. The shot-planning reference enforces this in script structure.

• 9:16 vertical is the default. 95%+ of reels are vertical. Override with --aspect square|horizontal only when targeting non-vertical platforms.

• ffmpeg failure → graceful: if ffmpeg fails (codec mismatch, exotic edge case), save shots + music separately and print the manual ffmpeg command. Don't lose the work.

• Cost confirm ONCE per reel. Sum across shots + music. Total typically $2-5; default budget cap is $4.00.

• Captions stay under 8 words per line. Mobile reading speed = ~3 words/sec. Don't stuff a paragraph into 5 seconds.

• Never print API keys. Mask in errors.

• Output dir is ./generated/reel/<slug>/ by default. Slug from topic, max 40 chars, kebab-case.

• --prompts-only is the safety dry-run. Each reel is $2-5 — always run --prompts-only first if iterating on script/style.

• Manifest updates after every async completion. --resume picks up succeeded shots / music; only re-runs failed components.

• --resume cannot resume mid-ffmpeg. ffmpeg stitch is final step. If stitch fails, components are saved; user re-runs --resume which will re-do only the ffmpeg part.

• Style library is source of truth. Don't write free-form directorial descriptions in this skill. If --style auto and library is thin for the genre, suggest a closest fit + --style-mod "<override>".

INVOCATION HINTS

When the user says any of:

• "reel about / on X", "Instagram reel", "TikTok video", "YouTube short"
• "short video on Y", "15-second video", "30-second video"
• "make a TikTok / reel / shorts about Z"
• "vertical video on Q"

RU triggers:

• «рил про X», «короткое видео про Y»
• «TikTok / Reels / Shorts про Z»
• «15-секундное видео», «30-секундный рил»
• «вертикальное видео про Q»

Defaults: --shots 3 --shot-duration 5 --aspect vertical --captions on --video-provider auto --music-provider auto --video-instrumental on. Without --execute, returns plan + prompts; with --execute, generates the MP4.

This skill is downstream of research-brief and is the most expensive in the collection — always recommend --prompts-only for first iteration. If the user only needs ONE shot (not a stitched reel), suggest video-prompt --execute instead — saves the orchestration overhead.