@thunderkiller/video-clipper 1.1.0

package/dist/services/transcriptFetcher/index.js

@@ -0,0 +1,124 @@
+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';
+/**
+ * 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) {
+    const lines = vttContent.split(/\r?\n/);
+    const result = [];
+    // 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 = [];
+            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) {
+    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/dist/services/urlParser/index.js

@@ -0,0 +1,46 @@
+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) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new Error(`Invalid URL: "${url}"`);
+    }
+    const { hostname, pathname, searchParams } = parsed;
+    const host = hostname.replace(/^www\./, '');
+    let videoId = 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/dist/services/videoDownloader/index.js

@@ -0,0 +1,212 @@
+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';
+/**
+ * Formats a timestamp for yt-dlp --download-sections.
+ * Converts seconds to HH:MM:SS.mmm format with millisecond precision.
+ */
+function formatTimestamp(seconds) {
+    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) {
+    return (data) => {
+        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, customPath) {
+    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, segment, index, customPath) {
+    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, segments, customPath) {
+    if (segments.length === 0) {
+        return [];
+    }
+    const limit = pLimit(Math.min(config.LLM_CONCURRENCY, 3));
+    const results = await Promise.allSettled(segments.map((segment, index) => limit(() => downloadSegment(videoId, segment, index, customPath))));
+    const paths = [];
+    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, mode = 'all', segments = [], customPath) {
+    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/dist/types/audio.js

@@ -0,0 +1,15 @@
+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 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(),
+});

package/dist/types/cli.js

@@ -0,0 +1 @@
+export {};

package/dist/types/config.js

