eprec 0.0.1 → 1.1.0

package/process-course/jarvis-commands/windows.ts

@@ -0,0 +1,254 @@
+import { clamp } from '../../utils'
+import { detectSpeechSegmentsWithVad } from '../../speech-detection'
+import { readAudioSamples } from '../ffmpeg'
+import { CONFIG } from '../config'
+import { logInfo } from '../logging'
+import { formatSeconds } from '../../utils'
+import { mergeTimeRanges } from '../utils/time-ranges'
+import {
+	buildSilenceGapsFromSpeech,
+	findSilenceBoundaryFromGaps,
+	findSilenceBoundaryWithRms,
+	computeRms,
+	computeMinWindowRms,
+} from '../utils/audio-analysis'
+import type { TimeRange, SilenceBoundaryDirection } from '../types'
+import type { TranscriptCommand, CommandWindowOptions } from './types'
+
+/**
+ * Build time windows to remove based on detected commands.
+ */
+export function buildCommandWindows(
+	commands: TranscriptCommand[],
+	options: CommandWindowOptions,
+): TimeRange[] {
+	if (commands.length === 0) {
+		return []
+	}
+	const windows = commands
+		.map((command) => {
+			const start = clamp(
+				options.offset + command.window.start - options.paddingSeconds,
+				options.min,
+				options.max,
+			)
+			const end = clamp(
+				options.offset + command.window.end + options.paddingSeconds,
+				options.min,
+				options.max,
+			)
+			if (end <= start) {
+				return null
+			}
+			return { start, end }
+		})
+		.filter((window): window is TimeRange => Boolean(window))
+	return mergeTimeRanges(windows)
+}
+
+/**
+ * Refine command windows to align with silence boundaries.
+ */
+export async function refineCommandWindows(options: {
+	commandWindows: TimeRange[]
+	inputPath: string
+	duration: number
+}): Promise<TimeRange[]> {
+	if (options.commandWindows.length === 0) {
+		return []
+	}
+	const refined: TimeRange[] = []
+	for (const window of options.commandWindows) {
+		const shouldKeepStart = await isSilenceAtTarget({
+			inputPath: options.inputPath,
+			duration: options.duration,
+			targetTime: window.start,
+			label: 'start',
+		})
+		let refinedStart = shouldKeepStart
+			? window.start
+			: await findSilenceBoundary({
+					inputPath: options.inputPath,
+					duration: options.duration,
+					targetTime: window.start,
+					direction: 'before',
+					maxSearchSeconds: CONFIG.commandSilenceSearchSeconds,
+				})
+		if (
+			refinedStart !== null &&
+			window.start - refinedStart > CONFIG.commandSilenceMaxBackwardSeconds
+		) {
+			refinedStart = window.start
+		}
+		const shouldKeepEnd = await isSilenceAtTarget({
+			inputPath: options.inputPath,
+			duration: options.duration,
+			targetTime: window.end,
+			label: 'end',
+		})
+		const refinedEnd = shouldKeepEnd
+			? window.end
+			: await findSilenceBoundary({
+					inputPath: options.inputPath,
+					duration: options.duration,
+					targetTime: window.end,
+					direction: 'after',
+					maxSearchSeconds: CONFIG.commandSilenceSearchSeconds,
+				})
+		const start = clamp(refinedStart ?? window.start, 0, options.duration)
+		const end = clamp(refinedEnd ?? window.end, 0, options.duration)
+		if (end <= start + 0.01) {
+			refined.push({ start: window.start, end: window.end })
+			continue
+		}
+		if (
+			Math.abs(start - window.start) > 0.01 ||
+			Math.abs(end - window.end) > 0.01
+		) {
+			logInfo(
+				`Refined command window ${formatSeconds(window.start)}-${formatSeconds(
+					window.end,
+				)} to ${formatSeconds(start)}-${formatSeconds(end)}`,
+			)
+		}
+		refined.push({ start, end })
+	}
+	return mergeTimeRanges(refined)
+}
+
+export async function findSilenceBoundary(options: {
+	inputPath: string
+	duration: number
+	targetTime: number
+	direction: SilenceBoundaryDirection
+	maxSearchSeconds: number
+}): Promise<number | null> {
+	const searchStart =
+		options.direction === 'before'
+			? Math.max(0, options.targetTime - options.maxSearchSeconds)
+			: options.targetTime
+	const searchEnd =
+		options.direction === 'before'
+			? options.targetTime
+			: Math.min(
+					options.duration,
+					options.targetTime + options.maxSearchSeconds,
+				)
+	const searchDuration = searchEnd - searchStart
+	if (searchDuration <= 0.05) {
+		return null
+	}
+	const samples = await readAudioSamples({
+		inputPath: options.inputPath,
+		start: searchStart,
+		duration: searchDuration,
+		sampleRate: CONFIG.vadSampleRate,
+	})
+	if (samples.length === 0) {
+		return null
+	}
+
+	const targetOffset = options.targetTime - searchStart
+	let boundary =
+		(await findSilenceBoundaryWithVad({
+			samples,
+			duration: searchDuration,
+			targetOffset,
+			direction: options.direction,
+		})) ??
+		findSilenceBoundaryWithRms({
+			samples,
+			sampleRate: CONFIG.vadSampleRate,
+			direction: options.direction,
+			rmsWindowMs: CONFIG.commandSilenceRmsWindowMs,
+			rmsThreshold: CONFIG.commandSilenceRmsThreshold,
+			minSilenceMs: CONFIG.commandSilenceMinDurationMs,
+		})
+	if (boundary === null || !Number.isFinite(boundary)) {
+		return null
+	}
+	boundary = clamp(boundary, 0, searchDuration)
+	return searchStart + boundary
+}
+
+async function isSilenceAtTarget(options: {
+	inputPath: string
+	duration: number
+	targetTime: number
+	label?: string
+}): Promise<boolean> {
+	const halfWindowSeconds = Math.max(
+		0.005,
+		(CONFIG.commandSilenceRmsWindowMs / 1000) * 1.5,
+	)
+	const windowStart = clamp(
+		options.targetTime - halfWindowSeconds,
+		0,
+		options.duration,
+	)
+	const windowEnd = clamp(
+		options.targetTime + halfWindowSeconds,
+		0,
+		options.duration,
+	)
+	const windowDuration = windowEnd - windowStart
+	if (windowDuration <= 0.01) {
+		return false
+	}
+	const samples = await readAudioSamples({
+		inputPath: options.inputPath,
+		start: windowStart,
+		duration: windowDuration,
+		sampleRate: CONFIG.vadSampleRate,
+	})
+	if (samples.length === 0) {
+		return false
+	}
+	const windowSamples = Math.max(
+		1,
+		Math.round(
+			(CONFIG.vadSampleRate * CONFIG.commandSilenceRmsWindowMs) / 1000,
+		),
+	)
+	const rms = computeRms(samples)
+	const minRms = computeMinWindowRms(samples, windowSamples)
+	const label = options.label ? ` ${options.label}` : ''
+	logInfo(
+		`Command window${label} RMS at ${formatSeconds(options.targetTime)}: avg ${rms.toFixed(
+			4,
+		)}, min ${minRms.toFixed(4)} (threshold ${CONFIG.commandSilenceRmsThreshold})`,
+	)
+	return minRms < CONFIG.commandSilenceRmsThreshold
+}
+
+async function findSilenceBoundaryWithVad(options: {
+	samples: Float32Array
+	duration: number
+	targetOffset: number
+	direction: SilenceBoundaryDirection
+}): Promise<number | null> {
+	try {
+		const vadSegments = await detectSpeechSegmentsWithVad(
+			options.samples,
+			CONFIG.vadSampleRate,
+			CONFIG,
+		)
+		if (vadSegments.length === 0) {
+			return null
+		}
+		const silenceGaps = buildSilenceGapsFromSpeech(
+			vadSegments,
+			options.duration,
+		)
+		return findSilenceBoundaryFromGaps(
+			silenceGaps,
+			options.targetOffset,
+			options.direction,
+		)
+	} catch {
+		logInfo(
+			`VAD silence scan failed (${options.direction}); using RMS fallback.`,
+		)
+		return null
+	}
+}

