eprec 0.0.1 → 1.1.0

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

@@ -0,0 +1,214 @@
+import { normalizeWords } from '../utils/transcript'
+import type { TranscriptMismatchError, TranscriptWordWithIndex } from './types'
+
+export type DiffResult = {
+	success: boolean
+	removedWords: TranscriptWordWithIndex[]
+	error?: string
+	mismatch?: TranscriptMismatchError
+}
+
+export type ValidationResult = {
+	valid: boolean
+	error?: string
+	mismatch?: TranscriptMismatchError
+	details?: {
+		unexpectedWord: string
+		position: number
+	}
+}
+
+export function diffTranscripts(options: {
+	originalWords: TranscriptWordWithIndex[]
+	editedText: string
+}): DiffResult {
+	const validation = validateEditedTranscript(options)
+	if (!validation.valid) {
+		return {
+			success: false,
+			removedWords: [],
+			error: validation.error,
+			mismatch: validation.mismatch,
+		}
+	}
+
+	const editedWords = tokenizeEditedText(options.editedText)
+	const removedWords: TranscriptWordWithIndex[] = []
+	let originalIndex = 0
+	let editedIndex = 0
+
+	while (originalIndex < options.originalWords.length) {
+		const originalWord = options.originalWords[originalIndex]
+		if (!originalWord) {
+			originalIndex += 1
+			continue
+		}
+		const editedWord = editedWords[editedIndex]
+		if (editedWord && originalWord.word === editedWord) {
+			originalIndex += 1
+			editedIndex += 1
+			continue
+		}
+		removedWords.push(originalWord)
+		originalIndex += 1
+	}
+
+	if (editedIndex < editedWords.length) {
+		const mismatch = buildMismatchError({
+			type: 'word_added',
+			position: editedIndex,
+			editedWord: editedWords[editedIndex],
+			originalWord: null,
+		})
+		return {
+			success: false,
+			removedWords: [],
+			error: mismatch.message,
+			mismatch,
+		}
+	}
+
+	return { success: true, removedWords }
+}
+
+export function validateEditedTranscript(options: {
+	originalWords: TranscriptWordWithIndex[]
+	editedText: string
+}): ValidationResult {
+	const editedWords = tokenizeEditedText(options.editedText)
+	if (options.originalWords.length === 0) {
+		return {
+			valid: false,
+			error: 'Original transcript has no words. Regenerate the transcript.',
+		}
+	}
+	if (editedWords.length === 0) {
+		return {
+			valid: false,
+			error:
+				'Edited transcript is empty. Regenerate the transcript if this was unintentional.',
+		}
+	}
+
+	let originalIndex = 0
+	let editedIndex = 0
+
+	while (
+		originalIndex < options.originalWords.length &&
+		editedIndex < editedWords.length
+	) {
+		const originalWord = options.originalWords[originalIndex]
+		const editedWord = editedWords[editedIndex]
+		if (!originalWord || !editedWord) {
+			break
+		}
+		if (originalWord.word === editedWord) {
+			originalIndex += 1
+			editedIndex += 1
+			continue
+		}
+
+		const nextMatchIndex = findNextMatchIndex(
+			options.originalWords,
+			editedWord,
+			originalIndex + 1,
+		)
+		if (nextMatchIndex === -1) {
+			const mismatchType = resolveMismatchType(
+				options.originalWords,
+				editedWord,
+				originalIndex,
+			)
+			const mismatch = buildMismatchError({
+				type: mismatchType,
+				position: editedIndex,
+				editedWord,
+				originalWord: originalWord.word,
+			})
+			return {
+				valid: false,
+				error: mismatch.message,
+				mismatch,
+				details: {
+					unexpectedWord: editedWord,
+					position: editedIndex,
+				},
+			}
+		}
+		originalIndex += 1
+	}
+
+	if (editedIndex < editedWords.length) {
+		const mismatch = buildMismatchError({
+			type: 'word_added',
+			position: editedIndex,
+			editedWord: editedWords[editedIndex],
+			originalWord: null,
+		})
+		return {
+			valid: false,
+			error: mismatch.message,
+			mismatch,
+			details: {
+				unexpectedWord: editedWords[editedIndex] ?? '',
+				position: editedIndex,
+			},
+		}
+	}
+
+	return { valid: true }
+}
+
+function tokenizeEditedText(text: string): string[] {
+	return normalizeWords(text)
+}
+
+function findNextMatchIndex(
+	words: TranscriptWordWithIndex[],
+	target: string,
+	startIndex: number,
+): number {
+	for (let index = startIndex; index < words.length; index += 1) {
+		if (words[index]?.word === target) {
+			return index
+		}
+	}
+	return -1
+}
+
+function resolveMismatchType(
+	words: TranscriptWordWithIndex[],
+	editedWord: string,
+	originalIndex: number,
+): TranscriptMismatchError['type'] {
+	const anyIndex = words.findIndex((word) => word.word === editedWord)
+	if (anyIndex >= 0 && anyIndex < originalIndex) {
+		return 'word_out_of_order'
+	}
+	return anyIndex >= 0 ? 'word_out_of_order' : 'word_modified'
+}
+
+function buildMismatchError(options: {
+	type: TranscriptMismatchError['type']
+	position: number
+	editedWord: string | undefined
+	originalWord: string | null
+}): TranscriptMismatchError {
+	const expected =
+		options.originalWord === null ? 'end of transcript' : options.originalWord
+	const found = options.editedWord ?? 'end of transcript'
+	const typeLabel =
+		options.type === 'word_added'
+			? 'Unexpected word'
+			: options.type === 'word_out_of_order'
+				? 'Word out of order'
+				: 'Word modified'
+	const message = `Error: Transcript mismatch at word position ${options.position}.\nExpected: "${expected}"\nFound: "${found}"\n\nThe edited transcript contains changes that don't match the original.\nPlease regenerate the transcript and try again.`
+	return {
+		type: options.type,
+		position: options.position,
+		originalWord: options.originalWord ?? undefined,
+		editedWord: options.editedWord ?? undefined,
+		message: `${typeLabel}. ${message}`,
+	}
+}

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

