---
name: reels-playbook
description: Extract video (Reels/TikTok/Shorts/any MP4), analyze frame-by-frame, generate production playbook, then reconstruct in Remotion via video-director skill. Use when asked to deconstruct, clone, or recreate a video programmatically.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Task
---

# Reels Playbook → Remotion Reconstruction

Extract any short-form video, analyze frame-by-frame, generate a production playbook, then feed into `video-director` to reconstruct in Remotion.

## Pipeline

```
Video source → Download → Frames (2fps) → Audio → Transcribe → Vision analysis → PLAYBOOK.md → video-director → Remotion code → .mp4
```

## When to Use

- User has a video URL (Instagram, TikTok, YouTube Shorts, any)
- User has a local video file (.mp4, .mov, .webm)
- User wants to "clone", "recreate", "rebuild" a video in code
- User wants to understand how a video was made (decupagem)
- User provides a reference video for a new project

## Input Types

### 1. URL (Instagram/TikTok/Shorts)
```bash
bash .claude/skills/reels-playbook/scripts/extract-reels.sh \
  "https://www.instagram.com/reel/ABC123/" \
  "playbooks/topic_name" \
  2  # fps
```

### 2. Local Video File
Skip download, extract directly:
```bash
OUTPUT_DIR="playbooks/my_video"
mkdir -p "$OUTPUT_DIR/frames"
cp /path/to/video.mp4 "$OUTPUT_DIR/video.mp4"

# Extract frames
ffmpeg -i "$OUTPUT_DIR/video.mp4" -vf "fps=2" "$OUTPUT_DIR/frames/frame_%03d.jpg" -y

# Extract audio
ffmpeg -i "$OUTPUT_DIR/video.mp4" -vn -acodec pcm_s16le -ar 16000 -ac 1 "$OUTPUT_DIR/audio.wav" -y
```

## Output Location

All outputs: `playbooks/{slug}/`

```
playbooks/{slug}/
├── video.mp4          # Original video
├── audio.wav          # Extracted audio (16kHz mono)
├── transcript.txt     # Timestamped transcript
├── metadata.json      # Source metadata (if from URL)
├── frames/            # High-density frames (2fps)
│   ├── frame_001.jpg
│   ├── frame_002.jpg
│   └── ...
└── PLAYBOOK.md        # Production playbook
```

## Analysis Workflow

### Step 1: Extract
Run script or manual extraction (see Input Types above).

### Step 2: Read Context
```
- metadata.json → engagement, author, caption
- transcript.txt → what is said, timestamps
- ffprobe video.mp4 → duration, resolution, fps
```

### Step 3: Analyze Frames (CRITICAL)

Read EVERY frame image. At 2fps, each frame = 0.5s.

For each scene/segment, identify:

**Shot Composition:**
- Wide / Medium / Close-up / POV
- Camera angle, static vs motion
- Framing, rule of thirds

**Visual Elements:**
- Background (color, gradient, image, video)
- Text overlays (content, font, position, animation, color)
- UI elements (cards, buttons, mockups, frames-within-frames)
- People/subjects, props

**Motion & Transitions:**
- Cut type (hard, jump, match, morph)
- Effects (zoom, pan, swipe, fade, wipe)
- Timing relative to audio/beat
- Pacing (cuts per minute)

**Production:**
- Color grading (warm/cold/natural/saturated)
- Split screen, picture-in-picture
- Overlay effects (grain, blur, glow)

### Step 4: Generate PLAYBOOK.md

Structure:

