eprec 0.0.1 → 1.1.0

package/process-course/edits/remove-ranges.ts

@@ -0,0 +1,287 @@
+#!/usr/bin/env bun
+import path from 'node:path'
+import os from 'node:os'
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises'
+import yargs from 'yargs/yargs'
+import { hideBin } from 'yargs/helpers'
+import { extractChapterSegmentAccurate, concatSegments } from '../ffmpeg'
+import { buildKeepRanges, mergeTimeRanges } from '../utils/time-ranges'
+import { clamp, getMediaDurationSeconds } from '../../utils'
+import type { TimeRange } from '../types'
+
+export type RemoveRangesOptions = {
+	inputPath: string
+	outputPath: string
+	ranges: TimeRange[]
+	duration?: number
+}
+
+export type RemoveRangesResult = {
+	success: boolean
+	error?: string
+	outputPath?: string
+	removedRanges: TimeRange[]
+	keepRanges: TimeRange[]
+}
+
+export function buildRangesRemovedOutputPath(inputPath: string): string {
+	const parsed = path.parse(inputPath)
+	return path.join(parsed.dir, `${parsed.name}.ranges-removed${parsed.ext}`)
+}
+
+export function parseTimeRanges(value: string): TimeRange[] {
+	const trimmed = value.trim()
+	if (!trimmed) {
+		throw new Error('No time ranges provided.')
+	}
+	const normalized = trimmed
+		.replace(/\s*-\s*/g, '-')
+		.replace(/\s*\.\.\s*/g, '..')
+	const tokens = normalized.split(/[\s,;]+/).filter(Boolean)
+	if (tokens.length === 0) {
+		throw new Error('No time ranges provided.')
+	}
+	return tokens.map(parseRangeToken)
+}
+
+export function normalizeRemovalRanges(options: {
+	ranges: TimeRange[]
+	duration: number
+}): { ranges: TimeRange[]; warnings: string[] } {
+	const normalized: TimeRange[] = []
+	const warnings: string[] = []
+	for (const range of options.ranges) {
+		const clampedStart = clamp(range.start, 0, options.duration)
+		const clampedEnd = clamp(range.end, 0, options.duration)
+		if (clampedStart !== range.start || clampedEnd !== range.end) {
+			warnings.push(
+				`Clamped range ${range.start.toFixed(3)}-${range.end.toFixed(3)} to ${clampedStart.toFixed(3)}-${clampedEnd.toFixed(3)}.`,
+			)
+		}
+		if (clampedEnd <= clampedStart + 0.005) {
+			warnings.push(
+				`Skipping empty range ${clampedStart.toFixed(3)}-${clampedEnd.toFixed(3)}.`,
+			)
+			continue
+		}
+		normalized.push({ start: clampedStart, end: clampedEnd })
+	}
+	return { ranges: mergeTimeRanges(normalized), warnings }
+}
+
+export async function removeRangesFromMedia(
+	options: RemoveRangesOptions,
+): Promise<RemoveRangesResult> {
+	const removedRanges: TimeRange[] = []
+	const keepRanges: TimeRange[] = []
+	try {
+		const duration =
+			typeof options.duration === 'number'
+				? options.duration
+				: await getMediaDurationSeconds(options.inputPath)
+		const normalized = normalizeRemovalRanges({
+			ranges: options.ranges,
+			duration,
+		})
+		normalized.warnings.forEach((warning) => console.warn(`[warn] ${warning}`))
+		removedRanges.push(...normalized.ranges)
+		if (removedRanges.length === 0) {
+			return {
+				success: false,
+				error: 'No valid ranges to remove after normalization.',
+				removedRanges,
+				keepRanges,
+			}
+		}
+		keepRanges.push(...buildKeepRanges(0, duration, removedRanges))
+		if (keepRanges.length === 0) {
+			return {
+				success: false,
+				error: 'Requested removals delete the entire file.',
+				removedRanges,
+				keepRanges,
+			}
+		}
+
+		const resolvedInput = path.resolve(options.inputPath)
+		const resolvedOutput = path.resolve(options.outputPath)
+		if (resolvedInput === resolvedOutput) {
+			return {
+				success: false,
+				error: 'Output path must be different from input path.',
+				removedRanges,
+				keepRanges,
+			}
+		}
+
+		await mkdir(path.dirname(options.outputPath), { recursive: true })
+
+		const isFullRange =
+			keepRanges.length === 1 &&
+			keepRanges[0] &&
+			keepRanges[0].start <= 0.001 &&
+			keepRanges[0].end >= duration - 0.001
+		if (isFullRange) {
+			await copyFile(options.inputPath, options.outputPath)
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedRanges,
+				keepRanges,
+			}
+		}
+
+		if (keepRanges.length === 1 && keepRanges[0]) {
+			await extractChapterSegmentAccurate({
+				inputPath: options.inputPath,
+				outputPath: options.outputPath,
+				start: keepRanges[0].start,
+				end: keepRanges[0].end,
+			})
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedRanges,
+				keepRanges,
+			}
+		}
+
+		const tempDir = await mkdtemp(path.join(os.tmpdir(), 'remove-ranges-'))
+		try {
+			const segmentPaths: string[] = []
+			for (const [index, range] of keepRanges.entries()) {
+				const segmentPath = path.join(tempDir, `segment-${index + 1}.mp4`)
+				await extractChapterSegmentAccurate({
+					inputPath: options.inputPath,
+					outputPath: segmentPath,
+					start: range.start,
+					end: range.end,
+				})
+				segmentPaths.push(segmentPath)
+			}
+			if (segmentPaths.length < 2) {
+				throw new Error('Expected at least two segments to concat.')
+			}
+			await concatSegments({
+				segmentPaths,
+				outputPath: options.outputPath,
+			})
+		} finally {
+			await rm(tempDir, { recursive: true, force: true })
+		}
+
+		return {
+			success: true,
+			outputPath: options.outputPath,
+			removedRanges,
+			keepRanges,
+		}
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+			removedRanges,
+			keepRanges,
+		}
+	}
+}
+
+async function main() {
+	const argv = yargs(hideBin(process.argv))
+		.scriptName('remove-ranges')
+		.option('input', {
+			type: 'string',
+			demandOption: true,
+			describe: 'Input media file',
+		})
+		.option('ranges', {
+			type: 'string',
+			demandOption: true,
+			describe: 'Comma or space-separated ranges (e.g. 12-15, 1:02-1:05)',
+		})
+		.option('output', {
+			type: 'string',
+			describe: 'Output path (defaults to .ranges-removed)',
+		})
+		.help()
+		.parseSync()
+
+	const inputPath = path.resolve(String(argv.input))
+	const outputPath =
+		typeof argv.output === 'string' && argv.output.trim().length > 0
+			? path.resolve(argv.output)
+			: buildRangesRemovedOutputPath(inputPath)
+	const ranges = parseTimeRanges(String(argv.ranges))
+	const result = await removeRangesFromMedia({
+		inputPath,
+		outputPath,
+		ranges,
+	})
+	if (!result.success) {
+		console.error(result.error ?? 'Range removal failed.')
+		process.exit(1)
+	}
+	console.log(`Updated file written to ${outputPath}`)
+}
+
+function parseRangeToken(token: string): TimeRange {
+	const separator = token.includes('..') ? '..' : '-'
+	const parts = token.split(separator)
+	if (parts.length !== 2) {
+		throw new Error(`Invalid range "${token}". Use start-end format.`)
+	}
+	const startText = parts[0]?.trim() ?? ''
+	const endText = parts[1]?.trim() ?? ''
+	if (!startText || !endText) {
+		throw new Error(`Invalid range "${token}". Start and end required.`)
+	}
+	const start = parseTimestamp(startText)
+	const end = parseTimestamp(endText)
+	if (end <= start) {
+		throw new Error(`Invalid range "${token}". End must be after start.`)
+	}
+	return { start, end }
+}
+
+function parseTimestamp(value: string): number {
+	const trimmed = value.trim()
+	if (!trimmed) {
+		throw new Error('Invalid time value.')
+	}
+	if (!trimmed.includes(':')) {
+		const seconds = Number.parseFloat(trimmed)
+		if (!Number.isFinite(seconds) || seconds < 0) {
+			throw new Error(`Invalid time value "${value}".`)
+		}
+		return seconds
+	}
+	const parts = trimmed.split(':')
+	if (parts.length < 2 || parts.length > 3) {
+		throw new Error(`Invalid time value "${value}".`)
+	}
+	let totalSeconds = 0
+	for (const [index, part] of parts.entries()) {
+		const segment = part.trim()
+		if (!segment) {
+			throw new Error(`Invalid time value "${value}".`)
+		}
+		if (segment.includes('.') && index < parts.length - 1) {
+			throw new Error(`Invalid time value "${value}".`)
+		}
+		const numberValue = Number.parseFloat(segment)
+		if (!Number.isFinite(numberValue) || numberValue < 0) {
+			throw new Error(`Invalid time value "${value}".`)
+		}
+		totalSeconds = totalSeconds * 60 + numberValue
+	}
+	return totalSeconds
+}
+
+if (import.meta.main) {
+	main().catch((error) => {
+		console.error(
+			`[error] ${error instanceof Error ? error.message : String(error)}`,
+		)
+		process.exit(1)
+	})
+}

