reels-playbook

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 .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:

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:

# 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