# Microdrama Script Framework

## Core Concept: Storyteller-Driven Satire

Every microdrama needs a **STORYTELLER** - a character who guides us through the absurd news story. The storyteller:
- Is the emotional anchor (reacts with awe, disbelief, fear, laughter)
- Appears in opening and closing scenes (bookends)
- Can appear in reaction shots throughout
- Takes the news SERIOUSLY (deadpan delivery makes absurdity funnier)

## Structure: 3-Act + Reactions

### Act 1: HOOK (Scene 1-2)
- **Scene 1 (hook)**: Storyteller discovers/presents the news
  - Breaking news energy, dramatic reveal
  - Caption: headline or key phrase
  - Sound: dramatic sting, paper rustle, notification

- **Scene 2 (setup)**: The situation explained
  - Key visual that sets up the absurdity
  - Caption: context (date, location, organization)

### Act 2: DEVELOPMENT (Scene 3-5)
- **Scene 3 (escalation)**: The absurdity builds
  - First major ridiculous detail
  - Storyteller reaction possible

- **Scene 4 (flashback/detail)**: Supporting "evidence"
  - Historical context, document, quote visualization
  - Can be stylized (sepia, black-and-white, dramatic)

- **Scene 5 (twist)**: Plot thickens or reverses
  - Unexpected development
  - Maximum absurdity

### Act 3: PUNCHLINE (Scene 6-7)
- **Scene 6 (climax)**: Peak absurdity moment
  - The most ridiculous visual/quote
  - Big reaction

- **Scene 7 (punchline)**: Storyteller's final reaction
  - Breaking character slightly (smirk, shrug, facepalm)
  - Caption: deadpan conclusion or "well then..."
  - Meme energy

## Storyteller Types

### 1. News Anchor
- Professional appearance (suit, desk, microphone)
- Modern setting with news graphics
- Reactions: raised eyebrow, pursed lips, stifled laugh
- Good for: political satire, official announcements

### 2. Historian/Academic
- Tweed jacket, glasses, archive setting
- Surrounded by books, documents
- Reactions: scholarly disbelief, head shaking, sighing
- Good for: historical satire, "discovered documents"

### 3. Conspiracy Theorist
- Disheveled, basement/board with strings
- Intense, wide-eyed
- Reactions: vindication, paranoid glances
- Good for: absurd theories presented as fact

### 4. Field Reporter
- Microphone, outdoor/location setting
- On-the-scene energy
- Reactions: bewilderment, looking around confused
- Good for: location-based stories

## Visual Effects & Captions

### Caption Styles
- **breaking_news**: Red bar, urgent font, top position
- **quote**: Quotation marks, attributed, center
- **impact**: Large bold text, center, dramatic
- **silent_film**: Sepia card, vintage font
- **meme**: Impact font, white with black outline
- **subtitle**: Bottom, clean, translated text

### Transition Effects
- **flash_white**: Between scenes for impact
- **zoom_burst**: For reveals
- **dissolve**: For flashbacks
- **fade_to_black**: Scene endings
- **cut**: Hard cuts for comedy timing

### Sound Design (Veo3 diegetic)
- Dramatic stings
- Paper/document sounds
- Gasps, sighs, reactions
- Impact sounds (whoosh, bang)
- NO music, NO speech

## Character Consistency Rules

1. **Storyteller** must have reference sheet used in ALL their scenes
2. **Historical/fictional characters** use generic descriptions (avoid prominent people filter)
3. **Objects** (documents, symbols) need consistency across scenes
4. Frame descriptions use character IDs from script, not real names

## Script JSON Format (v5)

