reelclaw

Category: Data & AI | Uploader: dansugc | Downloads: 0 | Version: v1.0（Latest）
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, and track performance via DanSUGC's built-in analytics proxy.
Changelog: Source: GitHub https://github.com/dansugc/reelclaw
Directory Structure

Current level: Root
📁 references/
- 📄 ffmpeg-patterns.md 6.7 KB
- 📄 green-zone.md 3.9 KB
- 📄 tools-setup.md 6.3 KB
- 📄 virality.md 4.3 KB
📄 README.md 2.6 KB
📄 SKILL.md 16.4 KB
SKILL.md

---
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, and track performance 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 "file=@reel-final.mp4" 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.

**Base URL:** `https://app.dansugcmodels.com/api/v1/scrapecreators/`
**Auth:** Same DanSUGC API key (`Authorization: Bearer dsk_YOUR_KEY`)

```bash
# Get TikTok video stats
curl -s "https://app.dansugcmodels.com/api/v1/scrapecreators/v1/tiktok/video?url=$VIDEO_URL" \
  -H "Authorization: Bearer $DANSUGC_API_KEY" | \
  python3 -c "
import sys, json
d = json.load(sys.stdin)
stats = d.get('data', {}).get('stats', {})
print(f'Views: {stats.get(\"playCount\", 0):,}')
print(f'Likes: {stats.get(\"diggCount\", 0):,}')
print(f'Comments: {stats.get(\"commentCount\", 0):,}')
print(f'Shares: {stats.get(\"shareCount\", 0):,}')
"

# Search TikTok videos by keyword
curl -s "https://app.dansugcmodels.com/api/v1/scrapecreators/v1/tiktok/search/keyword?query=KEYWORD&sort_by=relevance" \
  -H "Authorization: Bearer $DANSUGC_API_KEY"

# Get TikTok profile videos
curl -s "https://app.dansugcmodels.com/api/v1/scrapecreators/v3/tiktok/profile/videos?handle=USERNAME&sort_by=popular" \
  -H "Authorization: Bearer $DANSUGC_API_KEY"

# Search Instagram reels
curl -s "https://app.dansugcmodels.com/api/v1/scrapecreators/v2/instagram/reels/search?query=KEYWORD" \
  -H "Authorization: Bearer $DANSUGC_API_KEY"
```

**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)`

---

## 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)
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
reelclaw

Directory Structure

SKILL.md

Report

Notice
