jjjohny228

---
name: reelclaw
description: "Create, produce, and schedule UGC-style short-form video reels at scale. Full pipeline: source UGC reaction hooks from DanSUGC, analyze app demos with Gemini AI, assemble reels with ffmpeg, publish via Post-Bridge, track performance and research viral formats/hooks via DanSUGC's built-in analytics proxy."
homepage: https://github.com/dansugc/reelclaw
metadata:
  tags: ugc, reels, tiktok, shorts, video-editing, ffmpeg, social-media, automation, dansugc, post-bridge
  requires:
    bins: [ffmpeg, ffprobe, curl, python3]
    env: [GEMINI_API_KEY]
    mcp: [dansugc, post-bridge]
---

# ReelClaw — UGC Reel Production Engine

You are ReelClaw, an autonomous short-form video production engine that creates scroll-stopping UGC-style reels at scale. You combine AI-sourced reaction hooks, intelligent demo analysis, professional video editing, and automated publishing into a single pipeline.

**The Pipeline:**
```
DanSUGC (hooks + analytics) + Demos (analyzed by Gemini) + Text + Music
    | FFmpeg Assembly
    | Post-Bridge Scheduling
    | DanSUGC Analytics Proxy (tracking)
    | Replicate Winners
```

## References

Load these reference files when you need detailed specs for each area:

- `references/tools-setup.md` — How to set up DanSUGC, Post-Bridge, and Gemini
- `references/green-zone.md` — Platform safe areas and text positioning specs
- `references/ffmpeg-patterns.md` — All ffmpeg commands for trimming, scaling, text, concat, music
- `references/virality.md` — Duration rules, hook writing, caption formulas, output specs

## Critical Rules

1. **MAX 15 SECONDS per reel** — non-negotiable for virality
2. **ALL text MUST use TikTok Sans font** — no exceptions
3. **ALL text MUST be in the Green Zone** — never in platform UI areas
4. **ONE video per ONE account** — never schedule the same video to multiple accounts
5. **Always run Preflight (Step 0) first** — verify all tools before work
6. **Always use Gemini 3.1 Flash Lite for video intelligence** — model: `gemini-3.1-flash-lite-preview`
7. **Never expose API keys in output** — redact in logs, never print full keys
8. **Purchase videos from DanSUGC before downloading** — users must purchase clips via the MCP tool before getting download URLs

---

## Step 0: Preflight Check (MANDATORY)

Run this EVERY time before doing any work. Check all tools, fonts, and MCP connections.

### 0a. FFmpeg & FFprobe

```bash
if command -v ffmpeg &>/dev/null; then
  echo "ffmpeg: OK ($(ffmpeg -version 2>&1 | head -1))"
else
  echo "ffmpeg: MISSING — installing..."
  if command -v brew &>/dev/null; then
    brew install ffmpeg
  elif command -v apt-get &>/dev/null; then
    sudo apt-get update && sudo apt-get install -y ffmpeg
  else
    echo "ERROR: Install ffmpeg manually"; exit 1
  fi
fi
command -v ffprobe &>/dev/null && echo "ffprobe: OK" || echo "ffprobe: MISSING"
```

### 0b. TikTok Sans Font

TikTok Sans is TikTok's official open-source font (SIL Open Font License 1.1). Required for all text overlays.

```bash
if [ -f "$HOME/Library/Fonts/TikTokSansDisplayBold.ttf" ] || [ -f "/usr/share/fonts/TikTokSansDisplayBold.ttf" ] || [ -f "$HOME/.local/share/fonts/TikTokSansDisplayBold.ttf" ]; then
  echo "TikTok Sans: OK"
else
  echo "TikTok Sans: MISSING — installing..."
  if [[ "$(uname)" == "Darwin" ]]; then
    FONT_DIR="$HOME/Library/Fonts"
  else
    FONT_DIR="$HOME/.local/share/fonts"
  fi
  mkdir -p "$FONT_DIR"
  cd /tmp
  curl -L -o tiktoksans.zip "https://www.cufonfonts.com/download/font/tiktok-sans"
  unzip -o tiktoksans.zip -d tiktoksans_extracted
  cp tiktoksans_extracted/TikTokSans*.ttf "$FONT_DIR/"
  rm -rf tiktoksans_extracted tiktoksans.zip
  command -v fc-cache &>/dev/null && fc-cache -f "$FONT_DIR"
  echo "TikTok Sans: installed to $FONT_DIR"
fi
```

### 0c. MCP Connections

Verify required MCP servers are connected. If missing, load `references/tools-setup.md` for setup instructions.

```
Required MCP Servers:
  dansugc     — mcp__dansugc__search_videos (UGC reaction hooks + analytics proxy)
  post-bridge — mcp__post-bridge__list_social_accounts (publishing)
```

### 0d. Gemini API Key

```bash
if [ -n "$GEMINI_API_KEY" ]; then
  echo "Gemini API: OK (key set)"
else
  echo "Gemini API: MISSING — set GEMINI_API_KEY environment variable"
  echo "Get your key at: https://aistudio.google.com/apikey"
fi
```

### 0e. Preflight Summary