package/process-course/logging.ts

@@ -0,0 +1,24 @@
+import { formatCommand } from '../utils'
+import { buildChapterLogPath } from './paths'
+
+export function logCommand(command: string[]) {
+	console.log(`[cmd] ${formatCommand(command)}`)
+}
+
+export function logInfo(message: string) {
+	console.log(`[info] ${message}`)
+}
+
+export function logWarn(message: string) {
+	console.warn(`[warn] ${message}`)
+}
+
+export async function writeChapterLog(
+	tmpDir: string,
+	outputPath: string,
+	lines: string[],
+) {
+	const logPath = buildChapterLogPath(tmpDir, outputPath)
+	const body = `${lines.join('\n')}\n`
+	await Bun.write(logPath, body)
+}

package/process-course/paths.test.ts

@@ -0,0 +1,59 @@
+import path from 'node:path'
+import { test, expect } from 'bun:test'
+import {
+	buildChapterLogPath,
+	buildIntermediateAudioPath,
+	buildIntermediatePath,
+	buildJarvisEditLogPath,
+	buildJarvisOutputBase,
+	buildJarvisWarningLogPath,
+	buildSummaryLogPath,
+	buildTranscriptionOutputBase,
+} from './paths'
+
+test('buildIntermediatePath appends suffix with original extension', () => {
+	const result = buildIntermediatePath('/tmp', '/videos/lesson.mp4', 'trimmed')
+	expect(result).toBe(path.join('/tmp', 'lesson-trimmed.mp4'))
+})
+
+test('buildIntermediateAudioPath forces wav extension', () => {
+	const result = buildIntermediateAudioPath(
+		'/tmp',
+		'/videos/lesson.mp4',
+		'speech',
+	)
+	expect(result).toBe(path.join('/tmp', 'lesson-speech.wav'))
+})
+
+test('buildTranscriptionOutputBase appends transcribe suffix', () => {
+	const result = buildTranscriptionOutputBase('/tmp', '/videos/lesson.mp4')
+	expect(result).toBe(path.join('/tmp', 'lesson-transcribe'))
+})
+
+test('buildJarvisOutputBase appends jarvis suffix', () => {
+	const result = buildJarvisOutputBase('/tmp', '/videos/lesson.mp4')
+	expect(result).toBe(path.join('/tmp', 'lesson-jarvis'))
+})
+
+test('buildSummaryLogPath uses process-summary.log', () => {
+	expect(buildSummaryLogPath('/tmp')).toBe(
+		path.join('/tmp', 'process-summary.log'),
+	)
+})
+
+test('buildJarvisWarningLogPath uses jarvis-warnings.log', () => {
+	expect(buildJarvisWarningLogPath('/out')).toBe(
+		path.join('/out', 'jarvis-warnings.log'),
+	)
+})
+
+test('buildJarvisEditLogPath uses jarvis-edits.log', () => {
+	expect(buildJarvisEditLogPath('/out')).toBe(
+		path.join('/out', 'jarvis-edits.log'),
+	)
+})
+
+test('buildChapterLogPath uses output filename for log', () => {
+	const result = buildChapterLogPath('/tmp', '/videos/lesson.mp4')
+	expect(result).toBe(path.join('/tmp', 'lesson.log'))
+})

