aivee 0.1.0-alpha.0 → 0.1.0-dev.d34a6ba

package/src/doctor.mjs

@@ -1,133 +1,133 @@
-#!/usr/bin/env node
-import { spawnSync } from 'node:child_process';
-import { createRequire } from 'node:module';
-import { listFfmpegEncoders, listFfmpegFilters } from './media/ffmpeg-capabilities.mjs';
-import { doctorHyperframes } from './render/hyperframes.mjs';
-
-const nodeVersion = process.versions.node.split('.').map(Number);
-const require = createRequire(import.meta.url);
-const results = [
-  {
-    name: 'Node.js',
-    ok: nodeVersion[0] >= 22,
-    detail: `found ${process.versions.node}; requires 22 or newer`,
-  },
-  checkCommand('FFmpeg', 'ffmpeg'),
-  checkCommand('ffprobe', 'ffprobe'),
-  checkPackage('HyperFrames', 'hyperframes'),
-  checkPackage('GSAP', 'gsap'),
-];
-
-for (const result of results) {
-  console.log(`${result.ok ? '✓' : '✗'} ${result.name}: ${result.detail}`);
-  if (!result.ok && result.name !== 'Node.js') {
-    if (result.name === 'FFmpeg' || result.name === 'ffprobe') {
-      console.log('  Install FFmpeg with ffprobe and make both commands available on PATH.');
-      console.log('  Guide: https://ffmpeg.org/download.html');
-    } else if (result.name === 'HyperFrames' || result.name === 'GSAP') {
-      console.log('  Run npm install in the engine repository.');
-    }
-  } else if (!result.ok && result.name === 'Node.js') {
-    console.log('  Install Node.js 22 or newer: https://nodejs.org/en/download');
-  }
-}
-
-const ready = results.every((result) => result.ok);
-const otioPython = process.env.AIVE_OTIO_PYTHON || process.env.PYTHON || 'python';
-const openTimelineIO = checkPythonModule('OpenTimelineIO', otioPython);
-console.log(`${openTimelineIO.ok ? '✓' : '⚠'} Optional ${openTimelineIO.name}: ${openTimelineIO.detail}`);
-if (!openTimelineIO.ok) {
-  console.log('  Install with `python -m pip install -r requirements-otio.txt` or set `AIVE_OTIO_PYTHON` to a Python command with OpenTimelineIO installed.');
-}
-if (results.find((result) => result.name === 'HyperFrames')?.ok) {
-  console.log('\nChecking HyperFrames renderer requirements:');
-  try {
-    doctorHyperframes(process.cwd());
-  } catch (error) {
-    console.error(error.message);
-    process.exitCode = 1;
-  }
-}
-console.log(ready
-  ? 'Core Engine requirements are available; optional and feature-specific tools are reported above.'
-  : 'Some required Engine tools are missing.');
-try {
-  const filters = listFfmpegFilters();
-  for (const [filter, requirement] of [
-    ['rubberband', 'pitch-preserving audio speed ramps'],
-    ['equalizer', 'audio equalization and mastering bands'],
-    ['highpass', 'audio high-pass filtering'],
-    ['lowpass', 'audio low-pass filtering'],
-    ['acompressor', 'audio compression effects'],
-    ['afftdn', 'per-clip spectral denoise'],
-    ['stereotools', 'per-clip stereo balance'],
-    ['sidechaincompress', 'signal-aware sidechain compression'],
-    ['loudnorm', 'audio loudness mastering'],
-    ['alimiter', 'audio peak limiting'],
-    ['aresample', 'mastered output channel mapping'],
-    ['reverse', 'video reverse playback'],
-    ['areverse', 'audio reverse playback'],
-    ['colorspace', 'Rec.709 and Rec.2020 SDR output profiles'],
-    ['zscale', 'HDR10 output'],
-  ]) {
-    const available = filters.has(filter);
-    console.log(`${available ? '✓' : '⚠'} FFmpeg ${filter} filter: ${available ? 'available' : `not available; required for ${requirement}`}`);
-  }
-} catch (error) {
-  console.log(`⚠ FFmpeg filters: could not verify (${error.message})`);
-}
-if (results.find((result) => result.name === 'FFmpeg')?.ok) {
-  try {
-    const encoders = listFfmpegEncoders();
-    for (const [name, encoder] of [['H.264', 'libx264'], ['H.265', 'libx265'], ['VP9', 'libvpx-vp9'], ['ProRes', 'prores_ks']]) {
-      const available = encoders.has(encoder);
-      console.log(`${available ? '✓' : '⚠'} FFmpeg ${name} encoder: ${available ? 'available' : `not available (${encoder})`}`);
-    }
-  } catch (error) {
-    console.log(`⚠ FFmpeg encoders: could not verify (${error.message})`);
-  }
-}
-if (!ready) process.exitCode = 1;
-
-function checkCommand(label, command, args = ['-version']) {
-  const result = spawnSync(command, args, {
-    encoding: 'utf8',
-    windowsHide: true,
-  });
-  if (result.error || result.status !== 0) {
-    return { name: label, ok: false, detail: 'not found or failed to run' };
-  }
-  const firstLine = result.stdout.trim().split(/\r?\n/, 1)[0];
-  return { name: label, ok: true, detail: firstLine };
-}
-
-function checkPackage(label, packageName) {
-  try {
-    require.resolve(`${packageName}/package.json`);
-    return { name: label, ok: true, detail: 'installed' };
-  } catch {
-    return { name: label, ok: false, detail: 'not installed' };
-  }
-}
-
-function checkPythonModule(label, command) {
-  const result = spawnSync(command, ['-c', "import opentimelineio as otio; assert 'otio_json' in otio.adapters.available_adapter_names(), 'otio_json adapter unavailable'; print(getattr(otio, '__version__', 'installed'))"], {
-    encoding: 'utf8',
-    windowsHide: true,
-    maxBuffer: 1024 * 1024,
-  });
-  if (result.error) return { name: label, ok: false, detail: `Python command unavailable (${command})` };
-  if (result.status !== 0) {
-    const details = `${result.stderr}\n${result.stdout}`;
-    return {
-      name: label,
-      ok: false,
-      detail: /No module named ['"]?opentimelineio/.test(details)
-        ? 'Python package not installed'
-        : /otio_json adapter unavailable/.test(details)
-          ? 'JSON adapter not available'
-          : 'Python package failed to import',
-    };
-  }
-  return { name: label, ok: true, detail: `Python package ${result.stdout.trim().split(/\r?\n/, 1)[0]}` };
-}
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { listFfmpegEncoders, listFfmpegFilters } from './media/ffmpeg-capabilities.mjs';
+import { doctorHyperframes } from './render/hyperframes.mjs';
+
+const nodeVersion = process.versions.node.split('.').map(Number);
+const require = createRequire(import.meta.url);
+const results = [
+  {
+    name: 'Node.js',
+    ok: nodeVersion[0] >= 22,
+    detail: `found ${process.versions.node}; requires 22 or newer`,
+  },
+  checkCommand('FFmpeg', 'ffmpeg'),
+  checkCommand('ffprobe', 'ffprobe'),
+  checkPackage('HyperFrames', 'hyperframes'),
+  checkPackage('GSAP', 'gsap'),
+];
+
+for (const result of results) {
+  console.log(`${result.ok ? '✓' : '✗'} ${result.name}: ${result.detail}`);
+  if (!result.ok && result.name !== 'Node.js') {
+    if (result.name === 'FFmpeg' || result.name === 'ffprobe') {
+      console.log('  Install FFmpeg with ffprobe and make both commands available on PATH.');
+      console.log('  Guide: https://ffmpeg.org/download.html');
+    } else if (result.name === 'HyperFrames' || result.name === 'GSAP') {
+      console.log('  Run npm install in the engine repository.');
+    }
+  } else if (!result.ok && result.name === 'Node.js') {
+    console.log('  Install Node.js 22 or newer: https://nodejs.org/en/download');
+  }
+}
+
+const ready = results.every((result) => result.ok);
+const otioPython = process.env.AIVE_OTIO_PYTHON || process.env.PYTHON || 'python';
+const openTimelineIO = checkPythonModule('OpenTimelineIO', otioPython);
+console.log(`${openTimelineIO.ok ? '✓' : '⚠'} Optional ${openTimelineIO.name}: ${openTimelineIO.detail}`);
+if (!openTimelineIO.ok) {
+  console.log('  Install with `python -m pip install -r requirements-otio.txt` or set `AIVE_OTIO_PYTHON` to a Python command with OpenTimelineIO installed.');
+}
+if (results.find((result) => result.name === 'HyperFrames')?.ok) {
+  console.log('\nChecking HyperFrames renderer requirements:');
+  try {
+    doctorHyperframes(process.cwd());
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}
+console.log(ready
+  ? 'Core Engine requirements are available; optional and feature-specific tools are reported above.'
+  : 'Some required Engine tools are missing.');
+try {
+  const filters = listFfmpegFilters();
+  for (const [filter, requirement] of [
+    ['rubberband', 'pitch-preserving audio speed ramps'],
+    ['equalizer', 'audio equalization and mastering bands'],
+    ['highpass', 'audio high-pass filtering'],
+    ['lowpass', 'audio low-pass filtering'],
+    ['acompressor', 'audio compression effects'],
+    ['afftdn', 'per-clip spectral denoise'],
+    ['stereotools', 'per-clip stereo balance'],
+    ['sidechaincompress', 'signal-aware sidechain compression'],
+    ['loudnorm', 'audio loudness mastering'],
+    ['alimiter', 'audio peak limiting'],
+    ['aresample', 'mastered output channel mapping'],
+    ['reverse', 'video reverse playback'],
+    ['areverse', 'audio reverse playback'],
+    ['colorspace', 'Rec.709 and Rec.2020 SDR output profiles'],
+    ['zscale', 'HDR10 output'],
+  ]) {
+    const available = filters.has(filter);
+    console.log(`${available ? '✓' : '⚠'} FFmpeg ${filter} filter: ${available ? 'available' : `not available; required for ${requirement}`}`);
+  }
+} catch (error) {
+  console.log(`⚠ FFmpeg filters: could not verify (${error.message})`);
+}
+if (results.find((result) => result.name === 'FFmpeg')?.ok) {
+  try {
+    const encoders = listFfmpegEncoders();
+    for (const [name, encoder] of [['H.264', 'libx264'], ['H.265', 'libx265'], ['VP9', 'libvpx-vp9'], ['ProRes', 'prores_ks']]) {
+      const available = encoders.has(encoder);
+      console.log(`${available ? '✓' : '⚠'} FFmpeg ${name} encoder: ${available ? 'available' : `not available (${encoder})`}`);
+    }
+  } catch (error) {
+    console.log(`⚠ FFmpeg encoders: could not verify (${error.message})`);
+  }
+}
+if (!ready) process.exitCode = 1;
+
+function checkCommand(label, command, args = ['-version']) {
+  const result = spawnSync(command, args, {
+    encoding: 'utf8',
+    windowsHide: true,
+  });
+  if (result.error || result.status !== 0) {
+    return { name: label, ok: false, detail: 'not found or failed to run' };
+  }
+  const firstLine = result.stdout.trim().split(/\r?\n/, 1)[0];
+  return { name: label, ok: true, detail: firstLine };
+}
+
+function checkPackage(label, packageName) {
+  try {
+    require.resolve(`${packageName}/package.json`);
+    return { name: label, ok: true, detail: 'installed' };
+  } catch {
+    return { name: label, ok: false, detail: 'not installed' };
+  }
+}
+
+function checkPythonModule(label, command) {
+  const result = spawnSync(command, ['-c', "import opentimelineio as otio; assert 'otio_json' in otio.adapters.available_adapter_names(), 'otio_json adapter unavailable'; print(getattr(otio, '__version__', 'installed'))"], {
+    encoding: 'utf8',
+    windowsHide: true,
+    maxBuffer: 1024 * 1024,
+  });
+  if (result.error) return { name: label, ok: false, detail: `Python command unavailable (${command})` };
+  if (result.status !== 0) {
+    const details = `${result.stderr}\n${result.stdout}`;
+    return {
+      name: label,
+      ok: false,
+      detail: /No module named ['"]?opentimelineio/.test(details)
+        ? 'Python package not installed'
+        : /otio_json adapter unavailable/.test(details)
+          ? 'JSON adapter not available'
+          : 'Python package failed to import',
+    };
+  }
+  return { name: label, ok: true, detail: `Python package ${result.stdout.trim().split(/\r?\n/, 1)[0]}` };
+}

package/src/edits/analysis-to-edl.mjs

@@ -1,43 +1,43 @@
-import { validateEdl } from './retime-transcript.mjs';
-import { normalizeMediaFindings } from '../media/analysis-provider.mjs';
-
-/** Convert explicit provider cut suggestions into an EDL that requires review. */
-export function mediaAnalysisToEdl(analysis, { minConfidence = 0 } = {}) {
-  if (!analysis || typeof analysis !== 'object' || analysis.schemaVersion !== 1
-      || !Number.isFinite(analysis.durationSeconds) || analysis.durationSeconds <= 0
-      || !Array.isArray(analysis.findings)) {
-    throw new TypeError('Media analysis must be a normalized schemaVersion 1 result.');
-  }
-  if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 1) {
-    throw new TypeError('minConfidence must be between 0 and 1.');
-  }
-  const normalizedFindings = normalizeMediaFindings({ findings: analysis.findings }, analysis.durationSeconds).findings;
-
-  const cuts = normalizedFindings
-    .filter((finding) => finding.suggestion && (finding.confidence ?? 0) >= minConfidence)
-    .map((finding) => ({
-      sourceStart: finding.suggestion.sourceStart,
-      sourceEnd: finding.suggestion.sourceEnd,
-      reason: `${finding.id}: ${finding.suggestion.reason}`,
-    }))
-    .sort((left, right) => left.sourceStart - right.sourceStart || left.sourceEnd - right.sourceEnd)
-    .reduce((result, cut) => {
-      const previous = result.at(-1);
-      if (previous && cut.sourceStart < previous.sourceEnd) {
-        previous.sourceEnd = Math.max(previous.sourceEnd, cut.sourceEnd);
-        previous.reason = `${previous.reason}; ${cut.reason}`;
-      } else {
-        result.push(cut);
-      }
-      return result;
-    }, []);
-
-  const edl = {
-    schemaVersion: 1,
-    sourceDurationSeconds: analysis.durationSeconds,
-    reviewStatus: 'needs-review',
-    cuts,
-  };
-  validateEdl(edl, analysis.durationSeconds);
-  return edl;
-}
+import { validateEdl } from './retime-transcript.mjs';
+import { normalizeMediaFindings } from '../media/analysis-provider.mjs';
+
+/** Convert explicit provider cut suggestions into an EDL that requires review. */
+export function mediaAnalysisToEdl(analysis, { minConfidence = 0 } = {}) {
+  if (!analysis || typeof analysis !== 'object' || analysis.schemaVersion !== 1
+      || !Number.isFinite(analysis.durationSeconds) || analysis.durationSeconds <= 0
+      || !Array.isArray(analysis.findings)) {
+    throw new TypeError('Media analysis must be a normalized schemaVersion 1 result.');
+  }
+  if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 1) {
+    throw new TypeError('minConfidence must be between 0 and 1.');
+  }
+  const normalizedFindings = normalizeMediaFindings({ findings: analysis.findings }, analysis.durationSeconds).findings;
+
+  const cuts = normalizedFindings
+    .filter((finding) => finding.suggestion && (finding.confidence ?? 0) >= minConfidence)
+    .map((finding) => ({
+      sourceStart: finding.suggestion.sourceStart,
+      sourceEnd: finding.suggestion.sourceEnd,
+      reason: `${finding.id}: ${finding.suggestion.reason}`,
+    }))
+    .sort((left, right) => left.sourceStart - right.sourceStart || left.sourceEnd - right.sourceEnd)
+    .reduce((result, cut) => {
+      const previous = result.at(-1);
+      if (previous && cut.sourceStart < previous.sourceEnd) {
+        previous.sourceEnd = Math.max(previous.sourceEnd, cut.sourceEnd);
+        previous.reason = `${previous.reason}; ${cut.reason}`;
+      } else {
+        result.push(cut);
+      }
+      return result;
+    }, []);
+
+  const edl = {
+    schemaVersion: 1,
+    sourceDurationSeconds: analysis.durationSeconds,
+    reviewStatus: 'needs-review',
+    cuts,
+  };
+  validateEdl(edl, analysis.durationSeconds);
+  return edl;
+}

package/src/edits/detect-silence.mjs

@@ -1,51 +1,51 @@
-import { spawnSync } from 'node:child_process';
-import { probeMedia } from '../media/probe.mjs';
-import { validateEdl } from './retime-transcript.mjs';
-
-export function detectAcousticSilence(inputPath, options = {}) {
-  const media = probeMedia(inputPath, { requireVideo: false });
-  if (!media.hasAudio) throw new TypeError('Acoustic silence detection requires an audio stream.');
-  const noiseDb = options.noiseDb ?? -35;
-  const minSilenceSeconds = options.minSilenceSeconds ?? 0.5;
-  const paddingSeconds = options.paddingSeconds ?? 0.12;
-  if (!Number.isFinite(noiseDb) || noiseDb < -90 || noiseDb > 0) throw new TypeError('noiseDb must be between -90 and 0.');
-  if (!Number.isFinite(minSilenceSeconds) || minSilenceSeconds <= 0) throw new TypeError('minSilenceSeconds must be positive.');
-  if (!Number.isFinite(paddingSeconds) || paddingSeconds < 0) throw new TypeError('paddingSeconds must be non-negative.');
-
-  const result = spawnSync('ffmpeg', [
-    '-nostdin', '-hide_banner', '-i', media.path,
-    '-af', `silencedetect=noise=${noiseDb}dB:d=${minSilenceSeconds}`,
-    '-f', 'null', '-',
-  ], { encoding: 'utf8', windowsHide: true });
-  if (result.error || result.status !== 0) throw new Error(`FFmpeg silence detection failed: ${result.error?.message ?? result.stderr.trim()}`);
-
-  const intervals = parseSilenceIntervals(result.stderr, media.durationSeconds);
-  const cuts = intervals.flatMap(({ start, end }) => {
-    const sourceStart = round(start + paddingSeconds);
-    const sourceEnd = round(end - paddingSeconds);
-    return sourceEnd > sourceStart ? [{ sourceStart, sourceEnd, reason: `acoustic silence (${round(end - start)}s)` }] : [];
-  });
-  const edl = { schemaVersion: 1, sourceDurationSeconds: media.durationSeconds, cuts };
-  validateEdl(edl, media.durationSeconds);
-  return edl;
-}
-
-export function parseSilenceIntervals(log, durationSeconds) {
-  const intervals = [];
-  const events = /silence_(start|end):\s*(-?(?:\d+(?:\.\d*)?|\.\d+))/g;
-  let silenceStart;
-  for (const match of log.matchAll(events)) {
-    const time = Number(match[2]);
-    if (match[1] === 'start') silenceStart = Math.max(0, time);
-    else if (silenceStart !== undefined && time > silenceStart) {
-      intervals.push({ start: silenceStart, end: Math.min(time, durationSeconds) });
-      silenceStart = undefined;
-    }
-  }
-  if (silenceStart !== undefined && durationSeconds > silenceStart) intervals.push({ start: silenceStart, end: durationSeconds });
-  return intervals;
-}
-
-function round(value) {
-  return Number(value.toFixed(3));
-}
+import { spawnSync } from 'node:child_process';
+import { probeMedia } from '../media/probe.mjs';
+import { validateEdl } from './retime-transcript.mjs';
+
+export function detectAcousticSilence(inputPath, options = {}) {
+  const media = probeMedia(inputPath, { requireVideo: false });
+  if (!media.hasAudio) throw new TypeError('Acoustic silence detection requires an audio stream.');
+  const noiseDb = options.noiseDb ?? -35;
+  const minSilenceSeconds = options.minSilenceSeconds ?? 0.5;
+  const paddingSeconds = options.paddingSeconds ?? 0.12;
+  if (!Number.isFinite(noiseDb) || noiseDb < -90 || noiseDb > 0) throw new TypeError('noiseDb must be between -90 and 0.');
+  if (!Number.isFinite(minSilenceSeconds) || minSilenceSeconds <= 0) throw new TypeError('minSilenceSeconds must be positive.');
+  if (!Number.isFinite(paddingSeconds) || paddingSeconds < 0) throw new TypeError('paddingSeconds must be non-negative.');
+
+  const result = spawnSync('ffmpeg', [
+    '-nostdin', '-hide_banner', '-i', media.path,
+    '-af', `silencedetect=noise=${noiseDb}dB:d=${minSilenceSeconds}`,
+    '-f', 'null', '-',
+  ], { encoding: 'utf8', windowsHide: true });
+  if (result.error || result.status !== 0) throw new Error(`FFmpeg silence detection failed: ${result.error?.message ?? result.stderr.trim()}`);
+
+  const intervals = parseSilenceIntervals(result.stderr, media.durationSeconds);
+  const cuts = intervals.flatMap(({ start, end }) => {
+    const sourceStart = round(start + paddingSeconds);
+    const sourceEnd = round(end - paddingSeconds);
+    return sourceEnd > sourceStart ? [{ sourceStart, sourceEnd, reason: `acoustic silence (${round(end - start)}s)` }] : [];
+  });
+  const edl = { schemaVersion: 1, sourceDurationSeconds: media.durationSeconds, cuts };
+  validateEdl(edl, media.durationSeconds);
+  return edl;
+}
+
+export function parseSilenceIntervals(log, durationSeconds) {
+  const intervals = [];
+  const events = /silence_(start|end):\s*(-?(?:\d+(?:\.\d*)?|\.\d+))/g;
+  let silenceStart;
+  for (const match of log.matchAll(events)) {
+    const time = Number(match[2]);
+    if (match[1] === 'start') silenceStart = Math.max(0, time);
+    else if (silenceStart !== undefined && time > silenceStart) {
+      intervals.push({ start: silenceStart, end: Math.min(time, durationSeconds) });
+      silenceStart = undefined;
+    }
+  }
+  if (silenceStart !== undefined && durationSeconds > silenceStart) intervals.push({ start: silenceStart, end: durationSeconds });
+  return intervals;
+}
+
+function round(value) {
+  return Number(value.toFixed(3));
+}

package/src/edits/find-mistake-candidates.mjs

@@ -1,42 +1,42 @@
-import { validateTranscript } from '../transcript/validate.mjs';
-
-export function findMistakeCandidates(transcript, { maxRepeatGap = 0.5 } = {}) {
-  validateTranscript(transcript);
-  if (transcript.granularity === 'cue') {
-    throw new TypeError('Mistake candidates require a word-level transcript.');
-  }
-  if (!Number.isFinite(maxRepeatGap) || maxRepeatGap < 0) {
-    throw new TypeError('maxRepeatGap must be a non-negative number.');
-  }
-
-  const candidates = [];
-  for (let index = 1; index < transcript.words.length; index++) {
-    const first = transcript.words[index - 1];
-    const second = transcript.words[index];
-    const firstToken = normalize(first.text);
-    const secondToken = normalize(second.text);
-    const gap = second.start - first.end;
-    if (!firstToken || firstToken !== secondToken || gap < 0 || gap > maxRepeatGap) continue;
-
-    candidates.push({
-      id: `repeat-${String(candidates.length + 1).padStart(3, '0')}`,
-      type: 'repeated-word',
-      confidence: 'review',
-      cut: {
-        sourceStart: first.start,
-        sourceEnd: second.start,
-        reason: `possible repeated word: ${first.text}`,
-      },
-      removes: first.text,
-      keeps: second.text,
-      context: transcript.words.slice(Math.max(0, index - 4), Math.min(transcript.words.length, index + 4))
-        .map((word) => word.text)
-        .join(' '),
-    });
-  }
-  return candidates;
-}
-
-function normalize(text) {
-  return text.toLowerCase().normalize('NFKC').replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
-}
+import { validateTranscript } from '../transcript/validate.mjs';
+
+export function findMistakeCandidates(transcript, { maxRepeatGap = 0.5 } = {}) {
+  validateTranscript(transcript);
+  if (transcript.granularity === 'cue') {
+    throw new TypeError('Mistake candidates require a word-level transcript.');
+  }
+  if (!Number.isFinite(maxRepeatGap) || maxRepeatGap < 0) {
+    throw new TypeError('maxRepeatGap must be a non-negative number.');
+  }
+
+  const candidates = [];
+  for (let index = 1; index < transcript.words.length; index++) {
+    const first = transcript.words[index - 1];
+    const second = transcript.words[index];
+    const firstToken = normalize(first.text);
+    const secondToken = normalize(second.text);
+    const gap = second.start - first.end;
+    if (!firstToken || firstToken !== secondToken || gap < 0 || gap > maxRepeatGap) continue;
+
+    candidates.push({
+      id: `repeat-${String(candidates.length + 1).padStart(3, '0')}`,
+      type: 'repeated-word',
+      confidence: 'review',
+      cut: {
+        sourceStart: first.start,
+        sourceEnd: second.start,
+        reason: `possible repeated word: ${first.text}`,
+      },
+      removes: first.text,
+      keeps: second.text,
+      context: transcript.words.slice(Math.max(0, index - 4), Math.min(transcript.words.length, index + 4))
+        .map((word) => word.text)
+        .join(' '),
+    });
+  }
+  return candidates;
+}
+
+function normalize(text) {
+  return text.toLowerCase().normalize('NFKC').replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, '');
+}