@thunderkiller/video-clipper

A TypeScript CLI (and library) that analyzes a YouTube video with an LLM, finds the most interesting moments, and 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 — OpenAI, Anthropic, Google, and more)
    │
    ▼
Merge with audio event detection → rank & deduplicate segments
    │
    ▼
Refine clip boundaries (second LLM pass)
    │
    ▼
(Optional) Download video + cut clips with ffmpeg

Requirements

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

# macOS
brew install yt-dlp ffmpeg

Installation

# Global CLI
npm install -g @thunderkiller/video-clipper

# One-off with npx (no install)
npx @thunderkiller/video-clipper <url>

# As a library
npm install @thunderkiller/video-clipper

Quick Start

1. Configure your LLM provider

Create a .env file in your working directory:

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...

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

2. Run

# Analyze only — prints ranked segments as JSON
video-clipper https://youtube.com/watch?v=VIDEO_ID

# Analyze and cut clips (downloads video, runs ffmpeg)
video-clipper https://youtube.com/watch?v=VIDEO_ID --clip

# Download only the top 3 segments (faster than full video)
video-clipper https://youtube.com/watch?v=VIDEO_ID --download-sections 3

CLI Flags

Output

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

Programmatic API

import { runPipeline, parseArgs, config } from '@thunderkiller/video-clipper';

const args = parseArgs(process.argv);
await runPipeline(args);

All public types and Zod schemas are exported from the package root. See src/lib.ts for the full surface.

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit with Conventional Commits — enforced by commitlint
4. Push and open a Pull Request

Pre-commit hooks run automatically: formatting (Prettier), type-check, and tests. Make sure yt-dlp and ffmpeg are installed locally.

Documentation