package/process-course/paths.ts

@@ -0,0 +1,53 @@
+import path from 'node:path'
+
+export function buildIntermediatePath(
+	tmpDir: string,
+	outputPath: string,
+	suffix: string,
+) {
+	const parsed = path.parse(outputPath)
+	return path.join(tmpDir, `${parsed.name}-${suffix}${parsed.ext}`)
+}
+
+export function buildIntermediateAudioPath(
+	tmpDir: string,
+	outputPath: string,
+	suffix: string,
+) {
+	const parsed = path.parse(outputPath)
+	return path.join(tmpDir, `${parsed.name}-${suffix}.wav`)
+}
+
+export function buildTranscriptionOutputBase(
+	tmpDir: string,
+	outputPath: string,
+) {
+	const parsed = path.parse(outputPath)
+	return path.join(tmpDir, `${parsed.name}-transcribe`)
+}
+
+export function buildJarvisOutputBase(tmpDir: string, outputPath: string) {
+	const parsed = path.parse(outputPath)
+	return path.join(tmpDir, `${parsed.name}-jarvis`)
+}
+
+export function buildSummaryLogPath(tmpDir: string) {
+	return path.join(tmpDir, 'process-summary.log')
+}
+
+export function buildJarvisWarningLogPath(outputDir: string) {
+	return path.join(outputDir, 'jarvis-warnings.log')
+}
+
+export function buildJarvisEditLogPath(outputDir: string) {
+	return path.join(outputDir, 'jarvis-edits.log')
+}
+
+export function buildJarvisNoteLogPath(outputDir: string) {
+	return path.join(outputDir, 'jarvis-notes.log')
+}
+
+export function buildChapterLogPath(tmpDir: string, outputPath: string) {
+	const parsed = path.parse(outputPath)
+	return path.join(tmpDir, `${parsed.name}.log`)
+}