@@ -0,0 +1,50 @@
+import { test, expect } from 'bun:test'
+import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import {
+	buildTranscriptWordsWithIndices,
+	generateTranscriptJson,
+	generateTranscriptText,
+} from './transcript-output'
+
+function createSegment(
+	start: number,
+	end: number,
+	text: string,
+): TranscriptSegment {
+	return { start, end, text }
+}
+
+test('buildTranscriptWordsWithIndices assigns indices in order', () => {
+	const segments = [createSegment(0, 2, 'Hello world')]
+	const words = buildTranscriptWordsWithIndices(segments)
+	expect(words).toHaveLength(2)
+	expect(words[0]).toMatchObject({ word: 'hello', index: 0, start: 0, end: 1 })
+	expect(words[1]).toMatchObject({ word: 'world', index: 1, start: 1, end: 2 })
+})
+
+test('generateTranscriptText returns readable prose', () => {
+	const segments = [createSegment(0, 2, 'Hello world')]
+	const words = buildTranscriptWordsWithIndices(segments)
+	expect(generateTranscriptText(words)).toBe('hello world\n')
+})
+
+test('generateTranscriptJson outputs valid metadata', () => {
+	const segments = [createSegment(0, 2, 'Hello world')]
+	const words = buildTranscriptWordsWithIndices(segments)
+	const json = generateTranscriptJson({
+		sourceVideo: 'chapter-01.mp4',
+		sourceDuration: 2,
+		words,
+	})
+	const parsed = JSON.parse(json) as {
+		version: number
+		source_video: string
+		source_duration: number
+		words: Array<{ word: string; start: number; end: number; index: number }>
+	}
+	expect(parsed.version).toBe(1)
+	expect(parsed.source_video).toBe('chapter-01.mp4')
+	expect(parsed.source_duration).toBe(2)
+	expect(parsed.words).toHaveLength(2)
+	expect(parsed.words[0]).toHaveProperty('word', 'hello')
+})