```markdown
# PLAYBOOK: [Topic/Creator]

> Decupagem de [duration]s — [source]

**Source:** [URL or file]
**Duration:** [X]s | **Resolution:** [WxH] | **FPS:** [N]

---

## METRICAS DE EDICAO

| Metrica | Valor |
|---------|-------|
| Duracao total | Xs |
| Total de cenas | X |
| Cortes por minuto | X |
| Duracao media de cena | X.Xs |

---

## ESTRUTURA GERAL

| Secao | Tempo | Duracao | Proposito |
|-------|-------|---------|-----------|
| Hook | 0:00-0:03 | 3s | Capturar atencao |
| ... | ... | ... | ... |

---

## DECUPAGEM FRAME-A-FRAME

### HOOK (0:00 - 0:03)

| Elemento | Detalhe |
|----------|---------|
| Shot | Close-up |
| Fundo | #0a0a0a gradiente |
| Texto | "Title" — Inter Bold 72px, centro |
| Animacao | Spring scale-in, 0.5s |
| Audio | Riser → Impact no reveal |
| Transicao → | Fade 0.5s |

### CENA N: [Nome] (0:XX - 0:XX)
...

---

## ELEMENTOS DE PRODUCAO

### Tipografia
| Fonte | Uso | Peso |
|-------|-----|------|
| Inter | Titulos | 800 |
| Inter | Corpo | 400 |

### Paleta
- Dominante: #XXXXXX
- Acentos: #XXXXXX
- Background: #XXXXXX

### Audio
| Elemento | Detalhes |
|----------|----------|
| Musica | [estilo/BPM] |
| SFX | [categorias: ambient, riser, impact, whoosh, tick, typing] |

---

## FORMULA REPLICAVEL

```
0:00-0:03 → HOOK: [pattern]
0:03-0:08 → SETUP: [pattern]
...
```

---

## REMOTION RECONSTRUCTION NOTES

Decisoes ja tomadas pela analise (pra alimentar video-director):

- **Tipo:** [title card / promo / explainer / social clip]
- **Duracao:** [X]s
- **Formato:** [WxH] @ [fps]fps
- **Fontes:** heading=[Font Weight], body=[Font Weight]
- **Fundo por cena:** [lista]
- **Animacoes:** [tipos identificados]
- **Audio:** [categorias necessarias]
- **Transicoes:** [tipos identificados]

Estas decisoes pulam o Discovery do video-director — ir direto pro Storyboard.
```

### Step 5: Reconstruct with video-director

After PLAYBOOK.md aprovado:

1. Invocar skill `video-director`
2. Pular Fase 1 (Discovery) — brief ja extraido do PLAYBOOK
3. Ir direto pra Fase 2 (Storyboard) usando a decupagem como base
4. Seguir fluxo normal: Scene Builder → Sound Design → Polish → Render

**A secao "REMOTION RECONSTRUCTION NOTES" do playbook vira o brief do video-director.**

## Frame Timestamp Reference (2fps)

```
frame_001.jpg = 0.0s
frame_002.jpg = 0.5s
frame_003.jpg = 1.0s
frame_010.jpg = 4.5s
frame_060.jpg = 29.5s

Formula: timestamp = (frame_number - 1) / fps
```

## FPS Guide

| Conteudo | FPS recomendado | Motivo |
|----------|-----------------|--------|
| Talking head, tutorial | 1 | Pouca mudanca visual |
| Reels/TikTok padrao | 2 | Bom balanco |
| Fast edits, gaming, memes | 3 | Muitos cortes curtos |
| Transicoes complexas | 4+ | Precisa mais granularidade |

## Quality Checklist

Antes de finalizar PLAYBOOK.md:

- [ ] Identificou TODAS as mudancas de cena
- [ ] Analisou hook (primeiros 3s) em detalhe
- [ ] Contou cortes por minuto
- [ ] Documentou estilos de texto overlay
- [ ] Mapeou transicoes usadas
- [ ] Sincronizou edicao com audio/beat
- [ ] Criou formula replicavel
- [ ] Preencheu REMOTION RECONSTRUCTION NOTES
- [ ] Listou fontes e cores exatas

## Dependencies

- `ffmpeg` + `ffprobe` (frame/audio extraction)
- `yt-dlp` (video download from URLs)
- `HIKER_API_KEY` in .env (optional, for Instagram metadata)
- `GROQ_API_KEY` or `OPENAI_API_KEY` in .env (transcription)
- Vision model access (frame analysis)

## Related Skills

- **video-director** — receives PLAYBOOK output, runs 6-phase pipeline to Remotion code
- **remotion-video-toolkit** — Remotion coding patterns used by video-director