package/process-course/summary.test.ts

@@ -0,0 +1,209 @@
+import { test, expect } from 'bun:test'
+import path from 'node:path'
+import os from 'node:os'
+import { mkdtemp, rm, mkdir } from 'node:fs/promises'
+import {
+	buildJarvisEditLogPath,
+	buildJarvisWarningLogPath,
+	buildSummaryLogPath,
+} from './paths'
+import type {
+	Chapter,
+	JarvisEdit,
+	JarvisWarning,
+	TimeRange,
+	EditWorkspaceInfo,
+} from './types'
+import { writeJarvisLogs, writeSummaryLogs } from './summary'
+
+async function createTempDir(): Promise<string> {
+	return mkdtemp(path.join(os.tmpdir(), 'summary-logs-'))
+}
+
+function createChapter(index: number, title = `Chapter ${index + 1}`): Chapter {
+	return { index, start: 0, end: 10, title }
+}
+
+function createTimestamp(start: number, end: number): TimeRange {
+	return { start, end }
+}
+
+function createWarning(
+	index: number,
+	outputPath: string,
+	timestamps: TimeRange[] = [],
+): JarvisWarning {
+	return { chapter: createChapter(index), outputPath, timestamps }
+}
+
+function createEdit(index: number, outputPath: string): JarvisEdit {
+	return { chapter: createChapter(index), outputPath }
+}
+
+function createEditWorkspace(
+	index: number,
+	outputPath: string,
+	editsDirectory: string,
+): EditWorkspaceInfo {
+	return {
+		chapter: createChapter(index),
+		outputPath,
+		reason: 'edit-command',
+		editsDirectory,
+		transcriptTextPath: path.join(editsDirectory, 'transcript.txt'),
+		transcriptJsonPath: path.join(editsDirectory, 'transcript.json'),
+		originalVideoPath: path.join(editsDirectory, 'original.mp4'),
+		instructionsPath: path.join(editsDirectory, 'edit-instructions.md'),
+	}
+}
+
+test('writeJarvisLogs writes warning and edit logs', async () => {
+	const tmpDir = await createTempDir()
+	const outputDir = path.join(tmpDir, 'output')
+	await mkdir(outputDir)
+	try {
+		const warning = createWarning(0, path.join(outputDir, 'chapter-01.mp4'), [
+			createTimestamp(1, 1.5),
+			createTimestamp(4.25, 4.75),
+		])
+		const edit = createEdit(1, path.join(outputDir, 'chapter-02.mp4'))
+
+		await writeJarvisLogs({
+			outputDir,
+			inputPath: '/videos/course.mp4',
+			jarvisWarnings: [warning],
+			jarvisEdits: [edit],
+			jarvisNotes: [],
+			editWorkspaces: [
+				createEditWorkspace(
+					1,
+					path.join(outputDir, 'chapter-02.mp4'),
+					path.join(outputDir, 'edits', 'chapter-02'),
+				),
+			],
+			dryRun: false,
+		})
+
+		const warningLog = await Bun.file(
+			buildJarvisWarningLogPath(outputDir),
+		).text()
+		expect(warningLog).toContain('Input: /videos/course.mp4')
+		expect(warningLog).toContain('Jarvis warnings: 1')
+		expect(warningLog).toContain('Detected in:')
+		expect(warningLog).toContain('Chapter 1')
+		expect(warningLog).toContain('chapter-01.mp4')
+		expect(warningLog).toContain('Jarvis timestamps: 1.00s-1.50s, 4.25s-4.75s')
+
+		const editLog = await Bun.file(buildJarvisEditLogPath(outputDir)).text()
+		expect(editLog).toContain('Input: /videos/course.mp4')
+		expect(editLog).toContain('Edit commands: 1')
+		expect(editLog).toContain('Files needing edits:')
+		expect(editLog).toContain('Chapter 2')
+		expect(editLog).toContain('chapter-02.mp4')
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('writeJarvisLogs handles empty warning and edit lists', async () => {
+	const tmpDir = await createTempDir()
+	const outputDir = path.join(tmpDir, 'output')
+	await mkdir(outputDir)
+	try {
+		await writeJarvisLogs({
+			outputDir,
+			inputPath: '/videos/course.mp4',
+			jarvisWarnings: [],
+			jarvisEdits: [],
+			jarvisNotes: [],
+			editWorkspaces: [],
+			dryRun: false,
+		})
+
+		const warningLog = await Bun.file(
+			buildJarvisWarningLogPath(outputDir),
+		).text()
+		expect(warningLog).toContain('Detected in: none')
+
+		const editLog = await Bun.file(buildJarvisEditLogPath(outputDir)).text()
+		expect(editLog).toContain('Files needing edits: none')
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('writeSummaryLogs writes summary file with details', async () => {
+	const tmpDir = await createTempDir()
+	const outputDir = path.join(tmpDir, 'output')
+	await mkdir(outputDir)
+	try {
+		await writeSummaryLogs({
+			tmpDir,
+			outputDir,
+			inputPath: '/videos/course.mp4',
+			summary: {
+				totalSelected: 3,
+				processed: 2,
+				skippedShortInitial: 0,
+				skippedShortTrimmed: 1,
+				skippedTranscription: 0,
+				fallbackNotes: 1,
+				logsWritten: 2,
+				jarvisWarnings: 0,
+				editsPending: 1,
+			},
+			summaryDetails: ['- Chapter 2 skipped (short)'],
+			jarvisWarnings: [],
+			jarvisEdits: [],
+			editWorkspaces: [
+				createEditWorkspace(
+					1,
+					path.join(outputDir, 'chapter-02.mp4'),
+					path.join(outputDir, 'edits', 'chapter-02'),
+				),
+			],
+			dryRun: false,
+		})
+
+		const summaryLog = await Bun.file(buildSummaryLogPath(tmpDir)).text()
+		expect(summaryLog).toContain('Input: /videos/course.mp4')
+		expect(summaryLog).toContain('Processed chapters: 2')
+		expect(summaryLog).toContain('Details:')
+		expect(summaryLog).toContain('- Chapter 2 skipped (short)')
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})
+
+test('writeSummaryLogs skips writing file in dry run mode', async () => {
+	const tmpDir = await createTempDir()
+	const outputDir = path.join(tmpDir, 'output')
+	await mkdir(outputDir)
+	try {
+		await writeSummaryLogs({
+			tmpDir,
+			outputDir,
+			inputPath: '/videos/course.mp4',
+			summary: {
+				totalSelected: 1,
+				processed: 1,
+				skippedShortInitial: 0,
+				skippedShortTrimmed: 0,
+				skippedTranscription: 0,
+				fallbackNotes: 0,
+				logsWritten: 0,
+				jarvisWarnings: 0,
+				editsPending: 0,
+			},
+			summaryDetails: [],
+			jarvisWarnings: [],
+			jarvisEdits: [],
+			editWorkspaces: [],
+			dryRun: true,
+		})
+
+		expect(await Bun.file(buildSummaryLogPath(tmpDir)).exists()).toBe(false)
+	} finally {
+		await rm(tmpDir, { recursive: true, force: true })
+	}
+})