package/process-course/edits/transcript-output.ts

@@ -0,0 +1,36 @@
+import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import { buildTranscriptWords } from '../jarvis-commands/parser'
+import type { TranscriptJson, TranscriptWordWithIndex } from './types'
+
+export function buildTranscriptWordsWithIndices(
+	segments: TranscriptSegment[],
+): TranscriptWordWithIndex[] {
+	const words = buildTranscriptWords(segments)
+	return words.map((word, index) => ({
+		...word,
+		index,
+	}))
+}
+
+export function generateTranscriptText(
+	words: TranscriptWordWithIndex[],
+): string {
+	if (words.length === 0) {
+		return ''
+	}
+	return `${words.map((word) => word.word).join(' ')}\n`
+}
+
+export function generateTranscriptJson(options: {
+	sourceVideo: string
+	sourceDuration: number
+	words: TranscriptWordWithIndex[]
+}): string {
+	const payload: TranscriptJson = {
+		version: 1,
+		source_video: options.sourceVideo,
+		source_duration: options.sourceDuration,
+		words: options.words,
+	}
+	return `${JSON.stringify(payload, null, 2)}\n`
+}

package/process-course/edits/types.ts

@@ -0,0 +1,26 @@
+export type TranscriptWordWithIndex = {
+	word: string
+	start: number
+	end: number
+	index: number
+}
+
+export type TranscriptJson = {
+	version: 1
+	source_video: string
+	source_duration: number
+	words: TranscriptWordWithIndex[]
+}
+
+export type TranscriptMismatchType =
+	| 'word_added'
+	| 'word_modified'
+	| 'word_out_of_order'
+
+export type TranscriptMismatchError = {
+	type: TranscriptMismatchType
+	position: number
+	originalWord?: string
+	editedWord?: string
+	message: string
+}

package/process-course/edits/video-editor.ts

