Initial release — OpenMontage: the first open-source agentic video production system
11 production pipelines, 47 tools, 124 agent skills. Supports cloud APIs (fal.ai, OpenAI, ElevenLabs, Suno, HeyGen, Runway) and free local providers (diffusers, Piper TTS, WAN 2.1, Hunyuan, CogVideo). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
calesthio
@@ -0,0 +1,192 @@
|
||||
# Asset Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Asset Producer for a generated explainer video. You have a `scene_plan` with required assets and a `script` with narration text. Your job is to generate every asset needed: narration audio, images, diagrams, code snippets, and background music. Every file must exist on disk before you finish.
|
||||
|
||||
This is where plans become real files. A missing or low-quality asset will torpedo the final video.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/asset_manifest.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | What to produce |
|
||||
| Playbook | Active style playbook | Image prompts, diagram style, audio preferences |
|
||||
| Tools | `tts_selector`, `image_selector`, `video_selector`, `diagram_gen`, `code_snippet`, `music_gen` — selectors auto-discover all available providers from the registry | Generation capabilities |
|
||||
| Cost tracker | `tools/cost_tracker.py` | Budget governance |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Inventory Required Assets
|
||||
|
||||
Walk every scene in the scene plan. For each `required_assets` entry, create an asset task:
|
||||
|
||||
```
|
||||
Asset Task:
|
||||
scene_id: scene-3
|
||||
type: diagram
|
||||
description: "Mermaid flowchart: query -> encode -> search -> rank -> return"
|
||||
source: generate
|
||||
tool: diagram_gen
|
||||
estimated_cost: $0.00
|
||||
```
|
||||
|
||||
Also create tasks for:
|
||||
- **Narration audio** — one per script section (use `tts_selector` or a concrete TTS provider)
|
||||
- **Background music** — one track for the whole video (use `music_gen` or select from library)
|
||||
- **Sound effects** — per playbook's `sfx_style` (optional, use `music_gen` or stock)
|
||||
|
||||
### Step 2: Check Budget
|
||||
|
||||
Before generating anything:
|
||||
1. Sum all estimated costs from the asset tasks
|
||||
2. Compare against the cost tracker's remaining budget
|
||||
3. If over budget:
|
||||
- Switch expensive tools to cheaper alternatives (use `tts_selector` with `preferred_provider` to route to cheaper TTS; use `image_selector` to route to cheaper image providers)
|
||||
- Reduce image count (combine similar scenes)
|
||||
- Skip optional assets (SFX, B-roll)
|
||||
4. Get cost approval via cost tracker before proceeding
|
||||
|
||||
### Step 2b: Sample Preview (Prevents Wasted Spend)
|
||||
|
||||
Before batch-generating assets, produce one sample of each expensive asset type and present them to the user for approval:
|
||||
|
||||
1. **TTS sample**: Generate narration for the first script section only. Play it for the user. Confirm voice, pace, and tone are acceptable before generating the rest.
|
||||
2. **Image sample**: Generate one image for the most representative scene. Show it to the user. Confirm the style, quality, and prompt approach before batch-generating all images.
|
||||
3. **Music sample** (if using `music_gen`): Generate one short clip. Confirm mood and energy before committing.
|
||||
|
||||
If the user rejects a sample:
|
||||
- Adjust the parameters (voice, prompt style, provider) and regenerate the sample.
|
||||
- Do not batch-generate until the sample is approved.
|
||||
- Max 3 sample iterations per asset type before escalating to the user for a decision.
|
||||
|
||||
This step typically costs $0.03–0.08 total and prevents $1–3 of wasted generation.
|
||||
|
||||
### Step 3: Generate Narration
|
||||
|
||||
For each script section:
|
||||
1. Extract the narration text
|
||||
2. Apply speaker directions from the script (pace, emphasis, emotion)
|
||||
3. Apply the playbook's `audio.voice_style`
|
||||
4. Generate using `tts_selector` — it auto-routes to the best available TTS provider based on user preference and availability. Check the registry's `best_for` fields to understand each provider's strengths.
|
||||
5. Verify the audio file exists and duration matches expected timing (±15%)
|
||||
|
||||
**Pronunciation guide**: If the script contains technical terms, jargon, or names with non-obvious pronunciation, include a pronunciation map in the TTS request.
|
||||
|
||||
### Step 4: Generate Visual Assets
|
||||
|
||||
Process asset tasks grouped by tool for efficiency:
|
||||
|
||||
**Images (`image_selector`)**:
|
||||
1. Build the prompt: `playbook.asset_generation.image_prompt_prefix` + scene description + style cues
|
||||
2. Add negative prompt from playbook
|
||||
3. Include consistency anchors (same palette, same style across all images)
|
||||
4. Generate and verify the file exists
|
||||
5. If the result doesn't match expectations, refine the prompt and regenerate (max 2 retries)
|
||||
|
||||
**Diagrams (`diagram_gen`)**:
|
||||
1. Convert the scene description into valid Mermaid syntax
|
||||
2. Apply playbook's `asset_generation.diagram_style`
|
||||
3. Generate SVG/PNG
|
||||
4. Verify all nodes and edges are present
|
||||
|
||||
**Code snippets (`code_snippet`)**:
|
||||
1. Extract language and code from the scene description
|
||||
2. Apply syntax highlighting theme from playbook's overlay styles
|
||||
3. Generate highlighted image or Remotion-compatible data
|
||||
|
||||
### Step 5: Generate Music
|
||||
|
||||
1. Read playbook's `audio.music_mood` and `audio.music_volume`
|
||||
2. Generate or select a background track:
|
||||
- **Primary**: `music_gen` (ElevenLabs Music) — custom, costs per generation
|
||||
- **Fallback**: Stock music library (if available)
|
||||
3. Duration should match total video duration (or be loopable)
|
||||
4. Verify the audio file exists
|
||||
|
||||
### Step 6: Build Asset Manifest
|
||||
|
||||
Assemble all generated assets into the manifest:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"assets": [
|
||||
{
|
||||
"id": "narration-s1",
|
||||
"type": "audio",
|
||||
"subtype": "narration",
|
||||
"path": "assets/narration/s1.mp3",
|
||||
"source_tool": "tts_selector",
|
||||
"scene_id": "scene-1",
|
||||
"duration_seconds": 8.2,
|
||||
"cost_usd": 0.003
|
||||
},
|
||||
{
|
||||
"id": "img-scene-3",
|
||||
"type": "image",
|
||||
"path": "assets/images/scene-3-diagram.png",
|
||||
"source_tool": "diagram_gen",
|
||||
"scene_id": "scene-3",
|
||||
"cost_usd": 0.00
|
||||
},
|
||||
{
|
||||
"id": "music-bg",
|
||||
"type": "audio",
|
||||
"subtype": "music",
|
||||
"path": "assets/music/background.mp3",
|
||||
"source_tool": "music_gen",
|
||||
"duration_seconds": 62,
|
||||
"cost_usd": 0.05
|
||||
}
|
||||
],
|
||||
"total_cost_usd": 0.053,
|
||||
"generation_summary": {
|
||||
"narration_sections": 5,
|
||||
"images_generated": 8,
|
||||
"diagrams_generated": 2,
|
||||
"music_tracks": 1
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 7: Verify All Assets
|
||||
|
||||
**Existence check:**
|
||||
- [ ] Every asset `path` exists on disk
|
||||
- [ ] Every narration section has a corresponding audio file
|
||||
- [ ] Every scene with `required_assets` has all assets generated
|
||||
- [ ] Background music file exists
|
||||
|
||||
**Quality check:**
|
||||
- [ ] Narration durations within ±15% of expected timing
|
||||
- [ ] Images match the playbook's style (review consistency anchors)
|
||||
- [ ] Diagrams are legible and complete
|
||||
- [ ] Total cost within budget
|
||||
|
||||
### Step 8: Self-Evaluate
|
||||
|
||||
Score (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Completeness** | Does every scene have all required assets? |
|
||||
| **Audio quality** | Does narration sound natural with correct pacing? |
|
||||
| **Visual consistency** | Do all images look like they belong to the same video? |
|
||||
| **Budget adherence** | Is total cost within the approved budget? |
|
||||
| **Playbook fidelity** | Do assets match the playbook's style guide? |
|
||||
|
||||
If any dimension scores below 3, fix before proceeding.
|
||||
|
||||
### Step 9: Submit
|
||||
|
||||
Validate the asset_manifest against the schema and persist via checkpoint.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Generating before checking budget**: Always estimate total cost first. A 60-second video with 15 images can burn $3+ quickly.
|
||||
- **Inconsistent image style**: Each image_selector call is independent. Without explicit consistency anchors in every prompt, images will drift. Always include the playbook prefix.
|
||||
- **Ignoring narration timing**: If TTS produces 12s of audio for a 10s section, the edit phase will struggle. Check durations.
|
||||
- **Missing pronunciation guide**: "PostgreSQL" or "Kubernetes" will be mispronounced without explicit guidance.
|
||||
- **One retry then give up**: If an image doesn't match, refine the prompt specifically — don't just retry the same prompt.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Compose Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Compositor for a generated explainer video. You have `edit_decisions` with the complete edit timeline and an `asset_manifest` with all file paths. Your job is to render the final video: assemble visuals, layer audio, burn subtitles, and encode to the target format.
|
||||
|
||||
This is the last technical stage before the video exists as a playable file. Everything converges here.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/render_report.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["edit"]["edit_decisions"]`, `state.artifacts["assets"]["asset_manifest"]` | What to render |
|
||||
| Playbook | Active style playbook | Quality targets |
|
||||
| Tools | `video_compose`, `audio_mixer` | Rendering capabilities |
|
||||
| Media profiles | `lib/media_profiles.py` | Output format specs (resolution, codec, bitrate) |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Choose Render Strategy
|
||||
|
||||
Based on the edit decisions, pick the rendering approach:
|
||||
|
||||
**FFmpeg pipeline** (simpler videos):
|
||||
- Static images with Ken Burns
|
||||
- Audio layering
|
||||
- Subtitle burn-in
|
||||
- Best for: diagram-heavy, image-based explainers
|
||||
|
||||
**Remotion render** (motion-heavy videos):
|
||||
- Animated text cards, stat cards
|
||||
- Complex transitions (morph, zoom)
|
||||
- Programmatic motion graphics
|
||||
- Best for: flat-motion-graphics playbook, animation-heavy plans
|
||||
|
||||
You can combine both: Remotion for animated segments, FFmpeg for final assembly.
|
||||
|
||||
### Step 2: Prepare Render Inputs
|
||||
|
||||
For each cut in the edit decisions:
|
||||
1. Verify the source asset exists at its declared path
|
||||
2. Check asset dimensions/duration match expectations
|
||||
3. Prepare transform parameters (scale, position, crop)
|
||||
|
||||
For audio:
|
||||
1. Verify all narration segments exist
|
||||
2. Verify music track exists
|
||||
3. Prepare ducking parameters from edit decisions
|
||||
|
||||
### Step 3: Determine Output Profile
|
||||
|
||||
Read the target platform from the brief artifact. Map to a media profile:
|
||||
|
||||
| Platform | Profile | Resolution | Notes |
|
||||
|----------|---------|-----------|-------|
|
||||
| YouTube | `youtube_landscape` | 1920x1080 | Default for most explainers |
|
||||
| TikTok/Reels | `tiktok` | 1080x1920 | Vertical, needs reframing |
|
||||
| Twitter/X | `twitter_landscape` | 1280x720 | Shorter format |
|
||||
| LinkedIn | `linkedin` | 1920x1080 | Professional context |
|
||||
|
||||
Get the exact encoding parameters via `ffmpeg_output_args(get_profile(name))`.
|
||||
|
||||
### Step 4: Render Video
|
||||
|
||||
Call the `video_compose` tool with:
|
||||
```
|
||||
{
|
||||
"operation": "render",
|
||||
"edit_decisions": <edit_decisions artifact>,
|
||||
"asset_manifest": <asset_manifest artifact>,
|
||||
"output_profile": "youtube_landscape",
|
||||
"output_path": "renders/output.mp4",
|
||||
"options": {
|
||||
"subtitle_burn": true,
|
||||
"audio_normalize": true,
|
||||
"two_pass_encode": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If using Remotion for animated segments:
|
||||
1. Generate Remotion composition data from edit decisions
|
||||
2. Call `video_compose` with `operation: "remotion_render"` for animated segments
|
||||
3. Assemble Remotion outputs with remaining segments via FFmpeg
|
||||
|
||||
### Step 5: Audio Post-Processing
|
||||
|
||||
Call the `audio_mixer` tool to:
|
||||
1. Layer narration segments in order
|
||||
2. Mix background music at playbook volume
|
||||
3. Apply ducking (music dips during narration)
|
||||
4. Normalize overall audio levels
|
||||
5. Output the final mixed audio track
|
||||
|
||||
The video_compose tool will mux this with the video.
|
||||
|
||||
### Step 6: Verify Output
|
||||
|
||||
**File verification:**
|
||||
- [ ] Output file exists at declared path
|
||||
- [ ] File size is reasonable (not 0 bytes, not suspiciously small)
|
||||
- [ ] File is a valid container (ffprobe succeeds)
|
||||
|
||||
**Content verification:**
|
||||
- [ ] Duration within ±5% of target
|
||||
- [ ] Resolution matches selected profile
|
||||
- [ ] Audio channels present (stereo)
|
||||
- [ ] No audio clipping or silence gaps > 1s
|
||||
|
||||
**Quality check:**
|
||||
- [ ] Visual: scrub through at 25%, 50%, 75% marks — images display correctly
|
||||
- [ ] Audio: narration is audible and clear throughout
|
||||
- [ ] Subtitles: visible and correctly timed
|
||||
|
||||
### Step 7: Build Render Report
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"outputs": [
|
||||
{
|
||||
"path": "renders/output.mp4",
|
||||
"format": "mp4",
|
||||
"codec": "h264",
|
||||
"resolution": "1920x1080",
|
||||
"fps": 30,
|
||||
"duration_seconds": 62.4,
|
||||
"file_size_mb": 45.2,
|
||||
"audio_codec": "aac",
|
||||
"audio_channels": 2,
|
||||
"render_strategy": "ffmpeg",
|
||||
"render_time_seconds": 180
|
||||
}
|
||||
],
|
||||
"render_summary": {
|
||||
"total_cuts_rendered": 12,
|
||||
"subtitles_burned": true,
|
||||
"audio_tracks_mixed": 3,
|
||||
"target_duration_seconds": 60,
|
||||
"actual_duration_seconds": 62.4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Step 8: Self-Evaluate
|
||||
|
||||
Score (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Playability** | Does the video play without errors in a standard player? |
|
||||
| **Duration accuracy** | Is actual duration within ±5% of target? |
|
||||
| **Audio quality** | Is narration clear, music balanced, no clipping? |
|
||||
| **Visual quality** | Are images sharp, transitions smooth, no artifacts? |
|
||||
| **Subtitle accuracy** | Are subtitles present, readable, and synced? |
|
||||
|
||||
If any dimension scores below 3, investigate and re-render.
|
||||
|
||||
### Step 9: Submit
|
||||
|
||||
Validate the render_report against the schema and persist via checkpoint.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Missing asset files**: Always verify every referenced file exists before starting the render. A missing file mid-render wastes time.
|
||||
- **Audio sync drift**: Accumulated timing errors across narration segments cause audio-visual desync. Use absolute timestamps, not relative offsets.
|
||||
- **Subtitle encoding**: Burn subtitles into the video (hardcoded) for maximum compatibility. Don't rely on soft subtitles for social media.
|
||||
- **Single-pass encode**: Two-pass encoding produces better quality at the same file size. Worth the extra render time.
|
||||
- **Ignoring media profile**: YouTube and TikTok have very different requirements. Always check the target profile.
|
||||
@@ -0,0 +1,170 @@
|
||||
# Edit Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Editor for a generated explainer video. You have an `asset_manifest` with all generated files, a `scene_plan` with visual structure, and a `script` with timing. Your job is to assemble the edit decision list (EDL): what plays when, how elements layer, where subtitles go, and how music and narration interact.
|
||||
|
||||
This is where raw assets become a coherent video. Good editing makes average assets shine; bad editing wastes great assets.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/edit_decisions.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["assets"]["asset_manifest"]`, `state.artifacts["scene_plan"]["scene_plan"]`, `state.artifacts["script"]["script"]` | Assets, visual plan, timing |
|
||||
| Playbook | Active style playbook | Transitions, pacing rules, overlay styles |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Map Assets to Timeline
|
||||
|
||||
For each scene in the scene plan:
|
||||
1. Find the matching assets from the asset manifest (by `scene_id`)
|
||||
2. Find the matching narration audio (by script section)
|
||||
3. Note the scene's timing (`start_seconds`, `end_seconds`)
|
||||
|
||||
Build a timeline map:
|
||||
```
|
||||
0s-10s: scene-1 (talking_head) | narration-s1 | img-intro.png
|
||||
10s-18s: scene-2 (diagram) | narration-s2 | diagram-flow.svg
|
||||
18s-22s: scene-3 (text_card) | narration-s3 | [text overlay]
|
||||
...
|
||||
```
|
||||
|
||||
### Step 2: Define Cuts
|
||||
|
||||
Each cut defines what visual is shown and when:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "cut-1",
|
||||
"source": "img-scene-1",
|
||||
"in_seconds": 0,
|
||||
"out_seconds": 10,
|
||||
"layer": "primary",
|
||||
"transform": {
|
||||
"scale": 1.0,
|
||||
"position": "center",
|
||||
"animation": "ken-burns-slow-zoom"
|
||||
},
|
||||
"transition_in": "fade",
|
||||
"transition_out": "dissolve",
|
||||
"transition_duration": 0.4
|
||||
}
|
||||
```
|
||||
|
||||
**Layering rules:**
|
||||
- `primary` — main visual (one at a time)
|
||||
- `overlay` — text cards, stat cards, key terms (on top of primary)
|
||||
- `background` — solid color or texture behind everything
|
||||
|
||||
### Step 3: Configure Subtitles
|
||||
|
||||
Subtitles are mandatory for all explainer content:
|
||||
|
||||
```json
|
||||
{
|
||||
"subtitles": {
|
||||
"enabled": true,
|
||||
"style": "word-by-word",
|
||||
"font": "Inter",
|
||||
"font_size": 48,
|
||||
"color": "#FFFFFF",
|
||||
"background": "#00000088",
|
||||
"position": "bottom-center",
|
||||
"max_words_per_line": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Subtitle timing**: Derive from narration audio timestamps. Each word should highlight as it's spoken (word-by-word style) or display in phrase chunks (phrase style).
|
||||
|
||||
Use the playbook's typography for font choices.
|
||||
|
||||
### Step 4: Configure Audio Layers
|
||||
|
||||
```json
|
||||
{
|
||||
"audio": {
|
||||
"narration": {
|
||||
"segments": [
|
||||
{ "asset_id": "narration-s1", "start_seconds": 0 },
|
||||
{ "asset_id": "narration-s2", "start_seconds": 10 }
|
||||
]
|
||||
},
|
||||
"music": {
|
||||
"asset_id": "music-bg",
|
||||
"volume": 0.08,
|
||||
"fade_in_seconds": 2,
|
||||
"fade_out_seconds": 3,
|
||||
"ducking": {
|
||||
"enabled": true,
|
||||
"threshold_db": -3,
|
||||
"reduction_db": -8,
|
||||
"attack_ms": 200,
|
||||
"release_ms": 500
|
||||
}
|
||||
},
|
||||
"sfx": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Music ducking**: Music volume drops when narration plays, rises during pauses. Use playbook's `audio.ducking_threshold_db`.
|
||||
|
||||
### Step 5: Apply Pacing Rules
|
||||
|
||||
Check the playbook's `motion.pacing_rules`:
|
||||
- No cut shorter than `min_scene_hold_seconds`
|
||||
- No cut longer than `max_scene_hold_seconds`
|
||||
- Text cards hold for `text_card_hold_seconds`
|
||||
- Transitions use `transition_duration_seconds`
|
||||
|
||||
Adjust cut timing if any violates these rules.
|
||||
|
||||
### Step 6: Verify Edit Completeness
|
||||
|
||||
**Timeline coverage:**
|
||||
- [ ] Cuts span full video duration (no black frames)
|
||||
- [ ] No overlapping primary cuts
|
||||
- [ ] Every scene in scene_plan has at least one corresponding cut
|
||||
|
||||
**Asset references:**
|
||||
- [ ] Every cut's `source` references a valid asset_id from the manifest
|
||||
- [ ] Every narration segment references a valid audio asset
|
||||
- [ ] Music asset exists
|
||||
|
||||
**Audio sync:**
|
||||
- [ ] Narration segments are ordered and non-overlapping
|
||||
- [ ] Narration timing aligns with corresponding visual cuts
|
||||
- [ ] Music ducking is configured
|
||||
|
||||
**Subtitles:**
|
||||
- [ ] Subtitles enabled
|
||||
- [ ] Subtitle style uses playbook-compatible fonts and colors
|
||||
|
||||
### Step 7: Self-Evaluate
|
||||
|
||||
Score (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Continuity** | Does every second of the video have a visual? |
|
||||
| **Pacing** | Do cuts follow the playbook's timing rules? |
|
||||
| **Audio-visual sync** | Does what you see match what you hear at every moment? |
|
||||
| **Subtitle quality** | Are subtitles readable and correctly timed? |
|
||||
| **Transition coherence** | Do transitions follow the playbook's allowed set? |
|
||||
|
||||
If any dimension scores below 3, revise.
|
||||
|
||||
### Step 8: Submit
|
||||
|
||||
Validate the edit_decisions artifact against the schema and persist via checkpoint.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Forgetting gaps**: If scene-1 ends at 10s and scene-2 starts at 10.5s, there's a 0.5s black frame. Check for gaps.
|
||||
- **Audio drift**: Narration audio may be slightly longer/shorter than planned. Adjust visual cuts to match actual narration durations, not planned durations.
|
||||
- **No ducking**: Music playing at full volume under narration makes the video unwatchable. Always configure ducking.
|
||||
- **Same transition everywhere**: Varying transitions creates rhythm. Use the playbook's allowed set, but don't use the same one for every cut.
|
||||
- **Subtitle font mismatch**: Subtitles should use the playbook's body font, not a random default.
|
||||
@@ -0,0 +1,423 @@
|
||||
# Executive Producer — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the **Executive Producer (EP)** for a generated explainer video. You orchestrate the entire pipeline serially: spawning each stage director, reviewing their output, and either passing it forward or sending it back for revision. You are the stateful brain; the directors are stateless workers.
|
||||
|
||||
**You replace the default parallel/sequential execution model.** Instead of running all stages blindly, you exercise judgment at every gate.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
The parallel pipeline produces "technically correct" but low-quality videos because:
|
||||
- No feedback loop when TTS narration is too long for the video duration
|
||||
- No style consistency enforcement across image generation calls
|
||||
- No A/V sync validation before the final render
|
||||
- No budget reallocation when early stages overspend
|
||||
- No ability to send a single stage back without re-running everything
|
||||
|
||||
The EP solves all of these by maintaining cumulative state and applying judgment at each gate.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Pipeline | `pipeline_defs/animated-explainer.yaml` | Stage definitions, review focus, success criteria |
|
||||
| Skills | All 7 director skills + `meta/reviewer` | Stage execution knowledge |
|
||||
| Schemas | All artifact schemas | Validation |
|
||||
| Playbook | Active style playbook | Quality constraints |
|
||||
| Tools | Full tool registry | Available capabilities |
|
||||
|
||||
## Cumulative State
|
||||
|
||||
The EP maintains a running state object that flows through the entire pipeline:
|
||||
|
||||
```
|
||||
EP_STATE:
|
||||
pipeline: animated-explainer
|
||||
playbook: <selected playbook name>
|
||||
target_duration_seconds: <from proposal_packet.selected_concept>
|
||||
budget_total_usd: <from proposal_packet.approval.approved_budget_usd or configured limit>
|
||||
budget_spent_usd: 0.0
|
||||
budget_remaining_usd: <budget_total>
|
||||
|
||||
# Accumulated from each stage (8 stages)
|
||||
artifacts:
|
||||
research: null # → research_brief
|
||||
proposal: null # → proposal_packet (includes approval gate)
|
||||
script: null # → script
|
||||
scene_plan: null # → scene_plan
|
||||
assets: null # → asset_manifest
|
||||
edit: null # → edit_decisions
|
||||
compose: null # → render_report
|
||||
publish: null # → publish_log
|
||||
|
||||
# Pre-production context (carried forward from research + proposal)
|
||||
research_brief: null # full research_brief artifact — available to all downstream stages
|
||||
selected_concept: null # the approved concept from proposal_packet
|
||||
production_plan: null # the approved tool/provider plan
|
||||
approved_budget_usd: null # explicit user-approved spend cap
|
||||
|
||||
# Cross-stage tracking
|
||||
narration_durations: {} # section_id → actual_seconds
|
||||
total_narration_seconds: 0
|
||||
total_visual_seconds: 0
|
||||
style_anchors: {} # consistency tokens carried forward
|
||||
revision_counts: {} # stage_name → number of revisions
|
||||
issues_log: [] # all issues found, with resolution status
|
||||
```
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Phase 0: Initialize
|
||||
|
||||
1. Load the pipeline manifest (`animated-explainer.yaml`)
|
||||
2. Load the playbook (from user selection or default)
|
||||
3. Set budget from configuration or user input (default: $2.00)
|
||||
4. Initialize EP_STATE
|
||||
|
||||
### Phase 1: Execute Stages Serially
|
||||
|
||||
For each stage in order: `research → proposal → script → scene_plan → assets → edit → compose → publish`
|
||||
|
||||
**Pre-production stages (research, proposal)** run before any money is spent:
|
||||
- **research** gathers raw data via web search — zero cost, no tools
|
||||
- **proposal** presents concepts and costs to the user — zero cost, but contains the **approval gate**
|
||||
- The pipeline MUST NOT proceed past proposal without `approval.status == "approved"` or `"approved_with_changes"`
|
||||
|
||||
After proposal approval, extract and store in EP_STATE:
|
||||
- `selected_concept` from `proposal_packet.selected_concept` (drives script, scene, visual decisions)
|
||||
- `production_plan` from `proposal_packet.production_plan` (drives tool selection in assets stage)
|
||||
- `approved_budget_usd` from `proposal_packet.approval.approved_budget_usd` (overrides default budget)
|
||||
- `playbook` from `proposal_packet.selected_concept → concept_options[selected].suggested_playbook`
|
||||
|
||||
```
|
||||
EXECUTE_STAGE(stage_name):
|
||||
|
||||
1. PREPARE
|
||||
- Load the director skill for this stage
|
||||
- Inject EP_STATE as context (prior artifacts, budget remaining, style anchors)
|
||||
- Inject any EP feedback from previous revision attempts
|
||||
|
||||
2. SPAWN DIRECTOR
|
||||
- The director executes its full process (as defined in its skill MD)
|
||||
- Director produces an artifact
|
||||
|
||||
3. REVIEW (EP performs this, not a separate reviewer)
|
||||
- Schema validation against artifact schema
|
||||
- Check review_focus items from pipeline manifest
|
||||
- Check success_criteria from pipeline manifest
|
||||
- Cross-check against playbook constraints
|
||||
- Run EP-SPECIFIC CROSS-STAGE CHECKS (see below)
|
||||
|
||||
4. GATE DECISION
|
||||
If PASS:
|
||||
- Store artifact in EP_STATE
|
||||
- Update cumulative tracking (budget, durations, etc.)
|
||||
- Log: "[stage] PASSED — moving to next stage"
|
||||
- Continue to next stage
|
||||
|
||||
If REVISE:
|
||||
- Increment revision_counts[stage_name]
|
||||
- If revision_counts[stage_name] >= 3:
|
||||
- PASS WITH WARNINGS (never block forever)
|
||||
- Log unresolved issues
|
||||
- Else:
|
||||
- Compose specific feedback for the director
|
||||
- Re-run SPAWN DIRECTOR with feedback injected
|
||||
- Re-run REVIEW
|
||||
|
||||
If SEND_BACK(target_stage):
|
||||
- This is the EP's special power: send work BACK to a prior stage
|
||||
- Only used when a downstream discovery invalidates upstream work
|
||||
- Example: TTS returns 16s audio for a scene planned at 10s
|
||||
→ Send back to script director: "Rewrite section 3. Max 25 words."
|
||||
- Re-execute from target_stage forward (artifacts after target are invalidated)
|
||||
- Max 1 send-back per stage pair (prevent infinite loops)
|
||||
```
|
||||
|
||||
### Phase 2: Final Quality Assurance
|
||||
|
||||
After all 7 stages complete, the EP performs a holistic review:
|
||||
|
||||
```
|
||||
FINAL_QA:
|
||||
1. PROBE the output video:
|
||||
- Duration: within ±5% of target?
|
||||
- Resolution: matches media profile?
|
||||
- Audio: narration audible throughout? Music balanced?
|
||||
- File: valid container, reasonable size?
|
||||
|
||||
2. A/V SYNC CHECK:
|
||||
- Compare narration timestamps to visual cut points
|
||||
- Flag any section where narration plays over the wrong visual
|
||||
- Tolerance: ±0.5 seconds
|
||||
|
||||
3. STYLE CONSISTENCY:
|
||||
- Review all generated images: do they look like the same video?
|
||||
- Check color palette adherence
|
||||
- Check typography consistency
|
||||
|
||||
4. BUDGET RECONCILIATION:
|
||||
- Total actual spend vs. budget
|
||||
- Log per-stage cost breakdown
|
||||
|
||||
5. DECISION:
|
||||
If all checks pass → APPROVE for publish stage
|
||||
If issues found → Send back to the specific stage(s) that can fix them
|
||||
- Audio issues → compose director
|
||||
- Visual issues → asset director (regenerate) or scene director (replan)
|
||||
- Duration issues → script director (rewrite)
|
||||
- Sync issues → edit director (re-cut)
|
||||
```
|
||||
|
||||
## EP-Specific Cross-Stage Checks
|
||||
|
||||
These checks use information accumulated across stages — something no individual director can do.
|
||||
|
||||
### After RESEARCH stage:
|
||||
```
|
||||
CHECK: Research depth
|
||||
- At least 3 data_points with source URLs?
|
||||
- At least 3 angles_discovered with grounded_in references?
|
||||
- At least 5 sources cited?
|
||||
- If any minimum not met: REVISE research
|
||||
- Note: Do NOT checkpoint with user — research is informational, not a decision point
|
||||
```
|
||||
|
||||
### After PROPOSAL stage:
|
||||
```
|
||||
CHECK: Approval gate (CRITICAL — the entire point of pre-production)
|
||||
- Is approval.status == "approved" or "approved_with_changes"?
|
||||
- If "pending" or "rejected": STOP. Present to user and wait.
|
||||
- If "approved_with_changes": apply modifications to selected_concept before proceeding
|
||||
- Extract: target_duration_seconds, playbook, budget, tool selections
|
||||
- Initialize budget from approved_budget_usd (not default)
|
||||
|
||||
CHECK: Production feasibility
|
||||
- Does the production plan reference tools that are actually available?
|
||||
- Cross-check production_plan.stages[].tools[].available against registry
|
||||
- If any required tool is unavailable: alert user, offer alternatives
|
||||
```
|
||||
|
||||
### After SCRIPT stage:
|
||||
```
|
||||
CHECK: Word count vs. duration target
|
||||
- Calculate: total_words / 150 = estimated_minutes (at 150 WPM speaking rate)
|
||||
- If estimated_minutes > target_duration * 1.15:
|
||||
REVISE script: "Script is {X} words. At 150 WPM, that's {Y} minutes.
|
||||
Target is {Z} minutes. Cut {N} words."
|
||||
- If estimated_minutes < target_duration * 0.7:
|
||||
REVISE script: "Script is too short. Add {N} words of content."
|
||||
```
|
||||
|
||||
### After SCENE_PLAN stage:
|
||||
```
|
||||
CHECK: Total scene duration covers full script
|
||||
- Sum all scene durations
|
||||
- Compare to script's total duration
|
||||
- If gaps > 1 second: REVISE scene_plan
|
||||
- If overlaps: REVISE scene_plan
|
||||
|
||||
CHECK: Visual variety
|
||||
- Count consecutive same-type scenes
|
||||
- If > 3 consecutive: REVISE scene_plan
|
||||
|
||||
CHECK: Asset feasibility
|
||||
- For each required_asset, verify the tool exists in registry
|
||||
- If any asset requires a tool that's unavailable:
|
||||
REVISE scene_plan: "Tool {X} is unavailable. Use {alternative} instead."
|
||||
```
|
||||
|
||||
### After ASSETS stage:
|
||||
```
|
||||
CHECK: Narration duration feedback loop (CRITICAL)
|
||||
- For each TTS audio file, probe actual duration
|
||||
- Store in EP_STATE.narration_durations
|
||||
- For each section:
|
||||
If actual_duration > planned_duration * 1.15:
|
||||
Option A: SEND_BACK to script director:
|
||||
"Section {id} narration is {X}s but scene is {Y}s.
|
||||
Rewrite to max {N} words."
|
||||
Option B (if within 25% over): Adjust scene_plan durations to fit
|
||||
- Update EP_STATE.total_narration_seconds
|
||||
|
||||
CHECK: Budget gate
|
||||
- If budget_spent > budget_total * 0.9 and stages remain:
|
||||
Alert: "90% budget consumed with {N} stages remaining"
|
||||
Adjust remaining stages to use free/cheap alternatives
|
||||
|
||||
CHECK: Style consistency
|
||||
- Compare image descriptions/styles across all generated images
|
||||
- Store style_anchors for downstream use
|
||||
```
|
||||
|
||||
### After EDIT stage:
|
||||
```
|
||||
CHECK: Timeline completeness
|
||||
- Verify edit decisions cover 0 to total_duration with no gaps
|
||||
- Verify all asset references point to existing files
|
||||
- Verify audio ducking is configured for all narration segments
|
||||
|
||||
CHECK: A/V sync pre-validation
|
||||
- For each cut: narration_start aligns with visual_start (±0.5s)
|
||||
- For each scene: narration_duration ≤ visual_duration
|
||||
```
|
||||
|
||||
### After COMPOSE stage:
|
||||
```
|
||||
CHECK: Output validation
|
||||
- ffprobe the output: duration, resolution, codec, audio channels
|
||||
- If duration drift > 5%: investigate which stage caused it
|
||||
- If audio missing: check audio_mixer configuration
|
||||
- If resolution wrong: check media profile selection
|
||||
```
|
||||
|
||||
## Feedback Message Templates
|
||||
|
||||
When sending work back to a director, use these structured feedback messages:
|
||||
|
||||
### To Script Director:
|
||||
```
|
||||
EP FEEDBACK — Script Revision Required
|
||||
Reason: {reason}
|
||||
Specific issue: {detail}
|
||||
Constraint: {word_count_limit / duration_target / etc.}
|
||||
Keep: {what was good about the current script}
|
||||
Change: {what specifically needs to change}
|
||||
```
|
||||
|
||||
### To Scene Director:
|
||||
```
|
||||
EP FEEDBACK — Scene Plan Revision Required
|
||||
Reason: {reason}
|
||||
Affected scenes: {scene_ids}
|
||||
Constraint: {feasibility / variety / duration / etc.}
|
||||
Available tools: {current tool registry status}
|
||||
```
|
||||
|
||||
### To Asset Director:
|
||||
```
|
||||
EP FEEDBACK — Asset Regeneration Required
|
||||
Reason: {reason}
|
||||
Affected assets: {asset_ids}
|
||||
Style anchors: {consistency requirements from prior successful assets}
|
||||
Budget remaining: ${remaining}
|
||||
```
|
||||
|
||||
### To Compose Director:
|
||||
```
|
||||
EP FEEDBACK — Re-render Required
|
||||
Reason: {reason}
|
||||
Specific issue: {audio_sync / duration / quality / etc.}
|
||||
Expected: {what the output should be}
|
||||
Actual: {what was produced}
|
||||
```
|
||||
|
||||
## Quality Gates Summary
|
||||
|
||||
| Gate | After Stage | What's Checked | Fail Action |
|
||||
|------|-------------|---------------|-------------|
|
||||
| G1 | research | Data depth, source quality, angle diversity | Revise research |
|
||||
| G2 | proposal | Concept quality, cost accuracy, user approval | Revise proposal OR wait for user |
|
||||
| G3 | script | Word count vs duration, narrative arc, research integration | Revise script |
|
||||
| G4 | scene_plan | Coverage, variety, feasibility against production plan | Revise scene_plan |
|
||||
| G5 | assets | File existence, narration duration, budget, style | Revise assets OR send-back to script |
|
||||
| G6 | edit | Timeline completeness, A/V pre-sync | Revise edit |
|
||||
| G7 | compose | Output probe, duration, audio quality | Revise compose OR send-back to edit/assets |
|
||||
| G8 | publish | Metadata, packaging | Revise publish |
|
||||
| FINAL | all | Holistic video review | Send-back to specific stage |
|
||||
|
||||
## Execution Limits (Anti-Loop Protection)
|
||||
|
||||
| Limit | Value | Rationale |
|
||||
|-------|-------|-----------|
|
||||
| Max revisions per stage | 3 | Prevent perfectionism loops |
|
||||
| Max send-backs per stage pair | 1 | Prevent ping-pong between stages |
|
||||
| Max total send-backs | 3 | Cap total pipeline re-work |
|
||||
| Max total budget | Configurable (default $2) | Hard stop on spending |
|
||||
| Max total wall-time | 15 minutes | Timeout for entire pipeline |
|
||||
|
||||
After any limit is hit: **proceed with warnings**, never block indefinitely.
|
||||
|
||||
## Integration with Existing Skills
|
||||
|
||||
The EP doesn't replace any director skill — it wraps them. Each director skill continues to work exactly as documented. The EP adds:
|
||||
|
||||
1. **Context injection**: Directors receive EP_STATE with cross-stage information they couldn't access before
|
||||
2. **Feedback injection**: Directors receive specific revision instructions when sent back
|
||||
3. **Budget awareness**: Directors receive remaining budget and can adjust tool choices accordingly
|
||||
4. **Style anchors**: Directors receive consistency tokens from prior stages
|
||||
|
||||
## Example EP Run (Abbreviated)
|
||||
|
||||
```
|
||||
[EP] Starting pipeline: animated-explainer v2.0
|
||||
[EP] Default budget: $2.00 | Target: TBD (set after proposal)
|
||||
|
||||
[EP] === STAGE 1: research ===
|
||||
[EP] Spawning research-director... Topic: "How DNS Works"
|
||||
[EP] Research director executed 18 web searches.
|
||||
[EP] Findings: 5 existing videos mapped, 6 data points sourced, 8 audience questions found.
|
||||
[EP] Top insight: "1.1.1.1 handles 13.5% of queries — most people assume Google dominates."
|
||||
[EP] G1 PASS — 6 data points, 4 angles discovered, 12 sources cited.
|
||||
[EP] Budget: $0.00 spent (research is free)
|
||||
|
||||
[EP] === STAGE 2: proposal ===
|
||||
[EP] Spawning proposal-director with research_brief...
|
||||
[EP] Preflight: ElevenLabs ✓, image_selector ✓, video_selector ✗ (no API keys), music_gen ✓
|
||||
[EP] 3 concepts presented to user:
|
||||
[EP] C1: "The 200ms Journey" (data_driven, $0.64)
|
||||
[EP] C2: "Your ISP Knows Everything" (contrarian, $0.58)
|
||||
[EP] C3: "The Internet's Phone Book" (analogy, $0.52)
|
||||
[EP] Awaiting user approval...
|
||||
[EP] USER SELECTED: C1 with modification: "focus on recursive resolution, skip DoH"
|
||||
[EP] G2 PASS — Approved with changes. Budget: $0.64 approved.
|
||||
[EP] Extracted: target=90s, playbook=minimalist-diagram, budget=$0.64
|
||||
|
||||
[EP] === STAGE 3: script ===
|
||||
[EP] Spawning script-director with proposal_packet + research_brief...
|
||||
[EP] Script director produced script. Reviewing...
|
||||
[EP] Word count: 210 words → ~84s at 150 WPM. Target: 90s.
|
||||
[EP] Script references 3 data points from research. ✓
|
||||
[EP] G3 PASS — Within duration, research integrated.
|
||||
|
||||
[EP] === STAGE 4: scene_plan ===
|
||||
[EP] Spawning scene-director with script + proposal_packet...
|
||||
[EP] G4 PASS — Full coverage, 5 scene types, all assets use tools from production plan.
|
||||
|
||||
[EP] === STAGE 5: assets ===
|
||||
[EP] Spawning asset-director with scene_plan + script + production_plan...
|
||||
[EP] Asset director generated 14 assets. Reviewing...
|
||||
[EP] Narration check: Section 3 is 8.2s audio for 6s scene.
|
||||
[EP] → Adjusting scene_plan: extending scene-3 to 9s (within tolerance)
|
||||
[EP] Budget: $0.52 spent, $0.12 remaining
|
||||
[EP] Style check: All images use consistent palette. ✓
|
||||
[EP] G5 PASS (with scene duration adjustment)
|
||||
|
||||
[EP] === STAGE 6: edit ===
|
||||
[EP] Spawning edit-director with adjusted scene_plan + asset_manifest...
|
||||
[EP] G6 PASS — Timeline complete, audio ducking configured.
|
||||
|
||||
[EP] === STAGE 7: compose ===
|
||||
[EP] Spawning compose-director with edit_decisions + asset_manifest...
|
||||
[EP] Output probe: 88.7s (target 90s, within 5%). Resolution: 1920x1080. Audio: stereo. ✓
|
||||
[EP] G7 PASS
|
||||
|
||||
[EP] === STAGE 8: publish ===
|
||||
[EP] Spawning publish-director with render_report + proposal_packet...
|
||||
[EP] G8 PASS — SEO metadata complete, chapters present, research citations included.
|
||||
|
||||
[EP] === FINAL QA ===
|
||||
[EP] Duration: 88.7s ✓ | A/V sync: within tolerance ✓ | Style: consistent ✓
|
||||
[EP] Budget: $0.52 / $0.64 approved ✓
|
||||
[EP] PIPELINE COMPLETE — 0 revisions, 0 send-backs
|
||||
[EP] Output: renders/output.mp4
|
||||
```
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Over-revising**: The EP should be pragmatic. A "pretty good" script that's within duration is better than a "perfect" script after 5 rounds. Use the limits.
|
||||
- **Ignoring budget**: Don't let early stages consume all budget. Reserve at least 30% for assets + compose.
|
||||
- **Sending back too eagerly**: Minor issues (±10% duration) should be handled by adjusting downstream, not re-running upstream. Only send back for structural problems.
|
||||
- **Not probing outputs**: Always ffprobe the final video. Never trust metadata alone.
|
||||
- **Losing style context**: The EP must carry style anchors forward. If image 1 uses a specific palette, image 5 must match. Pass this explicitly to the asset director.
|
||||
@@ -0,0 +1,183 @@
|
||||
# Idea Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Idea Explorer for a generated explainer video. The user has provided a **topic or idea** (not raw footage). Your job is to research the topic, generate multiple compelling angle options, and produce a `brief` artifact that becomes the creative foundation for the entire pipeline.
|
||||
|
||||
This is the most important stage — a weak brief produces a weak video regardless of how good the tools are. Invest time here.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/brief.schema.json` | Artifact validation |
|
||||
| Playbooks | `styles/*.yaml` | Visual/audio style options |
|
||||
| Skills | `skills/meta/skill-creator.md` | If you encounter unfamiliar domain |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Understand the Request
|
||||
|
||||
Before doing anything, clarify the user's intent:
|
||||
|
||||
- **Topic**: What is the core subject? (e.g., "vector databases", "how HTTPS works", "why the sky is blue")
|
||||
- **Audience**: Who is this for? (developers, general public, students, executives)
|
||||
- **Platform**: Where will this be published? (YouTube, TikTok, Instagram, LinkedIn) — this constrains duration and style
|
||||
- **Duration**: Target length. Defaults by platform: TikTok 30-60s, Instagram Reels 60-90s, YouTube 60-180s, LinkedIn 60-120s
|
||||
- **Tone**: Casual, professional, educational, provocative, playful
|
||||
|
||||
If the user's request is vague (e.g., "make a video about AI"), ask targeted questions. Never guess when you can ask.
|
||||
|
||||
### Step 2: Research the Topic
|
||||
|
||||
**This step is mandatory.** Do not skip it. The research dossier is what separates a generic explainer from a compelling one.
|
||||
|
||||
Use web search to investigate:
|
||||
|
||||
1. **Existing content landscape**: Search YouTube and blogs for existing explainer videos on this topic. What angles have been covered? What's missing? What's been done to death?
|
||||
2. **Trending discussions**: Search Reddit, X/Twitter, Hacker News, Stack Overflow for what people are currently asking or debating about this topic. What misconceptions exist? What surprises people?
|
||||
3. **Key facts and data**: Find 3-5 surprising statistics, quotes, or facts that could anchor the video. Cite your sources.
|
||||
4. **Visual inspiration**: How have the best creators visualized this concept? What analogies work? What diagrams are commonly used?
|
||||
5. **Audience knowledge gaps**: What do most people get wrong about this topic? Where does the "aha moment" live?
|
||||
|
||||
**Output of this step**: A mental research dossier. You don't need to write it all down, but reference specific findings in your angle options.
|
||||
|
||||
### Step 3: Generate Angle Options
|
||||
|
||||
Generate **at least 3 genuinely different angles**. Not rewordings — structurally different approaches to the same topic.
|
||||
|
||||
For each angle, specify:
|
||||
|
||||
| Field | What | Quality Bar |
|
||||
|-------|------|-------------|
|
||||
| `name` | Short title (5-8 words) | Specific, not generic. "Why Vector Search Beats SQL LIKE" not "About Vector Databases" |
|
||||
| `hook` | Opening line/question (under 15 words) | Must create curiosity or surprise in one sentence |
|
||||
| `narrative_structure` | How the story unfolds | One of: analogy, problem-solution, journey, debate, myth-busting, timeline, comparison |
|
||||
| `visual_approach` | Primary visual style | e.g., "animated diagrams with vector space visualizations" |
|
||||
| `suggested_playbook` | Best-matching style playbook | Reference available playbooks in `styles/` |
|
||||
| `target_audience` | Who this angle serves best | Specific: "mid-level developers evaluating databases" not "developers" |
|
||||
| `why_this_works` | Rationale | Reference your research — why is this angle compelling right now? |
|
||||
|
||||
**Angle diversity checklist:**
|
||||
- [ ] At least one angle is technical/detailed
|
||||
- [ ] At least one angle is intuitive/accessible (uses analogy or story)
|
||||
- [ ] At least one angle is provocative/surprising (challenges assumptions)
|
||||
- [ ] No two angles use the same narrative structure
|
||||
- [ ] Each angle suggests a different visual approach
|
||||
|
||||
### Step 4: Present to User and Select
|
||||
|
||||
Present all angle options clearly. Let the user:
|
||||
- Select one as-is
|
||||
- Ask you to combine elements from multiple angles
|
||||
- Describe a custom direction entirely
|
||||
|
||||
If the user provides a custom direction, use it — but apply the research and quality bar from Steps 2-3.
|
||||
|
||||
### Step 5: Assemble the Brief
|
||||
|
||||
Build the `brief` artifact with all required and relevant optional fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"title": "...",
|
||||
"hook": "...",
|
||||
"key_points": ["...", "...", "..."],
|
||||
"core_message": "...",
|
||||
"cta": "...",
|
||||
"tone": "...",
|
||||
"style": "...",
|
||||
"target_audience": "...",
|
||||
"target_platform": "youtube|instagram|tiktok|linkedin|generic",
|
||||
"target_duration_seconds": 60,
|
||||
"reference_material": ["..."],
|
||||
"angle_options": [
|
||||
{"name": "...", "description": "..."},
|
||||
{"name": "...", "description": "..."},
|
||||
{"name": "...", "description": "..."}
|
||||
],
|
||||
"selected_angle": "..."
|
||||
}
|
||||
```
|
||||
|
||||
**Field quality bar:**
|
||||
|
||||
| Field | Excellent | Mediocre |
|
||||
|-------|-----------|----------|
|
||||
| `title` | "How Vector Databases Find Your Data in 1ms" | "Vector Databases Explained" |
|
||||
| `hook` | "Your database searches every single row. What if it didn't have to?" | "Today we'll learn about vector databases" |
|
||||
| `key_points` | Concrete, specific claims the video will prove | Vague topics like "how it works" |
|
||||
| `core_message` | One sentence the viewer should remember tomorrow | Absent or too broad |
|
||||
| `cta` | Actionable and relevant: "Try building a similarity search with 10 lines of Python" | Generic: "Like and subscribe" |
|
||||
| `tone` | Matches audience and platform | Mismatched (e.g., corporate tone on TikTok) |
|
||||
|
||||
### Step 6: Self-Evaluate
|
||||
|
||||
Before submitting, score your brief on this rubric (1-5 each):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Hook strength** | Would someone stop scrolling for this? Does it create an information gap? |
|
||||
| **Specificity** | Are key_points concrete claims, not vague topics? |
|
||||
| **Research depth** | Does the brief reference real data, trends, or insights from Step 2? |
|
||||
| **Audience fit** | Is the tone, complexity, and duration right for the target audience? |
|
||||
| **Playbook match** | Does the selected style genuinely fit the content? |
|
||||
| **Uniqueness** | Does this angle offer something the existing content landscape doesn't? |
|
||||
|
||||
If any dimension scores below 3, iterate before submitting. The reviewer will check the same criteria.
|
||||
|
||||
### Step 7: Submit
|
||||
|
||||
Call `handle_explainer_idea(state, {"brief": brief_json})` to validate and persist.
|
||||
|
||||
## Playbook Selection Guide
|
||||
|
||||
| Content Type | Recommended Playbooks | Why |
|
||||
|--------------|----------------------|-----|
|
||||
| Technical architecture | `minimalist-diagram` | Clean diagrams, whiteboard feel |
|
||||
| Business/SaaS concept | `clean-professional` | Polished, trustworthy |
|
||||
| Social media / quick explainer | `flat-motion-graphics` | Eye-catching, data-driven |
|
||||
| Storytelling / narrative | Warm playbooks (Ghibli, Watercolor) | Emotional connection |
|
||||
| Developer tutorial | `minimalist-diagram` or custom | Focus on code/diagrams |
|
||||
|
||||
If no existing playbook fits, describe the desired style in `brief.style` and the pipeline can create a custom playbook later.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Skipping research**: The #1 failure mode. Without research, angles are generic and hooks are weak.
|
||||
- **Reworded angles**: Three variations of "explain how X works" are not three angles. Change the narrative structure.
|
||||
- **Wrong duration for platform**: A 3-minute explainer doesn't work on TikTok. A 30-second video can't explain Kubernetes.
|
||||
- **Ignoring the audience**: A video for CTOs needs different framing than one for junior developers, even on the same topic.
|
||||
- **Vague key_points**: "How vector databases work" is a topic, not a key point. "Vector databases use high-dimensional math to find similar items in milliseconds" is a key point.
|
||||
|
||||
## Examples
|
||||
|
||||
### Good Angle Set (Topic: "How HTTPS Works")
|
||||
|
||||
**Angle 1: The Spy Analogy**
|
||||
- Hook: "Every time you visit a website, you're having a secret conversation. Here's how."
|
||||
- Structure: Analogy (spy/espionage metaphor)
|
||||
- Visual: Animated characters passing secret messages
|
||||
- Playbook: `flat-motion-graphics`
|
||||
- Audience: General public, non-technical
|
||||
|
||||
**Angle 2: The Handshake Deep Dive**
|
||||
- Hook: "The TLS handshake takes 100 milliseconds and involves 4 messages. Here's what each one does."
|
||||
- Structure: Timeline/process walkthrough
|
||||
- Visual: Technical diagram with packet animations
|
||||
- Playbook: `minimalist-diagram`
|
||||
- Audience: CS students, junior developers
|
||||
|
||||
**Angle 3: The Myth Buster**
|
||||
- Hook: "The padlock icon doesn't mean what you think it means."
|
||||
- Structure: Myth-busting (challenge assumption, then reveal truth)
|
||||
- Visual: Split-screen before/after misconception
|
||||
- Playbook: `clean-professional`
|
||||
- Audience: Business professionals, security-aware users
|
||||
|
||||
### Bad Angle Set (same topic)
|
||||
|
||||
- Angle 1: "HTTPS Explained" — generic, no hook
|
||||
- Angle 2: "How HTTPS Works" — same thing, reworded
|
||||
- Angle 3: "Understanding HTTPS" — still the same, no structural difference
|
||||
@@ -0,0 +1,343 @@
|
||||
# Proposal Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the **Proposal Director** for a generated explainer video. You sit between the Research Director and the Script Director. You receive a `research_brief` full of raw findings and transform it into a concrete, reviewable proposal that the user approves before any money is spent.
|
||||
|
||||
**This is the approval gate.** Nothing downstream runs until the user says "go." Your job is to make that decision easy by presenting clear options, honest costs, and explicit tradeoffs.
|
||||
|
||||
Think of yourself as a creative agency pitching to a client: you present concepts backed by research, show what it'll cost, explain the tradeoffs, and let the client choose.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/proposal_packet.schema.json` | Artifact validation |
|
||||
| Prior artifact | `research_brief` from Research Director | Raw research findings |
|
||||
| Pipeline manifest | `pipeline_defs/animated-explainer.yaml` | Stage and tool definitions |
|
||||
| Tool registry | `support_envelope()` output | What's actually available right now |
|
||||
| Cost tracker | `tools/cost_tracker.py` | Cost estimation data |
|
||||
| Style playbooks | `styles/*.yaml` | Available visual styles |
|
||||
| User input | Topic, any preferences expressed | Creative direction |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Absorb the Research
|
||||
|
||||
Read the `research_brief` thoroughly. Extract:
|
||||
|
||||
- **`research_summary`** — read this first. This is the researcher's single most important finding.
|
||||
- **`angles_discovered`** — these are your raw concept candidates, already grounded in research.
|
||||
- **`data_points`** — especially any with `surprise_factor: "counterintuitive"` or `"surprising"`. These become hooks.
|
||||
- **`audience_insights.misconceptions`** — myth-busting is a proven engagement pattern.
|
||||
- **`landscape.underserved_gaps`** — this is where the opportunity lives. Our video should fill a gap, not repeat what exists.
|
||||
- **`trending`** — if there's a timeliness window, factor it into concept urgency.
|
||||
|
||||
### Step 2: Run Preflight
|
||||
|
||||
Before designing concepts, know what tools are available:
|
||||
|
||||
```bash
|
||||
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.support_envelope(), indent=2))"
|
||||
```
|
||||
|
||||
Also check the capability catalog:
|
||||
|
||||
```bash
|
||||
python -c "from tools.tool_registry import registry; import json; registry.discover(); print(json.dumps(registry.capability_catalog(), indent=2))"
|
||||
```
|
||||
|
||||
Record:
|
||||
- Which TTS providers are available — run `registry.get_by_capability("tts")` and check status
|
||||
- Which video generation providers are available — run `registry.get_by_capability("video_generation")` and check status
|
||||
- Which enhancement tools are available
|
||||
- Image generation status — run `registry.get_by_capability("image_generation")` and check status
|
||||
- **Remotion render engine status** — check `video_compose.get_info()["render_engines"]["remotion"]`. If `true`, Remotion is available for animated text cards, stat cards, charts, spring-physics transitions, and image-to-video rendering. This is a major quality upgrade over Ken Burns pan-and-zoom.
|
||||
|
||||
This directly affects what you can promise in the production plan. **Do not propose a concept that requires tools you don't have.**
|
||||
|
||||
**Setup offers:** If critical tools are UNAVAILABLE but fixable with a simple configuration, read each tool's `install_instructions` from the registry and offer the user setup help before designing around the limitation. See AGENT_GUIDE.md "Provider Menu" protocol for the approach. Group related tools that share the same env var dependency.
|
||||
|
||||
### Step 3: Design Concept Options
|
||||
|
||||
Build **at least 3 genuinely different concepts.** Start from the `angles_discovered` in the research brief, but elevate them into full production concepts.
|
||||
|
||||
For each concept, specify all fields in the `proposal_packet.concept_options` schema:
|
||||
|
||||
#### 3a: Title and Hook
|
||||
|
||||
The title and hook are the most important two lines. They determine whether the user gets excited or scrolls past.
|
||||
|
||||
**Hook construction patterns** (use the research to fill these):
|
||||
|
||||
| Pattern | Template | When to Use |
|
||||
|---------|----------|-------------|
|
||||
| **Surprising stat** | "[Counterintuitive number]. Here's why." | When you have a data point with high surprise factor |
|
||||
| **Misconception flip** | "You've been told [myth]. The truth is [reality]." | When audience_insights.misconceptions has a strong entry |
|
||||
| **Recency** | "[Thing] just changed everything about [topic]. Here's what happened." | When trending.recent_developments has a timely event |
|
||||
| **Question** | "Why does [thing everyone experiences] actually happen?" | When audience_insights.common_questions has a strong entry |
|
||||
| **Contrast** | "[Thing A] takes [big number]. [Thing B] takes [small number]. Here's the trick." | When data_points has comparison data |
|
||||
| **Insider knowledge** | "The thing about [topic] that nobody explains." | When landscape.underserved_gaps reveals a strong gap |
|
||||
|
||||
**Rules:**
|
||||
- Hook must be under 20 words
|
||||
- Hook must create an information gap — the viewer needs to watch to close it
|
||||
- Hook must be grounded in a specific research finding (cite it in `grounded_in`)
|
||||
- Never use: "In this video we'll...", "Hey guys...", "Let me explain..."
|
||||
|
||||
#### 3b: Narrative Structure
|
||||
|
||||
Choose the structure that best fits the research findings:
|
||||
|
||||
| Structure | Best When | Research Signal |
|
||||
|-----------|-----------|-----------------|
|
||||
| `myth_busting` | Strong misconceptions found | `audience_insights.misconceptions` has 2+ entries |
|
||||
| `problem_solution` | Clear pain points | `audience_insights.pain_points` is rich |
|
||||
| `data_narrative` | Strong surprising data | Multiple data_points with high surprise_factor |
|
||||
| `comparison` | Two approaches to compare | Data_points contain comparative data |
|
||||
| `timeline` | Topic has evolution/history | Landscape shows topic changing over time |
|
||||
| `journey` | Complex topic needs progressive reveal | `audience_insights.knowledge_level` shows big gaps |
|
||||
| `analogy` | Abstract topic needs grounding | Audience is non-technical |
|
||||
| `debate` | Community is divided | `trending.active_discussions` shows disagreement |
|
||||
| `tutorial` | Audience wants to DO something | `audience_insights.common_questions` are how-to |
|
||||
| `story` | Human interest angle exists | Expert voices or real-world cases available |
|
||||
|
||||
#### 3c: Visual Approach and Playbook
|
||||
|
||||
Match the visual approach to the content. **Check Remotion availability first** — if `video_compose` reports `render_engines.remotion: true`, the Remotion render path unlocks animated text cards, stat cards, charts, spring-physics transitions, and component-based scenes. This should change your visual design:
|
||||
|
||||
| Content Type | Visual Approach (Remotion available) | Visual Approach (FFmpeg only) | Playbook |
|
||||
|--------------|--------------------------------------|-------------------------------|----------|
|
||||
| Technical architecture/process | Remotion animated diagrams, flowcharts with spring transitions | Static diagrams with Ken Burns motion | `minimalist-diagram` |
|
||||
| Data-heavy narrative | Remotion stat cards, animated charts, comparison cards | Static image cards with zoom-in | `flat-motion-graphics` |
|
||||
| Professional/business | Remotion text cards with clean typography | Image-based title cards | `clean-professional` |
|
||||
| Storytelling/analogy | Remotion scenes with animated character cards | Image sequence with pan | Warm/narrative playbook |
|
||||
| Tutorial/how-to | Screen captures + Remotion callout overlays | Screen captures + static overlays | `minimalist-diagram` |
|
||||
|
||||
**Remotion components available** (when Remotion engine is active):
|
||||
- `text_card` — animated text with spring entrance
|
||||
- `stat_card` — number + label with count-up animation
|
||||
- `callout` — highlighted explanation box
|
||||
- `comparison` — side-by-side with animated reveal
|
||||
- `progress` — animated progress bar
|
||||
- `chart` — bar, line, pie charts with animated data entry
|
||||
- `kpi_grid` — multi-stat dashboard layout
|
||||
|
||||
**Important:** When Remotion is available and the playbook is `flat-motion-graphics`, **always design for Remotion component scenes** rather than static AI-generated images with Ken Burns pan. This is the difference between a professional motion graphics video and a slideshow.
|
||||
|
||||
#### 3d: Duration and Platform
|
||||
|
||||
Set realistic duration based on platform and content depth:
|
||||
|
||||
| Platform | Duration Range | Word Budget (150 WPM) |
|
||||
|----------|---------------|----------------------|
|
||||
| TikTok | 30-60s | 65-150 words |
|
||||
| Instagram Reels | 30-90s | 65-225 words |
|
||||
| YouTube Shorts | 30-60s | 65-150 words |
|
||||
| YouTube | 60-180s | 150-450 words |
|
||||
| LinkedIn | 60-120s | 150-300 words |
|
||||
|
||||
#### 3e: Concept Diversity Check
|
||||
|
||||
Before finalizing, verify diversity:
|
||||
|
||||
- [ ] No two concepts use the same narrative structure
|
||||
- [ ] No two concepts use the same hook pattern
|
||||
- [ ] At least one concept targets a different audience segment
|
||||
- [ ] At least one concept leverages the most surprising data point
|
||||
- [ ] At least one concept addresses the biggest content gap found
|
||||
- [ ] Each concept's `grounded_in` references different research findings
|
||||
|
||||
### Step 4: Present Concepts and Get Selection
|
||||
|
||||
Present all concepts clearly to the user. For each concept, show:
|
||||
|
||||
1. **Title** and **hook** — the creative pitch
|
||||
2. **Why this works** — the research backing, in one sentence
|
||||
3. **What it'll look like** — visual approach in plain language
|
||||
4. **Duration** — how long the video will be
|
||||
|
||||
Let the user:
|
||||
- Select one as-is
|
||||
- Combine elements from multiple concepts
|
||||
- Request modifications
|
||||
- Describe a completely different direction (in which case, use the research to strengthen it)
|
||||
|
||||
Record the selection in `selected_concept` with rationale and any modifications.
|
||||
|
||||
### Step 5: Build the Production Plan
|
||||
|
||||
For the selected concept, design the stage-by-stage production plan.
|
||||
|
||||
For each stage in the pipeline manifest (`animated-explainer.yaml`), specify:
|
||||
|
||||
1. **Which tools will be used** — specific provider names, not just selectors
|
||||
2. **Whether each tool is available** — from the preflight check
|
||||
3. **Estimated cost per tool** — from the tool's cost metadata
|
||||
4. **Why this provider** — explain the choice ("ElevenLabs for narration because voice quality is critical for this topic" or "Piper TTS because running local-only and free")
|
||||
5. **Fallback if unavailable** — what happens if the primary tool is down
|
||||
|
||||
**Tool selection rationale must be honest:**
|
||||
- If using a free/local tool because the cloud tool is unavailable, say so
|
||||
- If using a cloud tool when a local alternative exists, explain the quality tradeoff
|
||||
- If a capability is entirely missing, say what the video will lack
|
||||
|
||||
#### Quality/Cost Tradeoff Matrix
|
||||
|
||||
For each meaningful choice, present the tradeoff:
|
||||
|
||||
```
|
||||
TRADEOFF: TTS Provider
|
||||
├── Premium: ElevenLabs ($0.18-0.30) — natural voice, emotional delivery
|
||||
├── Standard: OpenAI TTS ($0.05-0.15) — good quality, less expressive
|
||||
└── Free: Piper local ($0.00) — robotic but works offline
|
||||
|
||||
TRADEOFF: Visual Assets
|
||||
├── Premium: AI video clips ($0.10-0.50/clip) — motion, dynamic
|
||||
├── Standard: AI images ($0.02-0.04/image) — static, reliable
|
||||
└── Free: Diagrams/code ($0.00) — text-based, technical feel
|
||||
|
||||
TRADEOFF: Render Path (check video_compose render_engines)
|
||||
├── Remotion ($0.00, local): Animated text cards, stat cards, charts,
|
||||
│ spring-physics transitions, component-based scenes. Professional
|
||||
│ motion graphics feel. Requires Node.js.
|
||||
└── FFmpeg ($0.00, local): Ken Burns pan-and-zoom on images, video
|
||||
concat. Functional but less engaging for explainer content.
|
||||
```
|
||||
|
||||
**If Remotion is available:** Design the scene plan around Remotion component types (text_card, stat_card, chart, etc.) rather than generating AI images for every scene. This is both cheaper (fewer image gen calls) and higher quality (animated motion graphics vs. static images with pan).
|
||||
|
||||
Also present **alternative production paths** — complete packages at different price points:
|
||||
|
||||
| Path | Quality | Cost | What Changes |
|
||||
|------|---------|------|-------------|
|
||||
| Premium | Best TTS + video clips + music | ~$1.50-2.50 | Full production value |
|
||||
| Standard | Good TTS + images + music | ~$0.50-1.00 | Static visuals, still professional |
|
||||
| Budget | Local TTS + images | ~$0.05-0.15 | Robotic voice, image-only |
|
||||
| Free | Local TTS + diagrams | $0.00 | Functional but minimal |
|
||||
|
||||
### Step 6: Build the Cost Estimate
|
||||
|
||||
Itemize every paid operation:
|
||||
|
||||
```
|
||||
COST ESTIMATE
|
||||
├── TTS Narration: tts_selector × 1 run (~150 words) $0.18
|
||||
├── Image Generation: image_selector × 6 scenes $0.24
|
||||
├── Music: music_gen × 1 track (30s) $0.10
|
||||
├── Video Generation: video_selector × 2 clips (optional) $0.00 (local)
|
||||
├── Audio Enhancement: audio_enhance × 1 pass $0.00 (local)
|
||||
└── TOTAL ESTIMATED $0.52
|
||||
Budget cap: $2.00
|
||||
Verdict: within_budget ✓
|
||||
Headroom: $1.48 for revisions/regeneration
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Always show per-item costs, not just the total
|
||||
- Always show the budget cap comparison
|
||||
- If over budget, list specific savings options (e.g., "Switch to a cheaper TTS provider: saves $0.18" — check each provider's `estimate_cost` via the registry)
|
||||
- Include headroom note — some budget should remain for revisions
|
||||
|
||||
### Step 7: Assemble the Approval Gate
|
||||
|
||||
The approval section is where the user commits. Present it as a clear decision point:
|
||||
|
||||
```
|
||||
────────────────────────────────────────
|
||||
PROPOSAL READY FOR APPROVAL
|
||||
|
||||
Concept: [selected title]
|
||||
Duration: [X] seconds for [platform]
|
||||
Estimated cost: $[X.XX] of $[budget] budget
|
||||
Production path: [premium/standard/budget/free]
|
||||
|
||||
Proceed? (approve / approve with changes / reject)
|
||||
────────────────────────────────────────
|
||||
```
|
||||
|
||||
Set `approval.status: "pending"` in the artifact. The EP or the user updates this to `approved` before the pipeline continues.
|
||||
|
||||
**Critical rule:** The pipeline MUST NOT proceed past this stage without explicit approval. This is the last free exit. Everything after this costs money and time.
|
||||
|
||||
### Step 8: Submit
|
||||
|
||||
Validate the `proposal_packet` artifact against `schemas/artifacts/proposal_packet.schema.json` and submit.
|
||||
|
||||
## How This Connects Downstream
|
||||
|
||||
| Downstream Stage | What It Takes From proposal_packet |
|
||||
|------------------|------------------------------------|
|
||||
| Script Director | `selected_concept` (title, hook, key_points, core_message, tone, narrative_structure) + research_brief data points |
|
||||
| Scene Director | `selected_concept.visual_approach` + `production_plan.playbook` |
|
||||
| Asset Director | `production_plan.stages[assets].tools` — knows exactly which providers to use |
|
||||
| Executive Producer | `cost_estimate` — initializes budget tracking |
|
||||
| All stages | `approval.approved_budget_usd` — hard spending cap |
|
||||
|
||||
The `selected_concept` in the proposal_packet effectively replaces what the old `brief` artifact used to be — but it's grounded in research and comes with an explicit production plan attached.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Presenting concepts without research grounding**: Every concept's `why_this_works` must reference specific research findings. "This is a popular topic" is not grounding. "Cloudflare Radar shows 13.5% of DNS queries hit 1.1.1.1, which contradicts the common belief that Google DNS dominates" is grounding.
|
||||
- **Hiding costs**: Be transparent. If ElevenLabs will cost $0.30, say $0.30. Don't round down or omit items. The user trusts you more when you're honest.
|
||||
- **Over-promising tool availability**: If the preflight shows only Piper TTS available, don't design a concept that depends on expressive voice acting. Design around constraints.
|
||||
- **Three versions of the same concept**: "Kubernetes Explained", "Understanding Kubernetes", and "Kubernetes Guide" are not three concepts. They're one concept with three titles. Structural diversity means different narrative structures, different hooks, different audiences.
|
||||
- **Skipping the approval gate**: This is the whole point of pre-production. No shortcuts.
|
||||
- **Not showing alternatives**: The user should always see at least 2 production paths at different price points. Let them make an informed choice.
|
||||
|
||||
## Example: Full Proposal Flow
|
||||
|
||||
### Input: research_brief on "How DNS Works"
|
||||
|
||||
**Concept 1: "The 200ms Journey" (data_driven)**
|
||||
- Hook: "Every website you visit starts with a 200-millisecond treasure hunt across the internet."
|
||||
- Structure: journey — follow a DNS query step by step
|
||||
- Visual: minimalist-diagram, animated packet flow
|
||||
- Duration: 90s (YouTube)
|
||||
- Grounded in: recursive resolution timing data, audience gap about multi-step process
|
||||
- Why it works: Most viewers think DNS is instant and singular. Showing the real journey is the aha moment.
|
||||
|
||||
**Concept 2: "Your ISP Knows Everything" (contrarian)**
|
||||
- Hook: "Your internet provider logs every website you visit. Here's the 40-year-old system that makes it possible."
|
||||
- Structure: myth_busting — challenge "private browsing = private" belief
|
||||
- Visual: clean-professional, privacy-focused with dark tones
|
||||
- Duration: 75s (YouTube)
|
||||
- Grounded in: DNS privacy misconception (audience research), DoH trending signal
|
||||
- Why it works: Privacy is emotionally charged. The misconception that HTTPS = full privacy is widespread.
|
||||
|
||||
**Concept 3: "The Internet's Phone Book" (analogy)**
|
||||
- Hook: "DNS is a phone book designed in 1983 that somehow still runs the modern internet."
|
||||
- Structure: analogy — phone book metaphor through historical evolution
|
||||
- Visual: flat-motion-graphics, retro-to-modern visual timeline
|
||||
- Duration: 60s (LinkedIn)
|
||||
- Grounded in: audience knowledge gap about DNS age, landscape gap (no historical angle found)
|
||||
- Why it works: Simplest on-ramp for non-technical audience. The "still works after 40 years" angle is inherently surprising.
|
||||
|
||||
**Production plan (for selected concept 1, Remotion available):**
|
||||
```
|
||||
script → no tools, no cost
|
||||
scene → no tools, no cost — design 4 Remotion component scenes + 4 AI image scenes
|
||||
assets → tts_selector ($0.22), image_selector × 4 ($0.16), music_gen ($0.10)
|
||||
edit → no tools, no cost
|
||||
compose → video_compose/Remotion render (free) — animated text cards, stat cards,
|
||||
spring transitions, image scenes with animation. NOT Ken Burns.
|
||||
publish → no tools, no cost
|
||||
TOTAL: $0.48 of $2.00 budget (saved $0.16 by using Remotion components instead of
|
||||
generating images for text/data scenes)
|
||||
```
|
||||
|
||||
**Production plan (for selected concept 1, FFmpeg only):**
|
||||
```
|
||||
script → no tools, no cost
|
||||
scene → no tools, no cost
|
||||
assets → tts_selector ($0.22), image_selector × 8 ($0.32), music_gen ($0.10)
|
||||
edit → no tools, no cost
|
||||
compose → video_compose/FFmpeg (free) — Ken Burns pan-and-zoom on images
|
||||
publish → no tools, no cost
|
||||
TOTAL: $0.64 of $2.00 budget
|
||||
```
|
||||
|
||||
**Alternative paths:**
|
||||
- Premium (Remotion): Best available TTS + 4 AI images + 4 Remotion animated scenes = $0.48
|
||||
- Standard: Mid-tier TTS + images = $0.40
|
||||
- Free: Local TTS + Remotion component scenes only = $0.00 (no images, pure motion graphics)
|
||||
@@ -0,0 +1,152 @@
|
||||
# Publish Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Publisher for a generated explainer video. You have a `render_report` with the final video file. Your job is to prepare the video for distribution: generate SEO metadata, create thumbnails, package exports, and log the publish event.
|
||||
|
||||
This is where a great video reaches its audience. Without proper metadata and packaging, even the best content gets buried.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/publish_log.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["compose"]["render_report"]`, `state.artifacts["idea"]["brief"]` | Video file and original brief |
|
||||
| Playbook | Active style playbook | Visual style for thumbnail |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Gather Context
|
||||
|
||||
Collect everything needed for metadata:
|
||||
- **Brief**: title, hook, key points, target platform, tone
|
||||
- **Render report**: output path, duration, resolution
|
||||
- **Script**: section summaries for description/chapters
|
||||
|
||||
### Step 2: Generate SEO Metadata
|
||||
|
||||
**Title** (max 60 characters for YouTube):
|
||||
- Include the primary keyword from the brief
|
||||
- Lead with a hook or number
|
||||
- Avoid clickbait but be compelling
|
||||
- Examples: "Vector Databases Explained in 60 Seconds" > "About Vector Databases"
|
||||
|
||||
**Description** (first 150 chars are critical — shown in search):
|
||||
- Opening line: restate the hook with the main value proposition
|
||||
- Body: key topics covered, with relevant keywords naturally included
|
||||
- Chapters: timestamp markers for each major section (from script sections)
|
||||
- Call to action: subscribe/like/follow
|
||||
- Links: relevant resources mentioned in the video
|
||||
|
||||
**Tags/Keywords** (platform-dependent):
|
||||
- 5-10 specific tags derived from brief's key_points
|
||||
- Mix broad and specific: "machine learning" + "vector database tutorial"
|
||||
- Include the topic, format ("explainer"), and related terms
|
||||
|
||||
**Hashtags** (for social platforms):
|
||||
- 3-5 relevant hashtags
|
||||
- Mix trending and niche
|
||||
|
||||
### Step 3: Generate Thumbnail Concept
|
||||
|
||||
Describe a thumbnail that:
|
||||
1. Uses the playbook's visual style
|
||||
2. Features the video's core concept visually
|
||||
3. Includes 3-5 words of text (the hook or key stat)
|
||||
4. Has high contrast and is readable at small sizes
|
||||
5. Uses the playbook's accent colors for text
|
||||
|
||||
```json
|
||||
{
|
||||
"thumbnail": {
|
||||
"concept": "Split screen: left side shows slow SQL query (red X), right shows fast vector search (green check). Large text: '100x FASTER'",
|
||||
"text_overlay": "100x FASTER",
|
||||
"style_notes": "Use playbook accent colors, bold Inter font, dark background"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
*Note: Actual thumbnail generation happens via image_selector if available, otherwise it's a concept for manual creation.*
|
||||
|
||||
### Step 4: Create Chapter Markers
|
||||
|
||||
From the script sections, generate YouTube-style chapters:
|
||||
|
||||
```
|
||||
0:00 - Introduction
|
||||
0:15 - What are Vector Databases?
|
||||
0:45 - How Embeddings Work
|
||||
1:20 - The Search Algorithm
|
||||
1:55 - Real-World Examples
|
||||
2:30 - When to Use Vector DBs
|
||||
```
|
||||
|
||||
Each chapter maps to a script section's `start_seconds`.
|
||||
|
||||
### Step 5: Package Export
|
||||
|
||||
Create the export directory structure:
|
||||
|
||||
```
|
||||
exports/
|
||||
<project_name>/
|
||||
video/
|
||||
output.mp4 # Final rendered video
|
||||
metadata/
|
||||
metadata.json # All SEO metadata
|
||||
chapters.txt # Chapter markers
|
||||
description.txt # Ready-to-paste description
|
||||
tags.txt # One tag per line
|
||||
thumbnails/
|
||||
concept.json # Thumbnail concept (or generated image)
|
||||
```
|
||||
|
||||
### Step 6: Build Publish Log
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "1.0",
|
||||
"entries": [
|
||||
{
|
||||
"platform": "youtube",
|
||||
"status": "draft",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"metadata": {
|
||||
"title": "Vector Databases Explained in 60 Seconds",
|
||||
"description_length": 450,
|
||||
"tags_count": 8,
|
||||
"chapters_count": 6,
|
||||
"thumbnail_ready": false
|
||||
},
|
||||
"export_path": "exports/vector-db-explainer/",
|
||||
"video_path": "renders/output.mp4"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Step 7: Self-Evaluate
|
||||
|
||||
Score (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **SEO quality** | Would this title and description rank well for the topic? |
|
||||
| **Description completeness** | Does the description include chapters, CTA, and keywords? |
|
||||
| **Thumbnail concept** | Would this thumbnail stand out in a feed? |
|
||||
| **Export package** | Is everything a creator needs in the export directory? |
|
||||
| **Platform fit** | Is metadata tailored to the target platform? |
|
||||
|
||||
If any dimension scores below 3, revise.
|
||||
|
||||
### Step 8: Submit
|
||||
|
||||
Validate the publish_log against the schema and persist via checkpoint.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Generic titles**: "Video About X" loses to "X Explained in 60 Seconds" every time. Be specific and compelling.
|
||||
- **No chapters**: YouTube rewards videos with chapters. Always include them.
|
||||
- **Description keyword stuffing**: Write for humans first, search engines second. Natural language with keywords woven in.
|
||||
- **Forgetting the CTA**: Every description should end with a call to action.
|
||||
- **Wrong platform format**: YouTube descriptions differ from TikTok captions. Tailor to the target platform.
|
||||
@@ -0,0 +1,311 @@
|
||||
# Research Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the **Research Director** for a generated explainer video. You are the first stage in the pipeline — before any creative decisions, before any script, before any money is spent. Your job is to **deeply research the topic** using web search and produce a `research_brief` artifact that grounds the entire video in real data, real trends, and real audience insights.
|
||||
|
||||
This stage is what separates an OpenMontage video from generic AI slop. Without research, the agent produces vague platitudes. With research, it produces content that has authority, specificity, and timeliness.
|
||||
|
||||
**You do NOT make creative decisions.** You gather raw material. The Proposal Director downstream will use your findings to craft concept options.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/research_brief.schema.json` | Artifact validation |
|
||||
| User input | Topic, audience hint, platform hint | Research scope |
|
||||
| Tools | Web search, web fetch | Research execution |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Scope the Research
|
||||
|
||||
Before searching anything, establish boundaries:
|
||||
|
||||
- **Topic**: What is the core subject? Extract from user input.
|
||||
- **Audience hint**: Did the user mention who this is for? (developers, general public, executives, students)
|
||||
- **Platform hint**: Did the user mention where this will go? (YouTube, TikTok, LinkedIn)
|
||||
- **Depth**: Is this a well-known topic (HTTPS, React) or niche (vector clock CRDTs, QUIC protocol)?
|
||||
|
||||
If the user's request is a single phrase like "make a video about kubernetes," that's fine — you have enough to research. Do NOT ask clarifying questions at this stage. Research first, clarify later (in the Proposal stage).
|
||||
|
||||
### Step 2: Content Landscape Scan
|
||||
|
||||
**Goal:** Understand what already exists so we can find gaps.
|
||||
|
||||
Execute these searches in parallel:
|
||||
|
||||
```
|
||||
SEARCH BATCH 1 — Landscape (run all in parallel)
|
||||
|
||||
Q1: "[topic] explained" site:youtube.com
|
||||
→ Find: Top existing explainer videos. Note titles, view counts, angles used.
|
||||
|
||||
Q2: "[topic]" (guide OR tutorial OR explained OR breakdown) -site:youtube.com
|
||||
→ Find: Blog posts and articles covering this topic.
|
||||
|
||||
Q3: "[topic] [current month] [current year]"
|
||||
→ Find: The freshest content. What's being published RIGHT NOW?
|
||||
|
||||
Q4: "best [topic category] [current year]"
|
||||
→ Find: Listicles and comparisons — reveals the competitive landscape.
|
||||
```
|
||||
|
||||
**Parse results for:**
|
||||
- Which angles have been done to death (saturated)
|
||||
- Which questions remain unanswered (gaps)
|
||||
- What the top-performing content looks like (benchmarks)
|
||||
- When the most recent quality content was published (freshness)
|
||||
|
||||
Record at least 3 entries in `landscape.existing_content` with specific titles, sources, and gap analysis.
|
||||
|
||||
### Step 3: Trending Pulse
|
||||
|
||||
**Goal:** Find what's happening RIGHT NOW — news, debates, controversies, launches.
|
||||
|
||||
```
|
||||
SEARCH BATCH 2 — Trending (run all in parallel)
|
||||
|
||||
Q5: "[topic]" (announcement OR launch OR update OR controversy) after:[current year]-01-01
|
||||
→ Find: Recent events that make this topic timely.
|
||||
|
||||
Q6: "[topic]" site:reddit.com after:[6 months ago]
|
||||
→ Find: Active community discussions, pain points, hot takes.
|
||||
|
||||
Q7: "[topic]" site:news.ycombinator.com
|
||||
→ Find: Tech-literate opinions, contrarian takes, deeper analysis.
|
||||
|
||||
Q8: "why is [topic]" (trending OR popular OR important OR everywhere) [current year]
|
||||
→ Find: Meta-commentary on why people care about this right now.
|
||||
```
|
||||
|
||||
**Parse results for:**
|
||||
- Recent developments that could be the hook ("X just happened, here's what it means")
|
||||
- Active debates where people disagree (debate = engagement)
|
||||
- Sentiment — is the community excited, frustrated, confused, divided?
|
||||
- Timeliness window — is this a "publish this week" moment or evergreen?
|
||||
|
||||
If no trending signal exists, that's fine — note `timeliness_window: "evergreen"` and move on. Not every topic has a news hook, and that's okay.
|
||||
|
||||
### Step 4: Data and Evidence Gathering
|
||||
|
||||
**Goal:** Find specific, citable facts that will anchor the script.
|
||||
|
||||
```
|
||||
SEARCH BATCH 3 — Data (run all in parallel)
|
||||
|
||||
Q9: "[topic]" statistics [current year]
|
||||
→ Find: Hard numbers — market size, adoption rates, performance benchmarks.
|
||||
|
||||
Q10: "[topic]" (study OR research OR survey OR report) [current year - 1] OR [current year]
|
||||
→ Find: Academic or industry research with credible methodology.
|
||||
|
||||
Q11: "[topic]" "according to" (report OR study OR survey)
|
||||
→ Find: Cited claims with named sources.
|
||||
|
||||
Q12: "[topic]" "surprisingly" OR "counterintuitively" OR "most people don't know"
|
||||
→ Find: Surprising facts — these become hooks and retention anchors.
|
||||
|
||||
Q13: "[topic]" (comparison OR benchmark OR "vs") data
|
||||
→ Find: Comparative data that can become visual stat cards.
|
||||
```
|
||||
|
||||
**For each data point found, record:**
|
||||
- The specific claim (not vague — "73% of developers use X" not "most developers use X")
|
||||
- Source URL and source name
|
||||
- Credibility rating: `primary_source` (original research), `secondary_source` (reporting on research), `anecdotal` (blog post, opinion)
|
||||
- Surprise factor: would the target audience find this expected or counterintuitive?
|
||||
- How it could be used: `hook`, `stat_card`, `script_anchor`, `closing_punch`
|
||||
|
||||
**Minimum: 3 data points. Target: 5-8.** If the topic is data-poor (e.g., philosophical or creative), find expert quotes instead.
|
||||
|
||||
### Step 5: Audience Mining
|
||||
|
||||
**Goal:** Understand what real people ask, believe, and get wrong about this topic.
|
||||
|
||||
```
|
||||
SEARCH BATCH 4 — Audience (run all in parallel)
|
||||
|
||||
Q14: "[topic]" site:reddit.com "help" OR "confused" OR "why does" OR "ELI5"
|
||||
→ Find: Real questions from real people struggling with this topic.
|
||||
|
||||
Q15: "[topic]" site:quora.com OR site:stackoverflow.com
|
||||
→ Find: Structured Q&A — what do beginners ask?
|
||||
|
||||
Q16: "why is [topic] so" (hard OR confusing OR expensive OR slow OR popular)
|
||||
→ Find: Pain points and frustrations.
|
||||
|
||||
Q17: "[topic]" "common mistakes" OR "myths" OR "misconceptions" OR "wrong about"
|
||||
→ Find: What people get wrong — myth-busting is powerful engagement.
|
||||
|
||||
Q18: "[topic]" "wish I knew" OR "before you start" OR "nobody tells you"
|
||||
→ Find: Insider knowledge that feels valuable.
|
||||
```
|
||||
|
||||
**Parse results for:**
|
||||
- Top 5+ real questions (not generated — sourced from actual forum posts)
|
||||
- Common misconceptions with the real answer (myth vs reality)
|
||||
- Knowledge level of the target audience (what they already know, what's new)
|
||||
- Pain points and frustrations
|
||||
|
||||
### Step 6: Expert Voices (Optional but High-Value)
|
||||
|
||||
**Goal:** Find named experts and their positions — adds authority.
|
||||
|
||||
```
|
||||
SEARCH BATCH 5 — Experts (run if topic has known figures)
|
||||
|
||||
Q19: "[topic]" (creator OR inventor OR pioneer OR expert) (interview OR talk OR keynote)
|
||||
→ Find: The key voices on this topic.
|
||||
|
||||
Q20: "[topic]" "unpopular opinion" OR "hot take" OR "controversial"
|
||||
→ Find: Contrarian positions that create debate framing.
|
||||
```
|
||||
|
||||
**For each expert, record:**
|
||||
- Name and affiliation
|
||||
- Their position or notable quote
|
||||
- Whether they're mainstream or contrarian (contrarian views make great "but..." moments in scripts)
|
||||
|
||||
### Step 7: Visual Reference Scan (Quick Pass)
|
||||
|
||||
**Goal:** See how others visualize this concept — inform the Proposal Director's visual approach.
|
||||
|
||||
```
|
||||
Q21: "[topic]" (explainer OR animation OR infographic OR diagram)
|
||||
→ Find: Visual treatments that work for this topic.
|
||||
```
|
||||
|
||||
Record 2-3 visual references with what works about each approach.
|
||||
|
||||
### Step 8: Angle Synthesis
|
||||
|
||||
**This is where you earn your keep.** Using everything from Steps 2-7, identify at least 3 genuinely different angle candidates.
|
||||
|
||||
For each angle, specify:
|
||||
|
||||
| Field | What | Quality Bar |
|
||||
|-------|------|-------------|
|
||||
| `name` | Short title (5-8 words) | Specific. "Why Vector Search Beats SQL LIKE" not "About Vector Databases" |
|
||||
| `hook` | One-sentence grabber | Must create an information gap or surprise |
|
||||
| `type` | `trending`, `evergreen`, `contrarian`, `narrative`, `data_driven` | Categorize honestly |
|
||||
| `why_now` | Why this angle is compelling right now | **Must cite specific research findings** — not vibes |
|
||||
| `grounded_in` | Which data points or audience insights support it | Cross-reference your findings |
|
||||
|
||||
**Angle diversity checklist:**
|
||||
- [ ] At least one angle leverages trending/recent findings (if available)
|
||||
- [ ] At least one angle is evergreen (works in 6 months too)
|
||||
- [ ] At least one angle is surprising or contrarian
|
||||
- [ ] No two angles use the same hook structure
|
||||
- [ ] Each angle is grounded in different research findings
|
||||
|
||||
### Step 9: Source Bibliography
|
||||
|
||||
Compile all URLs used, organized by which section of the brief they support. Minimum 5 sources.
|
||||
|
||||
**Source quality rules:**
|
||||
- Primary sources (original studies, official docs) > secondary (news articles, blog posts) > anecdotal (forum comments, tweets)
|
||||
- At least 2 sources should be primary
|
||||
- Every data_point must have a source_url
|
||||
- Flag any source older than 2 years — it may be outdated
|
||||
|
||||
### Step 10: Assemble and Submit
|
||||
|
||||
Build the `research_brief` artifact per the schema. Include:
|
||||
|
||||
1. `research_summary` — one paragraph capturing the single most important insight. This is what the Proposal Director reads first.
|
||||
2. All sections from Steps 2-9
|
||||
|
||||
Validate against `schemas/artifacts/research_brief.schema.json` before submitting.
|
||||
|
||||
## Search Query Construction Rules
|
||||
|
||||
These rules ensure your searches actually find useful results:
|
||||
|
||||
### Use the Current Date
|
||||
|
||||
Always include time context in queries where freshness matters:
|
||||
- `[topic] [current year]` for general freshness
|
||||
- `[topic] [current month] [current year]` for trending signals
|
||||
- `after:[YYYY-MM-DD]` filters when supported
|
||||
|
||||
### Topic Decomposition
|
||||
|
||||
For compound topics, search both the whole and the parts:
|
||||
- Topic: "how kubernetes autoscaling works"
|
||||
- Search 1: `kubernetes autoscaling explained`
|
||||
- Search 2: `kubernetes HPA` (the specific mechanism)
|
||||
- Search 3: `container orchestration autoscaling` (the broader category)
|
||||
|
||||
### Audience-Aware Query Variants
|
||||
|
||||
The same topic needs different queries for different audiences:
|
||||
- For developers: `[topic] implementation` / `[topic] architecture` / `[topic] code example`
|
||||
- For executives: `[topic] ROI` / `[topic] business impact` / `[topic] case study`
|
||||
- For general public: `[topic] explained simply` / `what is [topic]` / `[topic] for beginners`
|
||||
|
||||
### Quote Mining
|
||||
|
||||
To find specific quotable content:
|
||||
- `"[topic]" "the problem is"` — finds people articulating problems
|
||||
- `"[topic]" "the key insight"` — finds distilled wisdom
|
||||
- `"[topic]" "what surprised me"` — finds surprise reactions
|
||||
|
||||
### The Negative Space
|
||||
|
||||
Search for what's NOT being said:
|
||||
- `[topic] "nobody talks about"` — finds underserved angles
|
||||
- `[topic] "overlooked"` — finds hidden aspects
|
||||
- `[topic] -[obvious_subtopic]` — filters out saturated content
|
||||
|
||||
## Quality Bar
|
||||
|
||||
Before submitting your research_brief, verify:
|
||||
|
||||
| Criterion | Minimum | Target |
|
||||
|-----------|---------|--------|
|
||||
| Existing content surveyed | 3 pieces | 5-8 pieces |
|
||||
| Data points with sources | 3 | 5-8 |
|
||||
| Audience questions sourced | 3 | 5-10 |
|
||||
| Misconceptions identified | 1 | 2-3 |
|
||||
| Angle candidates | 3 | 4-5 |
|
||||
| Total sources cited | 5 | 10-15 |
|
||||
| Searches executed | 10 | 15-21 |
|
||||
|
||||
**If you can't find data points:** The topic may be too niche or too new. That's useful information — record it in `research_summary` and note that the angle should lean narrative/analogy rather than data-driven.
|
||||
|
||||
**If you can't find existing content:** That's a strong signal — a content gap IS the opportunity. Note this prominently.
|
||||
|
||||
## Execution Constraints
|
||||
|
||||
| Constraint | Value | Why |
|
||||
|------------|-------|-----|
|
||||
| Max time on research | 3-5 minutes | Research is valuable but has diminishing returns |
|
||||
| Max searches | 25 | Prevent infinite rabbit holes |
|
||||
| Min searches | 10 | Ensure adequate coverage |
|
||||
| No paid tools | — | Research uses web search only — zero cost |
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Skipping to angles without research**: The angles_discovered must be grounded in findings from the other sections. If you can't point to specific data_points or audience_insights that support an angle, the angle is just a guess.
|
||||
- **Recording vague data**: "Most companies use AI" is not a data point. "87% of Fortune 500 companies have active AI projects (McKinsey 2025)" is a data point.
|
||||
- **Only searching one way**: If `[topic] statistics` returns nothing, try `[topic] survey`, `[topic] report`, `[topic] data`, `[topic] benchmark`. Vary your query terms.
|
||||
- **Ignoring negative results**: If searches for trending content return nothing recent, that IS a finding — it means this topic is evergreen, not trending. Record it.
|
||||
- **Treating all sources equally**: A peer-reviewed study and a random blog post are not equal. Label credibility honestly.
|
||||
- **Stopping at surface-level**: The first page of Google results is what everyone sees. Dig into specific discussions, specific studies, specific data. The value is in specificity.
|
||||
|
||||
## Example: Good vs Bad Research
|
||||
|
||||
### Topic: "How DNS Works"
|
||||
|
||||
**Bad research output:**
|
||||
- "DNS is important for the internet"
|
||||
- "There are many DNS providers"
|
||||
- Angles: "DNS Explained", "How DNS Works", "Understanding DNS"
|
||||
|
||||
**Good research output:**
|
||||
- Landscape: "Fireship's 'DNS in 100 seconds' has 2.1M views and covers basics but skips DNSSEC entirely. Cloudflare's blog series is comprehensive but text-only. Gap: no visual explainer covers DNS-over-HTTPS controversy."
|
||||
- Data point: "1.1.1.1 handles 13.5% of all DNS queries globally (Cloudflare Radar 2025, primary source). Surprise factor: counterintuitive — most people think Google's 8.8.8.8 is #1."
|
||||
- Audience: "Top Reddit question: 'Why does DNS take so long sometimes?' (r/networking, 847 upvotes). Misconception: people think DNS is a single lookup, not a recursive chain."
|
||||
- Trending: "Cloudflare just launched DNS-over-QUIC support (March 2026). DoH vs DoT debate is active on HN."
|
||||
- Angles: "The 200ms Journey Your Browser Takes Before Loading Anything" (data_driven, grounded in recursive resolution timing data), "Why Your ISP Knows Every Website You Visit — And How to Stop It" (contrarian, grounded in DNS privacy research + DoH trending signal), "DNS is a 40-Year-Old Phone Book Running the Modern Internet" (narrative/analogy, grounded in audience knowledge gap about DNS age + simplicity)
|
||||
@@ -0,0 +1,183 @@
|
||||
# Scene Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Scene Planner for a generated explainer video. You have a `script` artifact with timestamped sections and enhancement cues. Your job is to transform the script into a visual plan: what the viewer sees at every moment, what assets need to be created, and how scenes transition.
|
||||
|
||||
This is where words become visuals. A great script with a bad scene plan produces a confusing video.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/scene_plan.schema.json` | Artifact validation |
|
||||
| Prior artifacts | `state.artifacts["script"]["script"]`, `state.artifacts["idea"]["brief"]` | Script sections and creative brief |
|
||||
| Playbook | Active style playbook | Visual language, transitions, motion rules |
|
||||
| Layer 3 | `.agents/skills/flux-best-practices/`, `.agents/skills/beautiful-mermaid/`, `.agents/skills/manim-composer/` | Image gen, diagram, animation knowledge |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Analyze the Script
|
||||
|
||||
Read every section. For each, note:
|
||||
- What concept is being explained?
|
||||
- What enhancement cues did the script writer embed?
|
||||
- What's the emotional beat? (curiosity, revelation, emphasis, humor, conclusion)
|
||||
- How much time is available? (end_seconds - start_seconds)
|
||||
|
||||
### Step 2: Research Visual Approaches
|
||||
|
||||
**Use web search** to find visual techniques for this topic:
|
||||
|
||||
1. **How do top creators visualize this?** Search YouTube thumbnails, blog diagrams, conference slides for the topic.
|
||||
2. **What visual metaphors work?** Some concepts have well-known visual representations (e.g., neural networks as node graphs, encryption as locks/keys). Use these — viewers recognize them instantly.
|
||||
3. **What's novel?** Is there a visual approach nobody has tried? A fresh visualization can make an explainer memorable.
|
||||
4. **What's feasible?** Match your ambitions to available tools: `image_selector` (static images), `diagram_gen` (Mermaid flowcharts/sequences), `code_snippet` (syntax-highlighted code), Remotion (motion graphics, text animations), Manim (mathematical animations).
|
||||
|
||||
If you encounter a visualization need that no existing skill covers, use the **Skill Creator** (`skills/meta/skill-creator.md`) to create a new skill.
|
||||
|
||||
### Step 3: Decompose into Scenes
|
||||
|
||||
Transform each script section into 1-3 visual scenes. Each scene is a distinct visual moment.
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "scene-3",
|
||||
"type": "diagram",
|
||||
"description": "Mermaid flowchart showing query → encode → vector search → rank → return results. Nodes appear one by one as narrator describes each step.",
|
||||
"start_seconds": 15,
|
||||
"end_seconds": 22,
|
||||
"script_section_id": "s3",
|
||||
"framing": "full-screen diagram, centered",
|
||||
"movement": "progressive reveal left-to-right",
|
||||
"transition_in": "fade",
|
||||
"transition_out": "dissolve",
|
||||
"overlay_notes": "Label each node as it appears",
|
||||
"required_assets": [
|
||||
{
|
||||
"type": "diagram",
|
||||
"description": "Mermaid flowchart: query → encode embedding → vector search (ANN) → rank by cosine similarity → return top-k results",
|
||||
"source": "generate"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Scene Types and When to Use Them
|
||||
|
||||
| Type | Best For | Available Tools | Duration Guidance |
|
||||
|------|----------|-----------------|-------------------|
|
||||
| `animation` | Concepts needing motion (data flow, transformations, math) | Remotion, Manim | 4-10s |
|
||||
| `diagram` | Processes, architecture, relationships | `diagram_gen` (Mermaid), `image_selector` (stylized) | 4-8s |
|
||||
| `text_card` | Key terms, definitions, statistics, quotes | Remotion TextCard component | 3-5s |
|
||||
| `generated` | Illustrations, metaphors, real-world imagery | `image_selector` (FLUX/DALL-E) | 3-6s |
|
||||
| `talking_head` | AI avatar speaking (if HeyGen available) | HeyGen tools | 5-15s |
|
||||
| `broll` | Context, real-world examples | Stock or generated footage | 3-6s |
|
||||
| `transition` | Dedicated transition moment between topics | Remotion transition | 1-2s |
|
||||
| `screen_recording` | Code demos, UI walkthroughs | Recorded or simulated | 5-15s |
|
||||
|
||||
### Step 4: Apply the Visual Technique Library
|
||||
|
||||
These are proven patterns for explainer visuals. Reference them by name in scene descriptions:
|
||||
|
||||
**Diagram Reveal**
|
||||
Build a diagram progressively — start empty, add components with labels as the narrator describes each part. Perfect for architecture, processes, and systems.
|
||||
- Tools: Mermaid + Remotion animation or FLUX-generated diagram
|
||||
- Example: "Show the vector database architecture. Add the encoder node when narrator says 'embeddings'. Add the index when narrator says 'search'."
|
||||
|
||||
**Analogy Visualization**
|
||||
Show the abstract concept alongside its real-world analogy. Split screen or side-by-side.
|
||||
- Tools: `image_selector` for both sides
|
||||
- Example: "Left: actual vector space with dots. Right: a library with books sorted by topic."
|
||||
|
||||
**Stat Card Punch**
|
||||
Full-screen number or comparison. Appears with impact animation (scale up, slight bounce). Hold for 2-3 seconds.
|
||||
- Tools: Remotion TextCard component
|
||||
- Example: "1ms" in large text, then smaller text below: "vs 500ms with traditional search"
|
||||
|
||||
**Before/After Split**
|
||||
Show the problem, then the solution. Can be sequential (problem → transition → solution) or split-screen.
|
||||
- Tools: `image_selector` for both states
|
||||
- Example: "Before: SQL query scanning millions of rows (slow). After: vector search finding nearest neighbors (fast)."
|
||||
|
||||
**Timeline Progression**
|
||||
Left-to-right or top-to-bottom sequence showing evolution or process steps. Each step appears as narrator describes it.
|
||||
- Tools: Remotion with animated elements or Mermaid timeline
|
||||
- Example: "1990: keyword search → 2010: semantic search → 2020: vector databases → 2024: multimodal search"
|
||||
|
||||
**Zoom and Focus**
|
||||
Start with a wide view of a system, then zoom into a specific component to explain it in detail. Creates spatial context.
|
||||
- Tools: Remotion with scale animation on a generated image
|
||||
- Example: "Show full system architecture. Zoom into the 'embedding model' component."
|
||||
|
||||
**Code Walkthrough**
|
||||
Show code with syntax highlighting. Highlight specific lines as the narrator explains them. Can animate typing or progressive reveal.
|
||||
- Tools: `code_snippet` tool + Remotion
|
||||
- Example: "Python code: `results = collection.query(embedding, n_results=5)`. Highlight `embedding` parameter when narrator says 'vector'."
|
||||
|
||||
### Step 5: Validate Against Playbook
|
||||
|
||||
The style playbook constrains your visual choices:
|
||||
|
||||
| Playbook Field | Scene Impact |
|
||||
|----------------|-------------|
|
||||
| `visual_language.color_palette` | All generated images and diagrams must use these colors |
|
||||
| `visual_language.composition` | Framing rules (rule-of-thirds, centered, etc.) |
|
||||
| `motion.transitions` | Allowed transition types (e.g., `gentle-fade`, `soft-dissolve`) |
|
||||
| `motion.animation_style` | Animation feel (e.g., `ease-in-out, organic curves`) |
|
||||
| `motion.pacing_rules` | Minimum hold times (e.g., "hold establishing shots for 2s minimum") |
|
||||
| `asset_generation.image_prompt_prefix` | Prepend to all image generation prompts |
|
||||
| `asset_generation.consistency_anchors` | What must stay consistent across all images (color palette, lighting, style) |
|
||||
|
||||
**Checklist before submitting:**
|
||||
- [ ] Every scene uses playbook-compatible transitions
|
||||
- [ ] All required_asset descriptions include style cues from the playbook
|
||||
- [ ] No scene violates pacing rules (min/max duration)
|
||||
- [ ] Image descriptions reference playbook's color palette and texture
|
||||
|
||||
### Step 6: Verify Coverage and Variety
|
||||
|
||||
**Coverage check:**
|
||||
- [ ] Scenes span the full script duration (first scene starts at 0s, last scene ends at total_duration)
|
||||
- [ ] Every script section has at least one corresponding scene
|
||||
- [ ] No gaps > 1s between scenes (unless intentional beat)
|
||||
- [ ] All enhancement cues from the script are addressed by a scene or required_asset
|
||||
|
||||
**Variety check:**
|
||||
- [ ] No more than 3 consecutive scenes of the same type
|
||||
- [ ] At least 3 different scene types used in the video
|
||||
- [ ] Visual pacing alternates between high-information scenes (diagrams, animations) and breathing room (text cards, generated images)
|
||||
|
||||
**Feasibility check:**
|
||||
- [ ] Every `required_asset` with `source: "generate"` is achievable with available tools
|
||||
- [ ] Diagram descriptions are specific enough for Mermaid syntax generation
|
||||
- [ ] Image descriptions are specific enough for FLUX/DALL-E prompt engineering
|
||||
- [ ] No scene requires tools that aren't in the tool registry
|
||||
|
||||
### Step 7: Self-Evaluate
|
||||
|
||||
Score (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Visual storytelling** | Does each scene advance understanding, not just decorate? |
|
||||
| **Script alignment** | Does every scene match what the narrator is saying at that moment? |
|
||||
| **Technique variety** | Did you use multiple visual techniques, not just one? |
|
||||
| **Playbook fidelity** | Would every scene look like it belongs to the same video? |
|
||||
| **Asset feasibility** | Can every required_asset actually be generated with available tools? |
|
||||
| **Pacing** | Does the visual rhythm feel natural? High-info scenes balanced with breathing room? |
|
||||
|
||||
If any dimension scores below 3, revise.
|
||||
|
||||
### Step 8: Submit
|
||||
|
||||
Call `handle_explainer_scene_plan(state, {"scene_plan": scene_plan_json})` to validate and persist.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **One scene per section**: Script sections often cover multiple concepts. A 10-second section might need 2-3 visual scenes to avoid boring stasis.
|
||||
- **Ignoring enhancement cues**: The script writer embedded visual hints in `enhancement_cues`. Don't ignore them — they represent the writer's visual intent.
|
||||
- **Overly ambitious animations**: "Photorealistic 3D fly-through of a data center" can't be generated with current tools. Keep it achievable.
|
||||
- **No transition strategy**: Random transitions feel chaotic. Use the playbook's transition rules consistently. Reserve special transitions for topic shifts.
|
||||
- **Vague required_assets**: "An image about databases" is useless for prompt engineering. "Isometric illustration of a vector database with embedding vectors floating in 3D space, using the playbook's blue-green palette" is actionable.
|
||||
- **Static scenes for dynamic concepts**: If the narrator describes a process or transformation, the visual should move. Use animation or progressive reveal, not a static image.
|
||||
@@ -0,0 +1,223 @@
|
||||
# Script Director — Explainer Pipeline
|
||||
|
||||
## When to Use
|
||||
|
||||
You are the Script Writer for a generated explainer video. You have a `brief` artifact from the Idea Explorer. Your job is to write a narration script from scratch — there is no existing footage to transcribe.
|
||||
|
||||
The script is the backbone of the video. Every visual, every scene, every audio cue flows from what you write here. A mediocre script cannot be saved by great visuals.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
| Layer | Resource | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Schema | `schemas/artifacts/script.schema.json` | Artifact validation |
|
||||
| Prior artifact | `proposal_packet` | Selected concept with title, hook, key_points, core_message, tone, narrative_structure, duration |
|
||||
| Prior artifact | `research_brief` (optional but high-value) | Data points, audience insights, expert quotes — ground the script in real facts |
|
||||
| Playbook | Active style playbook from `proposal_packet.selected_concept.suggested_playbook` | Voice style, pacing rules |
|
||||
| Layer 3 | TTS provider skills (check `agent_skills` on the selected TTS tool) | TTS capabilities for speaker directions |
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Absorb the Proposal and Research
|
||||
|
||||
Read the `proposal_packet.selected_concept` carefully. Extract:
|
||||
- **Target duration** — this is your word budget (see timing table below)
|
||||
- **Hook** — your opening must deliver on this promise
|
||||
- **Key points** — these must all be covered in the script
|
||||
- **Core message** — the one thing the viewer should remember
|
||||
- **Tone** — shapes word choice, sentence length, formality
|
||||
- **Target audience** — shapes complexity and assumed knowledge
|
||||
- **Narrative structure** — the structural approach (myth_busting, journey, data_narrative, etc.)
|
||||
|
||||
Then read the `research_brief` for grounding material:
|
||||
- **`data_points`** — specific statistics and facts to weave into the script. Use claims with `surprise_factor: "surprising"` or `"counterintuitive"` as retention anchors.
|
||||
- **`audience_insights.misconceptions`** — if the narrative structure is `myth_busting`, these are your myth/reality pairs.
|
||||
- **`audience_insights.common_questions`** — address these directly in the script where they naturally fit.
|
||||
- **`expert_voices`** — quotable experts add authority. Use sparingly — one or two per script.
|
||||
- **`trending.recent_developments`** — if timely, reference them to make the content feel current.
|
||||
|
||||
**The research_brief is your cheat sheet.** Every fact, every surprising stat, every misconception is pre-verified and sourced. Use them. A script that cites "73% of developers..." (from research) is more compelling than one that says "many developers..."
|
||||
|
||||
### Step 2: Deepen Research Where Needed
|
||||
|
||||
The Research Director has already done the heavy lifting — you have a `research_brief` full of sourced facts. Your job here is targeted:
|
||||
|
||||
1. **Verify and update**: If any data point from the research_brief feels stale or uncertain, re-search to confirm.
|
||||
2. **Fill script-specific gaps**: The research gives you broad facts. You may need a specific analogy, a precise technical detail, or a better example for a particular section.
|
||||
3. **Find the best explanation**: How do the best educators (3Blue1Brown, Kurzgesagt, Fireship, Veritasium) explain this concept? What analogies work?
|
||||
4. **Source quotable moments**: If the research_brief's expert_voices section has useful quotes, use them. If not, search for one strong quote to anchor a key section.
|
||||
|
||||
**Do NOT duplicate the Research Director's work.** If the research_brief already has 6 data points, you don't need to find 6 more. Focus on script-level needs: the right word, the right analogy, the right sequence.
|
||||
|
||||
### Step 3: Plan the Narrative Arc
|
||||
|
||||
Before writing prose, plan the structure. Every explainer script follows a dramatic arc:
|
||||
|
||||
```
|
||||
HOOK (0-5s) → Grab attention. Question, bold claim, or surprising fact.
|
||||
NEVER: "In this video, we'll learn about..."
|
||||
NEVER: "Hey guys, welcome back..."
|
||||
|
||||
SETUP (5-15s) → Why should the viewer care? Create a knowledge gap.
|
||||
Show the problem or the question. Make them NEED the answer.
|
||||
|
||||
BUILD (15-Xs) → Progressive revelation. Each section builds on the last.
|
||||
Use "therefore / but" transitions, NOT "and then."
|
||||
South Park rule: "This happened, THEREFORE that happened,
|
||||
BUT then this complication arose..."
|
||||
|
||||
CLIMAX (X-5s before end) → The "aha" moment. Everything clicks into place.
|
||||
This is the payoff for the setup's knowledge gap.
|
||||
|
||||
LANDING (last 5s) → Quick recap of core message + CTA.
|
||||
Don't introduce new information here.
|
||||
```
|
||||
|
||||
Map each of the brief's `key_points` to a specific section in the BUILD phase.
|
||||
|
||||
### Step 4: Write the Script
|
||||
|
||||
Write each section with these fields:
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "s1",
|
||||
"label": "Hook",
|
||||
"text": "Your database searches every single row. Every. Single. One. What if it didn't have to?",
|
||||
"start_seconds": 0,
|
||||
"end_seconds": 5,
|
||||
"speaker_directions": "Emphasize 'every single row' with measured pacing. Brief pause before the question.",
|
||||
"enhancement_cues": [
|
||||
{
|
||||
"type": "animation",
|
||||
"description": "Database table with rows highlighted one by one, slowing down as count increases",
|
||||
"timestamp_seconds": 1
|
||||
}
|
||||
],
|
||||
"pronunciation_guides": []
|
||||
}
|
||||
```
|
||||
|
||||
#### Timing Estimation
|
||||
|
||||
| Pace | Words/minute | Use when |
|
||||
|------|-------------|----------|
|
||||
| Conversational | ~150 wpm | Default for most explainers |
|
||||
| Contemplative | ~120 wpm | Complex topics, need processing time |
|
||||
| Energetic | ~180 wpm | Short-form, high-energy, TikTok/Reels |
|
||||
| Technical | ~130 wpm | Code walkthroughs, architecture deep-dives |
|
||||
|
||||
**Word budget by duration:**
|
||||
- 30s video → ~65-75 words
|
||||
- 60s video → ~130-150 words
|
||||
- 90s video → ~195-225 words
|
||||
- 120s video → ~260-300 words
|
||||
|
||||
Count your words. If you're 20%+ over budget, the TTS will either rush or exceed duration. Cut ruthlessly.
|
||||
|
||||
#### Speaker Directions
|
||||
|
||||
Write directions that TTS can actually implement. Reference ElevenLabs capabilities:
|
||||
|
||||
| Direction | TTS Implementation |
|
||||
|-----------|-------------------|
|
||||
| "Speak slowly, with emphasis" | Lower speed setting, stability boost |
|
||||
| "Excited, picking up pace" | Higher speed, higher style setting |
|
||||
| "Pause for 1 second" | SSML `<break time="1s"/>` |
|
||||
| "Whisper" | SSML whisper tag (model-dependent) |
|
||||
| "Emphasize THIS word" | Note for post-processing or SSML emphasis |
|
||||
|
||||
Avoid directions TTS can't do: "smile while speaking", "gesture toward screen", "look at camera."
|
||||
|
||||
#### Enhancement Cues
|
||||
|
||||
Every section should have at least one enhancement cue. These tell the Scene Planner and Asset Generator what visuals to create.
|
||||
|
||||
| Cue Type | When to Use | Example |
|
||||
|----------|-------------|---------|
|
||||
| `overlay` | Key term, definition, label | "Show 'embedding' definition overlay" |
|
||||
| `diagram` | Process, architecture, flow | "Mermaid flowchart: query → encode → search → rank" |
|
||||
| `stat_card` | Surprising number or comparison | "Display: 1ms vs 500ms search time" |
|
||||
| `animation` | Concept that needs motion to understand | "Animate vectors moving through high-dimensional space" |
|
||||
| `code_snippet` | Code example | "Show Python: `results = collection.query(embedding)`" |
|
||||
| `broll` | Real-world context | "Show examples of apps using vector search" |
|
||||
|
||||
**Density rule**: At least one enhancement cue every 8-10 seconds. A 60-second video should have 6-8 cues minimum. Viewers disengage if the visual doesn't change.
|
||||
|
||||
#### Pronunciation Guides
|
||||
|
||||
For technical terms, acronyms, and non-English words:
|
||||
|
||||
```json
|
||||
{"word": "FAISS", "phonetic": "FACE"},
|
||||
{"word": "Qdrant", "phonetic": "kuh-DRANT"},
|
||||
{"word": "cosine", "phonetic": "CO-sign"}
|
||||
```
|
||||
|
||||
### Step 5: Validate Against Playbook
|
||||
|
||||
Read the active style playbook and verify:
|
||||
|
||||
| Playbook Field | Script Impact |
|
||||
|----------------|---------------|
|
||||
| `identity.pace` | Match word density. `contemplative` = fewer words, longer pauses |
|
||||
| `audio.voice_style` | Shape tone of speaker directions |
|
||||
| `motion.pacing_rules` | E.g., "hold establishing shots for 2s minimum" affects section timing |
|
||||
| `identity.mood` | Word choice: `warm` uses casual language; `professional` uses precise language |
|
||||
|
||||
### Step 6: Self-Evaluate
|
||||
|
||||
Score your script (1-5):
|
||||
|
||||
| Criterion | Question |
|
||||
|-----------|----------|
|
||||
| **Hook power** | Would someone stop scrolling in the first 3 seconds? |
|
||||
| **Word count accuracy** | Within ±10% of target for the duration? |
|
||||
| **Narrative flow** | Does each section build on the last? "Therefore/but" not "and then"? |
|
||||
| **Enhancement density** | At least one cue every 8-10 seconds? |
|
||||
| **Jargon management** | Technical terms explained or have pronunciation guides? |
|
||||
| **Climax payoff** | Does the aha moment deliver on the hook's promise? |
|
||||
| **CTA relevance** | Is the call to action specific and actionable? |
|
||||
|
||||
If any dimension scores below 3, revise before submitting.
|
||||
|
||||
### Step 7: Submit
|
||||
|
||||
Call `handle_explainer_script(state, {"script": script_json})` to validate and persist.
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- **Writing too many words**: The #1 failure. TTS pacing is fixed. If you write 250 words for a 60-second video, either the audio will be rushed or the video will be 100 seconds. Count your words.
|
||||
- **Front-loading information**: The hook should create curiosity, not dump information. "HTTPS uses TLS 1.3 with AEAD ciphers" is a terrible opening. "The padlock icon doesn't mean what you think it means" is compelling.
|
||||
- **Missing enhancement cues**: A script without visual direction is a podcast script. Every section needs at least one cue telling the visual team what to show.
|
||||
- **Generic speaker directions**: "Read naturally" is useless. "Start measured and precise, then accelerate through the list to convey scale" is actionable.
|
||||
- **Forgetting the audience**: A script for CTOs should use different words than one for high schoolers, even if covering the same concept.
|
||||
- **No transitions between sections**: Each section should have a logical bridge to the next. The viewer should never think "wait, why are we talking about this now?"
|
||||
|
||||
## Example: Well-Written Section
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "s3",
|
||||
"label": "The Core Idea",
|
||||
"text": "Instead of matching keywords, vector databases convert everything — text, images, audio — into lists of numbers called embeddings. Similar things get similar numbers. So finding related content becomes a math problem: which numbers are closest?",
|
||||
"start_seconds": 15,
|
||||
"end_seconds": 28,
|
||||
"speaker_directions": "Measured pace through 'text, images, audio' with slight pause between each. Speed up slightly on 'similar things get similar numbers' — it should feel like a revelation. Brief pause before the final question.",
|
||||
"enhancement_cues": [
|
||||
{
|
||||
"type": "animation",
|
||||
"description": "Show text/image/audio icons transforming into number arrays (embeddings). Arrays cluster by similarity in a 2D space.",
|
||||
"timestamp_seconds": 16
|
||||
},
|
||||
{
|
||||
"type": "stat_card",
|
||||
"description": "Display: 'Everything becomes numbers. Similar things → similar numbers.'",
|
||||
"timestamp_seconds": 22
|
||||
}
|
||||
],
|
||||
"pronunciation_guides": [
|
||||
{"word": "embeddings", "phonetic": "em-BED-ings"}
|
||||
]
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user