@thunderkiller/video-clipper 1.1.0

package/src/types/config.ts

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

package/src/types/index.ts

@@ -0,0 +1,26 @@
+export { ConfigSchema } from './config.js';
+export type { Config } from './config.js';
+
+export { TranscriptLineSchema, MicroBlockSchema, LLMChunkSchema } from './transcript.js';
+export type { TranscriptLine, MicroBlock, LLMChunk } from './transcript.js';
+
+export { AnalyzedSegmentSchema, RankedSegmentSchema, ChunkEvaluationSchema } from './segment.js';
+export type { AnalyzedSegment, RankedSegment, ChunkEvaluation } from './segment.js';
+
+export { AudioEventSchema, MergedCandidateSchema } from './audio.js';
+export type { AudioEvent, MergedCandidate } from './audio.js';
+
+export { VideoMetadataSchema, PipelineResultSchema } from './video.js';
+export type { VideoMetadata, PipelineResult } from './video.js';
+
+export type { CliArgs } from './cli.js';
+
+export type {
+  ChunkWindow,
+  VideoResolverResult,
+  AudioProcessorOpts,
+  SegmentAnalyzerOpts,
+  SegmentAnalyzerResult,
+  SegmentSelectorOpts,
+  ClipExporterOpts,
+} from './pipeline.js';

package/src/types/pipeline.ts

@@ -0,0 +1,93 @@
+/**
+ * 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,
+  MicroBlock,
+  LLMChunk,
+  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). */
+  start: number;
+  /** End of the window in seconds (exclusive upper bound). */
+  end: number;
+}
+
+// ---------------------------------------------------------------------------
+// Stage 1 — Video Resolver
+// ---------------------------------------------------------------------------
+
+export interface VideoResolverResult {
+  videoId: string;
+  metadata: VideoMetadata;
+}
+
+// ---------------------------------------------------------------------------
+// Stage 3 — Audio Processor
+// ---------------------------------------------------------------------------
+
+export interface AudioProcessorOpts {
+  noAudio: boolean;
+  gameProfile: string;
+  maxParallel: number;
+  /** Pre-downloaded audio WAV path. When provided, skips the downloadAudio call. */
+  audioPath?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Stage 4a + 4b — Segment Analyzer / Refiner
+// ---------------------------------------------------------------------------
+
+export interface SegmentAnalyzerOpts {
+  maxChunks?: number;
+  maxParallel: number;
+  noCache: boolean;
+}
+
+export interface SegmentAnalyzerResult {
+  lines: TranscriptLine[];
+  microBlocks: MicroBlock[];
+  chunks: LLMChunk[];
+  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;
+  /**
+   * yt-dlp download strategy.
+   *   - `'all'`   — download the full video, then cut clips with ffmpeg
+   *   - number    — download only the top-N segments via --download-sections
+   *   - undefined — same as `'all'`
+   */
+  downloadSections: 'all' | number | undefined;
+  /** Custom output/download directory (overrides config.DOWNLOAD_DIR / config.OUTPUT_DIR). */
+  videoPath?: string;
+}

package/src/types/segment.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+export const AnalyzedSegmentSchema = z.object({
+  interesting: z.boolean(),
+  score: z.number().min(1).max(10),
+  reason: z.string(),
+  clip_start: z.number(), // seconds
+  clip_end: z.number(), // seconds
+});
+export 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
+  score: z.number().min(1).max(10),
+  reason: z.string(),
+  source: z.enum(['transcript', 'audio', 'both']),
+  audio_event: z.string().optional(),
+});
+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
+});
+
+export const ChunkEvaluationSchema = z.discriminatedUnion('status', [
+  ChunkEvaluationBaseSchema.extend({
+    status: z.literal('success'),
+    interesting: z.boolean(),
+    score: z.number().min(1).max(10),
+    reason: z.string(),
+    clip_start: z.number(),
+    clip_end: z.number(),
+  }),
+  ChunkEvaluationBaseSchema.extend({
+    status: z.literal('failed'),
+    error: z.string(),
+  }),
+]);
+export type ChunkEvaluation = z.infer<typeof ChunkEvaluationSchema>;

package/src/types/transcript.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+export const TranscriptLineSchema = z.object({
+  text: z.string(),
+  start: z.number(), // seconds (normalized from offset ms)
+  duration: z.number(), // seconds (normalized from duration ms)
+});
+export type TranscriptLine = z.infer<typeof TranscriptLineSchema>;
+
+export const MicroBlockSchema = z.object({
+  start: z.number(), // seconds
+  end: z.number(), // seconds
+  text: z.string(),
+});
+export type MicroBlock = z.infer<typeof MicroBlockSchema>;
+
+export const LLMChunkSchema = z.object({
+  start: z.number(), // seconds
+  end: z.number(), // seconds
+  text: z.string(),
+});
+export type LLMChunk = z.infer<typeof LLMChunkSchema>;

package/src/types/video.ts

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

package/src/utils/cache.ts

