@thunderkiller/video-clipper 1.1.0

package/dist/services/llmAnalyzer/index.js

@@ -0,0 +1,173 @@
+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';
+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) {
+    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) {
+    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, chunkLines, chunkAudioEvents, isCustomSystemPrompt) {
+    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, chunkLines, chunkAudioEvents, noCache, chunkIndex) {
+    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;
+    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 = {
+                    status: 'success',
+                    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, lines, audioEvents, concurrency, noCache = false) {
+    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 = await Promise.all(results.map(async (result, i) => {
+        const chunk = chunks[i];
+        if (result.status === 'fulfilled') {
+            succeeded++;
+            const seg = result.value;
+            const evaluation = {
+                status: 'success',
+                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',
+                chunk_index: i,
+                chunk_start: chunk.start,
+                chunk_end: chunk.end,
+                error,
+            };
+        }
+    }));
+    log.info(`Analysis complete: ${succeeded}/${chunks.length} chunks succeeded`);
+    return evaluations;
+}

package/dist/services/metadataExtractor/index.js

@@ -0,0 +1,66 @@
+import { execa } from 'execa';
+import { config } from '../../config/index.js';
+import { log } from '../../utils/logger.js';
+const OEMBED_URL = 'https://www.youtube.com/oembed';
+/**
+ * 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) {
+    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);
+        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) {
+    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());
+    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) {
+    const ytDlpResult = await extractViaYtDlp(videoId);
+    if (ytDlpResult) {
+        return ytDlpResult;
+    }
+    log.warn(`yt-dlp failed for "${videoId}", falling back to oEmbed...`);
+    return extractViaOEmbed(videoId);
+}

package/dist/services/segmentRanker/index.js

@@ -0,0 +1,40 @@
+function overlapSeconds(aStart, aEnd, bStart, bEnd) {
+    const start = Math.max(aStart, bStart);
+    const end = Math.min(aEnd, bEnd);
+    return Math.max(0, end - start);
+}
+function significantlyOverlaps(aStart, aEnd, bStart, bEnd, aSource, bSource) {
+    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) {
+    const kept = [];
+    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, threshold, topN) {
+    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,
+        audio_event: s.audio_event,
+    }));
+}

package/dist/services/signalMerger/index.js

@@ -0,0 +1,36 @@
+import { config } from '../../config/index.js';
+export function mergeSignals(llmSegments, audioEvents, boostWindow, scoreBoost, preRoll, postRoll) {
+    const candidates = [];
+    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/dist/services/transcriptAnalyzers/base.js

@@ -0,0 +1,13 @@
+/**
+ * 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 class TranscriptAnalyzer {
+}

package/dist/services/transcriptAnalyzers/factory.js

@@ -0,0 +1,51 @@
+import { log } from '../../utils/logger.js';
+import { YtDlpTranscriptAnalyzer } from './ytdlp.js';
+import { WhisperTranscriptAnalyzer } from './whisper.js';
+import { GeminiTranscriptAnalyzer } from './gemini.js';
+const KNOWN_PROVIDERS = new Set(['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) {
+    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)) {
+            throw new Error(`Unknown transcript provider "${name}". Valid options: ytdlp, whisper, gemini (comma-separated for chain)`);
+        }
+    }
+    return names;
+}
+/**
+ * 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) {
+    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/dist/services/transcriptAnalyzers/gemini.js

@@ -0,0 +1,19 @@
+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 {
+    source = 'gemini';
+    async detect(_videoId, _audioPath) {
+        throw new Error('GeminiTranscriptAnalyzer is not yet implemented. ' +
+            'Use TRANSCRIPT_PROVIDER=ytdlp or TRANSCRIPT_PROVIDER=whisper instead.');
+    }
+}

package/dist/services/transcriptAnalyzers/index.js

@@ -0,0 +1,5 @@
+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';

package/dist/services/transcriptAnalyzers/whisper.js

@@ -0,0 +1,55 @@
+import { execa } from 'execa';
+import { z } from 'zod';
+import { config } from '../../config/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 {
+    source = 'whisper';
+    async detect(videoId, audioPath) {
+        if (!audioPath) {
+            throw new Error('WhisperTranscriptAnalyzer requires an audio file. ' +
+                'Ensure downloadAudio() runs before processTranscript() in the pipeline.');
+        }
+        const python = await getPythonBin();
+        let stdout;
+        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);
+        const segments = raw.map((seg) => WhisperSegmentSchema.parse(seg));
+        return segments.map((seg) => ({
+            text: seg.text.trim(),
+            start: seg.start,
+            duration: seg.duration,
+        }));
+    }
+}

package/dist/services/transcriptAnalyzers/ytdlp.js

@@ -0,0 +1,16 @@
+import { fetchTranscript } from '../transcriptFetcher/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 {
+    source = 'ytdlp';
+    async detect(videoId, _audioPath) {
+        return fetchTranscript(videoId);
+    }
+}

package/dist/services/transcriptDetector/index.js

@@ -0,0 +1,102 @@
+import { buildMicroBlocks, buildLLMChunks } from '../chunkBuilder/index.js';
+import { log } from '../../utils/logger.js';
+import { config } from '../../config/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 {
+    chain;
+    constructor(chain) {
+        this.chain = chain;
+        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, audioPath, cache) {
+        let lines;
+        // 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.
+     */
+    async fetchFromChain(videoId, audioPath) {
+        let lastError;
+        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. */
+    buildMicroBlocks(lines) {
+        return buildMicroBlocks(lines, config.MICRO_BLOCK_SEC);
+    }
+    /** Builds overlapping LLM analysis chunks from micro-blocks. */
+    buildChunks(microBlocks) {
+        return buildLLMChunks(microBlocks, config.CHUNK_LENGTH_SEC, config.CHUNK_OVERLAP_SEC);
+    }
+}