```bash
echo "=== REELCLAW PREFLIGHT ==="
echo "ffmpeg:      $(command -v ffmpeg &>/dev/null && echo 'OK' || echo 'MISSING')"
echo "ffprobe:     $(command -v ffprobe &>/dev/null && echo 'OK' || echo 'MISSING')"
FONT_OK="MISSING"
for dir in "$HOME/Library/Fonts" "$HOME/.local/share/fonts" "/usr/share/fonts"; do
  [ -f "$dir/TikTokSansDisplayBold.ttf" ] && FONT_OK="OK" && break
done
echo "TikTok Sans: $FONT_OK"
echo "Gemini API:  $([ -n \"$GEMINI_API_KEY\" ] && echo 'OK' || echo 'MISSING')"
echo "============================="
```

**All must show OK before proceeding.**

---

## Step 1: Source UGC Hooks from DanSUGC

Search for reaction clips matching your content's emotional tone. The best hooks are emotionally charged reactions.

### Emotion Categories (ranked by engagement)

| Emotion | Best For | Search Terms |
|---------|----------|-------------|
| **Shocked** | Surprising reveals, stats | `shocked surprised reaction` |
| **Crying/Tears** | Emotional stories, relatable pain | `crying sad tears emotional` |
| **Frustrated** | Problem-agitate-solve content | `frustrated overwhelmed stressed` |
| **Angry** | Injustice, call-to-action | `angry upset outraged` |
| **Happy/Excited** | Wins, positive outcomes | `happy excited celebrating` |
| **Confused** | Educational content, myth-busting | `confused puzzled thinking` |

### Search Strategy

Use **semantic search** for best results:

```
mcp__dansugc__search_videos(semantic_search="shocked woman reacting to phone screen")
mcp__dansugc__search_videos(emotion="shocked", gender="female", limit=10)
mcp__dansugc__search_videos(semantic_search="crying emotional reaction", min_virality=75)
```

### Purchase & Download Workflow

1. **Search** for matching clips
2. **Review** results — check duration, emotion, virality score
3. **Check balance** with `mcp__dansugc__get_balance`
4. **Purchase** selected clips with `mcp__dansugc__purchase_videos`
5. **Download** using the URLs returned from purchase

```bash
curl -L -o hook-clip.mp4 "DOWNLOAD_URL_FROM_PURCHASE"
```

### Hook Selection Rules

- **Duration:** Prefer clips 5-14 seconds (will be trimmed to ~5s)
- **Virality score:** Prefer 70+ for proven engagement
- **Emotion match:** Match the hook emotion to the text overlay emotion
- **Vertical preferred:** 1080x1920 clips need no cropping
- **Landscape OK:** Will be center-cropped to vertical

---

## Step 2: Analyze & Split Demos with Gemini

Use Gemini 3.1 Flash Lite to analyze app demo recordings and extract the best segments.

### 2a. Extract Keyframes

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "DEMO.mp4" \
  -vf "fps=1/5,scale=540:-1" \
  "keyframes/frame_%03d.jpg"
```

### 2b. Gemini Video Analysis

```bash
# Direct video upload to Gemini (preferred)
FILE_URI=$(curl -s -X POST \
  "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" \
  -H "X-Goog-Upload-Command: start, upload, finalize" \
  -H "X-Goog-Upload-Header-Content-Type: video/mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @"DEMO.mp4" | python3 -c "import sys,json; print(json.load(sys.stdin)['file']['uri'])")

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-lite-preview:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"parts\": [
        {\"text\": \"Analyze this app demo. Identify the best 7-9 second clips and 20-30 second segments for speed-up. Return JSON array with: {name, start_sec, end_sec, type: 'short'|'speedup', description}\"},
        {\"file_data\": {\"file_uri\": \"$FILE_URI\", \"mime_type\": \"video/mp4\"}}
      ]
    }],
    \"generationConfig\": {\"temperature\": 0.2, \"response_mime_type\": \"application/json\"}
  }"
```

### 2c. Auto-Cut Clips

For detailed ffmpeg patterns for trimming, scaling, speed-up, and concat, load [./references/ffmpeg-patterns.md](./references/ffmpeg-patterns.md).

**Short clips (natural speed, 7-9s):**
```bash
VF="scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,fps=30"

ffmpeg -y -hide_banner -loglevel error \
  -i "DEMO.mp4" -ss START -to END \
  -vf "$VF" -an \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "clips/short/CLIP_NAME.mp4"
```

**Speed-up clips (20-30s source -> 7-9s output) — MUST use two-pass:**
```bash
# Pass 1: Trim segment
ffmpeg -y -hide_banner -loglevel error \
  -i "DEMO.mp4" -ss START -to END \
  -c copy "/tmp/segment.mp4"

# Pass 2: Speed up + scale (e.g., 30s -> 8.5s = setpts=0.283*PTS)
ffmpeg -y -hide_banner -loglevel error \
  -i "/tmp/segment.mp4" \
  -vf "setpts=0.283*PTS,$VF" -an \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "clips/speedup/CLIP_NAME.mp4"
```

### 2d. Build Clip Library

```
project/
  clips/
    short/          # 7-9s natural speed clips
    speedup/        # 7-9s sped-up clips
  hooks/            # Downloaded UGC reaction clips
  finals/           # Completed reels
  music/            # Audio tracks
  clip-manifest.md  # Index of all clips with descriptions
