@thunderkiller/video-clipper 1.1.0

package/src/services/transcriptDetector/index.ts

@@ -0,0 +1,128 @@
+import { buildMicroBlocks, buildLLMChunks } from '../chunkBuilder/index.js';
+import { log } from '../../utils/logger.js';
+import { config } from '../../config/index.js';
+import type { TranscriptAnalyzer } from '../transcriptAnalyzers/index.js';
+import type { Cache } from '../../utils/cache.js';
+import type { TranscriptLine, MicroBlock, LLMChunk } from '../../types/index.js';
+
+export interface TranscriptDetectorResult {
+  lines: TranscriptLine[];
+  microBlocks: MicroBlock[];
+  chunks: LLMChunk[];
+}
+
+/**
+ * Top-level transcript detector.
+ *
+ * Holds an ordered chain of TranscriptAnalyzer instances and walks the chain
+ * on each `detect()` call: the first analyzer that succeeds wins. If an
+ * analyzer throws, the error is logged and the next analyzer in the chain is
+ * tried. If the entire chain is exhausted without success the error from the
+ * last analyzer is re-thrown.
+ *
+ * After obtaining raw transcript lines the detector groups them into
+ * micro-blocks and builds overlapping LLM analysis chunks — keeping the full
+ * "transcript concern" self-contained under one class.
+ *
+ * The chain is built once at startup via `createTranscriptChain(config.TRANSCRIPT_PROVIDER)`
+ * and injected here, keeping provider-selection logic out of this class.
+ *
+ * Results are cached via the injected Cache instance so that repeat runs skip
+ * the network round-trip to yt-dlp / Whisper.
+ *
+ * @example
+ *   const chain    = createTranscriptChain('ytdlp,whisper');
+ *   const detector = new TranscriptDetector(chain);
+ *   const { lines, microBlocks, chunks } = await detector.detect(videoId, audioPath, cache);
+ */
+export class TranscriptDetector {
+  constructor(private readonly chain: TranscriptAnalyzer[]) {
+    if (chain.length === 0) {
+      throw new Error('TranscriptDetector requires at least one TranscriptAnalyzer in the chain.');
+    }
+  }
+
+  /**
+   * Fetches, groups, and chunks the transcript for the given video ID.
+   *
+   * Walks the analyzer chain in order, falling back on error. Cache is checked
+   * first (before any analyzer is tried) and written after the first successful
+   * fetch so subsequent runs with the same provider config are instant.
+   *
+   * @param videoId   - YouTube video ID
+   * @param audioPath - Path to the downloaded WAV, or null if audio is not yet available
+   * @param cache     - Cache instance for read/write of transcript lines
+   */
+  async detect(
+    videoId: string,
+    audioPath: string | null,
+    cache: Cache,
+  ): Promise<TranscriptDetectorResult> {
+    let lines: TranscriptLine[];
+
+    // Cache-first: if we already have lines on disk, skip the provider chain entirely
+    const cached = await cache.readTranscript(videoId);
+    if (cached) {
+      log.info(`[cache hit] Transcript loaded from cache (${cached.length} lines)`);
+      lines = cached;
+    } else {
+      lines = await this.fetchFromChain(videoId, audioPath);
+      await cache.writeTranscript(videoId, lines);
+    }
+
+    const microBlocks = this.buildMicroBlocks(lines);
+    const chunks = this.buildChunks(microBlocks);
+
+    return { lines, microBlocks, chunks };
+  }
+
+  // -------------------------------------------------------------------------
+  // Private helpers
+  // -------------------------------------------------------------------------
+
+  /**
+   * Walks the analyzer chain in order.
+   * Falls back to the next analyzer whenever one throws.
+   */
+  private async fetchFromChain(
+    videoId: string,
+    audioPath: string | null,
+  ): Promise<TranscriptLine[]> {
+    let lastError: unknown;
+
+    for (let i = 0; i < this.chain.length; i++) {
+      const analyzer = this.chain[i];
+      const isLast = i === this.chain.length - 1;
+
+      try {
+        const lines = await analyzer.detect(videoId, audioPath);
+        log.info(`[transcript:${analyzer.source}] fetched ${lines.length} lines`);
+        return lines;
+      } catch (err) {
+        lastError = err;
+        const message = err instanceof Error ? err.message : String(err);
+
+        if (!isLast) {
+          const nextSource = this.chain[i + 1].source;
+          log.warn(
+            `[transcript:${analyzer.source}] failed, falling back to ${nextSource}: ${message}`,
+          );
+        } else {
+          log.error(`[transcript:${analyzer.source}] failed (no more fallbacks): ${message}`);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /** Groups raw transcript lines into micro-blocks. */
+  private buildMicroBlocks(lines: TranscriptLine[]): MicroBlock[] {
+    return buildMicroBlocks(lines, config.MICRO_BLOCK_SEC);
+  }
+
+  /** Builds overlapping LLM analysis chunks from micro-blocks. */
+  private buildChunks(microBlocks: MicroBlock[]): LLMChunk[] {
+    return buildLLMChunks(microBlocks, config.CHUNK_LENGTH_SEC, config.CHUNK_OVERLAP_SEC);
+  }
+}

package/src/services/transcriptFetcher/index.ts

@@ -0,0 +1,151 @@
+import { execa } from 'execa';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { log } from '../../utils/logger.js';
+import { config } from '../../config/index.js';
+import type { TranscriptLine } from '../../types/index.js';
+
+/**
+ * Parses a WebVTT string into TranscriptLine[].
+ *
+ * Handles:
+ * - `HH:MM:SS.mmm --> HH:MM:SS.mmm` timestamp lines
+ * - `<MM:SS.mmm><c>text</c>` inline cue tags (stripped)
+ * - Duplicate / empty cues (skipped)
+ *
+ * Exported for unit testing.
+ */
+export function parseVtt(vttContent: string): TranscriptLine[] {
+  const lines = vttContent.split(/\r?\n/);
+  const result: TranscriptLine[] = [];
+
+  // Regex: HH:MM:SS.mmm --> HH:MM:SS.mmm (optional positioning metadata after)
+  const TIMESTAMP_RE =
+    /^(\d{2}):(\d{2}):(\d{2})[.,](\d{3})\s+-->\s+(\d{2}):(\d{2}):(\d{2})[.,](\d{3})/;
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i].trim();
+    const match = TIMESTAMP_RE.exec(line);
+
+    if (match) {
+      const startSec =
+        parseInt(match[1], 10) * 3600 +
+        parseInt(match[2], 10) * 60 +
+        parseInt(match[3], 10) +
+        parseInt(match[4], 10) / 1000;
+
+      const endSec =
+        parseInt(match[5], 10) * 3600 +
+        parseInt(match[6], 10) * 60 +
+        parseInt(match[7], 10) +
+        parseInt(match[8], 10) / 1000;
+
+      // Collect cue text lines until blank line or EOF
+      i++;
+      const textLines: string[] = [];
+      while (i < lines.length && lines[i].trim() !== '') {
+        textLines.push(lines[i].trim());
+        i++;
+      }
+
+      const rawText = textLines.join(' ');
+
+      // Strip VTT inline tags: <00:00:00.000>, <c>, </c>, <b>, </b>, <i>, </i>, etc.
+      const text = rawText
+        .replace(/<[^>]+>/g, '')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&nbsp;/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim();
+
+      if (text.length === 0) {
+        continue;
+      }
+
+      const duration = Math.max(0, endSec - startSec);
+
+      // Deduplicate: skip if this cue text is identical to the previous one
+      // (YouTube VTT often repeats the same line as text scrolls)
+      if (result.length > 0 && result[result.length - 1].text === text) {
+        continue;
+      }
+
+      result.push({ text, start: startSec, duration });
+      continue;
+    }
+
+    i++;
+  }
+
+  return result;
+}
+
+/**
+ * Fetches the transcript for a given YouTube video ID using yt-dlp
+ * auto-generated subtitles (VTT format).
+ *
+ * The VTT file is written to a temp directory, parsed into TranscriptLine[],
+ * then cleaned up. Cookie config (YT_DLP_COOKIES_FROM_BROWSER /
+ * YT_DLP_COOKIES_FILE) is forwarded to yt-dlp automatically.
+ *
+ * @throws {Error} with the yt-dlp stderr if the command fails
+ * @throws {Error} if no subtitle file is produced
+ * @throws {Error} if the subtitle file contains no parseable cues
+ */
+export async function fetchTranscript(videoId: string): Promise<TranscriptLine[]> {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'vc-vtt-'));
+
+  try {
+    const args = [
+      '--write-auto-sub',
+      '--sub-format',
+      'vtt',
+      '--sub-lang',
+      'en.*',
+      '--skip-download',
+      '--output',
+      path.join(tmpDir, '%(id)s.%(ext)s'),
+      `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+
+    if (config.YT_DLP_COOKIES_FROM_BROWSER) {
+      args.unshift('--cookies-from-browser', config.YT_DLP_COOKIES_FROM_BROWSER);
+    } else if (config.YT_DLP_COOKIES_FILE) {
+      args.unshift('--cookies', config.YT_DLP_COOKIES_FILE);
+    }
+
+    try {
+      await execa('yt-dlp', args);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`yt-dlp failed to fetch subtitles for "${videoId}": ${message}`);
+    }
+
+    // Find the downloaded .vtt file (yt-dlp names it <id>.<lang>.vtt)
+    const files = await fs.readdir(tmpDir);
+    const vttFile = files.find((f) => f.endsWith('.vtt'));
+
+    if (!vttFile) {
+      throw new Error(
+        `No subtitles found for "${videoId}". The video may not have auto-generated captions.`,
+      );
+    }
+
+    const content = await fs.readFile(path.join(tmpDir, vttFile), 'utf8');
+    const lines = parseVtt(content);
+
+    log.info(`Parsed ${lines.length} cues from subtitle file "${vttFile}".`);
+
+    if (lines.length === 0) {
+      throw new Error(`Subtitle file for "${videoId}" was empty or contained no parseable cues.`);
+    }
+
+    return lines;
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+}

package/src/services/urlParser/index.ts

@@ -0,0 +1,53 @@
+const VIDEO_ID_LENGTH = 11;
+
+/**
+ * Parses a YouTube URL and returns the 11-character video ID.
+ * Supports:
+ *   - https://www.youtube.com/watch?v=VIDEO_ID
+ *   - https://youtu.be/VIDEO_ID
+ *   - https://www.youtube.com/embed/VIDEO_ID
+ *   - https://www.youtube.com/shorts/VIDEO_ID
+ *
+ * @throws {Error} if the URL is not a valid YouTube URL or the video ID is not 11 characters
+ */
+export function parseUrl(url: string): string {
+  let parsed: URL;
+
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid URL: "${url}"`);
+  }
+
+  const { hostname, pathname, searchParams } = parsed;
+  const host = hostname.replace(/^www\./, '');
+
+  let videoId: string | null = null;
+
+  if (host === 'youtube.com') {
+    if (pathname === '/watch') {
+      videoId = searchParams.get('v');
+    } else if (pathname.startsWith('/embed/')) {
+      videoId = pathname.split('/embed/')[1]?.split('/')[0] ?? null;
+    } else if (pathname.startsWith('/shorts/')) {
+      videoId = pathname.split('/shorts/')[1]?.split('/')[0] ?? null;
+    }
+  } else if (host === 'youtu.be') {
+    videoId = pathname.slice(1).split('/')[0] ?? null;
+  }
+
+  if (!videoId) {
+    throw new Error(`Could not extract video ID from URL: "${url}"`);
+  }
+
+  // Strip any extra query params that may have been part of the path segment
+  videoId = videoId.split('?')[0];
+
+  if (videoId.length !== VIDEO_ID_LENGTH) {
+    throw new Error(
+      `Invalid video ID "${videoId}": expected ${VIDEO_ID_LENGTH} characters, got ${videoId.length}`,
+    );
+  }
+
+  return videoId;
+}

