@thunderkiller/video-clipper 1.1.0

package/dist/utils/cache.js

@@ -0,0 +1,143 @@
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'fs';
+import path from 'path';
+import { z } from 'zod';
+import { log } from './logger.js';
+import { TranscriptLineSchema, ChunkEvaluationSchema, AudioEventSchema } from '../types/index.js';
+// ---------------------------------------------------------------------------
+// Internal cache-key helpers
+// ---------------------------------------------------------------------------
+/**
+ * Serializes audio events into a stable string for cache keying.
+ * Events are sorted by time so the key is order-independent.
+ */
+function audioEventsKey(events) {
+    if (events.length === 0)
+        return '';
+    const sorted = [...events].sort((a, b) => a.time - b.time);
+    return JSON.stringify(sorted);
+}
+function hashContent(input) {
+    return createHash('sha256').update(input).digest('hex');
+}
+async function readCacheFile(filePath, schema) {
+    try {
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsed = schema.safeParse(JSON.parse(raw));
+        if (!parsed.success) {
+            log.warn(`[cache] Corrupt entry at ${filePath} — ignoring`);
+            return null;
+        }
+        return parsed.data;
+    }
+    catch {
+        // File not found or unreadable — normal cache miss, stay silent
+        return null;
+    }
+}
+async function writeCacheFile(filePath, data) {
+    try {
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, JSON.stringify(data, null, 2), 'utf-8');
+    }
+    catch (err) {
+        log.warn(`[cache] Failed to write ${filePath}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+const SegmentRefinementSchema = z.object({
+    refined_start: z.number(),
+    refined_end: z.number(),
+});
+/**
+ * Disk-backed cache for all pipeline stages.
+ *
+ * Constructed once in runner.ts with the resolved cache directory and passed
+ * down to each stage that needs caching. Pass `disabled = true` to bypass all
+ * reads and writes (equivalent to --no-cache).
+ */
+export class Cache {
+    cacheDir;
+    disabled;
+    constructor(cacheDir, disabled = false) {
+        this.cacheDir = cacheDir;
+        this.disabled = disabled;
+    }
+    // ---- Transcript ---------------------------------------------------------
+    transcriptPath(videoId) {
+        return path.join(this.cacheDir, 'transcript', `${hashContent(videoId)}.json`);
+    }
+    async readTranscript(videoId) {
+        if (this.disabled)
+            return null;
+        return readCacheFile(this.transcriptPath(videoId), z.array(TranscriptLineSchema));
+    }
+    async writeTranscript(videoId, lines) {
+        if (this.disabled)
+            return;
+        await writeCacheFile(this.transcriptPath(videoId), lines);
+    }
+    // ---- LLM chunk results --------------------------------------------------
+    chunkPath(chunk, chunkAudioEvents = []) {
+        const audioKey = audioEventsKey(chunkAudioEvents);
+        return path.join(this.cacheDir, 'chunks', `${hashContent(`${chunk.start}|${chunk.end}|${chunk.text}|${audioKey}`)}.json`);
+    }
+    async readChunk(chunk, chunkAudioEvents = []) {
+        if (this.disabled)
+            return null;
+        return readCacheFile(this.chunkPath(chunk, chunkAudioEvents), ChunkEvaluationSchema);
+    }
+    async writeChunk(chunk, evaluation, chunkAudioEvents = []) {
+        if (this.disabled)
+            return;
+        if (evaluation.status !== 'success')
+            return;
+        await writeCacheFile(this.chunkPath(chunk, chunkAudioEvents), evaluation);
+    }
+    // ---- Segment refinement -------------------------------------------------
+    segmentRefinementPath(start, end, reason) {
+        return path.join(this.cacheDir, 'segments', `${hashContent(`${start}|${end}|${reason}`)}.json`);
+    }
+    async readSegmentRefinement(start, end, reason) {
+        if (this.disabled)
+            return null;
+        return readCacheFile(this.segmentRefinementPath(start, end, reason), SegmentRefinementSchema);
+    }
+    async writeSegmentRefinement(start, end, reason, refined) {
+        if (this.disabled)
+            return;
+        await writeCacheFile(this.segmentRefinementPath(start, end, reason), refined);
+    }
+    // ---- Audio events (whole-video) -----------------------------------------
+    audioEventPath(videoId, gameProfile, provider) {
+        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}`)}.json`);
+    }
+    async readAudioEvents(videoId, gameProfile, provider) {
+        if (this.disabled)
+            return null;
+        return readCacheFile(this.audioEventPath(videoId, gameProfile, provider), z.array(AudioEventSchema));
+    }
+    async writeAudioEvents(videoId, gameProfile, provider, events) {
+        if (this.disabled)
+            return;
+        await writeCacheFile(this.audioEventPath(videoId, gameProfile, provider), events);
+    }
+    // ---- Audio events (per-chunk) -------------------------------------------
+    /**
+     * Per-chunk audio cache — mirrors the LLM `chunks/` pattern.
+     * Key includes videoId, gameProfile, provider, and the exact window bounds
+     * so each 120s slice is stored independently.
+     */
+    audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd) {
+        return path.join(this.cacheDir, 'audio', `${hashContent(`${videoId}|${gameProfile}|${provider}|${windowStart}|${windowEnd}`)}.json`);
+    }
+    async readAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd) {
+        if (this.disabled)
+            return null;
+        return readCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), z.array(AudioEventSchema));
+    }
+    async writeAudioChunk(videoId, gameProfile, provider, windowStart, windowEnd, events) {
+        if (this.disabled)
+            return;
+        await writeCacheFile(this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd), events);
+    }
+}

package/dist/utils/chunker.js

@@ -0,0 +1,51 @@
+/**
+ * Generic windowed-chunker utility.
+ *
+ * Used by:
+ *   - transcriptProcessor  — builds LLM analysis windows over micro-blocks
+ *   - audioProcessor       — builds audio slice windows over the video duration
+ *
+ * The function returns non-overlapping or overlapping half-open intervals
+ * [start, end) that together cover the full range [0, totalDuration).
+ */
+/**
+ * Builds a list of time windows covering `[0, totalDuration)`.
+ *
+ * @param totalDuration - Total duration of the content in seconds.
+ * @param windowSec     - Width of each window in seconds. Must be > 0.
+ * @param overlapSec    - How many seconds consecutive windows share. Must be
+ *                        >= 0 and < windowSec. Defaults to 0.
+ * @returns Array of {start, end} windows. Empty when totalDuration <= 0.
+ *
+ * @example
+ * // No overlap — three equal windows
+ * buildWindows(60, 20)
+ * // → [{start:0,end:20}, {start:20,end:40}, {start:40,end:60}]
+ *
+ * @example
+ * // With overlap — each window starts 10s after the previous
+ * buildWindows(60, 30, 10)
+ * // → [{start:0,end:30}, {start:20,end:50}, {start:40,end:60}]
+ *
+ * @example
+ * // Remainder — last window is shorter
+ * buildWindows(70, 30)
+ * // → [{start:0,end:30}, {start:30,end:60}, {start:60,end:70}]
+ */
+export function buildWindows(totalDuration, windowSec, overlapSec = 0) {
+    if (totalDuration <= 0 || windowSec <= 0)
+        return [];
+    if (overlapSec < 0)
+        overlapSec = 0;
+    if (overlapSec >= windowSec)
+        overlapSec = 0; // guard against infinite loop
+    const step = windowSec - overlapSec;
+    const windows = [];
+    for (let start = 0; start < totalDuration; start += step) {
+        windows.push({
+            start,
+            end: Math.min(start + windowSec, totalDuration),
+        });
+    }
+    return windows;
+}

package/dist/utils/dumper.js

@@ -0,0 +1,36 @@
+import { promises as fs } from 'fs';
+import path from 'path';
+import { config } from '../config/index.js';
+import { log } from './logger.js';
+/**
+ * Writes the raw normalized transcript lines to
+ * `{OUTPUT_DIR}/transcript/{videoId}.json`.
+ */
+export async function dumpTranscript(videoId, lines) {
+    try {
+        const dir = path.join(config.OUTPUT_DIR, 'transcript');
+        await fs.mkdir(dir, { recursive: true });
+        const filePath = path.join(dir, `${videoId}.json`);
+        await fs.writeFile(filePath, JSON.stringify(lines, null, 2), 'utf-8');
+        log.info(`Transcript dumped to ${filePath}`);
+    }
+    catch (err) {
+        log.warn(`Failed to dump transcript for ${videoId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Writes the full pipeline result (metadata + ranked segments) to
+ * `{OUTPUT_DIR}/analysis/{videoId}.json`.
+ */
+export async function dumpAnalysis(videoId, result) {
+    try {
+        const dir = path.join(config.OUTPUT_DIR, 'analysis');
+        await fs.mkdir(dir, { recursive: true });
+        const filePath = path.join(dir, `${videoId}.json`);
+        await fs.writeFile(filePath, JSON.stringify(result, null, 2), 'utf-8');
+        log.info(`Analysis dumped to ${filePath}`);
+    }
+    catch (err) {
+        log.warn(`Failed to dump analysis for ${videoId}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}

package/dist/utils/format.js

@@ -0,0 +1,10 @@
+/**
+ * Converts a duration in seconds to HH:MM:SS string.
+ * e.g. 3723 → "01:02:03"
+ */
+export function formatSeconds(seconds) {
+    const h = Math.floor(seconds / 3600);
+    const m = Math.floor((seconds % 3600) / 60);
+    const s = Math.floor(seconds % 60);
+    return [h, m, s].map((v) => String(v).padStart(2, '0')).join(':');
+}

package/dist/utils/logger.js

@@ -0,0 +1,16 @@
+const LEVELS = {
+    info: '[info]',
+    warn: '[warn]',
+    error: '[error]',
+};
+export const log = {
+    info: (msg) => {
+        console.log(`${LEVELS.info} ${msg}`);
+    },
+    warn: (msg) => {
+        console.warn(`${LEVELS.warn} ${msg}`);
+    },
+    error: (msg) => {
+        console.error(`${LEVELS.error} ${msg}`);
+    },
+};

package/dist/utils/modelFactory.js

@@ -0,0 +1,60 @@
+import { createOpenAI, openai } from '@ai-sdk/openai';
+import { anthropic } from '@ai-sdk/anthropic';
+import { google } from '@ai-sdk/google';
+import { xai } from '@ai-sdk/xai';
+import { mistral } from '@ai-sdk/mistral';
+import { groq } from '@ai-sdk/groq';
+import { config } from '../config/index.js';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
+/**
+ * Returns a Vercel AI SDK LanguageModel instance for the configured provider
+ * and model. Both `llmAnalyzer` and `clipRefiner` call this instead of
+ * hard-coding `openai(config.LLM_MODEL)`.
+ *
+ * The active provider is controlled by `LLM_PROVIDER` in the environment.
+ * The model name is controlled by `LLM_MODEL`.
+ *
+ * In ai@5, all provider packages ship LanguageModelV3 which natively
+ * satisfies the LanguageModel interface.
+ */
+export function getModel() {
+    const model = config.LLM_MODEL;
+    switch (config.LLM_PROVIDER) {
+        case 'openai':
+            return openai.languageModel(model);
+        case 'anthropic':
+            return anthropic.languageModel(model);
+        case 'google':
+            return google.languageModel(model);
+        case 'xai':
+            return xai.languageModel(model);
+        case 'mistral':
+            return mistral.languageModel(model);
+        case 'groq':
+            return groq.languageModel(model);
+        case 'zai':
+            return createOpenAICompatible({
+                name: 'zai',
+                baseURL: 'https://api.z.ai/api/paas/v4',
+                apiKey: config.ZAI_API_KEY,
+                // Zai is OpenAI-compatible and supports json_schema response format.
+                // Without this flag the SDK falls back to json_object mode and emits
+                // a "responseFormat not supported" warning on every chunk call.
+                supportsStructuredOutputs: true,
+            }).languageModel(model);
+        case 'openrouter':
+            return createOpenAI({
+                baseURL: 'https://openrouter.ai/api/v1',
+                apiKey: config.OPENROUTER_API_KEY,
+            }).languageModel(model);
+        case 'custom':
+            return createOpenAICompatible({
+                name: 'custom',
+                baseURL: config.CUSTOM_OPENAI_BASE_URL,
+                apiKey: config.CUSTOM_OPENAI_API_KEY,
+                // Treat as a fully OpenAI-compatible endpoint with structured output
+                // support so generateObject uses json_schema mode, not json_object fallback.
+                supportsStructuredOutputs: true,
+            }).languageModel(model);
+    }
+}

package/dist/utils/redactConfig.js

@@ -0,0 +1,20 @@
+const SENSITIVE_KEYS = new Set([
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GOOGLE_GENERATIVE_AI_API_KEY',
+    'XAI_API_KEY',
+    'MISTRAL_API_KEY',
+    'GROQ_API_KEY',
+    'ZAI_API_KEY',
+]);
+/**
+ * Formats the resolved config as a single-line key=value string,
+ * omitting all API key fields and any undefined optional values.
+ */
+export function formatConfig(cfg) {
+    return Object.entries(cfg)
+        .filter(([k]) => !SENSITIVE_KEYS.has(k))
+        .filter(([, v]) => v !== undefined)
+        .map(([k, v]) => `${k}=${String(v)}`)
+        .join(' ');
+}

package/dist/utils/sliceAudio.js

@@ -0,0 +1,26 @@
+import * as path from 'path';
+import ffmpeg from 'fluent-ffmpeg';
+import { config } from '../config/index.js';
+if (config.FFMPEG_PATH) {
+    ffmpeg.setFfmpegPath(config.FFMPEG_PATH);
+}
+if (config.FFPROBE_PATH) {
+    ffmpeg.setFfprobePath(config.FFPROBE_PATH);
+}
+export async function sliceAudio(inputPath, startSec, durationSec, outputDir) {
+    const filename = path.basename(inputPath, path.extname(inputPath));
+    const outputPath = path.join(outputDir, `${filename}_slice_${startSec}.wav`);
+    await new Promise((resolve, reject) => {
+        ffmpeg(inputPath)
+            .setStartTime(startSec)
+            .setDuration(durationSec)
+            .audioFrequency(16000)
+            .audioChannels(1)
+            .format('wav')
+            .output(outputPath)
+            .on('end', () => resolve())
+            .on('error', (err) => reject(err))
+            .run();
+    });
+    return outputPath;
+}

package/docs/free-models.md

@@ -0,0 +1,78 @@
+# Free Models via OpenRouter
+
+This project supports [OpenRouter](https://openrouter.ai) as an LLM provider, which gives access to a number of completely free models (no cost per token).
+
+## Setup
+
+```env
+LLM_PROVIDER=openrouter
+OPENROUTER_API_KEY=sk-or-...
+LLM_MODEL=<model-id-from-table-below>
+```
+
+---
+
+## Recommended Free Models for Transcript Analysis
+
+These models have sufficient context length and instruction-following capability to work well with `generateObject` and structured transcript analysis.
+
+| Model ID                                        | Name                              | Context |
+| ----------------------------------------------- | --------------------------------- | ------- |
+| `meta-llama/llama-3.3-70b-instruct:free`        | Meta: Llama 3.3 70B Instruct      | 128K    |
+| `google/gemma-3-27b-it:free`                    | Google: Gemma 3 27B               | 131K    |
+| `mistralai/mistral-small-3.1-24b-instruct:free` | Mistral: Mistral Small 3.1 24B    | 128K    |
+| `nousresearch/hermes-3-llama-3.1-405b:free`     | Nous: Hermes 3 405B Instruct      | 131K    |
+| `qwen/qwen3-next-80b-a3b-instruct:free`         | Qwen: Qwen3 Next 80B A3B Instruct | 262K    |
+
+**Recommended default:** `meta-llama/llama-3.3-70b-instruct:free`
+
+- Most battle-tested for structured JSON output
+- Reliable with `generateObject` (which requires strict schema adherence)
+- 128K context handles most YouTube transcripts comfortably
+
+---
+
+## All Available Free Models (as of March 2026)
+
+| Model ID                                                        | Name                              | Context   |
+| --------------------------------------------------------------- | --------------------------------- | --------- |
+| `openrouter/hunter-alpha`                                       | Hunter Alpha                      | 1,048,576 |
+| `openrouter/healer-alpha`                                       | Healer Alpha                      | 262,144   |
+| `nvidia/nemotron-3-super-120b-a12b:free`                        | NVIDIA: Nemotron 3 Super          | 262,144   |
+| `minimax/minimax-m2.5:free`                                     | MiniMax: MiniMax M2.5             | 196,608   |
+| `openrouter/free`                                               | Free Models Router                | 200,000   |
+| `stepfun/step-3.5-flash:free`                                   | StepFun: Step 3.5 Flash           | 256,000   |
+| `arcee-ai/trinity-large-preview:free`                           | Arcee AI: Trinity Large Preview   | 131,000   |
+| `liquid/lfm-2.5-1.2b-thinking:free`                             | LiquidAI: LFM2.5-1.2B-Thinking    | 32,768    |
+| `liquid/lfm-2.5-1.2b-instruct:free`                             | LiquidAI: LFM2.5-1.2B-Instruct    | 32,768    |
+| `nvidia/nemotron-3-nano-30b-a3b:free`                           | NVIDIA: Nemotron 3 Nano 30B A3B   | 256,000   |
+| `arcee-ai/trinity-mini:free`                                    | Arcee AI: Trinity Mini            | 131,072   |
+| `nvidia/nemotron-nano-12b-v2-vl:free`                           | NVIDIA: Nemotron Nano 12B 2 VL    | 128,000   |
+| `qwen/qwen3-next-80b-a3b-instruct:free`                         | Qwen: Qwen3 Next 80B A3B Instruct | 262,144   |
+| `nvidia/nemotron-nano-9b-v2:free`                               | NVIDIA: Nemotron Nano 9B V2       | 128,000   |
+| `openai/gpt-oss-120b:free`                                      | OpenAI: gpt-oss-120b              | 131,072   |
+| `openai/gpt-oss-20b:free`                                       | OpenAI: gpt-oss-20b               | 131,072   |
+| `z-ai/glm-4.5-air:free`                                         | Z.ai: GLM 4.5 Air                 | 131,072   |
+| `qwen/qwen3-coder:free`                                         | Qwen: Qwen3 Coder 480B A35B       | 262,000   |
+| `cognitivecomputations/dolphin-mistral-24b-venice-edition:free` | Venice: Uncensored                | 32,768    |
+| `google/gemma-3n-e2b-it:free`                                   | Google: Gemma 3n 2B               | 8,192     |
+| `google/gemma-3n-e4b-it:free`                                   | Google: Gemma 3n 4B               | 8,192     |
+| `qwen/qwen3-4b:free`                                            | Qwen: Qwen3 4B                    | 40,960    |
+| `mistralai/mistral-small-3.1-24b-instruct:free`                 | Mistral: Mistral Small 3.1 24B    | 128,000   |
+| `google/gemma-3-4b-it:free`                                     | Google: Gemma 3 4B                | 32,768    |
+| `google/gemma-3-12b-it:free`                                    | Google: Gemma 3 12B               | 32,768    |
+| `google/gemma-3-27b-it:free`                                    | Google: Gemma 3 27B               | 131,072   |
+| `meta-llama/llama-3.3-70b-instruct:free`                        | Meta: Llama 3.3 70B Instruct      | 128,000   |
+| `meta-llama/llama-3.2-3b-instruct:free`                         | Meta: Llama 3.2 3B Instruct       | 131,072   |
+| `nousresearch/hermes-3-llama-3.1-405b:free`                     | Nous: Hermes 3 405B Instruct      | 131,072   |
+
+> Free models may have rate limits or availability constraints. Check [openrouter.ai/models](https://openrouter.ai/models) for the latest list.
+
+---
+
+## Notes
+
+- Free models on OpenRouter are subject to rate limits (typically lower than paid tiers).
+- Avoid models with context < 32K for long videos — chunks may not fit.
+- Models marked `:free` are permanently free; others (like `openrouter/hunter-alpha`) may change pricing.
+- If `generateObject` fails with a free model, it usually means the model doesn't follow JSON schema strictly enough — switch to `meta-llama/llama-3.3-70b-instruct:free` as a fallback.