@@ -0,0 +1,150 @@
+import { z } from 'zod';
+const LLM_PROVIDERS = [
+    'openai',
+    'anthropic',
+    'google',
+    'xai',
+    'mistral',
+    'groq',
+    'zai',
+    'openrouter',
+    'custom',
+];
+/** Map each provider to the env var name that holds its API key. */
+const PROVIDER_KEY_MAP = {
+    openai: 'OPENAI_API_KEY',
+    anthropic: 'ANTHROPIC_API_KEY',
+    google: 'GOOGLE_GENERATIVE_AI_API_KEY',
+    xai: 'XAI_API_KEY',
+    mistral: 'MISTRAL_API_KEY',
+    groq: 'GROQ_API_KEY',
+    zai: 'ZAI_API_KEY',
+    openrouter: 'OPENROUTER_API_KEY',
+    custom: 'CUSTOM_OPENAI_API_KEY',
+};
+export const ConfigSchema = z
+    .object({
+    // --- Provider selection ---
+    LLM_PROVIDER: z.enum(LLM_PROVIDERS).default('openai'),
+    // --- Per-provider API keys (all optional at schema level; enforced via superRefine) ---
+    OPENAI_API_KEY: z.string().optional(),
+    ANTHROPIC_API_KEY: z.string().optional(),
+    GOOGLE_GENERATIVE_AI_API_KEY: z.string().optional(),
+    XAI_API_KEY: z.string().optional(),
+    MISTRAL_API_KEY: z.string().optional(),
+    GROQ_API_KEY: z.string().optional(),
+    ZAI_API_KEY: z.string().optional(),
+    OPENROUTER_API_KEY: z.string().optional(),
+    CUSTOM_OPENAI_API_KEY: z.string().optional(),
+    CUSTOM_OPENAI_BASE_URL: z.string().url().optional(),
+    // --- Tunable parameters ---
+    SCORE_THRESHOLD: z.coerce.number().min(1).max(10).default(7),
+    TOP_N_SEGMENTS: z.coerce.number().min(1).default(10),
+    CHUNK_LENGTH_SEC: z.coerce.number().min(10).default(120),
+    CHUNK_OVERLAP_SEC: z.coerce.number().min(0).default(20),
+    MICRO_BLOCK_SEC: z.coerce.number().min(5).default(15),
+    LLM_MODEL: z.string().default('gpt-4o'),
+    LLM_MAX_RETRIES: z.coerce.number().min(0).default(3),
+    DOWNLOAD_DIR: z.string().default('downloads/'),
+    OUTPUT_DIR: z.string().default('outputs/'),
+    CACHE_DIR: z.string().default('outputs/cache'),
+    // --- Output dumping ---
+    DUMP_OUTPUTS: z.coerce.boolean().default(true),
+    // --- LLM evaluation limits ---
+    MAX_CHUNKS: z.coerce.number().min(1).optional(),
+    LLM_CONCURRENCY: z.coerce.number().min(1).default(3),
+    CLIP_CONCURRENCY: z.coerce.number().min(1).default(1),
+    // --- Custom system prompt (overrides the default if set) ---
+    LLM_SYSTEM_PROMPT: z.string().optional(),
+    // --- Gemini model used for audio event detection ---
+    AUDIO_GEMINI_MODEL: z.string().default('gemini-2.5-flash'),
+    // --- Extra instructions appended to the Gemini audio detection prompt ---
+    AUDIO_EXTRA_INSTRUCTIONS: z.string().optional(),
+    // --- Download mode for yt-dlp ---
+    DOWNLOAD_SECTIONS_MODE: z.union([z.literal('all'), z.number().int().positive()]).default('all'),
+    // --- FFmpeg paths (optional, for custom ffmpeg/ffprobe locations) ---
+    FFMPEG_PATH: z.string().optional(),
+    FFPROBE_PATH: z.string().optional(),
+    // --- FFmpeg encoding preset for clip generation ---
+    FFMPEG_PRESET: z
+        .enum(['ultrafast', 'superfast', 'veryfast', 'fast', 'medium', 'slow', 'slower'])
+        .default('fast'),
+    // --- Timestamp offset for clips (adjusts if transcript is misaligned with video) ---
+    TIMESTAMP_OFFSET_SECONDS: z.coerce.number().default(0),
+    // --- Transcript provider ---
+    // Comma-separated ordered fallback chain: "ytdlp" | "whisper" | "ytdlp,whisper" etc.
+    // First provider that succeeds wins; subsequent providers are tried only on failure.
+    TRANSCRIPT_PROVIDER: z
+        .string()
+        .default('ytdlp')
+        .refine((v) => {
+        const parts = v
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return parts.length > 0 && parts.every((p) => ['ytdlp', 'whisper', 'gemini'].includes(p));
+    }, {
+        message: 'TRANSCRIPT_PROVIDER must be a comma-separated list of: ytdlp, whisper, gemini (e.g. "ytdlp")',
+    }),
+    // --- Audio event detection ---
+    AUDIO_DETECTION_ENABLED: z.coerce.boolean().default(true),
+    // Comma-separated ordered fallback chain: "gemini,whisper" | "yamnet" | "gemini" etc.
+    // Legacy value "both" is accepted and mapped to "gemini,whisper" at runtime.
+    AUDIO_PROVIDER: z
+        .string()
+        .default('gemini,whisper')
+        .refine((v) => {
+        const legacy = v.trim() === 'both';
+        if (legacy)
+            return true;
+        const parts = v
+            .split(',')
+            .map((s) => s.trim())
+            .filter(Boolean);
+        return (parts.length > 0 && parts.every((p) => ['gemini', 'whisper', 'yamnet'].includes(p)));
+    }, {
+        message: 'AUDIO_PROVIDER must be a comma-separated list of: gemini, whisper, yamnet (e.g. "gemini,whisper")',
+    }),
+    AUDIO_WHISPER_MODEL: z.enum(['tiny', 'base', 'small', 'medium', 'large-v3']).default('medium'),
+    AUDIO_CONFIDENCE_THRESHOLD: z.coerce.number().min(0).max(1).default(0.3),
+    AUDIO_CLIP_PRE_ROLL: z.coerce.number().min(0).default(5),
+    AUDIO_CLIP_POST_ROLL: z.coerce.number().min(0).default(15),
+    AUDIO_LLM_BOOST_WINDOW: z.coerce.number().min(0).default(10),
+    AUDIO_LLM_SCORE_BOOST: z.coerce.number().min(0).default(2),
+    // --- Game profile ---
+    GAME_PROFILE: z.enum(['valorant', 'fps', 'boss_fight', 'general']).default('general'),
+    // --- yt-dlp cookie support (for bot detection / auth) ---
+    YT_DLP_COOKIES_FROM_BROWSER: z
+        .enum(['chrome', 'firefox', 'safari', 'brave', 'edge', 'opera', 'chromium'])
+        .optional(),
+    YT_DLP_COOKIES_FILE: z.string().optional(),
+})
+    .superRefine((data, ctx) => {
+    const provider = data.LLM_PROVIDER;
+    const keyName = PROVIDER_KEY_MAP[provider];
+    const keyValue = data[keyName];
+    if (!keyValue || keyValue.trim() === '') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [keyName],
+            message: `${keyName} is required when LLM_PROVIDER is "${provider}"`,
+        });
+    }
+    // custom provider also requires a base URL
+    if (provider === 'custom' &&
+        (!data.CUSTOM_OPENAI_BASE_URL || data.CUSTOM_OPENAI_BASE_URL.trim() === '')) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['CUSTOM_OPENAI_BASE_URL'],
+            message: 'CUSTOM_OPENAI_BASE_URL is required when LLM_PROVIDER is "custom"',
+        });
+    }
+    // Validate cookie config: only one method allowed at a time
+    if (data.YT_DLP_COOKIES_FROM_BROWSER && data.YT_DLP_COOKIES_FILE) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['YT_DLP_COOKIES_FROM_BROWSER'],
+            message: 'Cannot set both YT_DLP_COOKIES_FROM_BROWSER and YT_DLP_COOKIES_FILE. Use only one.',
+        });
+    }
+});