```json
{
  "task_id": "YYYYMMDD_HHMMSS_slug",
  "source_url": "https://panorama.pub/...",
  "style": "satire_news",
  "aspect_ratio": "9:16",

  "storyteller": {
    "type": "news_anchor|historian|conspiracy|reporter",
    "id": "anchor",
    "sheet": "char_anchor.jpg",
    "description": "Professional news anchor, 40s, suit and tie, serious demeanor"
  },

  "characters": {
    "character_id": {
      "sheet": "char_xxx.jpg",
      "description": "Generic description without real names"
    }
  },

  "objects": {
    "object_id": {
      "sheet": "obj_xxx.jpg",
      "description": "Object description"
    }
  },

  "scenes": [
    {
      "scene_id": 1,
      "act": "hook",
      "type": "hook|setup|escalation|flashback|twist|climax|punchline",
      "duration_sec": 8,  // Always 8s from Veo3
      "caption": "TEXT",
      "caption_position": "top|center|bottom",
      "caption_style": "breaking_news|quote|impact|silent_film|meme|subtitle",
      "color_grade": "normal|sepia|high_contrast|desaturated",
      "characters": ["storyteller_id", "other_ids"],
      "objects": ["object_ids"],
      "frames": {
        "first": "Detailed description of starting state",
        "last": "Detailed description of ending state (dramatically different!)"
      },
      "sound_hints": "specific sounds for this scene"
    }
  ]
}
```

## Reference Image Search (Yandex)

Use `yandex_image_search.py` to find reference images for real people, objects, locations.

### Setup
```bash
# Required environment variables in .env:
YANDEX_FOLDER_ID=your_folder_id
YANDEX_API_KEY=your_api_key
```

### Usage
```bash
cd /home/videobot/dev/microdrama/scripts
source ../../venv/bin/activate

# Search and download images
python yandex_image_search.py "Александр Дугин портрет фото" \
  -o /path/to/output/search \
  -n 3 --size large --download -p dugin

# Options:
#   -o, --output     Output directory
#   -n, --count      Number of images (default: 5)
#   --size           enormous|large|medium|small|wallpaper
#   --orient         horizontal|vertical|square
#   --format         jpeg|gif|png
#   -d, --download   Download images
#   -p, --prefix     Filename prefix
```

### Search Queries Examples
```
# Real people
"Александр Дугин портрет фото"
"Владимир Путин пресс конференция"

# Cartoon characters
"Чебурашка мультфильм"
"Крокодил Гена"

# Objects/Settings
"старинный документ печать сургуч"
"пресс конференция официальный представитель"
"телеведущая новости диктор студия"
```

### Using Downloaded Images

Downloaded images become **base references** for:
1. **Ken Burns scenes**: Use directly with zoom/pan effect
2. **NanoBanana generation**: Use as reference for styled versions
3. **Character sheets**: Use as base for turnaround generation

## Scene Types: Veo3 vs Ken Burns

| Method | Use When | Duration | Audio |
|--------|----------|----------|-------|
| **veo3** | Need motion, expressions, reactions | 8s (fixed) | Generated by Veo3 |
| **kenburns** | Static subjects, news footage style | 3-8s (flexible) | Silent (add in post) |

### When to Use Ken Burns
- Real people photos (avoids Veo3 prominent people filter)
- Documents, maps, graphics
- Quick establishing shots
- News report "B-roll" footage

### When to Use Veo3
- Storyteller scenes (need expressions, gestures)
- Action scenes (movement between frames)
- Character interactions
- Scenes requiring sound effects

## Workflow

1. **Article Analysis**: Extract premise, characters, key quotes, absurd elements
2. **Storyteller Selection**: Choose type based on article tone
3. **Scene Breakdown**: Map to 7-scene structure
4. **Reference Search**: Use Yandex to find base images for real people/objects
5. **Character Sheets**: Generate storyteller sheet (for Veo3 scenes)
6. **Frame Generation**:
   - Veo3 scenes: Generate first/last frames with NanoBanana
   - Ken Burns scenes: Use Yandex images or generate single frame
7. **Video Generation**:
   - Veo3 for motion scenes
   - Ken Burns (FFmpeg) for static image scenes
8. **Assembly**: Fade transitions with audio