package/src/services/videoDownloader/index.ts

@@ -0,0 +1,282 @@
+import { execa } from 'execa';
+import { promises as fs } from 'fs';
+import { join } from 'path';
+import pLimit from 'p-limit';
+import { config } from '../../config/index.js';
+import { log } from '../../utils/logger.js';
+import type { RankedSegment } from '../../types/index.js';
+
+export type DownloadMode = 'all' | 'segments';
+
+export interface DownloadResultAll {
+  mode: 'all';
+  path: string;
+}
+
+export interface DownloadResultSegments {
+  mode: 'segments';
+  paths: string[];
+}
+
+export type DownloadResult = DownloadResultAll | DownloadResultSegments;
+
+/**
+ * Formats a timestamp for yt-dlp --download-sections.
+ * Converts seconds to HH:MM:SS.mmm format with millisecond precision.
+ */
+function formatTimestamp(seconds: number): string {
+  const h = Math.floor(seconds / 3600);
+  const m = Math.floor((seconds % 3600) / 60);
+  const s = seconds % 60;
+  const sInt = Math.floor(s);
+  const ms = Math.round((s - sInt) * 1000);
+  return `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}:${String(sInt).padStart(2, '0')}.${String(ms).padStart(3, '0')}`;
+}
+
+/**
+ * Displays progress from yt-dlp stdout/stderr.
+ */
+function displayProgress(stream: 'stdout' | 'stderr'): (data: Buffer | string) => void {
+  return (data: Buffer | string) => {
+    const text = String(data);
+    const lines = text.split('\n').filter((line) => line.trim());
+
+    for (const line of lines) {
+      const progressMatch = line.match(/\[download\]\s+(\d+\.?\d*%)/);
+      if (progressMatch) {
+        process.stdout.write(`\r${progressMatch[0]}`);
+      }
+    }
+  };
+}
+
+/**
+ * Downloads a YouTube video using yt-dlp and returns the local file path.
+ *
+ * Strategy:
+ * - Skips download if the target file already exists.
+ * - Auto-creates the download directory if it doesn't exist.
+ * - Surfaces clear errors for common failure modes (yt-dlp not installed,
+ *   private/geo-blocked video, etc.).
+ *
+ * @param videoId - 11-character YouTube video ID
+ * @param customPath - Custom output directory (optional, overrides DOWNLOAD_DIR)
+ * @returns Absolute path to the downloaded mp4 file
+ * @throws {Error} if yt-dlp is not installed or the download fails
+ */
+export async function downloadFullVideo(videoId: string, customPath?: string): Promise<string> {
+  const downloadDir = customPath || config.DOWNLOAD_DIR;
+  await fs.mkdir(downloadDir, { recursive: true });
+
+  const outputPath = join(downloadDir, `${videoId}.mp4`);
+
+  try {
+    await fs.access(outputPath);
+    log.info(`Video already downloaded: ${outputPath}`);
+    return outputPath;
+  } catch {}
+
+  log.info(`Downloading full video ${videoId} via yt-dlp...`);
+
+  try {
+    const args = [
+      '-f',
+      'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]',
+      '--merge-output-format',
+      'mp4',
+      '-o',
+      outputPath,
+      '--no-playlist',
+      '--newline',
+      `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+
+    if (config.YT_DLP_COOKIES_FROM_BROWSER) {
+      args.splice(0, 0, '--cookies-from-browser', config.YT_DLP_COOKIES_FROM_BROWSER);
+    } else if (config.YT_DLP_COOKIES_FILE) {
+      args.splice(0, 0, '--cookies', config.YT_DLP_COOKIES_FILE);
+    }
+
+    const subprocess = execa('yt-dlp', args);
+
+    subprocess.stdout?.on('data', displayProgress('stdout'));
+    subprocess.stderr?.on('data', displayProgress('stderr'));
+
+    await subprocess;
+    process.stdout.write('\n');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    if (message.includes('command not found') || message.includes('ENOENT')) {
+      throw new Error('yt-dlp is required. Install it: https://github.com/yt-dlp/yt-dlp');
+    }
+
+    if (message.includes('Private video') || message.includes('Sign in')) {
+      throw new Error(`Video "${videoId}" is private and cannot be downloaded.`);
+    }
+
+    if (message.includes('not available in your country') || message.includes('geo')) {
+      throw new Error(`Video "${videoId}" is geo-blocked in your region.`);
+    }
+
+    throw new Error(`Download failed: ${message}`);
+  }
+
+  log.info(`Download complete: ${outputPath}`);
+  return outputPath;
+}
+
+/**
+ * Downloads a single segment using yt-dlp --download-sections.
+ */
+async function downloadSegment(
+  videoId: string,
+  segment: RankedSegment,
+  index: number,
+  customPath?: string,
+): Promise<string> {
+  const downloadDir = customPath || config.DOWNLOAD_DIR;
+  await fs.mkdir(downloadDir, { recursive: true });
+
+  const adjustedStart = Math.max(0, segment.start + config.TIMESTAMP_OFFSET_SECONDS);
+  const adjustedEnd = Math.max(adjustedStart + 1, segment.end + config.TIMESTAMP_OFFSET_SECONDS);
+  const startInt = Math.floor(adjustedStart);
+  const endInt = Math.ceil(adjustedEnd);
+  const outputPath = join(downloadDir, `${videoId}_${startInt}_${endInt}.mp4`);
+
+  try {
+    await fs.access(outputPath);
+    log.info(`Segment ${index + 1}/${index} already downloaded: ${outputPath}`);
+    return outputPath;
+  } catch {}
+
+  const startTs = formatTimestamp(adjustedStart);
+  const endTs = formatTimestamp(adjustedEnd);
+
+  log.info(`Downloading segment ${index + 1}: ${startTs} - ${endTs} (${segment.reason})`);
+  log.info(`  Requested: ${segment.start.toFixed(2)}s - ${segment.end.toFixed(2)}s`);
+  if (config.TIMESTAMP_OFFSET_SECONDS !== 0) {
+    log.info(
+      `  Adjusted: ${adjustedStart.toFixed(2)}s - ${adjustedEnd.toFixed(2)}s (offset: ${config.TIMESTAMP_OFFSET_SECONDS}s)`,
+    );
+  }
+
+  try {
+    const args = [
+      '-f',
+      'bestvideo[ext=mp4]+bestaudio[ext=m4a]/best[ext=mp4]',
+      '--merge-output-format',
+      'mp4',
+      '--download-sections',
+      `*${startTs}-${endTs}`,
+      '-o',
+      outputPath,
+      '--no-playlist',
+      '--newline',
+      `https://www.youtube.com/watch?v=${videoId}`,
+    ];
+
+    if (config.YT_DLP_COOKIES_FROM_BROWSER) {
+      args.splice(0, 0, '--cookies-from-browser', config.YT_DLP_COOKIES_FROM_BROWSER);
+    } else if (config.YT_DLP_COOKIES_FILE) {
+      args.splice(0, 0, '--cookies', config.YT_DLP_COOKIES_FILE);
+    }
+
+    const subprocess = execa('yt-dlp', args);
+
+    subprocess.stdout?.on('data', displayProgress('stdout'));
+    subprocess.stderr?.on('data', displayProgress('stderr'));
+
+    await subprocess;
+    process.stdout.write('\n');
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+
+    if (message.includes('command not found') || message.includes('ENOENT')) {
+      throw new Error('yt-dlp is required. Install it: https://github.com/yt-dlp/yt-dlp');
+    }
+
+    if (message.includes('Private video') || message.includes('Sign in')) {
+      throw new Error(`Video "${videoId}" is private and cannot be downloaded.`);
+    }
+
+    if (message.includes('not available in your country') || message.includes('geo')) {
+      throw new Error(`Video "${videoId}" is geo-blocked in your region.`);
+    }
+
+    throw new Error(`Segment download failed: ${message}`);
+  }
+
+  log.info(`Segment complete: ${outputPath}`);
+  return outputPath;
+}
+
+/**
+ * Downloads multiple segments in parallel.
+ */
+async function downloadSegments(
+  videoId: string,
+  segments: RankedSegment[],
+  customPath?: string,
+): Promise<string[]> {
+  if (segments.length === 0) {
+    return [];
+  }
+
+  const limit = pLimit(Math.min(config.LLM_CONCURRENCY, 3));
+  const results: Array<PromiseSettledResult<string>> = await Promise.allSettled(
+    segments.map((segment, index) =>
+      limit(() => downloadSegment(videoId, segment, index, customPath)),
+    ),
+  );
+
+  const paths: string[] = [];
+  for (let i = 0; i < results.length; i++) {
+    const result = results[i];
+    const segment = segments[i];
+    if (result.status === 'fulfilled') {
+      paths.push(result.value);
+    } else {
+      const reason = result.reason instanceof Error ? result.reason.message : String(result.reason);
+      log.warn(
+        `Failed to download segment [${formatTimestamp(segment.start)} – ${formatTimestamp(segment.end)}] (rank ${segment.rank}): ${reason}`,
+      );
+    }
+  }
+
+  return paths;
+}
+
+/**
+ * Downloads a YouTube video based on the specified mode.
+ *
+ * @param videoId - 11-character YouTube video ID
+ * @param mode - Download mode: 'all' (full video) or 'segments' (individual clips)
+ * @param segments - Ranked segments (required when mode is 'segments')
+ * @param customPath - Custom output directory (optional, overrides config defaults)
+ * @returns Download result containing the mode and either path or paths
+ */
+export async function downloadVideo(
+  videoId: string,
+  mode: DownloadMode = 'all',
+  segments: RankedSegment[] = [],
+  customPath?: string,
+): Promise<DownloadResult> {
+  if (mode === 'all') {
+    const path = await downloadFullVideo(videoId, customPath);
+    return { mode: 'all', path };
+  }
+
+  if (mode === 'segments') {
+    if (segments.length === 0) {
+      log.warn('No segments provided for download-segments mode. Skipping download.');
+      return { mode: 'segments', paths: [] };
+    }
+
+    log.info(`Downloading ${segments.length} segments in parallel...`);
+    const paths = await downloadSegments(videoId, segments, customPath);
+    return { mode: 'segments', paths };
+  }
+
+  throw new Error(`Invalid download mode: ${mode}`);
+}

