video-clipper

A TypeScript CLI tool that takes a YouTube URL, analyzes the transcript with an LLM, and returns the most interesting moments as ranked timestamp ranges. Optionally downloads the video and cuts clips automatically.

How it works

YouTube URL
    │
    ▼
Parse URL → fetch transcript → group into chunks
    │
    ▼
Parallel LLM analysis (Vercel AI SDK + gpt-4o)
    │
    ▼
Rank & deduplicate segments
    │
    ▼
Refine clip boundaries (second LLM pass)
    │
    ▼
(Optional) Download video + cut clips with ffmpeg

Tech Stack

Requirements

• Node.js 18+
• yt-dlp (for video download)
• ffmpeg (for clip cutting)

# macOS
brew install yt-dlp ffmpeg

Audio/Video Sync

Clips are generated by re-encoding with libx264 (video) and aac (audio) to ensure perfect audio/video synchronization. This is slower than stream copy mode but prevents the common issue where video and audio become desynchronized in the output clips.

Performance vs Quality Trade-off:

Use the FFMPEG_PRESET environment variable to adjust encoding speed:

Example:

# Faster processing (lower quality)
FFMPEG_PRESET=ultrafast npm run start -- <url> --clip

# Higher quality (slower)
FFMPEG_PRESET=medium npm run start -- <url> --clip

Setup

npm install
cp .env.example .env

Edit .env and configure your LLM provider:

# Choose your provider (openai, anthropic, google, xai, mistral, groq, zai, openrouter)
LLM_PROVIDER=openai
OPENAI_API_KEY=your_key_here

# Or use a free model via OpenRouter:
# LLM_PROVIDER=openrouter
# OPENROUTER_API_KEY=sk-or-...
# LLM_MODEL=meta-llama/llama-3.3-70b-instruct:free

Advanced Examples

# Analyze only (no download)
npm run start -- <youtube-url>

# Analyze and download full video
npm run start -- <youtube-url> --download

# Analyze and cut clips
npm run start -- <youtube-url> --clip

# Limit number of clips to generate
npm run start -- <youtube-url> --clip --max-clips 3

# Use custom output directory
OUTPUT_DIR=my-clips npm run start -- <youtube-url> --clip

Configuration

All parameters are set via .env:

Output

{
  "video_id": "abc123",
  "title": "Video Title",
  "duration": 1823,
  "segments": [
    {
      "rank": 1,
      "start": 120,
      "end": 150,
      "score": 9,
      "reason": "strong controversial opinion"
    },
    {
      "rank": 2,
      "start": 420,
      "end": 455,
      "score": 8,
      "reason": "funny storytelling moment"
    }
  ]
}

Caching

The CLI caches both transcript fetches and LLM chunk results to speed up subsequent runs:

• Transcript cache: Stored per video ID in CACHE_DIR
• LLM chunk cache: Stores successful chunk analyses to avoid re-analyzing the same content

Cache is automatically used on re-runs. Use --no-cache to bypass.

Working with Pre-Downloaded Videos

If you already have a video downloaded (from yt-dlp, browser download, or other tool), you can skip the download step and work directly with that file.

Workflow:

# Step 1: Run analysis once to get segment timestamps
npm run start -- <url> --output-json analysis.json

# Step 2: (Optional) Edit timestamps in analysis.json if needed
# Edit the "start" and "end" values for each segment

# Step 3: Place your video in downloads/ directory
cp /path/to/your/video.mp4 downloads/<videoId>.mp4

# Step 4: Run again - will skip download and use your video
npm run start -- <url> --clip

Use cases:

• Testing different settings - Run different clip configurations without re-downloading
• Manual timestamp adjustment - Fine-tune segment boundaries based on visual inspection
• Alternative video sources - Work with videos downloaded from other tools or browsers
• Large video files - If you have a high-quality version, use that instead

Notes:

• The video file must be named exactly {videoId}.mp4 in the DOWNLOAD_DIR
• You can apply TIMESTAMP_OFFSET_SECONDS globally instead of editing each timestamp
• Transcript cache is used, so re-running is fast (no API calls)

Combining with Timestamp Offset

For pre-downloaded videos with known sync issues:

# Skip download, apply 3-second offset to all clips
TIMESTAMP_OFFSET_SECONDS=-3 npm run start -- <url> --clip

The CLI will find the existing video in downloads/, skip the download step, and apply the offset to all clip generation.

Usage