package/process-course/edits/timestamp-refinement.test.ts

@@ -0,0 +1,25 @@
+import { test, expect } from 'bun:test'
+import { wordsToTimeRanges } from './timestamp-refinement'
+import type { TranscriptWordWithIndex } from './types'
+
+function createWord(
+	word: string,
+	start: number,
+	end: number,
+	index = 0,
+): TranscriptWordWithIndex {
+	return { word, start, end, index }
+}
+
+test('wordsToTimeRanges merges overlapping ranges', () => {
+	const words = [
+		createWord('hello', 0, 0.5, 0),
+		createWord('world', 0.45, 1, 1),
+	]
+	const ranges = wordsToTimeRanges(words)
+	expect(ranges).toEqual([{ start: 0, end: 1 }])
+})
+
+test('wordsToTimeRanges returns empty for no words', () => {
+	expect(wordsToTimeRanges([])).toEqual([])
+})

package/process-course/edits/timestamp-refinement.ts

@@ -0,0 +1,172 @@
+import { readAudioSamples } from '../ffmpeg'
+import { CONFIG, EDIT_CONFIG } from '../config'
+import { clamp } from '../../utils'
+import { mergeTimeRanges } from '../utils/time-ranges'
+import { findLowestAmplitudeBoundaryProgressive } from '../utils/audio-analysis'
+import type { TimeRange } from '../types'
+import type { TranscriptWordWithIndex } from './types'
+
+export type RefinedRange = {
+	original: TimeRange
+	refined: TimeRange
+}
+
+export function wordsToTimeRanges(
+	words: TranscriptWordWithIndex[],
+): TimeRange[] {
+	const ranges = words.map((word) => ({ start: word.start, end: word.end }))
+	return mergeTimeRanges(ranges)
+}
+
+export async function refineRemovalRange(options: {
+	inputPath: string
+	duration: number
+	range: TimeRange
+	paddingMs?: number
+}): Promise<RefinedRange> {
+	const paddingSeconds =
+		(options.paddingMs ?? EDIT_CONFIG.speechBoundaryPaddingMs) / 1000
+	const silenceStart = await findSilenceBoundary({
+		inputPath: options.inputPath,
+		duration: options.duration,
+		targetTime: options.range.start,
+		direction: 'before',
+	})
+	if (silenceStart === null) {
+		throw new Error(
+			buildSilenceError({
+				direction: 'before',
+				targetTime: options.range.start,
+				maxWindowSeconds: getMaxSilenceSearchSeconds({
+					duration: options.duration,
+					targetTime: options.range.start,
+					direction: 'before',
+				}),
+			}),
+		)
+	}
+	const silenceEnd = await findSilenceBoundary({
+		inputPath: options.inputPath,
+		duration: options.duration,
+		targetTime: options.range.end,
+		direction: 'after',
+	})
+	if (silenceEnd === null) {
+		throw new Error(
+			buildSilenceError({
+				direction: 'after',
+				targetTime: options.range.end,
+				maxWindowSeconds: getMaxSilenceSearchSeconds({
+					duration: options.duration,
+					targetTime: options.range.end,
+					direction: 'after',
+				}),
+			}),
+		)
+	}
+
+	const paddedStart = clamp(silenceStart + paddingSeconds, 0, options.duration)
+	const paddedEnd = clamp(silenceEnd - paddingSeconds, 0, options.duration)
+	const refinedStart =
+		paddedStart <= options.range.start ? paddedStart : silenceStart
+	const refinedEnd = paddedEnd >= options.range.end ? paddedEnd : silenceEnd
+
+	if (refinedEnd <= refinedStart + 0.005) {
+		throw new Error(
+			`Unable to create a non-empty cut around ${options.range.start.toFixed(3)}s-${options.range.end.toFixed(3)}s.`,
+		)
+	}
+
+	return {
+		original: options.range,
+		refined: { start: refinedStart, end: refinedEnd },
+	}
+}
+
+export async function refineAllRemovalRanges(options: {
+	inputPath: string
+	duration: number
+	ranges: TimeRange[]
+	paddingMs?: number
+}): Promise<RefinedRange[]> {
+	const refined: RefinedRange[] = []
+	for (const range of options.ranges) {
+		refined.push(
+			await refineRemovalRange({
+				inputPath: options.inputPath,
+				duration: options.duration,
+				range,
+				paddingMs: options.paddingMs,
+			}),
+		)
+	}
+	return refined
+}
+
+type SpeechBoundaryDirection = 'before' | 'after'
+
+async function findSilenceBoundary(options: {
+	inputPath: string
+	duration: number
+	targetTime: number
+	direction: SpeechBoundaryDirection
+}): Promise<number | null> {
+	const maxWindowSeconds = getMaxSilenceSearchSeconds(options)
+	if (maxWindowSeconds <= 0.01) {
+		return null
+	}
+	const windowStart =
+		options.direction === 'before'
+			? Math.max(0, options.targetTime - maxWindowSeconds)
+			: options.targetTime
+	const windowEnd =
+		options.direction === 'before'
+			? options.targetTime
+			: Math.min(options.duration, options.targetTime + maxWindowSeconds)
+	const windowDuration = windowEnd - windowStart
+	if (windowDuration <= 0.01) {
+		return null
+	}
+	const samples = await readAudioSamples({
+		inputPath: options.inputPath,
+		start: windowStart,
+		duration: windowDuration,
+		sampleRate: CONFIG.vadSampleRate,
+	})
+	if (samples.length === 0) {
+		return null
+	}
+
+	const boundary = findLowestAmplitudeBoundaryProgressive({
+		samples,
+		sampleRate: CONFIG.vadSampleRate,
+		direction: options.direction,
+		rmsWindowMs: CONFIG.commandSilenceRmsWindowMs,
+		rmsThreshold: CONFIG.commandSilenceRmsThreshold,
+		startWindowSeconds: EDIT_CONFIG.silenceSearchStartSeconds,
+		stepSeconds: EDIT_CONFIG.silenceSearchStepSeconds,
+		maxWindowSeconds: windowDuration,
+	})
+	return boundary === null ? null : windowStart + boundary
+}
+
+function buildSilenceError(options: {
+	direction: SpeechBoundaryDirection
+	targetTime: number
+	maxWindowSeconds: number
+}): string {
+	const directionLabel = options.direction === 'before' ? 'before' : 'after'
+	return `No low-amplitude boundary found ${directionLabel} ${options.targetTime.toFixed(3)}s within ${options.maxWindowSeconds.toFixed(2)}s.`
+}
+
+function getMaxSilenceSearchSeconds(options: {
+	duration: number
+	targetTime: number
+	direction: SpeechBoundaryDirection
+}): number {
+	const availableSeconds =
+		options.direction === 'before'
+			? options.targetTime
+			: options.duration - options.targetTime
+	return Math.min(EDIT_CONFIG.silenceSearchMaxSeconds, availableSeconds)
+}