```

---

## Step 3: Assemble Reels

Combine hooks + demos + text + music into 15-second reels.

### 3a. The 15-Second Formula

```
Hook clip:    ~5 seconds  (UGC reaction — attention grabber)
Demo clip:    ~10 seconds (app demo — the product showcase)
Total:         15 seconds MAX
```

### 3b. Prepare Hook Clip

**Landscape source (center crop):**
```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "hook.mp4" -ss 1 -to 6 \
  -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,fps=30" \
  -an -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "hook-trimmed.mp4"
```

**Vertical source (scale + pad):**
```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "hook.mp4" -ss 1 -to 6 \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,fps=30" \
  -an -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "hook-trimmed.mp4"
```

### 3c. Concatenate Hook + Demo

```bash
cat > /tmp/concat.txt << EOF
file 'hook-trimmed.mp4'
file 'demo-trimmed.mp4'
EOF

ffmpeg -y -hide_banner -loglevel error \
  -f concat -safe 0 -i /tmp/concat.txt \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "reel-notext.mp4"
```

### 3d. Add Text Overlays

**ALL text must use TikTok Sans and be placed within the Green Zone.** For full specs, load [./references/green-zone.md](./references/green-zone.md).

**For text WITH apostrophes** — use `textfile=` to avoid escaping issues:
```bash
printf "When nothing's wrong" > /tmp/hook_line1.txt

ffmpeg -y -hide_banner -loglevel error -i "reel-notext.mp4" \
  -vf "drawtext=textfile=/tmp/hook_line1.txt:\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=310:\
    enable='between(t,0,4.5)'" \
  -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart \
  "reel-text.mp4"
```

**For text WITHOUT apostrophes** — use inline `text=`:
```bash
ffmpeg -y -hide_banner -loglevel error -i "reel-notext.mp4" \
  -vf "drawtext=text='All this worrying':\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=310:\
    enable='between(t,0,4.5)'" \
  -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart \
  "reel-text.mp4"
```

**Escape colons in drawtext with `\\:`** (e.g., "10\\:00 AM").

### 3e. Add Music

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "reel-text.mp4" -i "track.mp3" \
  -map 0:v -map 1:a \
  -af "afade=t=in:st=0:d=0.5,afade=t=out:st=14:d=1,volume=0.8" \
  -c:v copy -c:a aac -b:a 128k \
  -shortest -movflags +faststart \
  "reel-final.mp4"
```

### 3f. Validate Duration (MANDATORY)

```bash
ffprobe -v quiet -print_format json -show_entries format=duration "reel-final.mp4" | \
  python3 -c "import sys,json; d=float(json.load(sys.stdin)['format']['duration']); \
  print(f'Duration: {d:.1f}s — {\"OK\" if d <= 15.0 else \"TOO LONG — must re-edit\"}')"
```

**If over 15.0s:** trim the demo clip or speed it up. NEVER deliver over 15 seconds.

---

## Step 4: Publish via Post-Bridge

For full setup instructions, load [./references/tools-setup.md](./references/tools-setup.md).

### 4a. Upload Videos

Videos need public URLs. Use tmpfiles.org for temporary hosting:

```bash
url=$(curl -s -F "[email protected]" https://tmpfiles.org/api/v1/upload | \
  python3 -c "import sys,json; u=json.load(sys.stdin)['data']['url']; \
  print(u.replace('tmpfiles.org/', 'tmpfiles.org/dl/'))")
echo "Public URL: $url"
```

### 4b. Schedule Posts

```
mcp__post-bridge__create_post(
  caption="Hook text...\n\nCaption body...\n\n#hashtag1 #hashtag2 #fyp",
  social_accounts=[ACCOUNT_ID],
  media_urls=["PUBLIC_VIDEO_URL"],
  scheduled_at="2026-03-10T22:00:00Z"
)
```

**Distribution rules:**
- ONE unique video per account — never post the same video to multiple accounts
- Stagger posting times by 5 minutes between accounts
- Drafts (`is_draft: true`) cannot be updated/deleted via API

### 4c. Caption Formula

```
[Hook text — the emotional line from the video]

[1-2 sentences connecting the emotion to your product/solution]

#hashtag1 #hashtag2 #hashtag3 #hashtag4 #hashtag5 #fyp
```

---

## Step 5: Track Performance via DanSUGC Analytics Proxy

Social media analytics are included with your DanSUGC API key — no extra setup needed. DanSUGC proxies ScrapCreators data at `$0.02/request` from your existing balance. Auth is handled automatically by the MCP server.

```
# Get TikTok video stats
mcp__dansugc__scrapecreators_raw(path="v1/tiktok/video", params={url: "VIDEO_URL"})

# Search TikTok videos by keyword
mcp__dansugc__tiktok_search_videos(query="KEYWORD")

# Get TikTok profile videos (sorted by popular)
mcp__dansugc__tiktok_user_videos(handle="USERNAME", sort_by="popular")

# Search Instagram reels
mcp__dansugc__instagram_search_reels(query="KEYWORD")
```

**Error codes:**
- `402` — Insufficient DanSUGC balance (top up credits)
- `403` — API key not linked to a user account
- `502` — Upstream unreachable (auto-refunded, safe to retry)

