short-form-pipeline · diff

git:20260417.af7f540 to git:20260417.b3a468b

14 added, 0 removed. Audit C to C.

# Short-Form Video Clip Pipeline — Skill

+ ## Preamble (runs on skill start)

+ ```bash

+ # Version check (silent if up to date)

+ python3 telemetry/version_check.py 2>/dev/null || true

+ # Telemetry opt-in (first run only, then remembers your choice)

+ python3 telemetry/telemetry_init.py 2>/dev/null || true

+ ```

+ > **Privacy:** This skill logs usage locally to `~/.ai-marketing-skills/analytics/`. Remote telemetry is opt-in only. No code, file paths, or repo content is ever collected. See `telemetry/README.md`.

+ ---

Extract viral short-form clips (TikTok, Reels, Shorts) from long-form YouTube videos. Handles download, transcription, AI segmentation, cutting, vertical cropping, and caption burn-in.

## Prerequisites

- `yt-dlp` and `ffmpeg` installed

- `ANTHROPIC_API_KEY` environment variable set

- Python dependencies from `requirements.txt` installed

- Optional: `mediapipe` and `opencv-python` for face-detected smart crop

## Quick Start

### Single video → clips

```bash

python3 scripts/shortform_pipeline.py \

--url "https://www.youtube.com/watch?v=VIDEO_ID" \

--max-clips 3 \

--output-dir ./output

```

### Standalone clipper (no Claude, heuristic scoring)

```bash

python3 scripts/video_clipper.py --url "https://www.youtube.com/watch?v=VIDEO_ID"

```

## Pipeline Overview

1. **Download** — yt-dlp fetches video + auto-generated VTT captions

2. **Transcribe** — Whisper generates word-level timestamps (falls back to YouTube captions)

3. **Segment** — Claude identifies 2–5 best 30–60s moments with hook scoring ≥7/10

4. **Cut Verification** — Second Claude pass verifies each clip ends on a complete thought

5. **Cut** — FFmpeg extracts each clip from the source video

6. **Vertical Crop** — Layout-aware 16:9 → 9:16 conversion with face detection

7. **Caption Burn** — TikTok-style word-highlighted captions (ASS format) burned in

## Key Files

| File | Purpose |

|------|---------|

| `scripts/shortform_pipeline.py` | Full pipeline: download → segment → cut → crop → caption |

| `scripts/video_clipper.py` | Standalone clipper with heuristic scoring (no Claude needed) |

| `scripts/clip_sender.py` | Helper for clip delivery and review workflow |

## Layout-Aware Cropping

The pipeline handles four video layouts differently:

- **`talking_head`** — Face-detected center crop using MediaPipe; audio panning fallback

- **`screen_share_overlay`** — Stacks screen content on top, webcam bubble on bottom

- **`side_by_side`** — Stacks screen on top, presenter face on bottom

- **`gallery_view`** — Crops to active speaker quadrant

Claude outputs a `layout_hint` for each segment during segmentation.

## Customization

### Voice patterns

Edit `VOICE_PATTERNS` in `video_clipper.py` to match your creator's speech patterns. These boost clip scoring for authentic-sounding segments.

### Segmentation prompt

The Claude prompt in `shortform_pipeline.py` can be customized:

- Adjust `hook_strength` minimum (default: 7/10)

- Change target duration range (default: 30–60s)

- Modify layout hint options

### Crop tuning

In `video_clipper.py`:

- `scale_factor` — Zoom level for single face (default: 1.08)

- `desired_face_y` — Target face position in frame (default: upper 35%)

## Output

Each clip is output as:

- **1080×1920** resolution (9:16 vertical)

- **H.264 + AAC** encoding

- **Word-highlighted captions** burned in

- Ready for direct upload to TikTok, Reels, or Shorts

## Troubleshooting

- **FFmpeg filter_complex error:** Don't use `-c:v copy` with `-filter_complex`. Only `-c:a copy` is safe.

- **Wrong output resolution:** Always crop before scaling. Verify with `ffprobe -show_entries stream=width,height`.

- **Caption sync issues:** Run Whisper on the cut clip, not the source episode.

- **TikTok upload fails:** Ensure H.264 + AAC encoding. Add `-c:v libx264 -c:a aac` if needed.

- **Clip too long:** Claude sometimes overshoots. The pipeline auto-trims clips >90s to 75s.