@thunderkiller/video-clipper 1.1.0 → 1.1.1

package/src/pipeline/stages/videoResolver.ts

@@ -18,7 +18,6 @@ export async function resolveVideo(
   rawUrl: string,
   maxDurationSec?: number,
 ): Promise<VideoResolverResult> {
-  // Parse URL → video ID
   let videoId: string;
   try {
     videoId = parseUrl(rawUrl);
@@ -26,14 +25,12 @@ export async function resolveVideo(
     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(

package/src/services/audioAnalyzers/factory.ts

@@ -3,8 +3,7 @@ import { AudioAnalyzer } from './base.js';
 import { GeminiAudioAnalyzer } from './gemini.js';
 import { WhisperAudioAnalyzer } from './whisper.js';
 import { YAMNetAudioAnalyzer } from './yamnet.js';
-
-export type AudioProviderName = 'gemini' | 'whisper' | 'yamnet';
+import type { AudioProviderName } from '../../types/index.js';
 
 const KNOWN_PROVIDERS = new Set<AudioProviderName>(['gemini', 'whisper', 'yamnet']);
 
@@ -17,7 +16,6 @@ const KNOWN_PROVIDERS = new Set<AudioProviderName>(['gemini', 'whisper', 'yamnet
  * Backward-compat: "both" is mapped to ['gemini', 'whisper'] with a deprecation warning.
  */
 export function parseProviderChain(providerString: string): AudioProviderName[] {
-  // 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.',

package/src/services/audioAnalyzers/gemini.ts

@@ -6,12 +6,14 @@ import { log } from '../../utils/logger.js';
 import type { AudioEvent } from '../../types/index.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),
@@ -56,18 +58,15 @@ function mmssToSeconds(value: number): number {
 export function normalizeGeminiTime(value: number, chunkDurationSec: number): number {
   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/src/services/audioAnalyzers/index.ts

@@ -3,4 +3,4 @@ export { GeminiAudioAnalyzer, normalizeGeminiTime } from './gemini.js';
 export { WhisperAudioAnalyzer, getPythonBin } from './whisper.js';
 export { YAMNetAudioAnalyzer } from './yamnet.js';
 export { createAnalyzerChain, parseProviderChain } from './factory.js';
-export type { AudioProviderName } from './factory.js';
+export type { AudioProviderName } from '../../types/index.js';

package/src/services/chunkBuilder/index.ts

@@ -15,20 +15,17 @@ export function buildMicroBlocks(lines: TranscriptLine[], windowSec: number): Mi
 
   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({
@@ -78,7 +75,6 @@ export function buildLLMChunks(
     const step = chunkLen - overlap;
     chunkStart += step;
 
-    // Guard: if overlap >= chunkLen we'd loop forever
     if (step <= 0) break;
   }
 

package/src/services/clipRefiner/index.ts

@@ -92,7 +92,7 @@ async function refineSegment(
     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));
 

package/src/services/llmAnalyzer/LLMAnalyzer.ts

@@ -11,24 +11,10 @@ import type {
   AudioEvent,
   ChunkEvaluation,
   RankedSegment,
+  LLMAnalyzerResult,
+  LLMAnalyzerOpts,
 } from '../../types/index.js';
 
-export interface LLMAnalyzerResult {
-  lines: TranscriptLine[];
-  microBlocks: MicroBlock[];
-  chunks: LLMChunk[];
-  chunkEvals: ChunkEvaluation[];
-}
-
-export interface LLMAnalyzerOpts {
-  videoId: string;
-  audioPath: string | null;
-  audioEvents: AudioEvent[];
-  maxChunks?: number;
-  maxParallel: number;
-  noCache: boolean;
-}
-
 /**
  * LLMAnalyzer — orchestrates transcript fetching + LLM-based segment analysis.
  *
@@ -62,14 +48,12 @@ export class LLMAnalyzer {
    * everything needed for the ranking step.
    */
   async analyze(opts: LLMAnalyzerOpts): Promise<LLMAnalyzerResult> {
-    // ── 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;
 

package/src/services/transcriptAnalyzers/factory.ts

@@ -3,8 +3,7 @@ import { TranscriptAnalyzer } from './base.js';
 import { YtDlpTranscriptAnalyzer } from './ytdlp.js';
 import { WhisperTranscriptAnalyzer } from './whisper.js';
 import { GeminiTranscriptAnalyzer } from './gemini.js';
-
-export type TranscriptProviderName = 'ytdlp' | 'whisper' | 'gemini';
+import type { TranscriptProviderName } from '../../types/index.js';
 
 const KNOWN_PROVIDERS = new Set<TranscriptProviderName>(['ytdlp', 'whisper', 'gemini']);
 

package/src/services/transcriptAnalyzers/index.ts

@@ -3,4 +3,4 @@ export { YtDlpTranscriptAnalyzer } from './ytdlp.js';
 export { WhisperTranscriptAnalyzer } from './whisper.js';
 export { GeminiTranscriptAnalyzer } from './gemini.js';
 export { createTranscriptChain, parseTranscriptProviderChain } from './factory.js';
-export type { TranscriptProviderName } from './factory.js';
+export type { TranscriptProviderName } from '../../types/index.js';

package/src/services/transcriptDetector/index.ts

@@ -3,13 +3,12 @@ import { log } from '../../utils/logger.js';
 import { config } from '../../config/index.js';
 import type { TranscriptAnalyzer } from '../transcriptAnalyzers/index.js';
 import type { Cache } from '../../utils/cache.js';
-import type { TranscriptLine, MicroBlock, LLMChunk } from '../../types/index.js';
-
-export interface TranscriptDetectorResult {
-  lines: TranscriptLine[];
-  microBlocks: MicroBlock[];
-  chunks: LLMChunk[];
-}
+import type {
+  TranscriptLine,
+  MicroBlock,
+  LLMChunk,
+  TranscriptDetectorResult,
+} from '../../types/index.js';
 
 /**
  * Top-level transcript detector.
@@ -60,7 +59,6 @@ export class TranscriptDetector {
   ): Promise<TranscriptDetectorResult> {
     let lines: TranscriptLine[];
 
-    // 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)`);
@@ -76,10 +74,6 @@ export class TranscriptDetector {
     return { lines, microBlocks, chunks };
   }
 
-  // -------------------------------------------------------------------------
-  // Private helpers
-  // -------------------------------------------------------------------------
-
   /**
    * Walks the analyzer chain in order.
    * Falls back to the next analyzer whenever one throws.

package/src/services/transcriptFetcher/index.ts

@@ -20,7 +20,7 @@ export function parseVtt(vttContent: string): TranscriptLine[] {
   const lines = vttContent.split(/\r?\n/);
   const result: TranscriptLine[] = [];
 
-  // 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})/;
 
@@ -42,7 +42,6 @@ export function parseVtt(vttContent: string): TranscriptLine[] {
         parseInt(match[7], 10) +
         parseInt(match[8], 10) / 1000;
 
-      // Collect cue text lines until blank line or EOF
       i++;
       const textLines: string[] = [];
       while (i < lines.length && lines[i].trim() !== '') {
@@ -52,7 +51,6 @@ export function parseVtt(vttContent: string): TranscriptLine[] {
 
       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, '&')
@@ -68,8 +66,7 @@ export function parseVtt(vttContent: string): TranscriptLine[] {
 
       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;
       }
@@ -125,7 +122,6 @@ export async function fetchTranscript(videoId: string): Promise<TranscriptLine[]
       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'));
 

package/src/services/urlParser/index.ts

@@ -40,7 +40,6 @@ export function parseUrl(url: string): string {
     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) {

package/src/services/videoDownloader/index.ts

@@ -4,21 +4,7 @@ import { join } from 'path';
 import pLimit from 'p-limit';
 import { config } from '../../config/index.js';
 import { log } from '../../utils/logger.js';
-import type { RankedSegment } from '../../types/index.js';
-
-export type DownloadMode = 'all' | 'segments';
-
-export interface DownloadResultAll {
-  mode: 'all';
-  path: string;
-}
-
-export interface DownloadResultSegments {
-  mode: 'segments';
-  paths: string[];
-}
-
-export type DownloadResult = DownloadResultAll | DownloadResultSegments;
+import type { RankedSegment, DownloadMode, DownloadResult } from '../../types/index.js';
 
 /**
  * Formats a timestamp for yt-dlp --download-sections.

package/src/types/analyzer.ts

@@ -0,0 +1,23 @@
+import type { TranscriptLine, MicroBlock, LLMChunk, ChunkEvaluation } from './index.js';
+
+export interface LLMAnalyzerResult {
+  lines: TranscriptLine[];
+  microBlocks: MicroBlock[];
+  chunks: LLMChunk[];
+  chunkEvals: ChunkEvaluation[];
+}
+
+export interface LLMAnalyzerOpts {
+  videoId: string;
+  audioPath: string | null;
+  audioEvents: import('./audio.js').AudioEvent[];
+  maxChunks?: number;
+  maxParallel: number;
+  noCache: boolean;
+}
+
+export interface TranscriptDetectorResult {
+  lines: TranscriptLine[];
+  microBlocks: MicroBlock[];
+  chunks: LLMChunk[];
+}

package/src/types/cache.ts

@@ -0,0 +1,8 @@
+import { z } from 'zod';
+
+export const SegmentRefinementSchema = z.object({
+  refined_start: z.number(),
+  refined_end: z.number(),
+});
+
+export type SegmentRefinement = z.infer<typeof SegmentRefinementSchema>;

package/src/types/config.ts

@@ -14,7 +14,6 @@ const LLM_PROVIDERS = [
 
 export type LLMProvider = (typeof LLM_PROVIDERS)[number];
 
-/** Map each provider to the env var name that holds its API key. */
 const PROVIDER_KEY_MAP: Record<LLMProvider, string> = {
   openai: 'OPENAI_API_KEY',
   anthropic: 'ANTHROPIC_API_KEY',
@@ -29,10 +28,8 @@ const PROVIDER_KEY_MAP: Record<LLMProvider, string> = {
 
 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(),
@@ -44,7 +41,6 @@ export const ConfigSchema = z
     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),
@@ -55,32 +51,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')
@@ -97,10 +81,7 @@ export const ConfigSchema = z
             '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')
@@ -127,9 +108,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(),
@@ -148,7 +127,6 @@ export const ConfigSchema = z
       });
     }
 
-    // custom provider also requires a base URL
     if (
       provider === 'custom' &&
       (!data.CUSTOM_OPENAI_BASE_URL || data.CUSTOM_OPENAI_BASE_URL.trim() === '')
@@ -160,7 +138,6 @@ export const ConfigSchema = z
       });
     }
 
-    // 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/src/types/downloader.ts

@@ -0,0 +1,15 @@
+import type { RankedSegment } from './index.js';
+
+export type DownloadMode = 'all' | 'segments';
+
+export interface DownloadResultAll {
+  mode: 'all';
+  path: string;
+}
+
+export interface DownloadResultSegments {
+  mode: 'segments';
+  paths: string[];
+}
+
+export type DownloadResult = DownloadResultAll | DownloadResultSegments;

package/src/types/factory.ts

@@ -0,0 +1,3 @@
+export type TranscriptProviderName = 'ytdlp' | 'whisper' | 'gemini';
+
+export type AudioProviderName = 'gemini' | 'whisper' | 'yamnet';

package/src/types/index.ts

@@ -24,3 +24,17 @@ export type {
   SegmentSelectorOpts,
   ClipExporterOpts,
 } from './pipeline.js';
+
+export type { LLMAnalyzerResult, LLMAnalyzerOpts, TranscriptDetectorResult } from './analyzer.js';
+
+export type {
+  DownloadMode,
+  DownloadResultAll,
+  DownloadResultSegments,
+  DownloadResult,
+} from './downloader.js';
+
+export { SegmentRefinementSchema } from './cache.js';
+export type { SegmentRefinement } from './cache.js';
+
+export type { TranscriptProviderName, AudioProviderName } from './factory.js';

package/src/types/pipeline.ts

@@ -1,12 +1,3 @@
-/**
- * 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.
- */
-
 import type {
   VideoMetadata,
   TranscriptLine,
@@ -15,10 +6,6 @@ import type {
   ChunkEvaluation,
 } from './index.js';
 
-// ---------------------------------------------------------------------------
-// Chunker utility
-// ---------------------------------------------------------------------------
-
 /** A half-open time window [start, end) in seconds. Returned by `buildWindows`. */
 export interface ChunkWindow {
   /** Start of the window in seconds (inclusive). */
@@ -27,19 +14,11 @@ export interface ChunkWindow {
   end: number;
 }
 
-// ---------------------------------------------------------------------------
-// Stage 1 — Video Resolver
-// ---------------------------------------------------------------------------
-
 export interface VideoResolverResult {
   videoId: string;
   metadata: VideoMetadata;
 }
 
-// ---------------------------------------------------------------------------
-// Stage 3 — Audio Processor
-// ---------------------------------------------------------------------------
-
 export interface AudioProcessorOpts {
   noAudio: boolean;
   gameProfile: string;
@@ -48,10 +27,6 @@ export interface AudioProcessorOpts {
   audioPath?: string | null;
 }
 
-// ---------------------------------------------------------------------------
-// Stage 4a + 4b — Segment Analyzer / Refiner
-// ---------------------------------------------------------------------------
-
 export interface SegmentAnalyzerOpts {
   maxChunks?: number;
   maxParallel: number;
@@ -65,19 +40,11 @@ export interface SegmentAnalyzerResult {
   chunkEvals: ChunkEvaluation[];
 }
 
-// ---------------------------------------------------------------------------
-// Stage 5 — Segment Selector
-// ---------------------------------------------------------------------------
-
 export interface SegmentSelectorOpts {
   threshold: number;
   topN: number;
 }
 
-// ---------------------------------------------------------------------------
-// Stage 6 — Clip Exporter
-// ---------------------------------------------------------------------------
-
 export interface ClipExporterOpts {
   /** Path to a pre-existing local video file. Skips yt-dlp download entirely. */
   localVideo?: string;

package/src/types/segment.ts

@@ -4,15 +4,15 @@ 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 type AnalyzedSegment = z.infer<typeof AnalyzedSegmentSchema>;
 
 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']),
@@ -22,8 +22,8 @@ export type RankedSegment = z.infer<typeof RankedSegmentSchema>;
 
 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', [

package/src/types/transcript.ts

@@ -2,21 +2,21 @@ 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 type TranscriptLine = z.infer<typeof TranscriptLineSchema>;
 
 export const MicroBlockSchema = z.object({
-  start: z.number(), // seconds
-  end: z.number(), // seconds
+  start: z.number(),
+  end: z.number(),
   text: z.string(),
 });
 export type MicroBlock = z.infer<typeof MicroBlockSchema>;
 
 export const LLMChunkSchema = z.object({
-  start: z.number(), // seconds
-  end: z.number(), // seconds
+  start: z.number(),
+  end: z.number(),
   text: z.string(),
 });
 export type LLMChunk = z.infer<typeof LLMChunkSchema>;

package/src/utils/cache.ts

@@ -3,12 +3,19 @@ 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';
-import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent } from '../types/index.js';
-
-// ---------------------------------------------------------------------------
-// Internal cache-key helpers
-// ---------------------------------------------------------------------------
+import {
+  TranscriptLineSchema,
+  ChunkEvaluationSchema,
+  AudioEventSchema,
+  SegmentRefinementSchema,
+} from '../types/index.js';
+import type {
+  TranscriptLine,
+  LLMChunk,
+  ChunkEvaluation,
+  AudioEvent,
+  SegmentRefinement,
+} from '../types/index.js';
 
 /**
  * Serializes audio events into a stable string for cache keying.
@@ -50,12 +57,6 @@ async function writeCacheFile(filePath: string, data: unknown): Promise<void> {
   }
 }
 
-const SegmentRefinementSchema = z.object({
-  refined_start: z.number(),
-  refined_end: z.number(),
-});
-type SegmentRefinement = z.infer<typeof SegmentRefinementSchema>;
-
 /**
  * Disk-backed cache for all pipeline stages.
  *