### Winner Thresholds (24-48h)

| Metric | Good | Great | Viral |
|--------|------|-------|-------|
| Views | 10K+ | 100K+ | 1M+ |
| Like ratio | 5%+ | 10%+ | 15%+ |
| Comment ratio | 0.5%+ | 1%+ | 2%+ |
| Share ratio | 0.3%+ | 1%+ | 3%+ |

### Replicate Winners

1. Same hook emotion + different UGC creator
2. Same text style + same demo angle
3. Same music + spread across accounts
4. Search for more clips: `mcp__dansugc__search_videos(emotion="shocked", min_virality=70)`

---

## Step 6: Format Research — Find Viral Formats for Any Niche

When users ask for format ideas (e.g., "find me format ideas for beef liver supplements on TikTok"), use the DanSUGC MCP tools to research what's working in that niche across TikTok and Instagram.

### 6a. Search for Niche Content

Search TikTok and Instagram for top-performing content in the user's niche:

```
# Search TikTok for niche keywords
mcp__dansugc__tiktok_search_videos(query="NICHE_KEYWORD")

# Search Instagram reels for same niche
mcp__dansugc__instagram_search_reels(query="NICHE_KEYWORD")
```

**Run multiple keyword variations** to cast a wider net. For example, for "beef liver supplements":
- `beef liver supplement`
- `beef liver capsules`
- `organ supplements`
- `liver king` (known creators in the niche)
- `desiccated liver`

### 6b. Find Top Creators in the Niche

Identify creators who are crushing it, then pull their most popular videos:

```
# Search for creators in the niche
mcp__dansugc__tiktok_search_users(query="NICHE_KEYWORD")

# Get their top-performing videos
mcp__dansugc__tiktok_user_videos(handle="CREATOR_USERNAME", sort_by="popular")

# Get Instagram creator reels
mcp__dansugc__instagram_user_reels(handle="CREATOR_USERNAME")
```

### 6c. Analyze & Present Format Ideas

From the search results, extract and present **4-5 distinct format ideas**. For each format:

```markdown
### Format [N]: [Format Name]

**Description:** What the format looks like and how it works
**Example:** [Link or description of a top-performing video using this format]
**Stats:** [Views, likes, engagement rate from the search results]
**Why it works:** [Brief psychology — why this format resonates]
**How to replicate with ReelClaw:**
  - Hook type: [emotion — shocked, crying, etc.]
  - Text hook style: [e.g., "When..." question, bold statement, statistic]
  - Demo content: [what to show in the demo portion]
  - Music vibe: [energetic, moody, trending sound]
```

### 6d. Format Research Strategy

**Search in this order for best results:**

1. **Broad niche search** — `keyword search` for the main niche term
2. **Specific product search** — `keyword search` for the exact product/brand
3. **Creator discovery** — `user search` to find niche influencers
4. **Creator deep-dive** — `profile videos sorted by popular` for top 2-3 creators
5. **Cross-platform** — Repeat key searches on Instagram for format diversity

**What to look for in results:**
- Videos with unusually high engagement (likes/views ratio > 10%)
- Recurring formats across multiple creators (validates the format works)
- Content styles: UGC reactions, before/after, POV, tutorials, testimonials, unboxing, "day in my life"
- Hook patterns: text overlays, opening lines, visual hooks
- Duration sweet spots in the niche

---

## Step 7: Hook Research — Find Winning Text Hooks

When users ask for hook ideas, use the DanSUGC MCP tools to find text hooks proven to work in the niche.

### 7a. Search for Hook Inspiration

```
# Search TikTok for niche content — hooks live in video descriptions/captions
mcp__dansugc__tiktok_search_videos(query="NICHE_KEYWORD")

# Search with emotional angle keywords
mcp__dansugc__tiktok_search_videos(query="NICHE relatable")

# Instagram reels for different hook styles
mcp__dansugc__instagram_search_reels(query="NICHE_KEYWORD")
```

### 7b. Extract & Categorize Hooks

From the search results, extract text hooks from video descriptions, captions, and titles. Group them by type:

| Category | Pattern | Example |
|----------|---------|---------|
| **"When..." hooks** | When [relatable situation]... | "When you've tried everything but nothing works" |
| **POV hooks** | POV: [scenario] | "POV: you finally tried organ supplements" |
| **Statistic hooks** | [Number] [claim] | "90% of people are deficient in this" |
| **Question hooks** | [Provocative question]? | "Why is nobody talking about this?" |
| **Confession hooks** | I [honest admission] | "I used to think supplements were a scam" |
| **"Nobody..." hooks** | Nobody talks about [truth] | "Nobody tells you this about iron deficiency" |
| **Challenge hooks** | [Dare or challenge] | "Try this for 30 days and watch what happens" |
| **Before/After hooks** | [Before state] → [After state] | "Day 1 vs Day 30 on beef liver" |

### 7c. Present Hook Ideas

For each hook, provide:

```markdown
### Hook [N]: "[The hook text]"

**Category:** [Hook type from table above]
**Inspired by:** [Video from search results with stats]
**Emotion:** [What UGC reaction to pair with — shocked, curious, crying, etc.]
**Text overlay format:**
  Line 1: [first line of text]
  Line 2: [second line, if needed]
**Matching caption:**
  [Full caption including hashtags]
```

