@thunderkiller/video-clipper 1.1.0 → 1.1.1

package/.github/workflows/release.yml

@@ -50,6 +50,10 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.PUSH_TOKEN }}
 
+      - name: Pull updated package.json after semantic-release
+        if: success()
+        run: git pull origin master
+
       - name: Verify GitHub Release
         if: success()
         run: |
@@ -69,4 +73,4 @@ jobs:
         if: success()
         run: npm publish
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## [1.1.1](https://github.com/AmreetKumarkhuntia/video-clipper/compare/v1.1.0...v1.1.1) (2026-03-19)
+
+### Bug Fixes
+
+- github workflows ([18a9536](https://github.com/AmreetKumarkhuntia/video-clipper/commit/18a953619ed17de71d3c9bd0a86e1b42a10aea37))
+- **release:** pull updated package.json before npm publish to avoid race condition ([1839e4a](https://github.com/AmreetKumarkhuntia/video-clipper/commit/1839e4a57d516234ad629f0217e4fa5f4852e4e3))
+- yaml correction ([33c7854](https://github.com/AmreetKumarkhuntia/video-clipper/commit/33c7854015e1266b3fc01b6206da4ec946f94307))
+
 # 1.0.0 (2026-03-18)
 
 ### Bug Fixes

package/dist/pipeline/runner.js

@@ -45,11 +45,10 @@ export async function runPipeline(args) {
     const gameProfile = args.gameProfile ?? config.GAME_PROFILE;
     const maxParallel = args.maxParallel ?? config.LLM_CONCURRENCY;
     const cache = new Cache(config.CACHE_DIR, args.noCache);
-    // ── Stage 1: Resolve video ID + metadata ─────────────────────────────────
     const { videoId, metadata } = await resolveVideo(args.url, args.maxDuration);
-    // ── Stage 2: Download audio ───────────────────────────────────────────────
-    // Downloaded before transcript so Whisper/Gemini transcript providers can
-    // use the WAV. Returns null when audio detection is disabled.
+    /** Downloaded before transcript so Whisper/Gemini transcript providers can
+     * use the WAV. Returns null when audio detection is disabled.
+     */
     let audioPath = null;
     const audioEnabled = config.AUDIO_DETECTION_ENABLED && !args.noAudio;
     if (audioEnabled) {
@@ -61,14 +60,12 @@ export async function runPipeline(args) {
             log.warn(`Audio download failed — continuing without audio: ${message}`);
         }
     }
-    // ── Stage 3: Audio event detection ───────────────────────────────────────
     const audioEvents = await processAudio(videoId, metadata.duration, cache, {
         noAudio: args.noAudio,
         gameProfile,
         maxParallel,
         audioPath,
     });
-    // ── Stage 4a: Fetch transcript + LLM analysis (informed by audio events) ──
     const { lines, microBlocks, chunkEvals } = await analyzeSegments(videoId, audioPath, audioEvents, cache, {
         maxChunks: args.maxChunks,
         maxParallel,
@@ -77,9 +74,7 @@ export async function runPipeline(args) {
     if (config.DUMP_OUTPUTS) {
         await dumpTranscript(videoId, lines);
     }
-    // ── Stage 5: Merge signals + rank ─────────────────────────────────────────
     const rankedSegments = selectSegments(chunkEvals, audioEvents, { threshold, topN });
-    // Build partial result for early-exit path (no segments above threshold)
     const partialResult = {
         video_id: videoId,
         title: metadata.title,
@@ -93,12 +88,10 @@ export async function runPipeline(args) {
             await dumpAnalysis(videoId, partialResult);
         return;
     }
-    // ── Stage 4b: Refine clip boundaries (LLM pass 2) ─────────────────────────
     const refinedSegments = await refineRankedSegments(rankedSegments, microBlocks, cache, {
         maxParallel,
         noCache: args.noCache,
     });
-    // ── Output result ─────────────────────────────────────────────────────────
     const result = {
         video_id: videoId,
         title: metadata.title,
@@ -110,7 +103,6 @@ export async function runPipeline(args) {
     if (config.DUMP_OUTPUTS)
         await dumpAnalysis(videoId, result);
     log.info('Done.');
-    // ── Stage 6: Download + generate clips (only with --clip) ─────────────────
     if (!args.clip) {
         log.info('Tip: run with --clip to download the video and generate mp4 clips.');
         return;

package/dist/pipeline/stages/audioProcessor.js

@@ -26,7 +26,6 @@ export async function processAudio(videoId, duration, cache, opts) {
     const audioEnabled = config.AUDIO_DETECTION_ENABLED && !opts.noAudio;
     if (!audioEnabled)
         return [];
-    // Cache-first
     const cached = await cache.readAudioEvents(videoId, opts.gameProfile, config.AUDIO_PROVIDER);
     if (cached) {
         log.info(`[cache hit] Audio events loaded from cache (${cached.length} events)`);
@@ -34,7 +33,6 @@ export async function processAudio(videoId, duration, cache, opts) {
     }
     try {
         const audioPath = opts.audioPath ?? (await downloadAudio(videoId, `${config.OUTPUT_DIR}/audio`));
-        // Build the analyzer chain once per run from config
         const chain = createAnalyzerChain(config.AUDIO_PROVIDER);
         const detector = new EventDetector(chain);
         const providerNames = chain.map((a) => a.source).join(' → ');

package/dist/pipeline/stages/clipExporter.js

@@ -14,15 +14,12 @@ import { config } from '../../config/index.js';
  * @returns Array of absolute paths to the generated clip files.
  */
 export async function exportClips(videoId, segments, opts) {
-    // Mode 1: local video already on disk — cut with ffmpeg
     if (opts.localVideo) {
         log.info(`Using local video: ${opts.localVideo}`);
         return generateClips(opts.localVideo, segments, videoId, opts.videoPath, config.CLIP_CONCURRENCY);
     }
-    // Determine yt-dlp mode
     const downloadSections = opts.downloadSections ?? config.DOWNLOAD_SECTIONS_MODE;
     if (typeof downloadSections === 'number') {
-        // Mode 2: download only the top-N segments via --download-sections
         const segmentsToDownload = segments.slice(0, downloadSections);
         if (segmentsToDownload.length < downloadSections) {
             log.warn(`Requested ${downloadSections} segments, but only ${segmentsToDownload.length} are available above threshold.`);
@@ -34,7 +31,6 @@ export async function exportClips(videoId, segments, opts) {
         }
         return organizeClips(downloadResult.paths, videoId, opts.videoPath, config.CLIP_CONCURRENCY);
     }
-    // Mode 3: full-video download → cut clips with ffmpeg
     log.info('Downloading full video via yt-dlp...');
     const downloadResult = await downloadVideo(videoId, 'all', [], opts.videoPath);
     if (downloadResult.mode !== 'all') {

package/dist/pipeline/stages/videoResolver.js

@@ -11,7 +11,6 @@ import { formatSeconds } from '../../utils/format.js';
  * @throws {Error} on invalid URL, metadata fetch failure, or exceeded duration
  */
 export async function resolveVideo(rawUrl, maxDurationSec) {
-    // Parse URL → video ID
     let videoId;
     try {
         videoId = parseUrl(rawUrl);
@@ -19,11 +18,9 @@ export async function resolveVideo(rawUrl, maxDurationSec) {
     catch {
         throw new Error(`Invalid YouTube URL: ${rawUrl}`);
     }
-    // Fetch metadata (yt-dlp → oEmbed fallback)
     log.info(`Fetching metadata for ${videoId}...`);
     const metadata = await extractMetadata(videoId);
     log.info(`Video: "${metadata.title}" (${metadata.duration > 0 ? formatSeconds(metadata.duration) : 'duration unknown'})`);
-    // --max-duration guard
     if (maxDurationSec !== undefined && metadata.duration > 0) {
         if (metadata.duration > maxDurationSec) {
             throw new Error(`Video duration exceeds --max-duration limit. ` +

package/dist/services/audioAnalyzers/factory.js

@@ -12,7 +12,6 @@ const KNOWN_PROVIDERS = new Set(['gemini', 'whisper', 'yamnet']);
  * Backward-compat: "both" is mapped to ['gemini', 'whisper'] with a deprecation warning.
  */
 export function parseProviderChain(providerString) {
-    // Backward compatibility: map legacy 'both' to the new comma-separated form
     if (providerString.trim() === 'both') {
         log.warn('[audio] AUDIO_PROVIDER=both is deprecated. Use AUDIO_PROVIDER=gemini,whisper instead.');
         return ['gemini', 'whisper'];

package/dist/services/audioAnalyzers/gemini.js

@@ -4,11 +4,13 @@ import { z } from 'zod';
 import { config } from '../../config/index.js';
 import { log } from '../../utils/logger.js';
 import { AudioAnalyzer } from './base.js';
+/**
+ * Gemini returns timestamps inconsistently as either:
+ * - MM.SS notation: 1.03 = 1 min 3 sec = 63s
+ * - True decimal seconds: 53.403 = 53.403s
+ * Use normalizeGeminiTime() to resolve correct value.
+ */
 const GeminiEventSchema = z.array(z.object({
-    // Gemini inconsistently returns timestamps in either:
-    //   - MM.SS notation: 1.03 = 1 min 3 sec = 63s
-    //   - True decimal seconds: 53.403 = 53.403s
-    // Use normalizeGeminiTime() to resolve the correct value.
     time_sec: z.number(),
     event: z.string(),
     confidence: z.number().min(0).max(1),
@@ -45,16 +47,13 @@ function mmssToSeconds(value) {
  */
 export function normalizeGeminiTime(value, chunkDurationSec) {
     const frac = value % 1;
-    // Fractional part > 0.59 is impossible in MM.SS — must be decimal seconds
     if (Math.round(frac * 100) > 59) {
         return value;
     }
-    // Fractional part ≤ 0.59: could be MM.SS — check if converted value fits in chunk
     const mmss = mmssToSeconds(value);
     if (mmss < chunkDurationSec) {
         return mmss;
     }
-    // MM.SS conversion overflows the chunk — must be true decimal seconds
     return value;
 }
 /**

package/dist/services/chunkBuilder/index.js

@@ -12,19 +12,16 @@ export function buildMicroBlocks(lines, windowSec) {
     let texts = [];
     for (const line of lines) {
         if (line.start >= windowStart + windowSec) {
-            // Flush current block
             blocks.push({
                 start: windowStart,
                 end: line.start,
                 text: texts.join(' '),
             });
-            // Start a new window aligned to the current line
             windowStart = line.start;
             texts = [];
         }
         texts.push(line.text);
     }
-    // Flush the final block
     if (texts.length > 0) {
         const lastLine = lines[lines.length - 1];
         blocks.push({
@@ -63,7 +60,6 @@ export function buildLLMChunks(blocks, chunkLen, overlap) {
         }
         const step = chunkLen - overlap;
         chunkStart += step;
-        // Guard: if overlap >= chunkLen we'd loop forever
         if (step <= 0)
             break;
     }

package/dist/services/clipRefiner/index.js

@@ -69,7 +69,7 @@ async function refineSegment(segment, allBlocks, noCache) {
         prompt: buildPrompt(segment, text, windowStart, windowEnd),
         maxRetries: config.LLM_MAX_RETRIES,
     });
-    // Clamp to the context window to ensure LLM doesn't hallucinate out-of-range values
+    /** Clamp to context window to prevent LLM from hallucinating out-of-range values */
     const refinedStart = Math.max(windowStart, Math.min(object.clip_start, object.clip_end - 1));
     const refinedEnd = Math.min(windowEnd, Math.max(object.clip_end, object.clip_start + 1));
     if (!noCache) {

package/dist/services/llmAnalyzer/LLMAnalyzer.js

@@ -36,9 +36,7 @@ export class LLMAnalyzer {
      * everything needed for the ranking step.
      */
     async analyze(opts) {
-        // ── Transcript ────────────────────────────────────────────────────────────
         const { lines, microBlocks, chunks } = await this.transcriptDetector.detect(opts.videoId, opts.audioPath, this.cache);
-        // ── LLM pass 1 ────────────────────────────────────────────────────────────
         const chunkLimit = opts.maxChunks ?? config.MAX_CHUNKS;
         const chunksToAnalyze = chunkLimit !== undefined ? chunks.slice(0, chunkLimit) : chunks;
         if (chunkLimit !== undefined) {

package/dist/services/transcriptDetector/index.js

@@ -46,7 +46,6 @@ export class TranscriptDetector {
      */
     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)`);
@@ -60,9 +59,6 @@ export class TranscriptDetector {
         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.

package/dist/services/transcriptFetcher/index.js

@@ -17,7 +17,7 @@ import { config } from '../../config/index.js';
 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)
+    /** Regex to match HH:MM:SS.mmm --> HH:MM:SS.mmm timestamp lines */
     const TIMESTAMP_RE = /^(\d{2}):(\d{2}):(\d{2})[.,](\d{3})\s+-->\s+(\d{2}):(\d{2}):(\d{2})[.,](\d{3})/;
     let i = 0;
     while (i < lines.length) {
@@ -32,7 +32,6 @@ export function parseVtt(vttContent) {
                 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() !== '') {
@@ -40,7 +39,6 @@ export function parseVtt(vttContent) {
                 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, '&')
@@ -53,8 +51,7 @@ export function parseVtt(vttContent) {
                 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)
+            /** Skip duplicate cues - YouTube VTT often repeats same line as text scrolls */
             if (result.length > 0 && result[result.length - 1].text === text) {
                 continue;
             }
@@ -104,7 +101,6 @@ export async function fetchTranscript(videoId) {
             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) {

package/dist/services/urlParser/index.js

@@ -37,7 +37,6 @@ export function parseUrl(url) {
     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}`);

package/dist/types/analyzer.js

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

package/dist/types/cache.js

@@ -0,0 +1,5 @@
+import { z } from 'zod';
+export const SegmentRefinementSchema = z.object({
+    refined_start: z.number(),
+    refined_end: z.number(),
+});

package/dist/types/config.js

@@ -10,7 +10,6 @@ const LLM_PROVIDERS = [
     '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',
@@ -24,9 +23,7 @@ const PROVIDER_KEY_MAP = {
 };
 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(),
@@ -37,7 +34,6 @@ export const ConfigSchema = z
     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),
@@ -48,32 +44,20 @@ export const ConfigSchema = z
     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')
@@ -86,10 +70,7 @@ export const ConfigSchema = z
     }, {
         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')
@@ -111,9 +92,7 @@ export const ConfigSchema = z
     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(),
@@ -130,7 +109,6 @@ export const ConfigSchema = z
             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({
@@ -139,7 +117,6 @@ export const ConfigSchema = z
             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,

package/dist/types/downloader.js

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

package/dist/types/factory.js

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

package/dist/types/index.js

@@ -3,3 +3,4 @@ export { TranscriptLineSchema, MicroBlockSchema, LLMChunkSchema } from './transc
 export { AnalyzedSegmentSchema, RankedSegmentSchema, ChunkEvaluationSchema } from './segment.js';
 export { AudioEventSchema, MergedCandidateSchema } from './audio.js';
 export { VideoMetadataSchema, PipelineResultSchema } from './video.js';
+export { SegmentRefinementSchema } from './cache.js';

package/dist/types/pipeline.js

@@ -1,9 +1 @@
-/**
- * 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

@@ -3,13 +3,13 @@ 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
+    clip_start: z.number(),
+    clip_end: z.number(),
 });
 export const RankedSegmentSchema = z.object({
     rank: z.number().int().min(1),
-    start: z.number(), // seconds
-    end: z.number(), // seconds
+    start: z.number(),
+    end: z.number(),
     score: z.number().min(1).max(10),
     reason: z.string(),
     source: z.enum(['transcript', 'audio', 'both']),
@@ -17,8 +17,8 @@ export const RankedSegmentSchema = z.object({
 });
 const ChunkEvaluationBaseSchema = z.object({
     chunk_index: z.number().int().min(0),
-    chunk_start: z.number(), // seconds
-    chunk_end: z.number(), // seconds
+    chunk_start: z.number(),
+    chunk_end: z.number(),
 });
 export const ChunkEvaluationSchema = z.discriminatedUnion('status', [
     ChunkEvaluationBaseSchema.extend({

package/dist/types/transcript.js

@@ -1,16 +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)
+    start: z.number(),
+    duration: z.number(),
 });
 export const MicroBlockSchema = z.object({
-    start: z.number(), // seconds
-    end: z.number(), // seconds
+    start: z.number(),
+    end: z.number(),
     text: z.string(),
 });
 export const LLMChunkSchema = z.object({
-    start: z.number(), // seconds
-    end: z.number(), // seconds
+    start: z.number(),
+    end: z.number(),
     text: z.string(),
 });

package/dist/utils/cache.js

@@ -3,10 +3,7 @@ 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
-// ---------------------------------------------------------------------------
+import { TranscriptLineSchema, ChunkEvaluationSchema, AudioEventSchema, SegmentRefinementSchema, } from '../types/index.js';
 /**
  * Serializes audio events into a stable string for cache keying.
  * Events are sorted by time so the key is order-independent.
@@ -44,10 +41,6 @@ async function writeCacheFile(filePath, data) {
         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.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thunderkiller/video-clipper",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "CLI that analyzes YouTube transcripts with an LLM to find interesting moments and cut clips",
   "license": "ISC",
   "author": "",

package/src/pipeline/runner.ts

@@ -52,12 +52,11 @@ export async function runPipeline(args: CliArgs): Promise<void> {
 
   const cache = new Cache(config.CACHE_DIR, args.noCache);
 
-  // ── Stage 1: Resolve video ID + metadata ─────────────────────────────────
   const { videoId, metadata } = await resolveVideo(args.url as string, args.maxDuration);
 
-  // ── Stage 2: Download audio ───────────────────────────────────────────────
-  // Downloaded before transcript so Whisper/Gemini transcript providers can
-  // use the WAV. Returns null when audio detection is disabled.
+  /** Downloaded before transcript so Whisper/Gemini transcript providers can
+   * use the WAV. Returns null when audio detection is disabled.
+   */
   let audioPath: string | null = null;
   const audioEnabled = config.AUDIO_DETECTION_ENABLED && !args.noAudio;
   if (audioEnabled) {
@@ -69,7 +68,6 @@ export async function runPipeline(args: CliArgs): Promise<void> {
     }
   }
 
-  // ── Stage 3: Audio event detection ───────────────────────────────────────
   const audioEvents = await processAudio(videoId, metadata.duration, cache, {
     noAudio: args.noAudio,
     gameProfile,
@@ -77,7 +75,6 @@ export async function runPipeline(args: CliArgs): Promise<void> {
     audioPath,
   });
 
-  // ── Stage 4a: Fetch transcript + LLM analysis (informed by audio events) ──
   const { lines, microBlocks, chunkEvals } = await analyzeSegments(
     videoId,
     audioPath,
@@ -94,10 +91,8 @@ export async function runPipeline(args: CliArgs): Promise<void> {
     await dumpTranscript(videoId, lines);
   }
 
-  // ── Stage 5: Merge signals + rank ─────────────────────────────────────────
   const rankedSegments = selectSegments(chunkEvals, audioEvents, { threshold, topN });
 
-  // Build partial result for early-exit path (no segments above threshold)
   const partialResult: PipelineResult = {
     video_id: videoId,
     title: metadata.title,
@@ -112,13 +107,11 @@ export async function runPipeline(args: CliArgs): Promise<void> {
     return;
   }
 
-  // ── Stage 4b: Refine clip boundaries (LLM pass 2) ─────────────────────────
   const refinedSegments = await refineRankedSegments(rankedSegments, microBlocks, cache, {
     maxParallel,
     noCache: args.noCache,
   });
 
-  // ── Output result ─────────────────────────────────────────────────────────
   const result: PipelineResult = {
     video_id: videoId,
     title: metadata.title,
@@ -132,7 +125,6 @@ export async function runPipeline(args: CliArgs): Promise<void> {
 
   log.info('Done.');
 
-  // ── Stage 6: Download + generate clips (only with --clip) ─────────────────
   if (!args.clip) {
     log.info('Tip: run with --clip to download the video and generate mp4 clips.');
     return;

package/src/pipeline/stages/audioProcessor.ts

@@ -36,7 +36,6 @@ export async function processAudio(
   const audioEnabled = config.AUDIO_DETECTION_ENABLED && !opts.noAudio;
   if (!audioEnabled) return [];
 
-  // Cache-first
   const cached = await cache.readAudioEvents(videoId, opts.gameProfile, config.AUDIO_PROVIDER);
   if (cached) {
     log.info(`[cache hit] Audio events loaded from cache (${cached.length} events)`);
@@ -47,7 +46,6 @@ export async function processAudio(
     const audioPath =
       opts.audioPath ?? (await downloadAudio(videoId, `${config.OUTPUT_DIR}/audio`));
 
-    // Build the analyzer chain once per run from config
     const chain = createAnalyzerChain(config.AUDIO_PROVIDER);
     const detector = new EventDetector(chain);
 

package/src/pipeline/stages/clipExporter.ts

@@ -22,7 +22,6 @@ export async function exportClips(
   segments: RankedSegment[],
   opts: ClipExporterOpts,
 ): Promise<string[]> {
-  // Mode 1: local video already on disk — cut with ffmpeg
   if (opts.localVideo) {
     log.info(`Using local video: ${opts.localVideo}`);
     return generateClips(
@@ -34,11 +33,9 @@ export async function exportClips(
     );
   }
 
-  // Determine yt-dlp mode
   const downloadSections = opts.downloadSections ?? config.DOWNLOAD_SECTIONS_MODE;
 
   if (typeof downloadSections === 'number') {
-    // Mode 2: download only the top-N segments via --download-sections
     const segmentsToDownload = segments.slice(0, downloadSections);
 
     if (segmentsToDownload.length < downloadSections) {
@@ -62,7 +59,6 @@ export async function exportClips(
     return organizeClips(downloadResult.paths, videoId, opts.videoPath, config.CLIP_CONCURRENCY);
   }
 
-  // Mode 3: full-video download → cut clips with ffmpeg
   log.info('Downloading full video via yt-dlp...');
   const downloadResult = await downloadVideo(videoId, 'all', [], opts.videoPath);