@thunderkiller/video-clipper 1.1.0

package/scripts/transcribe_whisper.py

@@ -0,0 +1,70 @@
+"""
+transcribe_whisper.py — Full Whisper transcription for transcript generation.
+
+Runs OpenAI Whisper on the provided audio file and writes a JSON array of
+transcript segments to stdout:
+
+    [{"text": "...", "start": 0.0, "duration": 3.5}, ...]
+
+Usage:
+    python transcribe_whisper.py <audio_path> [model_size]
+
+Arguments:
+    audio_path  - Path to the audio WAV file
+    model_size  - Whisper model to use (default: medium)
+                  Options: tiny, base, small, medium, large-v3
+
+Requires: pip install openai-whisper
+"""
+
+import json
+import sys
+
+
+def transcribe(audio_path: str, model_size: str = 'medium') -> list[dict]:
+    try:
+        import whisper  # type: ignore
+    except ImportError:
+        print(
+            'ModuleNotFoundError: openai-whisper not installed. Run: pip install openai-whisper',
+            file=sys.stderr,
+        )
+        sys.exit(2)
+
+    model = whisper.load_model(model_size)
+    result = model.transcribe(audio_path, word_timestamps=False, fp16=False)
+
+    segments: list[dict] = []
+    for seg in result.get('segments', []):
+        text: str = seg.get('text', '').strip()
+        start: float = float(seg.get('start', 0))
+        end: float = float(seg.get('end', start))
+        duration = max(0.0, round(end - start, 3))
+
+        if text:
+            segments.append({
+                'text': text,
+                'start': round(start, 3),
+                'duration': duration,
+            })
+
+    return segments
+
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print(
+            'Usage: python transcribe_whisper.py <audio_path> [model_size]',
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    audio_path = sys.argv[1]
+    model_size = sys.argv[2] if len(sys.argv) > 2 else 'medium'
+
+    try:
+        output = transcribe(audio_path, model_size)
+        print(json.dumps(output))
+    except Exception as e:
+        print(f'Error: {e}', file=sys.stderr)
+        sys.exit(1)

package/src/cli.ts

@@ -0,0 +1,186 @@
+import { config } from './config/index.js';
+import { log } from './utils/logger.js';
+import type { CliArgs } from './types/index.js';
+
+export type { CliArgs };
+
+// ---------------------------------------------------------------------------
+// Argument parser
+// ---------------------------------------------------------------------------
+
+export function parseArgs(argv: string[]): CliArgs {
+  const args = argv.slice(2);
+  const result: CliArgs = {
+    url: undefined,
+    clip: false,
+    downloadSections: undefined,
+    videoPath: undefined,
+    threshold: undefined,
+    topN: undefined,
+    maxDuration: undefined,
+    maxChunks: undefined,
+    maxParallel: undefined,
+    outputJson: undefined,
+    noCache: false,
+    noAudio: false,
+    gameProfile: undefined,
+    help: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      result.help = true;
+    } else if (arg === '--clip') {
+      result.clip = true;
+    } else if (arg === '--download-sections') {
+      const val = args[++i];
+      if (!val) {
+        log.error(`--download-sections requires a value: 'all' or a number (1, 2, 3, ...)`);
+        process.exit(1);
+      }
+
+      if (val === 'all') {
+        result.downloadSections = 'all';
+      } else if (val === 'segments') {
+        log.warn(
+          `--download-sections segments is deprecated. Use a number like --download-sections 5 to download top 5 segments, or --download-sections all for full video.`,
+        );
+        result.downloadSections = 'all';
+      } else {
+        const num = Number(val);
+        if (isNaN(num) || !Number.isInteger(num) || num < 1) {
+          log.error(`--download-sections requires 'all' or a positive integer (1, 2, 3, ...)`);
+          process.exit(1);
+        }
+        result.downloadSections = num;
+      }
+
+      result.clip = true;
+    } else if (arg === '--video-path') {
+      const val = args[++i];
+      if (!val) {
+        log.error(`--video-path requires a directory path`);
+        process.exit(1);
+      }
+      result.videoPath = val;
+    } else if (arg === '--local-video') {
+      const val = args[++i];
+      if (!val) {
+        log.error(`--local-video requires a file path`);
+        process.exit(1);
+      }
+      result.localVideo = val;
+      result.clip = true;
+    } else if (arg === '--no-cache') {
+      result.noCache = true;
+    } else if (arg === '--threshold') {
+      const val = Number(args[++i]);
+      if (isNaN(val)) {
+        log.error(`--threshold requires a numeric value`);
+        process.exit(1);
+      }
+      result.threshold = val;
+    } else if (arg === '--top-n') {
+      const val = Number(args[++i]);
+      if (isNaN(val)) {
+        log.error(`--top-n requires a numeric value`);
+        process.exit(1);
+      }
+      result.topN = val;
+    } else if (arg === '--max-duration') {
+      const val = Number(args[++i]);
+      if (isNaN(val)) {
+        log.error(`--max-duration requires a numeric value`);
+        process.exit(1);
+      }
+      result.maxDuration = val;
+    } else if (arg === '--max-chunks') {
+      const val = Number(args[++i]);
+      if (isNaN(val) || !Number.isInteger(val) || val < 1) {
+        log.error(`--max-chunks requires a positive integer`);
+        process.exit(1);
+      }
+      result.maxChunks = val;
+    } else if (arg === '--max-parallel') {
+      const val = Number(args[++i]);
+      if (isNaN(val) || !Number.isInteger(val) || val < 1) {
+        log.error(`--max-parallel requires a positive integer`);
+        process.exit(1);
+      }
+      result.maxParallel = val;
+    } else if (arg === '--no-audio') {
+      result.noAudio = true;
+    } else if (arg === '--game-profile') {
+      const val = args[++i];
+      if (!val) {
+        log.error(`--game-profile requires a value (valorant, fps, boss_fight, general)`);
+        process.exit(1);
+      }
+      result.gameProfile = val;
+    } else if (arg === '--output-json') {
+      result.outputJson = args[++i];
+      if (!result.outputJson) {
+        log.error(`--output-json requires a file path`);
+        process.exit(1);
+      }
+    } else if (!arg.startsWith('--')) {
+      result.url = arg;
+    } else {
+      log.error(`Unknown flag: ${arg}`);
+      printUsage();
+      process.exit(1);
+    }
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Usage text
+// ---------------------------------------------------------------------------
+
+export function printUsage(): void {
+  console.log(
+    `
+Usage: npm run start -- <youtube-url> [options]
+       npx tsx src/index.ts <youtube-url> [options]
+
+Note: when invoking via npm run, use -- to pass flags to the script:
+  npm run start -- <url> --max-chunks 3
+
+Arguments:
+  <youtube-url>           YouTube video URL (required)
+
+Options:
+  --clip                  Download video and generate mp4 clips for each segment
+  --download-sections <mode>  yt-dlp download mode: 'all' (full video) or N (top N segments only, e.g. 1, 2, 3...) (default: ${config.DOWNLOAD_SECTIONS_MODE})
+  --local-video <path>    Path to local video file (skips yt-dlp download, requires --clip)
+  --video-path <path>     Custom output directory for downloaded videos and clips (overrides DOWNLOAD_DIR/OUTPUT_DIR)
+  --threshold <n>         Minimum score to keep a segment (default: ${config.SCORE_THRESHOLD})
+  --top-n <n>             Maximum number of segments to return (default: ${config.TOP_N_SEGMENTS})
+  --max-duration <s>      Abort if video is longer than <s> seconds
+  --max-chunks <n>        Limit the number of transcript chunks sent to the LLM (useful for testing/cost control)
+  --max-parallel <n>      Max number of LLM calls to run in parallel (default: LLM_CONCURRENCY env, or 3)
+  --output-json <path>    Write output JSON to file instead of stdout
+  --no-cache              Bypass all caches and force a fresh run (transcript + chunk LLM results)
+  --no-audio             Disable audio event detection (transcript-only mode)
+  --game-profile <type>   Game profile: valorant, fps, boss_fight, general (default: ${config.GAME_PROFILE})
+  --help, -h              Show this help message
+
+Examples:
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ
+  npm run start -- https://youtu.be/dQw4w9WgXcQ --clip
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --download-sections all
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --download-sections 3
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --download-sections 5 --video-path ./my-clips
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --local-video ./downloads/dQw4w9WgXcQ.mp4
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --local-video /path/to/video.mp4 --top-n 5
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --threshold 8 --top-n 5
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --output-json results.json
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --max-chunks 3
+  npm run start -- https://youtube.com/watch?v=dQw4w9WgXcQ --max-parallel 5
+`.trim(),
+  );
+}

package/src/config/env.ts

@@ -0,0 +1,18 @@
+import 'dotenv/config';
+import { ConfigSchema } from '../types/config.js';
+
+function loadConfig() {
+  const result = ConfigSchema.safeParse(process.env);
+
+  if (!result.success) {
+    const issues = result.error.issues
+      .map((i) => `  - ${i.path.join('.')}: ${i.message}`)
+      .join('\n');
+    console.error(`[error] Invalid configuration:\n${issues}`);
+    process.exit(1);
+  }
+
+  return result.data;
+}
+
+export const config = loadConfig();

package/src/config/index.ts

@@ -0,0 +1,2 @@
+export { config } from './env.js';
+export type { Config } from '../types/config.js';

package/src/index.ts

@@ -0,0 +1,46 @@
+import { log } from './utils/logger.js';
+import { formatConfig } from './utils/redactConfig.js';
+import { config } from './config/index.js';
+import { parseArgs, printUsage } from './cli.js';
+import { runPipeline } from './pipeline/runner.js';
+
+const args = parseArgs(process.argv);
+
+if (args.help) {
+  printUsage();
+  process.exit(0);
+}
+
+if (!args.url) {
+  log.error('No YouTube URL provided.');
+  printUsage();
+  process.exit(1);
+}
+
+if (args.localVideo && !args.clip) {
+  log.error('--local-video requires --clip flag');
+  printUsage();
+  process.exit(1);
+}
+
+if (args.localVideo && args.downloadSections) {
+  log.warn(
+    '--download-sections is ignored when using --local-video (clipping all segments from --top-n)',
+  );
+}
+
+log.info(
+  `Starting video-clipper (model: ${config.LLM_MODEL})` +
+    (args.clip ? ' [--clip enabled]' : '') +
+    (args.localVideo ? ` [--local-video: ${args.localVideo}]` : '') +
+    (args.downloadSections !== undefined && args.downloadSections !== 'all'
+      ? ` [--download-sections: ${args.downloadSections}]`
+      : '') +
+    (args.videoPath ? ` [--video-path: ${args.videoPath}]` : ''),
+);
+log.info(`Config: ${formatConfig(config)}`);
+
+runPipeline(args).catch((err) => {
+  log.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/pipeline/runner.ts

@@ -0,0 +1,155 @@
+import { promises as fs } from 'fs';
+import { config } from '../config/index.js';
+import { Cache } from '../utils/cache.js';
+import { log } from '../utils/logger.js';
+import { dumpAnalysis, dumpTranscript } from '../utils/dumper.js';
+import { resolveVideo } from './stages/videoResolver.js';
+import { processAudio } from './stages/audioProcessor.js';
+import { analyzeSegments, refineRankedSegments } from './stages/segmentAnalyzer.js';
+import { selectSegments } from './stages/segmentSelector.js';
+import { exportClips } from './stages/clipExporter.js';
+import { downloadAudio } from '../services/audioDownloader/index.js';
+import type { CliArgs, PipelineResult } from '../types/index.js';
+
+async function outputResult(
+  result: PipelineResult,
+  outputJsonPath: string | undefined,
+): Promise<void> {
+  const json = JSON.stringify(result, null, 2);
+  if (outputJsonPath) {
+    await fs.writeFile(outputJsonPath, json, 'utf-8');
+    log.info(`Output written to ${outputJsonPath}`);
+  } else {
+    console.log('\n' + json);
+  }
+}
+
+/**
+ * Runs the full video-clipper pipeline for the given CLI arguments.
+ *
+ * Stage ordering:
+ *   1. resolveVideo         — parse URL, extract video ID + metadata
+ *   2. downloadAudio        — download WAV so Whisper/Gemini transcript providers can use it
+ *   3. processAudio         — detect audio events per window (reuses downloaded WAV)
+ *   4a. analyzeSegments     — fetch transcript + LLM pass 1 (informed by audio events)
+ *   5. selectSegments       — merge signals, rank, threshold filter
+ *   4b. refineRankedSegments — LLM pass 2 to tighten clip boundaries
+ *   6. exportClips          — download video + run ffmpeg (only if --clip)
+ *
+ * downloadAudio runs before analyzeSegments so that `audioPath` is available
+ * for Whisper/Gemini transcript providers. processAudio reuses the same WAV.
+ *
+ * Hard errors (invalid URL, transcript failure, all LLM chunks failed) are
+ * thrown so the caller can catch, log, and exit(1). Soft failures (audio
+ * detection, individual clip failures) are logged as warnings and the pipeline
+ * continues.
+ */
+export async function runPipeline(args: CliArgs): Promise<void> {
+  const threshold = args.threshold ?? config.SCORE_THRESHOLD;
+  const topN = args.topN ?? config.TOP_N_SEGMENTS;
+  const gameProfile = args.gameProfile ?? config.GAME_PROFILE;
+  const maxParallel = args.maxParallel ?? config.LLM_CONCURRENCY;
+
+  const cache = new Cache(config.CACHE_DIR, args.noCache);
+
+  // ── Stage 1: Resolve video ID + metadata ─────────────────────────────────
+  const { videoId, metadata } = await resolveVideo(args.url as string, args.maxDuration);
+
+  // ── Stage 2: Download audio ───────────────────────────────────────────────
+  // Downloaded before transcript so Whisper/Gemini transcript providers can
+  // use the WAV. Returns null when audio detection is disabled.
+  let audioPath: string | null = null;
+  const audioEnabled = config.AUDIO_DETECTION_ENABLED && !args.noAudio;
+  if (audioEnabled) {
+    try {
+      audioPath = await downloadAudio(videoId, `${config.OUTPUT_DIR}/audio`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      log.warn(`Audio download failed — continuing without audio: ${message}`);
+    }
+  }
+
+  // ── Stage 3: Audio event detection ───────────────────────────────────────
+  const audioEvents = await processAudio(videoId, metadata.duration, cache, {
+    noAudio: args.noAudio,
+    gameProfile,
+    maxParallel,
+    audioPath,
+  });
+
+  // ── Stage 4a: Fetch transcript + LLM analysis (informed by audio events) ──
+  const { lines, microBlocks, chunkEvals } = await analyzeSegments(
+    videoId,
+    audioPath,
+    audioEvents,
+    cache,
+    {
+      maxChunks: args.maxChunks,
+      maxParallel,
+      noCache: args.noCache,
+    },
+  );
+
+  if (config.DUMP_OUTPUTS) {
+    await dumpTranscript(videoId, lines);
+  }
+
+  // ── Stage 5: Merge signals + rank ─────────────────────────────────────────
+  const rankedSegments = selectSegments(chunkEvals, audioEvents, { threshold, topN });
+
+  // Build partial result for early-exit path (no segments above threshold)
+  const partialResult: PipelineResult = {
+    video_id: videoId,
+    title: metadata.title,
+    duration: metadata.duration,
+    chunk_evaluations: chunkEvals,
+    segments: rankedSegments,
+  };
+
+  if (rankedSegments.length === 0) {
+    await outputResult(partialResult, args.outputJson);
+    if (config.DUMP_OUTPUTS) await dumpAnalysis(videoId, partialResult);
+    return;
+  }
+
+  // ── Stage 4b: Refine clip boundaries (LLM pass 2) ─────────────────────────
+  const refinedSegments = await refineRankedSegments(rankedSegments, microBlocks, cache, {
+    maxParallel,
+    noCache: args.noCache,
+  });
+
+  // ── Output result ─────────────────────────────────────────────────────────
+  const result: PipelineResult = {
+    video_id: videoId,
+    title: metadata.title,
+    duration: metadata.duration,
+    chunk_evaluations: chunkEvals,
+    segments: refinedSegments,
+  };
+
+  await outputResult(result, args.outputJson);
+  if (config.DUMP_OUTPUTS) await dumpAnalysis(videoId, result);
+
+  log.info('Done.');
+
+  // ── Stage 6: Download + generate clips (only with --clip) ─────────────────
+  if (!args.clip) {
+    log.info('Tip: run with --clip to download the video and generate mp4 clips.');
+    return;
+  }
+
+  const clipPaths = await exportClips(videoId, refinedSegments, {
+    localVideo: args.localVideo,
+    downloadSections: args.downloadSections,
+    videoPath: args.videoPath,
+  });
+
+  if (clipPaths.length === 0) {
+    log.warn('No clips were generated successfully.');
+  } else {
+    log.info(`Done — ${clipPaths.length} clip${clipPaths.length !== 1 ? 's' : ''} saved:`);
+    for (const p of clipPaths) {
+      log.info(`  ${p}`);
+    }
+  }
+}

package/src/pipeline/stages/audioProcessor.ts

@@ -0,0 +1,129 @@
+import { promises as fs } from 'fs';
+import pLimit from 'p-limit';
+import { downloadAudio } from '../../services/audioDownloader/index.js';
+import { createAnalyzerChain } from '../../services/audioAnalyzers/index.js';
+import { EventDetector } from '../../services/eventDetector/index.js';
+import { sliceAudio } from '../../utils/sliceAudio.js';
+import { buildWindows } from '../../utils/chunker.js';
+import { log } from '../../utils/logger.js';
+import { config } from '../../config/index.js';
+import type { Cache } from '../../utils/cache.js';
+import type { AudioEvent, AudioProcessorOpts } from '../../types/index.js';
+
+export type { AudioProcessorOpts };
+
+/**
+ * Stage 3 — Audio Processor
+ *
+ * Downloads audio-only WAV, slices it into chunks using the generic
+ * `buildWindows` utility, runs event detection on each slice via an
+ * EventDetector (constructed from the ordered provider chain in config),
+ * and persists the results to cache.
+ *
+ * The provider chain is built once per run from `config.AUDIO_PROVIDER`
+ * (e.g. "gemini,whisper") via `createAnalyzerChain`. The EventDetector
+ * walks the chain in order, falling back to the next analyzer on failure.
+ *
+ * Returns an empty array immediately when audio detection is disabled via
+ * `--no-audio` or the `AUDIO_DETECTION_ENABLED` config flag.
+ */
+export async function processAudio(
+  videoId: string,
+  duration: number,
+  cache: Cache,
+  opts: AudioProcessorOpts,
+): Promise<AudioEvent[]> {
+  const audioEnabled = config.AUDIO_DETECTION_ENABLED && !opts.noAudio;
+  if (!audioEnabled) return [];
+
+  // Cache-first
+  const cached = await cache.readAudioEvents(videoId, opts.gameProfile, config.AUDIO_PROVIDER);
+  if (cached) {
+    log.info(`[cache hit] Audio events loaded from cache (${cached.length} events)`);
+    return cached;
+  }
+
+  try {
+    const audioPath =
+      opts.audioPath ?? (await downloadAudio(videoId, `${config.OUTPUT_DIR}/audio`));
+
+    // Build the analyzer chain once per run from config
+    const chain = createAnalyzerChain(config.AUDIO_PROVIDER);
+    const detector = new EventDetector(chain);
+
+    const providerNames = chain.map((a) => a.source).join(' → ');
+    log.info(
+      `Detecting audio events (chain: ${providerNames}, profile: ${opts.gameProfile}, max ${opts.maxParallel} parallel)...`,
+    );
+
+    const windows = buildWindows(duration, config.CHUNK_LENGTH_SEC, config.CHUNK_OVERLAP_SEC);
+    const limit = pLimit(opts.maxParallel);
+
+    const results = await Promise.allSettled(
+      windows.map((window) =>
+        limit(async () => {
+          log.info(`  Processing audio chunk ${window.start}s - ${window.end}s...`);
+
+          const cachedChunk = await cache.readAudioChunk(
+            videoId,
+            opts.gameProfile,
+            config.AUDIO_PROVIDER,
+            window.start,
+            window.end,
+          );
+          if (cachedChunk) {
+            log.info(
+              `  [cache hit] Audio chunk ${window.start}s - ${window.end}s (${cachedChunk.length} events)`,
+            );
+            return cachedChunk;
+          }
+
+          const slicePath = await sliceAudio(
+            audioPath,
+            window.start,
+            window.end - window.start,
+            config.OUTPUT_DIR,
+          );
+          const events = await detector.detect(
+            slicePath,
+            opts.gameProfile,
+            window.start,
+            window.end - window.start,
+          );
+          await fs.unlink(slicePath);
+
+          await cache.writeAudioChunk(
+            videoId,
+            opts.gameProfile,
+            config.AUDIO_PROVIDER,
+            window.start,
+            window.end,
+            events,
+          );
+
+          return events;
+        }),
+      ),
+    );
+
+    const audioEvents: AudioEvent[] = results
+      .flatMap((r, i) => {
+        if (r.status === 'fulfilled') return r.value;
+        const w = windows[i]!;
+        log.warn(
+          `  Audio event detection failed for chunk ${w.start}s - ${w.end}s: ${String(r.reason)}`,
+        );
+        return [];
+      })
+      .sort((a, b) => a.time - b.time);
+
+    log.info(`Audio event detection complete: ${audioEvents.length} events found`);
+
+    await cache.writeAudioEvents(videoId, opts.gameProfile, config.AUDIO_PROVIDER, audioEvents);
+    return audioEvents;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.warn(`Audio event detection disabled due to error: ${message}`);
+    return [];
+  }
+}

package/src/pipeline/stages/clipExporter.ts

@@ -0,0 +1,80 @@
+import { downloadVideo } from '../../services/videoDownloader/index.js';
+import { generateClips, organizeClips } from '../../services/clipGenerator/index.js';
+import { log } from '../../utils/logger.js';
+import { config } from '../../config/index.js';
+import type { RankedSegment, ClipExporterOpts } from '../../types/index.js';
+
+export type { ClipExporterOpts };
+
+/**
+ * Stage 6 — Clip Exporter
+ *
+ * Handles all three clip-generation modes:
+ *   1. Local video  — user supplied --local-video; run ffmpeg directly
+ *   2. Segments     -- --download-sections N; download top-N clips via yt-dlp
+ *                      --download-sections, then copy to outputs/
+ *   3. Full video   — download full video with yt-dlp, then cut clips with ffmpeg
+ *
+ * @returns Array of absolute paths to the generated clip files.
+ */
+export async function exportClips(
+  videoId: string,
+  segments: RankedSegment[],
+  opts: ClipExporterOpts,
+): Promise<string[]> {
+  // Mode 1: local video already on disk — cut with ffmpeg
+  if (opts.localVideo) {
+    log.info(`Using local video: ${opts.localVideo}`);
+    return generateClips(
+      opts.localVideo,
+      segments,
+      videoId,
+      opts.videoPath,
+      config.CLIP_CONCURRENCY,
+    );
+  }
+
+  // Determine yt-dlp mode
+  const downloadSections = opts.downloadSections ?? config.DOWNLOAD_SECTIONS_MODE;
+
+  if (typeof downloadSections === 'number') {
+    // Mode 2: download only the top-N segments via --download-sections
+    const segmentsToDownload = segments.slice(0, downloadSections);
+
+    if (segmentsToDownload.length < downloadSections) {
+      log.warn(
+        `Requested ${downloadSections} segments, but only ${segmentsToDownload.length} are available above threshold.`,
+      );
+    }
+
+    log.info(`Downloading ${segmentsToDownload.length} segments via yt-dlp --download-sections...`);
+    const downloadResult = await downloadVideo(
+      videoId,
+      'segments',
+      segmentsToDownload,
+      opts.videoPath,
+    );
+
+    if (downloadResult.mode !== 'segments') {
+      throw new Error('Expected segments download result but got full-video result.');
+    }
+
+    return organizeClips(downloadResult.paths, videoId, opts.videoPath, config.CLIP_CONCURRENCY);
+  }
+
+  // Mode 3: full-video download → cut clips with ffmpeg
+  log.info('Downloading full video via yt-dlp...');
+  const downloadResult = await downloadVideo(videoId, 'all', [], opts.videoPath);
+
+  if (downloadResult.mode !== 'all') {
+    throw new Error('Expected full-video download result but got segments result.');
+  }
+
+  return generateClips(
+    downloadResult.path,
+    segments,
+    videoId,
+    opts.videoPath,
+    config.CLIP_CONCURRENCY,
+  );
+}