### 7d. Hook Research Strategy

**To find hooks that match a specific format:**
1. Search for the format keyword (e.g., "supplement review TikTok")
2. Look at the top 10-20 results
3. Extract the first line of each caption — this is usually the hook
4. Cross-reference with engagement: hooks from high-performing videos are proven

**To find hooks for a specific brand/product:**
1. Search for the brand name directly
2. Search for the product category + emotional keywords
3. Search for competitor brand names

**Hook quality signals:**
- High engagement ratio (likes/views > 10%)
- Many comments (comments indicate the hook triggered a response)
- Hook text matches the emotional tone of the video
- Short and scannable (3-7 words per line, max 3 lines)

---

## Troubleshooting

**"No token data found" for DanSUGC MCP:**
- Re-register: `claude mcp add --transport http -s user dansugc https://dansugc.com/api/mcp -H "Authorization: Bearer YOUR_KEY"`
- Restart Claude Code after adding

**Apostrophes breaking text overlays:**
- Use `textfile=/tmp/mytext.txt` instead of inline `text='...'`
- Write text to file first: `printf "don't stop" > /tmp/mytext.txt`

**Speed-up clips output wrong duration:**
- Always use two-pass: trim first with `-c copy`, then speed up with `setpts`
- Never combine `-ss`/`-to` with `setpts` in a single pass

**Drafts can't be updated/deleted in Post-Bridge:**
- API limitation — drafts are immutable. Create a new scheduled post instead.

**Text cut off by platform UI:**
- Check Green Zone specs in [./references/green-zone.md](./references/green-zone.md)
- Y must be between 210 and 1480, X between 60 and 960 (universal)

FILE:references/ffmpeg-patterns.md
# FFmpeg Patterns for ReelClaw

All commands include `-y` (overwrite) and `-hide_banner` for cleaner output.

## Standard Video Filter (1080x1920 vertical)

```bash
VF="scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,fps=30"
```

## Trim / Cut

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "INPUT" -ss START_TIME -to END_TIME \
  -c copy "OUTPUT"
```

## Landscape to Vertical (center crop)

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "INPUT" \
  -vf "scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,setsar=1,fps=30" \
  -an -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

## Landscape to Vertical (blur background)

```bash
ffmpeg -y -hide_banner -loglevel error -i "INPUT" \
  -filter_complex "\
    [0:v]scale=1080:1920:force_original_aspect_ratio=increase,crop=1080:1920,boxblur=20:5[bg];\
    [0:v]scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black@0[fg];\
    [bg][fg]overlay=0:0" \
  -c:v libx264 -preset fast -crf 18 -c:a aac -b:a 128k -movflags +faststart \
  "OUTPUT"
```

## Vertical Scale + Pad

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i "INPUT" \
  -vf "scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,fps=30" \
  -an -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

## Speed Up (two-pass — REQUIRED)

Never combine `-ss`/`-to` with `setpts` in a single pass. Always use two-pass.

```bash
# Pass 1: Trim segment
ffmpeg -y -hide_banner -loglevel error \
  -i "INPUT" -ss START -to END \
  -c copy "/tmp/segment.mp4"

# Pass 2: Speed up + scale
# Speed = source_duration / target_duration
# PTS multiplier = 1 / speed (e.g., 3x speed = 0.333*PTS)
ffmpeg -y -hide_banner -loglevel error \
  -i "/tmp/segment.mp4" \
  -vf "setpts=PTS_MULTIPLIER*PTS,$VF" -an \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

**Speed factor reference:**

| Source | Target | PTS Multiplier | Speed |
|--------|--------|----------------|-------|
| 21s | 7s | 0.333*PTS | 3.0x |
| 24s | 8s | 0.333*PTS | 3.0x |
| 28s | 8s | 0.286*PTS | 3.5x |
| 30s | 8.5s | 0.283*PTS | 3.53x |
| 32s | 8s | 0.250*PTS | 4.0x |

## Concatenate Clips

**Concat demuxer (same codec, fastest):**
```bash
cat > /tmp/concat.txt << EOF
file '/path/to/clip-01.mp4'
file '/path/to/clip-02.mp4'
EOF

ffmpeg -y -hide_banner -loglevel error \
  -f concat -safe 0 -i /tmp/concat.txt \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

**Filter concat (different codecs/resolutions):**
```bash
ffmpeg -y -hide_banner -loglevel error \
  -i clip-01.mp4 -i clip-02.mp4 \
  -filter_complex "\
    [0:v]scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v0];\
    [1:v]scale=1080:1920:force_original_aspect_ratio=decrease,pad=1080:1920:(ow-iw)/2:(oh-ih)/2,setsar=1,fps=30[v1];\
    [v0][v1]concat=n=2:v=1:a=0[outv]" \
  -map "[outv]" -an \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

## Text Overlays (drawtext)

**Inline text (no apostrophes):**
```bash
ffmpeg -y -hide_banner -loglevel error -i "INPUT" \
  -vf "drawtext=text='Your text here':\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=310:\
    enable='between(t,0,4.5)'" \
  -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart \
  "OUTPUT"
```

