@thunderkiller/video-clipper 1.2.0 → 1.4.0

package/src/services/transcriptDetector/index.ts

@@ -1,122 +0,0 @@
-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,
-  TranscriptDetectorResult,
-} from '../../types/index.js';
-
-/**
- * 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[];
-
-    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 };
-  }
-
-  /**
-   * 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

@@ -1,147 +0,0 @@
-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 to match HH:MM:SS.mmm --> HH:MM:SS.mmm timestamp lines */
-  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;
-
-      i++;
-      const textLines: string[] = [];
-      while (i < lines.length && lines[i].trim() !== '') {
-        textLines.push(lines[i].trim());
-        i++;
-      }
-
-      const rawText = textLines.join(' ');
-
-      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);
-
-      /** Skip duplicate cues - YouTube VTT often repeats 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}`);
-    }
-
-    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

@@ -1,52 +0,0 @@
-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}"`);
-  }
-
-  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

@@ -1,268 +0,0 @@
-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, DownloadMode, DownloadResult } from '../../types/index.js';
-
-/**
- * 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/analyzer.ts

@@ -1,23 +0,0 @@
-import type { TranscriptLine, MicroBlock, LLMChunk, ChunkEvaluation } from './index.js';
-
-export interface LLMAnalyzerResult {
-  lines: TranscriptLine[];
-  microBlocks: MicroBlock[];
-  chunks: LLMChunk[];
-  chunkEvals: ChunkEvaluation[];
-}
-
-export interface LLMAnalyzerOpts {
-  videoId: string;
-  audioPath: string | null;
-  audioEvents: import('./audio.js').AudioEvent[];
-  maxChunks?: number;
-  maxParallel: number;
-  noCache: boolean;
-}
-
-export interface TranscriptDetectorResult {
-  lines: TranscriptLine[];
-  microBlocks: MicroBlock[];
-  chunks: LLMChunk[];
-}

package/src/types/audio.ts

@@ -1,19 +0,0 @@
-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/cache.ts

@@ -1,8 +0,0 @@
-import { z } from 'zod';
-
-export const SegmentRefinementSchema = z.object({
-  refined_start: z.number(),
-  refined_end: z.number(),
-});
-
-export type SegmentRefinement = z.infer<typeof SegmentRefinementSchema>;

package/src/types/cli.ts

@@ -1,22 +0,0 @@
-/**
- * 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;
-}