@@ -0,0 +1,246 @@
+import path from 'node:path'
+import os from 'node:os'
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises'
+import { extractChapterSegmentAccurate, concatSegments } from '../ffmpeg'
+import { buildKeepRanges, mergeTimeRanges } from '../utils/time-ranges'
+import { EDIT_CONFIG } from '../config'
+import { diffTranscripts, validateEditedTranscript } from './transcript-diff'
+import {
+	refineAllRemovalRanges,
+	wordsToTimeRanges,
+} from './timestamp-refinement'
+import type { TimeRange } from '../types'
+import type { TranscriptJson, TranscriptWordWithIndex } from './types'
+
+export interface EditVideoOptions {
+	inputPath: string
+	transcriptJsonPath: string
+	editedTextPath: string
+	outputPath: string
+	paddingMs?: number
+}
+
+export interface EditVideoResult {
+	success: boolean
+	error?: string
+	outputPath?: string
+	removedWords: TranscriptWordWithIndex[]
+	removedRanges: TimeRange[]
+}
+
+export function buildEditedOutputPath(inputPath: string): string {
+	const parsed = path.parse(inputPath)
+	return path.join(parsed.dir, `${parsed.name}.edited${parsed.ext}`)
+}
+
+export async function editVideo(
+	options: EditVideoOptions,
+): Promise<EditVideoResult> {
+	try {
+		const transcript = await readTranscriptJson(options.transcriptJsonPath)
+		const editedText = await Bun.file(options.editedTextPath).text()
+		const validation = validateEditedTranscript({
+			originalWords: transcript.words,
+			editedText,
+		})
+		if (!validation.valid) {
+			return {
+				success: false,
+				error: validation.error,
+				removedWords: [],
+				removedRanges: [],
+			}
+		}
+		const diffResult = diffTranscripts({
+			originalWords: transcript.words,
+			editedText,
+		})
+		if (!diffResult.success) {
+			return {
+				success: false,
+				error: diffResult.error,
+				removedWords: [],
+				removedRanges: [],
+			}
+		}
+
+		const removedWords = diffResult.removedWords
+		if (removedWords.length === 0) {
+			await ensureOutputCopy(options.inputPath, options.outputPath)
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedWords,
+				removedRanges: [],
+			}
+		}
+
+		const removalRanges = wordsToTimeRanges(removedWords)
+		if (removalRanges.length === 0) {
+			await ensureOutputCopy(options.inputPath, options.outputPath)
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedWords,
+				removedRanges: [],
+			}
+		}
+
+		const refinedRanges = await refineAllRemovalRanges({
+			inputPath: options.inputPath,
+			duration: transcript.source_duration,
+			ranges: removalRanges,
+			paddingMs: options.paddingMs ?? EDIT_CONFIG.speechBoundaryPaddingMs,
+		})
+		const mergedRanges = mergeTimeRanges(
+			refinedRanges.map((range) => range.refined),
+		)
+		const keepRanges = buildKeepRanges(
+			0,
+			transcript.source_duration,
+			mergedRanges,
+		)
+
+		if (keepRanges.length === 0) {
+			return {
+				success: false,
+				error:
+					'Edits remove the entire video. Regenerate the transcript and retry.',
+				removedWords,
+				removedRanges: mergedRanges,
+			}
+		}
+
+		await mkdir(path.dirname(options.outputPath), { recursive: true })
+
+		const isFullRange =
+			keepRanges.length === 1 &&
+			keepRanges[0] &&
+			keepRanges[0].start <= 0.001 &&
+			keepRanges[0].end >= transcript.source_duration - 0.001
+		if (isFullRange) {
+			await ensureOutputCopy(options.inputPath, options.outputPath)
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedWords,
+				removedRanges: mergedRanges,
+			}
+		}
+
+		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,
+				removedWords,
+				removedRanges: mergedRanges,
+			}
+		}
+
+		const tempDir = await mkdtemp(path.join(os.tmpdir(), 'video-edit-'))
+		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)
+			}
+			await concatSegments({
+				segmentPaths,
+				outputPath: options.outputPath,
+			})
+			return {
+				success: true,
+				outputPath: options.outputPath,
+				removedWords,
+				removedRanges: mergedRanges,
+			}
+		} finally {
+			await rm(tempDir, { recursive: true, force: true })
+		}
+	} catch (error) {
+		return {
+			success: false,
+			error: error instanceof Error ? error.message : String(error),
+			removedWords: [],
+			removedRanges: [],
+		}
+	}
+}
+
+async function ensureOutputCopy(inputPath: string, outputPath: string) {
+	const resolvedInput = path.resolve(inputPath)
+	const resolvedOutput = path.resolve(outputPath)
+	if (resolvedInput === resolvedOutput) {
+		return
+	}
+	await mkdir(path.dirname(outputPath), { recursive: true })
+	await copyFile(inputPath, outputPath)
+}
+
+async function readTranscriptJson(
+	transcriptJsonPath: string,
+): Promise<TranscriptJson> {
+	const raw = await Bun.file(transcriptJsonPath).text()
+	let parsed: unknown
+	try {
+		parsed = JSON.parse(raw)
+	} catch (error) {
+		throw new Error(
+			`Transcript JSON parse error: ${error instanceof Error ? error.message : String(error)}`,
+		)
+	}
+	if (!parsed || typeof parsed !== 'object') {
+		throw new Error('Transcript JSON is not an object.')
+	}
+	const payload = parsed as TranscriptJson
+	if (payload.version !== 1) {
+		throw new Error('Unsupported transcript JSON version.')
+	}
+	if (!payload.source_video || typeof payload.source_video !== 'string') {
+		throw new Error('Transcript JSON missing source_video.')
+	}
+	if (
+		typeof payload.source_duration !== 'number' ||
+		!Number.isFinite(payload.source_duration) ||
+		payload.source_duration <= 0
+	) {
+		throw new Error('Transcript JSON has invalid source_duration.')
+	}
+	if (!Array.isArray(payload.words)) {
+		throw new Error('Transcript JSON missing words array.')
+	}
+	const words: TranscriptWordWithIndex[] = payload.words.map((word, index) => {
+		if (!word || typeof word !== 'object') {
+			throw new Error(`Transcript JSON word ${index} is invalid.`)
+		}
+		const entry = word as TranscriptWordWithIndex
+		if (typeof entry.word !== 'string') {
+			throw new Error(`Transcript JSON word ${index} missing word.`)
+		}
+		if (typeof entry.start !== 'number' || typeof entry.end !== 'number') {
+			throw new Error(`Transcript JSON word ${index} missing timing.`)
+		}
+		if (typeof entry.index !== 'number') {
+			throw new Error(`Transcript JSON word ${index} missing index.`)
+		}
+		return entry
+	})
+	return {
+		version: 1,
+		source_video: payload.source_video,
+		source_duration: payload.source_duration,
+		words,
+	}
+}