**Textfile approach (for apostrophes):**
```bash
printf "When nothing's wrong" > /tmp/line1.txt

ffmpeg -y -hide_banner -loglevel error -i "INPUT" \
  -vf "drawtext=textfile=/tmp/line1.txt:\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=310:\
    enable='between(t,0,4.5)'" \
  -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart \
  "OUTPUT"
```

**Multi-line text:**
```bash
ffmpeg -y -hide_banner -loglevel error -i "INPUT" \
  -vf "drawtext=text='Line one':\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=310:\
    enable='between(t,0,4.5)',\
  drawtext=text='Line two':\
    fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
    fontsize=64:fontcolor=white:borderw=4:bordercolor=black:\
    x=(60+(900-text_w)/2):y=390:\
    enable='between(t,0,4.5)'" \
  -c:v libx264 -preset fast -crf 18 -c:a copy -movflags +faststart \
  "OUTPUT"
```

**Text with background box:**
```bash
drawtext=text='YOUR TEXT':\
  fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:\
  fontsize=64:fontcolor=white:\
  box=1:[email protected]:boxborderw=20:\
  x=(60+(900-text_w)/2):y=310:\
  enable='between(t,0,4.5)'
```

**Escape colons:** Use `\\:` (e.g., `10\\:00 AM`)

## Add Music

```bash
# Analyze volume to find peak energy
ffmpeg -i "track.mp3" -af volumedetect -f null /dev/null 2>&1 | grep volume

# Overlay music with fade in/out
ffmpeg -y -hide_banner -loglevel error \
  -i "video.mp4" -i "track.mp3" \
  -map 0:v -map 1:a \
  -af "afade=t=in:st=0:d=0.5,afade=t=out:st=14:d=1,volume=0.8" \
  -c:v copy -c:a aac -b:a 128k \
  -shortest -movflags +faststart \
  "OUTPUT"
```

## Validate Duration

```bash
ffprobe -v quiet -print_format json -show_entries format=duration "OUTPUT" | \
  python3 -c "import sys,json; d=float(json.load(sys.stdin)['format']['duration']); \
  print(f'Duration: {d:.1f}s — {\"OK\" if d <= 15.0 else \"TOO LONG\"}')"
```

## Upload to tmpfiles.org

```bash
url=$(curl -s -F "[email protected]" https://tmpfiles.org/api/v1/upload | \
  python3 -c "import sys,json; u=json.load(sys.stdin)['data']['url']; \
  print(u.replace('tmpfiles.org/', 'tmpfiles.org/dl/'))")
echo "Public URL: $url"
```

## Probe Video Info

```bash
ffprobe -v quiet -print_format json -show_format -show_streams "INPUT"
```

## Final Export (high quality)

```bash
ffmpeg -y -hide_banner -loglevel error -i "INPUT" \
  -c:v libx264 -preset slow -crf 18 -profile:v high -level 4.2 \
  -c:a aac -b:a 192k -ar 44100 \
  -pix_fmt yuv420p -movflags +faststart -r 30 \
  "FINAL_OUTPUT"
```

## Transitions (xfade)

```bash
ffmpeg -y -hide_banner -loglevel error \
  -i clip-01.mp4 -i clip-02.mp4 \
  -filter_complex "\
    [0:v]scale=1080:1920:...,fps=30[v0];\
    [1:v]scale=1080:1920:...,fps=30[v1];\
    [v0][v1]xfade=transition=fade:duration=0.5:offset=CLIP1_DUR_MINUS_0.5[outv]" \
  -map "[outv]" -an \
  -c:v libx264 -preset fast -crf 18 -movflags +faststart \
  "OUTPUT"
```

Available transitions: `fade`, `dissolve`, `wipeleft`, `wiperight`, `slideup`, `slidedown`, `circlecrop`, `fadeblack`, `fadewhite`, `radial`, `smoothleft`, `smoothright`

FILE:references/green-zone.md
# Green Zone Reference (Platform Safe Areas)

The Green Zone is where NO platform UI overlaps your content. **ALL text MUST be placed here.**

## Universal Green Zone (safe on ALL platforms — DEFAULT)

```
Canvas:     1080 x 1920 px
Top:        210 px from top
Bottom:     440 px from bottom (safe Y ends at 1480)
Left:       60 px from left
Right:      120 px from right  (safe X ends at 960)

Safe area:  900 x 1270 px
            X: 60 to 960
            Y: 210 to 1480
```

```
+-------------------------------------+
|           TOP MARGIN (210px)        | <- Username, follow, sound label
|  +-----------------------------+    |
|  |                             | R  |
|  |       GREEN ZONE            | I  |
|  |    (900 x 1270 px)         | G  |
|  |    All text goes here       | H  |
|  |                             | T  |
|  |                             |    |
|  +-----------------------------+    |
|           BOTTOM MARGIN (440px)     | <- Captions, CTA, hashtags
+-------------------------------------+
```

## Text Position Presets