package/process-course/edits/transcript-diff.test.ts

@@ -0,0 +1,105 @@
+import { test, expect } from 'bun:test'
+import { diffTranscripts, validateEditedTranscript } from './transcript-diff'
+import type { TranscriptWordWithIndex } from './types'
+
+function createWord(
+	word: string,
+	index: number,
+	start = index * 0.5,
+	end = start + 0.4,
+): TranscriptWordWithIndex {
+	return { word, index, start, end }
+}
+
+function createWords(...words: string[]): TranscriptWordWithIndex[] {
+	return words.map((word, index) => createWord(word, index))
+}
+
+test('diffTranscripts removes words from the middle', () => {
+	const originalWords = createWords('hello', 'this', 'is', 'a', 'test')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'hello this a test',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords.map((word) => word.word)).toEqual(['is'])
+})
+
+test('diffTranscripts removes words at the start', () => {
+	const originalWords = createWords('hello', 'this', 'is', 'a', 'test')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'this is a test',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords.map((word) => word.word)).toEqual(['hello'])
+})
+
+test('diffTranscripts removes words at the end', () => {
+	const originalWords = createWords('hello', 'this', 'is', 'a', 'test')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'hello this is a',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords.map((word) => word.word)).toEqual(['test'])
+})
+
+test('diffTranscripts removes multiple disjoint words', () => {
+	const originalWords = createWords('hello', 'this', 'is', 'a', 'test', 'today')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'hello is test today',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords.map((word) => word.word)).toEqual(['this', 'a'])
+})
+
+test('validateEditedTranscript errors on added words', () => {
+	const originalWords = createWords('hello', 'world')
+	const result = validateEditedTranscript({
+		originalWords,
+		editedText: 'hello brave world',
+	})
+	expect(result.valid).toBe(false)
+	expect(result.error).toContain('Transcript mismatch')
+})
+
+test('validateEditedTranscript errors on modified words', () => {
+	const originalWords = createWords('processing', 'pipeline')
+	const result = validateEditedTranscript({
+		originalWords,
+		editedText: 'prosessing pipeline',
+	})
+	expect(result.valid).toBe(false)
+	expect(result.error).toContain('Transcript mismatch')
+})
+
+test('validateEditedTranscript errors on empty edited text', () => {
+	const originalWords = createWords('hello', 'world')
+	const result = validateEditedTranscript({
+		originalWords,
+		editedText: '   ',
+	})
+	expect(result.valid).toBe(false)
+})
+
+test('diffTranscripts ignores whitespace differences', () => {
+	const originalWords = createWords('hello', 'world')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'hello\n  world\t',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords).toHaveLength(0)
+})
+
+test('diffTranscripts is case insensitive', () => {
+	const originalWords = createWords('hello', 'world')
+	const result = diffTranscripts({
+		originalWords,
+		editedText: 'Hello WORLD',
+	})
+	expect(result.success).toBe(true)
+	expect(result.removedWords).toHaveLength(0)
+})