@@ -0,0 +1,223 @@
+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';
+import type { TranscriptLine, LLMChunk, ChunkEvaluation, AudioEvent } 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: AudioEvent[]): string {
+  if (events.length === 0) return '';
+  const sorted = [...events].sort((a, b) => a.time - b.time);
+  return JSON.stringify(sorted);
+}
+
+function hashContent(input: string): string {
+  return createHash('sha256').update(input).digest('hex');
+}
+
+async function readCacheFile<T>(filePath: string, schema: z.ZodType<T>): Promise<T | null> {
+  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: string, data: unknown): Promise<void> {
+  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(),
+});
+type SegmentRefinement = z.infer<typeof SegmentRefinementSchema>;
+
+/**
+ * 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 {
+  constructor(
+    private readonly cacheDir: string,
+    private readonly disabled: boolean = false,
+  ) {}
+
+  // ---- Transcript ---------------------------------------------------------
+
+  private transcriptPath(videoId: string): string {
+    return path.join(this.cacheDir, 'transcript', `${hashContent(videoId)}.json`);
+  }
+
+  async readTranscript(videoId: string): Promise<TranscriptLine[] | null> {
+    if (this.disabled) return null;
+    return readCacheFile(this.transcriptPath(videoId), z.array(TranscriptLineSchema));
+  }
+
+  async writeTranscript(videoId: string, lines: TranscriptLine[]): Promise<void> {
+    if (this.disabled) return;
+    await writeCacheFile(this.transcriptPath(videoId), lines);
+  }
+
+  // ---- LLM chunk results --------------------------------------------------
+
+  private chunkPath(chunk: LLMChunk, chunkAudioEvents: AudioEvent[] = []): string {
+    const audioKey = audioEventsKey(chunkAudioEvents);
+    return path.join(
+      this.cacheDir,
+      'chunks',
+      `${hashContent(`${chunk.start}|${chunk.end}|${chunk.text}|${audioKey}`)}.json`,
+    );
+  }
+
+  async readChunk(
+    chunk: LLMChunk,
+    chunkAudioEvents: AudioEvent[] = [],
+  ): Promise<ChunkEvaluation | null> {
+    if (this.disabled) return null;
+    return readCacheFile(this.chunkPath(chunk, chunkAudioEvents), ChunkEvaluationSchema);
+  }
+
+  async writeChunk(
+    chunk: LLMChunk,
+    evaluation: ChunkEvaluation,
+    chunkAudioEvents: AudioEvent[] = [],
+  ): Promise<void> {
+    if (this.disabled) return;
+    if (evaluation.status !== 'success') return;
+    await writeCacheFile(this.chunkPath(chunk, chunkAudioEvents), evaluation);
+  }
+
+  // ---- Segment refinement -------------------------------------------------
+
+  private segmentRefinementPath(start: number, end: number, reason: string): string {
+    return path.join(this.cacheDir, 'segments', `${hashContent(`${start}|${end}|${reason}`)}.json`);
+  }
+
+  async readSegmentRefinement(
+    start: number,
+    end: number,
+    reason: string,
+  ): Promise<SegmentRefinement | null> {
+    if (this.disabled) return null;
+    return readCacheFile(this.segmentRefinementPath(start, end, reason), SegmentRefinementSchema);
+  }
+
+  async writeSegmentRefinement(
+    start: number,
+    end: number,
+    reason: string,
+    refined: SegmentRefinement,
+  ): Promise<void> {
+    if (this.disabled) return;
+    await writeCacheFile(this.segmentRefinementPath(start, end, reason), refined);
+  }
+
+  // ---- Audio events (whole-video) -----------------------------------------
+
+  private audioEventPath(videoId: string, gameProfile: string, provider: string): string {
+    return path.join(
+      this.cacheDir,
+      'audio',
+      `${hashContent(`${videoId}|${gameProfile}|${provider}`)}.json`,
+    );
+  }
+
+  async readAudioEvents(
+    videoId: string,
+    gameProfile: string,
+    provider: string,
+  ): Promise<AudioEvent[] | null> {
+    if (this.disabled) return null;
+    return readCacheFile(
+      this.audioEventPath(videoId, gameProfile, provider),
+      z.array(AudioEventSchema),
+    );
+  }
+
+  async writeAudioEvents(
+    videoId: string,
+    gameProfile: string,
+    provider: string,
+    events: AudioEvent[],
+  ): Promise<void> {
+    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.
+   */
+  private audioChunkPath(
+    videoId: string,
+    gameProfile: string,
+    provider: string,
+    windowStart: number,
+    windowEnd: number,
+  ): string {
+    return path.join(
+      this.cacheDir,
+      'audio',
+      `${hashContent(`${videoId}|${gameProfile}|${provider}|${windowStart}|${windowEnd}`)}.json`,
+    );
+  }
+
+  async readAudioChunk(
+    videoId: string,
+    gameProfile: string,
+    provider: string,
+    windowStart: number,
+    windowEnd: number,
+  ): Promise<AudioEvent[] | null> {
+    if (this.disabled) return null;
+    return readCacheFile(
+      this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd),
+      z.array(AudioEventSchema),
+    );
+  }
+
+  async writeAudioChunk(
+    videoId: string,
+    gameProfile: string,
+    provider: string,
+    windowStart: number,
+    windowEnd: number,
+    events: AudioEvent[],
+  ): Promise<void> {
+    if (this.disabled) return;
+    await writeCacheFile(
+      this.audioChunkPath(videoId, gameProfile, provider, windowStart, windowEnd),
+      events,
+    );
+  }
+}

package/src/utils/chunker.ts

@@ -0,0 +1,60 @@
+/**
+ * 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).
+ */
+
+import type { ChunkWindow } from '../types/index.js';
+
+export type { ChunkWindow };
+
+/**
+ * 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: number,
+  windowSec: number,
+  overlapSec: number = 0,
+): ChunkWindow[] {
+  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: ChunkWindow[] = [];
+
+  for (let start = 0; start < totalDuration; start += step) {
+    windows.push({
+      start,
+      end: Math.min(start + windowSec, totalDuration),
+    });
+  }
+
+  return windows;
+}