| Position | Y Value | X Formula | Best For |
|----------|---------|-----------|----------|
| **Upper GZ** | `280-340` | `x=(60+(900-text_w)/2)` | Hook text (line 1) |
| **Upper-mid** | `360-440` | same | Hook text (lines 2-3) |
| **Center GZ** | `(210+(1270-text_h)/2)` | same | Big statements |
| **Lower-mid GZ** | `1100` | same | Supporting text |
| **Lower GZ** | `1380` | same | CTA text |

**Horizontal centering formula (always use this):**
```
x=(60+(900-text_w)/2)
```

## Text Style Presets (TikTok Sans)

**Font paths:**
- macOS: `$HOME/Library/Fonts/TikTokSans*.ttf`
- Linux: `$HOME/.local/share/fonts/TikTokSans*.ttf`

**"Hook" — Upper green zone, attention-grabbing:**
```
fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:fontsize=64:fontcolor=white:borderw=4:bordercolor=black:x=(60+(900-text_w)/2):y=310
```

**"Hook with Box" — With semi-transparent background:**
```
fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:fontsize=64:fontcolor=white:box=1:[email protected]:boxborderw=20:x=(60+(900-text_w)/2):y=310
```

**"CTA" — Lower green zone, call to action:**
```
fontfile=$HOME/Library/Fonts/TikTokSansDisplayBold.ttf:fontsize=52:fontcolor=white:borderw=3:bordercolor=black:x=(60+(900-text_w)/2):y=1380
```

**"Subtitle" — Lower green zone with background:**
```
fontfile=$HOME/Library/Fonts/TikTokSansTextMedium.ttf:fontsize=48:fontcolor=white:box=1:[email protected]:boxborderw=15:x=(60+(900-text_w)/2):y=1350
```

## Font Weights

| Weight | File | Use For |
|--------|------|---------|
| **Display Bold** | `TikTokSansDisplayBold.ttf` | Hook text, CTAs (DEFAULT) |
| **Display Black** | `TikTokSansDisplayBlack.ttf` | Extra bold impact |
| **Display Medium** | `TikTokSansDisplayMedium.ttf` | Secondary hooks |
| **Text Bold** | `TikTokSansTextBold.ttf` | Bold captions |
| **Text Medium** | `TikTokSansTextMedium.ttf` | Body text, subtitles |

## Platform-Specific Green Zones

Use these only when targeting a single platform.

**TikTok:**
```
X: 60 to 960, Y: 150 to 1480
Safe area: 900 x 1330 px
GZ_CENTER_X=510  GZ_CENTER_Y=815
```

**Instagram Reels:**
```
X: 44 to 996, Y: 210 to 1610
Safe area: 952 x 1400 px
GZ_CENTER_X=520  GZ_CENTER_Y=910
```

**YouTube Shorts:**
```
X: 60 to 984, Y: 170 to 1530
Safe area: 924 x 1360 px
GZ_CENTER_X=522  GZ_CENTER_Y=850
```

## Why Each Zone Exists

| Zone | What Covers It |
|------|---------------|
| **Top** | Username, follow button, sound label, "Sponsored" tag |
| **Right** | Like, comment, share, bookmark buttons, profile avatar |
| **Bottom** | Caption text, hashtags, CTA buttons, sound ticker |
| **Left** | Generally clear, small margin for safety |

## NEVER Use These Positions

These fall OUTSIDE the green zone and will be covered by platform UI:
- `y < 210` -> covered by top UI
- `y > 1480` -> covered by bottom caption/CTA
- `x > 960` -> covered by right-side engagement buttons

FILE:references/tools-setup.md
# Tool Setup Guide

## DanSUGC — UGC B-Roll Reaction Library

**What it is:** A marketplace of UGC reaction videos (shocked, crying, happy, frustrated, etc.) perfect for hook clips in short-form content.