package/src/types/audio.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+export const AudioEventSchema = z.object({
+  time: z.number(),
+  event: z.string(),
+  confidence: z.number().min(0).max(1),
+  source: z.enum(['gemini', 'yamnet', 'whisper']),
+});
+export type AudioEvent = z.infer<typeof AudioEventSchema>;
+
+export const MergedCandidateSchema = z.object({
+  start: z.number(),
+  end: z.number(),
+  score: z.number().min(1).max(10),
+  source: z.enum(['transcript', 'audio', 'both']),
+  reason: z.string(),
+  audio_event: z.string().optional(),
+});
+export type MergedCandidate = z.infer<typeof MergedCandidateSchema>;

package/src/types/cli.ts

@@ -0,0 +1,22 @@
+/**
+ * Parsed CLI argument shape.
+ * Defined here so both `src/cli.ts` (which creates it) and
+ * `src/pipeline/runner.ts` (which consumes it) share a single source of truth.
+ */
+export interface CliArgs {
+  url: string | undefined;
+  clip: boolean;
+  downloadSections: 'all' | number | undefined;
+  localVideo?: string;
+  videoPath: string | undefined;
+  threshold: number | undefined;
+  topN: number | undefined;
+  maxDuration: number | undefined;
+  maxChunks: number | undefined;
+  maxParallel: number | undefined;
+  outputJson: string | undefined;
+  noCache: boolean;
+  noAudio: boolean;
+  gameProfile?: string;
+  help: boolean;
+}