@thunderkiller/video-clipper 1.2.0 → 1.4.0

package/src/services/llmAnalyzer/index.ts

@@ -1,231 +0,0 @@
-import { generateObject } from 'ai';
-import pLimit from 'p-limit';
-import { config } from '../../config/index.js';
-import { log } from '../../utils/logger.js';
-import { formatSeconds } from '../../utils/format.js';
-import { getModel } from '../../utils/modelFactory.js';
-import { Cache } from '../../utils/cache.js';
-import { AnalyzedSegmentSchema } from '../../types/index.js';
-import type {
-  LLMChunk,
-  TranscriptLine,
-  AnalyzedSegment,
-  ChunkEvaluation,
-  AudioEvent,
-} from '../../types/index.js';
-
-const BACKOFF_BASE_MS = 1000;
-const BACKOFF_JITTER_MS = 500;
-
-const DEFAULT_SYSTEM_PROMPT = `You are an expert video editor analyzing a YouTube transcript segment.
-
-Identify if this segment contains a potentially interesting moment worth clipping.
-
-Interesting moments include:
-- surprising insights or revelations
-- strong or controversial opinions
-- humor or entertaining storytelling
-- emotional moments
-- key explanations of important concepts
-- "aha" moments or turning points
-
-If audio events are listed in the segment, treat them as strong positive signals —
-they indicate high-action or high-energy moments that are often clip-worthy.`;
-
-function isRateLimitError(err: unknown): boolean {
-  const message = err instanceof Error ? err.message : String(err);
-  return (
-    message.toLowerCase().includes('rate limit') ||
-    message.includes('429') ||
-    message.toLowerCase().includes('too many requests')
-  );
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-/**
- * Builds the user prompt for a single transcript chunk.
- * Semantic scoring hints are omitted when a custom system prompt is in use.
- */
-function buildPrompt(
-  chunk: LLMChunk,
-  chunkLines: TranscriptLine[],
-  chunkAudioEvents: AudioEvent[],
-  isCustomSystemPrompt: boolean,
-): string {
-  const semanticRules = isCustomSystemPrompt
-    ? ''
-    : `- Set interesting=true only if the segment is genuinely compelling
-- Score 1-10 (7+ means worth clipping, 9-10 means viral potential)
-`;
-
-  const transcriptBody =
-    chunkLines.length > 0
-      ? chunkLines.map((l) => `[${l.start.toFixed(1)}s] ${l.text}`).join('\n')
-      : chunk.text;
-
-  const audioSection =
-    chunkAudioEvents.length > 0
-      ? `\nAudio Events Detected (within this segment):\n${chunkAudioEvents
-          .slice()
-          .sort((a, b) => a.time - b.time)
-          .map(
-            (e) => `  [${e.time.toFixed(1)}s] ${e.event} (confidence: ${e.confidence.toFixed(2)})`,
-          )
-          .join('\n')}\n`
-      : '';
-
-  return `Transcript Segment:
-START: ${chunk.start}s
-END: ${chunk.end}s
-
-${transcriptBody}
-${audioSection}
-Rules for your response:
-${semanticRules}- clip_start and clip_end must be within [${chunk.start}, ${chunk.end}]
-- clip_start must be less than clip_end`;
-}
-
-/**
- * Analyzes a single LLM chunk with exponential backoff + jitter on rate-limit errors.
- */
-async function analyzeChunk(
-  chunk: LLMChunk,
-  chunkLines: TranscriptLine[],
-  chunkAudioEvents: AudioEvent[],
-  noCache: boolean,
-  chunkIndex: number,
-): Promise<AnalyzedSegment> {
-  if (!noCache) {
-    const cache = new Cache(config.CACHE_DIR);
-    const cached = await cache.readChunk(chunk, chunkAudioEvents);
-    if (cached && cached.status === 'success') {
-      log.info(`[chunk] cache hit (${formatSeconds(chunk.start)}–${formatSeconds(chunk.end)})`);
-      return {
-        interesting: cached.interesting,
-        score: cached.score,
-        reason: cached.reason,
-        clip_start: cached.clip_start,
-        clip_end: cached.clip_end,
-      };
-    }
-  }
-
-  let lastError: unknown;
-
-  for (let attempt = 0; attempt <= config.LLM_MAX_RETRIES; attempt++) {
-    try {
-      const prompt = buildPrompt(chunk, chunkLines, chunkAudioEvents, !!config.LLM_SYSTEM_PROMPT);
-      const { object } = await generateObject({
-        model: getModel(),
-        schema: AnalyzedSegmentSchema,
-        system: config.LLM_SYSTEM_PROMPT ?? DEFAULT_SYSTEM_PROMPT,
-        prompt: prompt,
-        maxRetries: 0,
-      });
-      log.info(
-        `Chunk ${chunkIndex} analysis complete: interesting=${object.interesting}, score=${object.score}, reason=${object.reason}`,
-      );
-      if (!noCache) {
-        const evaluation: ChunkEvaluation = {
-          status: 'success' as const,
-          chunk_index: chunkIndex,
-          chunk_start: chunk.start,
-          chunk_end: chunk.end,
-          interesting: object.interesting,
-          score: object.score,
-          reason: object.reason,
-          clip_start: object.clip_start,
-          clip_end: object.clip_end,
-        };
-        await new Cache(config.CACHE_DIR).writeChunk(chunk, evaluation, chunkAudioEvents);
-      }
-      return object;
-    } catch (err) {
-      lastError = err;
-
-      if (isRateLimitError(err) && attempt < config.LLM_MAX_RETRIES) {
-        const delay = BACKOFF_BASE_MS * Math.pow(2, attempt) + Math.random() * BACKOFF_JITTER_MS;
-        log.warn(
-          `[chunk] Rate limit hit (attempt ${attempt + 1}/${config.LLM_MAX_RETRIES + 1}). ` +
-            `Retrying in ${Math.round(delay)}ms...`,
-        );
-        await sleep(delay);
-        continue;
-      } else {
-        log.error(`[chunk] Analysis failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
-
-      throw err;
-    }
-  }
-
-  throw lastError;
-}
-
-/**
- * Analyzes all LLM chunks via Promise.allSettled — one failure never aborts the rest.
- * Each chunk receives only the transcript lines and audio events within its window.
- * Pass noCache=true to bypass the on-disk chunk cache.
- */
-export async function analyzeChunks(
-  chunks: LLMChunk[],
-  lines: TranscriptLine[],
-  audioEvents: AudioEvent[],
-  concurrency: number,
-  noCache = false,
-): Promise<ChunkEvaluation[]> {
-  log.info(
-    `Analyzing ${chunks.length} chunk${chunks.length !== 1 ? 's' : ''} (max ${concurrency} parallel)...`,
-  );
-
-  const limit = pLimit(concurrency);
-  const results = await Promise.allSettled(
-    chunks.map((chunk, i) => {
-      const chunkLines = lines.filter((l) => l.start >= chunk.start && l.start < chunk.end);
-      const chunkAudioEvents = audioEvents.filter(
-        (e) => e.time >= chunk.start && e.time < chunk.end,
-      );
-      return limit(() => analyzeChunk(chunk, chunkLines, chunkAudioEvents, noCache, i));
-    }),
-  );
-
-  let succeeded = 0;
-  const evaluations: ChunkEvaluation[] = await Promise.all(
-    results.map(async (result, i) => {
-      const chunk = chunks[i];
-      if (result.status === 'fulfilled') {
-        succeeded++;
-        const seg: AnalyzedSegment = result.value;
-        const evaluation: ChunkEvaluation = {
-          status: 'success' as const,
-          chunk_index: i,
-          chunk_start: chunk.start,
-          chunk_end: chunk.end,
-          interesting: seg.interesting,
-          score: seg.score,
-          reason: seg.reason,
-          clip_start: seg.clip_start,
-          clip_end: seg.clip_end,
-        };
-        return evaluation;
-      } else {
-        const error =
-          result.reason instanceof Error ? result.reason.message : String(result.reason);
-        log.warn(`[chunk ${i}] LLM analysis skipped: ${error}`);
-        return {
-          status: 'failed' as const,
-          chunk_index: i,
-          chunk_start: chunk.start,
-          chunk_end: chunk.end,
-          error,
-        };
-      }
-    }),
-  );
-
-  log.info(`Analysis complete: ${succeeded}/${chunks.length} chunks succeeded`);
-  return evaluations;
-}

package/src/services/metadataExtractor/index.ts

@@ -1,83 +0,0 @@
-import { execa } from 'execa';
-import { config } from '../../config/index.js';
-import { log } from '../../utils/logger.js';
-import type { VideoMetadata } from '../../types/index.js';
-
-const OEMBED_URL = 'https://www.youtube.com/oembed';
-
-interface YtDlpJson {
-  title: string;
-  duration: number;
-}
-
-interface OEmbedResponse {
-  title: string;
-}
-
-/**
- * Attempts to extract video metadata via yt-dlp --dump-json.
- * Returns null if yt-dlp is not installed or the call fails.
- */
-async function extractViaYtDlp(videoId: string): Promise<VideoMetadata | null> {
-  try {
-    const args = ['--dump-json', '--no-playlist', `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);
-    }
-
-    const { stdout } = await execa('yt-dlp', args);
-    const data = JSON.parse(stdout) as YtDlpJson;
-    return {
-      videoId,
-      title: data.title,
-      duration: data.duration,
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    log.warn(`yt-dlp failed for "${videoId}": ${message}`);
-    return null;
-  }
-}
-
-/**
- * Falls back to YouTube oEmbed for the title (no API key needed).
- * Duration is unavailable via oEmbed, so it returns 0 with a warning.
- */
-async function extractViaOEmbed(videoId: string): Promise<VideoMetadata> {
-  const url = `${OEMBED_URL}?url=https://www.youtube.com/watch?v=${videoId}&format=json`;
-  const res = await fetch(url);
-  if (!res.ok) {
-    throw new Error(`oEmbed request failed for "${videoId}": HTTP ${res.status}`);
-  }
-  const data = (await res.json()) as OEmbedResponse;
-  log.warn(
-    `yt-dlp unavailable — duration unknown for "${videoId}". Install yt-dlp for full metadata.`,
-  );
-  return {
-    videoId,
-    title: data.title,
-    duration: 0,
-  };
-}
-
-/**
- * Extracts video metadata (title, duration) for a given YouTube video ID.
- *
- * Strategy:
- * 1. Try yt-dlp --dump-json (full metadata, requires yt-dlp installed)
- * 2. Fall back to YouTube oEmbed API (title only, duration = 0)
- *
- * @throws {Error} if both strategies fail
- */
-export async function extractMetadata(videoId: string): Promise<VideoMetadata> {
-  const ytDlpResult = await extractViaYtDlp(videoId);
-  if (ytDlpResult) {
-    return ytDlpResult;
-  }
-
-  log.warn(`yt-dlp failed for "${videoId}", falling back to oEmbed...`);
-  return extractViaOEmbed(videoId);
-}

package/src/services/segmentRanker/index.ts

@@ -1,88 +0,0 @@
-import type { MergedCandidate, RankedSegment } from '../../types/index.js';
-
-function overlapSeconds(aStart: number, aEnd: number, bStart: number, bEnd: number): number {
-  const start = Math.max(aStart, bStart);
-  const end = Math.min(aEnd, bEnd);
-  return Math.max(0, end - start);
-}
-
-function significantlyOverlaps(
-  aStart: number,
-  aEnd: number,
-  bStart: number,
-  bEnd: number,
-  aSource: string,
-  bSource: string,
-): boolean {
-  const overlap = overlapSeconds(aStart, aEnd, bStart, bEnd);
-  if (overlap === 0) return false;
-
-  const aDuration = aEnd - aStart;
-  const bDuration = bEnd - bStart;
-
-  const isAudioSource = aSource === 'audio' || bSource === 'audio';
-
-  if (isAudioSource) {
-    return overlap > 8;
-  }
-
-  return overlap / aDuration > 0.5 || overlap / bDuration > 0.5;
-}
-
-function deduplicateSegments(
-  segments: Array<{
-    start: number;
-    end: number;
-    score: number;
-    reason: string;
-    source: string;
-    audio_event?: string;
-  }>,
-): Array<{
-  start: number;
-  end: number;
-  score: number;
-  reason: string;
-  source: string;
-  audio_event?: string;
-}> {
-  const kept: typeof segments = [];
-
-  for (const candidate of segments) {
-    const dominated = kept.some((existing) =>
-      significantlyOverlaps(
-        existing.start,
-        existing.end,
-        candidate.start,
-        candidate.end,
-        existing.source,
-        candidate.source,
-      ),
-    );
-    if (!dominated) {
-      kept.push(candidate);
-    }
-  }
-
-  return kept;
-}
-
-export function rankSegments(
-  segments: MergedCandidate[],
-  threshold: number,
-  topN: number,
-): RankedSegment[] {
-  const filtered = segments.filter((s) => s.score >= threshold).sort((a, b) => b.score - a.score);
-
-  const deduped = deduplicateSegments(filtered);
-
-  return deduped.slice(0, topN).map((s, i) => ({
-    rank: i + 1,
-    start: s.start,
-    end: s.end,
-    score: s.score,
-    reason: s.reason,
-    source: s.source as 'transcript' | 'audio' | 'both',
-    audio_event: s.audio_event,
-  }));
-}

package/src/services/signalMerger/index.ts

@@ -1,53 +0,0 @@
-import type { MergedCandidate } from '../../types/index.js';
-import type { ChunkEvaluation } from '../../types/index.js';
-import type { AudioEvent } from '../../types/index.js';
-import { config } from '../../config/index.js';
-
-export function mergeSignals(
-  llmSegments: ChunkEvaluation[],
-  audioEvents: AudioEvent[],
-  boostWindow?: number,
-  scoreBoost?: number,
-  preRoll?: number,
-  postRoll?: number,
-): MergedCandidate[] {
-  const candidates: MergedCandidate[] = [];
-  const windowSec = boostWindow ?? config.AUDIO_LLM_BOOST_WINDOW;
-  const boost = scoreBoost ?? config.AUDIO_LLM_SCORE_BOOST;
-  const pre = preRoll ?? config.AUDIO_CLIP_PRE_ROLL;
-  const post = postRoll ?? config.AUDIO_CLIP_POST_ROLL;
-
-  const successfulSegments = llmSegments.filter((s) => s.status === 'success');
-
-  for (const seg of successfulSegments) {
-    if (!seg.interesting) continue;
-
-    const nearby = audioEvents.filter((e) => Math.abs(e.time - seg.clip_start) < windowSec);
-
-    candidates.push({
-      start: seg.clip_start,
-      end: seg.clip_end,
-      score: Math.min(10, seg.score + (nearby.length > 0 ? boost : 0)),
-      source: nearby.length > 0 ? 'both' : 'transcript',
-      reason: seg.reason,
-      audio_event: nearby.length > 0 ? nearby[0].event : undefined,
-    });
-  }
-
-  for (const evt of audioEvents) {
-    const hasLLM = successfulSegments.some((s) => Math.abs(s.clip_start - evt.time) < windowSec);
-
-    if (!hasLLM) {
-      candidates.push({
-        start: Math.max(0, evt.time - pre),
-        end: evt.time + post,
-        score: Math.round(evt.confidence * 10),
-        source: 'audio',
-        reason: `Audio event: ${evt.event} (${(evt.confidence * 100).toFixed(0)}% confidence)`,
-        audio_event: evt.event,
-      });
-    }
-  }
-
-  return candidates;
-}

package/src/services/transcriptAnalyzers/base.ts

@@ -1,26 +0,0 @@
-import type { TranscriptLine } from '../../types/index.js';
-
-/**
- * Contract every transcript analyzer implementation must satisfy.
- *
- * Each concrete analyzer (YtDlp, Whisper, Gemini) extends this class and
- * implements `detect()`. The `source` property tags the lines it returns so
- * downstream logging knows which backend produced them.
- *
- * Usage:
- *   const analyzer = new YtDlpTranscriptAnalyzer();
- *   const lines    = await analyzer.detect(videoId, null);
- */
-export abstract class TranscriptAnalyzer {
-  abstract readonly source: string;
-
-  /**
-   * Fetch transcript lines for the given video.
-   *
-   * @param videoId   - YouTube video ID (no URL)
-   * @param audioPath - Path to the downloaded WAV on disk, or null if audio
-   *                    is not yet available (e.g. ytdlp path has no audio dep)
-   * @returns Array of transcript lines sorted by start time
-   */
-  abstract detect(videoId: string, audioPath: string | null): Promise<TranscriptLine[]>;
-}

package/src/services/transcriptAnalyzers/factory.ts

@@ -1,66 +0,0 @@
-import { log } from '../../utils/logger.js';
-import { TranscriptAnalyzer } from './base.js';
-import { YtDlpTranscriptAnalyzer } from './ytdlp.js';
-import { WhisperTranscriptAnalyzer } from './whisper.js';
-import { GeminiTranscriptAnalyzer } from './gemini.js';
-import type { TranscriptProviderName } from '../../types/index.js';
-
-const KNOWN_PROVIDERS = new Set<TranscriptProviderName>(['ytdlp', 'whisper', 'gemini']);
-
-/**
- * Parses the TRANSCRIPT_PROVIDER config string into an ordered list of provider names.
- *
- * Accepts a comma-separated list: "ytdlp,whisper" → ['ytdlp', 'whisper']
- * Single values still work:        "ytdlp"         → ['ytdlp']
- */
-export function parseTranscriptProviderChain(providerString: string): TranscriptProviderName[] {
-  const names = providerString
-    .split(',')
-    .map((s) => s.trim().toLowerCase())
-    .filter(Boolean);
-
-  if (names.length === 0) {
-    throw new Error(
-      `TRANSCRIPT_PROVIDER is empty. Provide at least one of: ytdlp, whisper, gemini`,
-    );
-  }
-
-  for (const name of names) {
-    if (!KNOWN_PROVIDERS.has(name as TranscriptProviderName)) {
-      throw new Error(
-        `Unknown transcript provider "${name}". Valid options: ytdlp, whisper, gemini (comma-separated for chain)`,
-      );
-    }
-  }
-
-  return names as TranscriptProviderName[];
-}
-
-/**
- * Builds an ordered array of TranscriptAnalyzer instances from a provider chain string.
- *
- * The TranscriptDetector will walk this array in order — if the first analyzer
- * fails, it falls back to the next, and so on.
- *
- * @example
- *   // TRANSCRIPT_PROVIDER=ytdlp,whisper  →  [YtDlpTranscriptAnalyzer, WhisperTranscriptAnalyzer]
- *   const chain = createTranscriptChain(config.TRANSCRIPT_PROVIDER);
- */
-export function createTranscriptChain(providerString: string): TranscriptAnalyzer[] {
-  const names = parseTranscriptProviderChain(providerString);
-
-  return names.map((name) => {
-    switch (name) {
-      case 'ytdlp':
-        return new YtDlpTranscriptAnalyzer();
-      case 'whisper':
-        return new WhisperTranscriptAnalyzer();
-      case 'gemini':
-        log.warn(
-          '[transcript] GeminiTranscriptAnalyzer is not yet implemented — ' +
-            'it will throw if reached in the chain.',
-        );
-        return new GeminiTranscriptAnalyzer();
-    }
-  });
-}

package/src/services/transcriptAnalyzers/gemini.ts

@@ -1,24 +0,0 @@
-import type { TranscriptLine } from '../../types/index.js';
-import { TranscriptAnalyzer } from './base.js';
-
-/**
- * Transcribes a video using Google Gemini's multimodal audio understanding.
- *
- * @stub This implementation is not yet complete. It will:
- *   1. Split the audio file into overlapping chunks
- *   2. Send each chunk to the Gemini audio API for transcription
- *   3. Stitch the returned text segments back into TranscriptLine[]
- *
- * Set TRANSCRIPT_PROVIDER=ytdlp or TRANSCRIPT_PROVIDER=whisper to use a
- * working provider in the meantime.
- */
-export class GeminiTranscriptAnalyzer extends TranscriptAnalyzer {
-  readonly source = 'gemini' as const;
-
-  async detect(_videoId: string, _audioPath: string | null): Promise<TranscriptLine[]> {
-    throw new Error(
-      'GeminiTranscriptAnalyzer is not yet implemented. ' +
-        'Use TRANSCRIPT_PROVIDER=ytdlp or TRANSCRIPT_PROVIDER=whisper instead.',
-    );
-  }
-}

package/src/services/transcriptAnalyzers/index.ts

@@ -1,6 +0,0 @@
-export { TranscriptAnalyzer } from './base.js';
-export { YtDlpTranscriptAnalyzer } from './ytdlp.js';
-export { WhisperTranscriptAnalyzer } from './whisper.js';
-export { GeminiTranscriptAnalyzer } from './gemini.js';
-export { createTranscriptChain, parseTranscriptProviderChain } from './factory.js';
-export type { TranscriptProviderName } from '../../types/index.js';

package/src/services/transcriptAnalyzers/whisper.ts

@@ -1,68 +0,0 @@
-import { execa } from 'execa';
-import { z } from 'zod';
-import { config } from '../../config/index.js';
-import type { TranscriptLine } from '../../types/index.js';
-import { TranscriptAnalyzer } from './base.js';
-import { getPythonBin } from '../audioAnalyzers/whisper.js';
-
-const WhisperSegmentSchema = z.object({
-  text: z.string(),
-  start: z.number(),
-  duration: z.number(),
-});
-
-/**
- * Generates a transcript by running OpenAI Whisper locally on the downloaded
- * audio file, then normalising the output to TranscriptLine[].
- *
- * Requires:
- *   - audioPath must not be null (audio must be downloaded before calling detect)
- *   - pip install openai-whisper
- *
- * The underlying script is `scripts/transcribe_whisper.py` which writes a JSON
- * array of `{text, start, duration}` objects to stdout.
- */
-export class WhisperTranscriptAnalyzer extends TranscriptAnalyzer {
-  readonly source = 'whisper' as const;
-
-  async detect(videoId: string, audioPath: string | null): Promise<TranscriptLine[]> {
-    if (!audioPath) {
-      throw new Error(
-        'WhisperTranscriptAnalyzer requires an audio file. ' +
-          'Ensure downloadAudio() runs before processTranscript() in the pipeline.',
-      );
-    }
-
-    const python = await getPythonBin();
-
-    let stdout: string;
-    try {
-      const result = await execa(python, [
-        'scripts/transcribe_whisper.py',
-        audioPath,
-        config.AUDIO_WHISPER_MODEL,
-      ]);
-      stdout = result.stdout;
-    } catch (err) {
-      const message = err instanceof Error ? err.message : String(err);
-
-      if (message.includes('ModuleNotFoundError') || message.includes('No module named')) {
-        throw new Error(
-          'openai-whisper not installed. Run: pip install openai-whisper\n' +
-            'Or set TRANSCRIPT_PROVIDER=ytdlp in .env to use yt-dlp subtitles instead.',
-        );
-      }
-
-      throw new Error(`Whisper transcription failed for "${videoId}": ${message}`);
-    }
-
-    const raw = JSON.parse(stdout) as unknown[];
-    const segments = raw.map((seg) => WhisperSegmentSchema.parse(seg));
-
-    return segments.map((seg) => ({
-      text: seg.text.trim(),
-      start: seg.start,
-      duration: seg.duration,
-    }));
-  }
-}

package/src/services/transcriptAnalyzers/ytdlp.ts

@@ -1,19 +0,0 @@
-import { fetchTranscript } from '../transcriptFetcher/index.js';
-import type { TranscriptLine } from '../../types/index.js';
-import { TranscriptAnalyzer } from './base.js';
-
-/**
- * Fetches the YouTube transcript via yt-dlp auto-generated subtitles (VTT).
- *
- * This is the default transcript provider. It does not use the audio file —
- * the `audioPath` parameter is accepted but ignored.
- *
- * Requires: yt-dlp installed and available on PATH.
- */
-export class YtDlpTranscriptAnalyzer extends TranscriptAnalyzer {
-  readonly source = 'ytdlp' as const;
-
-  async detect(videoId: string, _audioPath: string | null): Promise<TranscriptLine[]> {
-    return fetchTranscript(videoId);
-  }
-}