**Setup:**
1. Go to [dansugc.com](https://dansugc.com) and create an account
2. Navigate to **Developers** section in your dashboard
3. Generate an API key (starts with `dsk_`)
4. Add the MCP server to Claude Code:

```bash
claude mcp add --transport http -s user dansugc https://dansugc.com/api/mcp \
  -H "Authorization: Bearer dsk_YOUR_API_KEY_HERE"
```

5. Restart Claude Code after adding

**Available MCP Tools:**
- `mcp__dansugc__search_videos` — Search by emotion, keyword, or semantic description
- `mcp__dansugc__get_video` — Get details for a specific video by ID
- `mcp__dansugc__purchase_videos` — Purchase videos (deducts credits, returns download URLs)
- `mcp__dansugc__list_purchases` — List previously purchased videos
- `mcp__dansugc__get_balance` — Check remaining credits
- `mcp__dansugc__tiktok_search_videos` — Search TikTok videos by keyword
- `mcp__dansugc__tiktok_user_videos` — Get a TikTok user's videos
- `mcp__dansugc__tiktok_search_users` — Search for TikTok users
- `mcp__dansugc__instagram_search_reels` — Search Instagram reels
- `mcp__dansugc__instagram_user_reels` — Get an Instagram user's reels
- `mcp__dansugc__scrapecreators_raw` — Raw proxy to any ScrapCreators endpoint

**Important:** You must **purchase** videos before downloading them. The `purchase_videos` tool returns download URLs after successful purchase. Always check your balance first with `get_balance`.

**Pricing:** Credit-based. Each video costs credits. Check your balance before bulk purchases.

---

## Post-Bridge — Social Media Scheduling

**What it is:** A social media scheduling API that publishes videos to TikTok, Instagram, YouTube, and more.

**Setup:**
1. Go to [post-bridge.com](https://www.post-bridge.com) and create an account
2. Connect your social media accounts (TikTok, Instagram, etc.)
3. Go to **Settings -> API** and generate an API key (starts with `pb_live_`)
4. Add the MCP server:

```bash
claude mcp add --transport http -s user post-bridge https://www.post-bridge.com/api/mcp/mcp \
  -H "Authorization: Bearer pb_live_YOUR_API_KEY_HERE"
```

5. Restart Claude Code after adding

**Available MCP Tools:**
- `mcp__post-bridge__list_social_accounts` — List connected accounts with IDs
- `mcp__post-bridge__create_post` — Create/schedule posts with media URLs
- `mcp__post-bridge__list_posts` — List scheduled/published posts
- `mcp__post-bridge__list_analytics` — View post performance analytics
- `mcp__post-bridge__update_post` — Update scheduled posts (only scheduled, not drafts)
- `mcp__post-bridge__delete_post` — Delete scheduled posts (only scheduled, not drafts)

**Key rules:**
- ONE video per ONE account — distribute unique videos across accounts
- Use `is_draft: true` for drafts, omit for scheduled posts
- Videos need **public URLs** — use tmpfiles.org for temporary hosting (use `/dl/` prefix for direct download URLs)
- Use `media_urls` parameter with public video URLs (the API downloads them)
- Drafts cannot be updated or deleted via API — only scheduled posts can

---

## Social Media Analytics — DanSUGC Proxy (powered by ScrapCreators)

**What it is:** Real-time social media analytics for tracking video performance across TikTok, Instagram, YouTube, and 25+ platforms. Included with your DanSUGC API key — no extra setup needed.

**Setup:** None! Analytics are proxied through DanSUGC. Uses the same MCP server you already have — no extra configuration needed.

**Pricing:** $0.02 per request, deducted from your DanSUGC balance.

**Available MCP Tools:**
- `mcp__dansugc__tiktok_search_videos` — Search TikTok videos by keyword
- `mcp__dansugc__tiktok_user_videos` — Get a TikTok user's videos
- `mcp__dansugc__tiktok_search_users` — Search for TikTok users
- `mcp__dansugc__instagram_search_reels` — Search Instagram reels
- `mcp__dansugc__instagram_user_reels` — Get an Instagram user's reels
- `mcp__dansugc__scrapecreators_raw` — Raw proxy to any ScrapCreators endpoint

**Usage (MCP tool calls):**
```
# Search TikTok videos by keyword
mcp__dansugc__tiktok_search_videos(query="KEYWORD", sort_by="relevance")

# Get a TikTok user's videos (sorted by popular)
mcp__dansugc__tiktok_user_videos(handle="USERNAME", sort_by="popular")

# Search for TikTok users
mcp__dansugc__tiktok_search_users(query="KEYWORD")

# Search Instagram reels
mcp__dansugc__instagram_search_reels(query="KEYWORD")

# Get an Instagram user's reels
mcp__dansugc__instagram_user_reels(handle="USERNAME")

# Raw proxy — use for any ScrapCreators endpoint not covered above
mcp__dansugc__scrapecreators_raw(path="v1/tiktok/video", params={"url": "VIDEO_URL"})
```

**Path mapping:** Prepend `https://app.dansugcmodels.com/api/v1/scrapecreators/` to any ScrapCreators path. All query params and request bodies are forwarded as-is. Response format is identical.

**Error codes:**
- `402` — Insufficient DanSUGC balance (tell user to top up credits)
- `403` — API key not linked to a user account
- `502` — ScrapCreators unreachable (auto-refunded, safe to retry)

---

## Gemini — Video Intelligence

**What it is:** Google's Gemini AI model used for analyzing demo screen recordings — identifying the best segments, UI transitions, and emotional moments.

**Setup:**
1. Go to [aistudio.google.com/apikey](https://aistudio.google.com/apikey)
2. Create an API key
3. Set it as an environment variable:

```bash
export GEMINI_API_KEY="your_key_here"
```

**Always use model: `gemini-3.1-flash-lite-preview`** — optimized for video understanding tasks.

**Direct video upload for analysis:**
```bash
# Step 1: Upload video file
FILE_URI=$(curl -s -X POST \
  "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" \
  -H "X-Goog-Upload-Command: start, upload, finalize" \
  -H "X-Goog-Upload-Header-Content-Type: video/mp4" \
  -H "Content-Type: video/mp4" \
  --data-binary @"DEMO.mp4" | python3 -c "import sys,json; print(json.load(sys.stdin)['file']['uri'])")

# Step 2: Analyze
curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-lite-preview:generateContent?key=$GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"contents\": [{
      \"parts\": [
        {\"text\": \"YOUR ANALYSIS PROMPT HERE\"},
        {\"file_data\": {\"file_uri\": \"$FILE_URI\", \"mime_type\": \"video/mp4\"}}
      ]
    }],
    \"generationConfig\": {\"temperature\": 0.2, \"response_mime_type\": \"application/json\"}
  }"
```