package/dist/types/index.js

@@ -0,0 +1,5 @@
+export { ConfigSchema } from './config.js';
+export { TranscriptLineSchema, MicroBlockSchema, LLMChunkSchema } from './transcript.js';
+export { AnalyzedSegmentSchema, RankedSegmentSchema, ChunkEvaluationSchema } from './segment.js';
+export { AudioEventSchema, MergedCandidateSchema } from './audio.js';
+export { VideoMetadataSchema, PipelineResultSchema } from './video.js';

package/dist/types/pipeline.js

@@ -0,0 +1,9 @@
+/**
+ * Pipeline-layer types: stage option bags, result shapes, and the generic
+ * time-window interface from the chunker utility.
+ *
+ * All types here are owned by one pipeline stage but live centrally so the
+ * runner (and any future consumers) can import them without reaching into
+ * individual stage files.
+ */
+export {};

package/dist/types/segment.js

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+export const AnalyzedSegmentSchema = z.object({
+    interesting: z.boolean(),
+    score: z.number().min(1).max(10),
+    reason: z.string(),
+    clip_start: z.number(), // seconds
+    clip_end: z.number(), // seconds
+});
+export const RankedSegmentSchema = z.object({
+    rank: z.number().int().min(1),
+    start: z.number(), // seconds
+    end: z.number(), // seconds
+    score: z.number().min(1).max(10),
+    reason: z.string(),
+    source: z.enum(['transcript', 'audio', 'both']),
+    audio_event: z.string().optional(),
+});
+const ChunkEvaluationBaseSchema = z.object({
+    chunk_index: z.number().int().min(0),
+    chunk_start: z.number(), // seconds
+    chunk_end: z.number(), // seconds
+});
+export const ChunkEvaluationSchema = z.discriminatedUnion('status', [
+    ChunkEvaluationBaseSchema.extend({
+        status: z.literal('success'),
+        interesting: z.boolean(),
+        score: z.number().min(1).max(10),
+        reason: z.string(),
+        clip_start: z.number(),
+        clip_end: z.number(),
+    }),
+    ChunkEvaluationBaseSchema.extend({
+        status: z.literal('failed'),
+        error: z.string(),
+    }),
+]);

package/dist/types/transcript.js

@@ -0,0 +1,16 @@
+import { z } from 'zod';
+export const TranscriptLineSchema = z.object({
+    text: z.string(),
+    start: z.number(), // seconds (normalized from offset ms)
+    duration: z.number(), // seconds (normalized from duration ms)
+});
+export const MicroBlockSchema = z.object({
+    start: z.number(), // seconds
+    end: z.number(), // seconds
+    text: z.string(),
+});
+export const LLMChunkSchema = z.object({
+    start: z.number(), // seconds
+    end: z.number(), // seconds
+    text: z.string(),
+});

package/dist/types/video.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { RankedSegmentSchema, ChunkEvaluationSchema } from './segment.js';
+export const VideoMetadataSchema = z.object({
+    videoId: z.string().length(11),
+    title: z.string(),
+    duration: z.number(), // seconds
+});
+export const PipelineResultSchema = z.object({
+    video_id: z.string().length(11),
+    title: z.string(),
+    duration: z.number(), // seconds
+    chunk_evaluations: z.array(ChunkEvaluationSchema),
+    segments: z.array(RankedSegmentSchema),
+});