Basic analysis (no download)

npm run start -- https://youtube.com/watch?v=abc123

Download full video and generate clips

npm run start -- https://youtube.com/watch?v=abc123 --clip

Download top N segments only

# Download top 3 segments
npm run start -- https://youtube.com/watch?v=abc123 --download-sections 3

# Download top 5 segments
npm run start -- https://youtube.com/watch?v=abc123 --download-sections 5

Custom output directory

# Store clips in custom directory
npm run start -- https://youtube.com/watch?v=abc123 --clip --video-path ./my-clips

# Download segments to custom path
npm run start -- https://youtube.com/watch?v=abc123 --download-sections 3 --video-path ./downloads

Custom thresholds

npm run start -- https://youtube.com/watch?v=abc123 --threshold 8 --top-n 5

Testing with limited chunks

npm run start -- https://youtube.com/watch?v=abc123 --max-chunks 3

Custom thresholds with timestamp offset

# Fix 3-second audio delay (shift earlier)
TIMESTAMP_OFFSET_SECONDS=-3 npm run start -- <url> --clip

# Fix 2-second early start (shift later)
TIMESTAMP_OFFSET_SECONDS=2 npm run start -- <url> --clip

# High quality, slower processing, with offset
FFMPEG_PRESET=slow TIMESTAMP_OFFSET_SECONDS=-3 npm run start -- <url> --clip

Troubleshooting Audio Sync Issues

Problem: Audio is delayed or starts early

Symptoms:

• Video starts at correct moment but audio plays 2-5 seconds later/earlier
• Lip movements don't match speech in the clip
• Content in clip doesn't match the transcript segment

Root Causes:

1. Transcript misalignment - Transcript timestamps don't perfectly match the video

   • Auto-generated captions: Often have 1-3 second delays
   • Manual captions: Usually more accurate but can have timing issues
   • Multiple caption tracks: Transcripts from different video versions

2. Millisecond precision loss - Old implementation lost decimal seconds

   • Now fixed: --download-sections uses HH:MM:SS.mmm format

3. Version differences - The transcript might be from a slightly different version of the video

Solution: Use TIMESTAMP_OFFSET_SECONDS

What it does: Applies a global offset to all clip timestamps. Positive = shift later, negative = shift earlier.

How to use:

# Add to .env
TIMESTAMP_OFFSET_SECONDS=-3

# Or inline
TIMESTAMP_OFFSET_SECONDS=-3 npm run start -- <url> --clip

Finding the Correct Offset

Step 1: Test with logging

Run a single segment and observe the logs:

TIMESTAMP_OFFSET_SECONDS=0 npm run start -- <url> --download-sections 1

Look for these log lines:

[info] Downloading segment 1: 00:02:00.500-00:02:30.000 (strong opinion...)
[info]   Requested: 120.50s - 150.00s
[info]   Adjusted: 117.50s - 147.00s (offset: -3s)
[info] Cutting clip: start=117.50s, end=147.00s, duration=29.50s

Step 2: Play and verify

• Open the generated clip
• Check if the moment matches the transcript description
• Note if it's too early or too late

Step 3: Adjust offset

If clip starts 3 seconds late:

TIMESTAMP_OFFSET_SECONDS=-3  # Negative = shift earlier

If clip starts 2 seconds early:

TIMESTAMP_OFFSET_SECONDS=2   # Positive = shift later

Step 4: Verify with multiple clips

TIMESTAMP_OFFSET_SECONDS=-3 npm run start -- <url> --download-sections 3

Check if the offset works consistently across different segments.

Binary Search for Optimal Offset

If you're unsure of the exact offset:

# Try 0, -3, -6, -9 to see which is closest
for offset in 0 -3 -6 -9; do
  TIMESTAMP_OFFSET_SECONDS=$offset npm run start -- <url> --download-sections 1
  echo "Tested offset: $offset"
  # Play and check accuracy
done

Then narrow down: -3 seems good, try -2 and -4, etc.

Common Scenarios

Verifying the Fix

After applying TIMESTAMP_OFFSET_SECONDS, verify:

1. Watch the clip: Audio and video should be synchronized
2. Check multiple clips: Offset should work consistently
3. Compare with original: Clip should match the described content

If offset varies between segments, the issue might be video-specific rather than a global transcript offset.

CLI Flags

Docs

Full architecture and build plan: docs/plan.md

yt-dlp download modes: docs/yt-downloader.md