package/process-course/errors.test.ts

@@ -0,0 +1,63 @@
+import { test, expect } from 'bun:test'
+import {
+	BadTakeError,
+	ChapterProcessingError,
+	ChapterTooShortError,
+	CommandParseError,
+	SpliceError,
+	TranscriptTooShortError,
+	TrimWindowError,
+} from './errors'
+
+test('ChapterProcessingError exposes metadata', () => {
+	const error = new ChapterProcessingError('Failed', 2, 'Intro')
+	expect(error.name).toBe('ChapterProcessingError')
+	expect(error.message).toBe('Failed')
+	expect(error.chapterIndex).toBe(2)
+	expect(error.chapterTitle).toBe('Intro')
+})
+
+test('ChapterTooShortError formats message with duration', () => {
+	const error = new ChapterTooShortError(1, 'Basics', 4.1234, 5)
+	expect(error.name).toBe('ChapterTooShortError')
+	expect(error.message).toBe('Chapter "Basics" is too short (4.12s < 5s)')
+	expect(error.duration).toBe(4.1234)
+	expect(error.minDuration).toBe(5)
+})
+
+test('CommandParseError stores transcript context', () => {
+	const error = new CommandParseError('Bad command', 'Jarvis bad take')
+	expect(error.name).toBe('CommandParseError')
+	expect(error.message).toBe('Bad command')
+	expect(error.transcript).toBe('Jarvis bad take')
+})
+
+test('TranscriptTooShortError formats message with word count', () => {
+	const error = new TranscriptTooShortError(0, 'Intro', 5, 10)
+	expect(error.name).toBe('TranscriptTooShortError')
+	expect(error.message).toBe(
+		'Chapter "Intro" transcript too short (5 words < 10)',
+	)
+	expect(error.wordCount).toBe(5)
+	expect(error.minWordCount).toBe(10)
+})
+
+test('BadTakeError sets name and message', () => {
+	const error = new BadTakeError(3, 'Outro')
+	expect(error.name).toBe('BadTakeError')
+	expect(error.message).toBe('Chapter "Outro" marked as bad take')
+})
+
+test('SpliceError uses custom name', () => {
+	const error = new SpliceError('Failed to splice')
+	expect(error.name).toBe('SpliceError')
+	expect(error.message).toBe('Failed to splice')
+})
+
+test('TrimWindowError formats message with precision', () => {
+	const error = new TrimWindowError(1.23456, 1.23999)
+	expect(error.name).toBe('TrimWindowError')
+	expect(error.message).toBe('Trim window too small (1.235s -> 1.240s)')
+	expect(error.start).toBe(1.23456)
+	expect(error.end).toBe(1.23999)
+})