eprec 0.0.1 → 1.0.1

package/process-course/errors.ts

@@ -0,0 +1,82 @@
+// Custom error types for better error handling and debugging
+
+export class ChapterProcessingError extends Error {
+	constructor(
+		message: string,
+		public readonly chapterIndex: number,
+		public readonly chapterTitle: string,
+	) {
+		super(message)
+		this.name = 'ChapterProcessingError'
+	}
+}
+
+export class ChapterTooShortError extends ChapterProcessingError {
+	constructor(
+		chapterIndex: number,
+		chapterTitle: string,
+		public readonly duration: number,
+		public readonly minDuration: number,
+	) {
+		super(
+			`Chapter "${chapterTitle}" is too short (${duration.toFixed(2)}s < ${minDuration}s)`,
+			chapterIndex,
+			chapterTitle,
+		)
+		this.name = 'ChapterTooShortError'
+	}
+}
+
+export class CommandParseError extends Error {
+	constructor(
+		message: string,
+		public readonly transcript?: string,
+	) {
+		super(message)
+		this.name = 'CommandParseError'
+	}
+}
+
+export class TranscriptTooShortError extends ChapterProcessingError {
+	constructor(
+		chapterIndex: number,
+		chapterTitle: string,
+		public readonly wordCount: number,
+		public readonly minWordCount: number,
+	) {
+		super(
+			`Chapter "${chapterTitle}" transcript too short (${wordCount} words < ${minWordCount})`,
+			chapterIndex,
+			chapterTitle,
+		)
+		this.name = 'TranscriptTooShortError'
+	}
+}
+
+export class BadTakeError extends ChapterProcessingError {
+	constructor(chapterIndex: number, chapterTitle: string) {
+		super(
+			`Chapter "${chapterTitle}" marked as bad take`,
+			chapterIndex,
+			chapterTitle,
+		)
+		this.name = 'BadTakeError'
+	}
+}
+
+export class SpliceError extends Error {
+	constructor(message: string) {
+		super(message)
+		this.name = 'SpliceError'
+	}
+}
+
+export class TrimWindowError extends Error {
+	constructor(
+		public readonly start: number,
+		public readonly end: number,
+	) {
+		super(`Trim window too small (${start.toFixed(3)}s -> ${end.toFixed(3)}s)`)
+		this.name = 'TrimWindowError'
+	}
+}

package/process-course/ffmpeg.ts

@@ -0,0 +1,449 @@
+import {
+	runCommand as runCommandBase,
+	runCommandBinary as runCommandBinaryBase,
+	formatSeconds,
+} from '../utils'
+import { CONFIG, TRANSCRIPTION_SAMPLE_RATE } from './config'
+import { logCommand, logInfo, logWarn } from './logging'
+import type { Chapter, LoudnormAnalysis } from './types'
+
+async function runCommand(command: string[], allowFailure = false) {
+	return runCommandBase(command, { allowFailure, logCommand })
+}
+
+async function runCommandBinary(command: string[], allowFailure = false) {
+	return runCommandBinaryBase(command, { allowFailure, logCommand })
+}
+
+export async function ensureFfmpegAvailable() {
+	const ffmpeg = await runCommand(['ffmpeg', '-version'], true)
+	const ffprobe = await runCommand(['ffprobe', '-version'], true)
+	if (ffmpeg.exitCode !== 0 || ffprobe.exitCode !== 0) {
+		throw new Error(
+			'ffmpeg/ffprobe not available. Install them and ensure they are on PATH.',
+		)
+	}
+}
+
+export async function getChapters(inputPath: string): Promise<Chapter[]> {
+	const result = await runCommand([
+		'ffprobe',
+		'-v',
+		'error',
+		'-print_format',
+		'json',
+		'-show_chapters',
+		'-i',
+		inputPath,
+	])
+
+	const payload = JSON.parse(result.stdout)
+	const chapters = payload.chapters ?? []
+	if (chapters.length === 0) {
+		return []
+	}
+
+	return chapters.map((chapter: any, index: number) => {
+		const start = Number.parseFloat(chapter.start_time)
+		const end = Number.parseFloat(chapter.end_time)
+		if (!Number.isFinite(start) || !Number.isFinite(end)) {
+			throw new Error(`Invalid chapter time data at index ${index}`)
+		}
+		return {
+			index,
+			start,
+			end,
+			title: chapter.tags?.title
+				? String(chapter.tags.title)
+				: `chapter-${index + 1}`,
+		}
+	})
+}
+
+export async function readAudioSamples(options: {
+	inputPath: string
+	start: number
+	duration: number
+	sampleRate: number
+}) {
+	const result = await runCommandBinary(
+		[
+			'ffmpeg',
+			'-hide_banner',
+			'-ss',
+			options.start.toFixed(3),
+			'-t',
+			options.duration.toFixed(3),
+			'-i',
+			options.inputPath,
+			'-vn',
+			'-sn',
+			'-dn',
+			'-ac',
+			'1',
+			'-ar',
+			String(options.sampleRate),
+			'-f',
+			'f32le',
+			'-',
+		],
+		true,
+	)
+
+	const bytes = result.stdout
+	if (bytes.byteLength === 0) {
+		return new Float32Array()
+	}
+	const buffer = bytes.buffer.slice(
+		bytes.byteOffset,
+		bytes.byteOffset + bytes.byteLength,
+	)
+	return new Float32Array(buffer)
+}
+
+function isValidLoudnessValue(
+	value: string,
+	min?: number,
+	max?: number,
+): boolean {
+	const num = Number.parseFloat(value)
+	if (!Number.isFinite(num)) {
+		return false
+	}
+	if (min !== undefined && num < min) {
+		return false
+	}
+	if (max !== undefined && num > max) {
+		return false
+	}
+	return true
+}
+
+function buildNormalizeAudioFilter(options: {
+	printFormat: 'json' | 'summary'
+	analysis: LoudnormAnalysis | null
+}) {
+	const prefilter =
+		CONFIG.normalizePrefilterEnabled && CONFIG.normalizePrefilter
+			? `${CONFIG.normalizePrefilter},`
+			: ''
+	const loudnorm = [
+		`loudnorm=I=${CONFIG.loudnessTargetI}`,
+		`LRA=${CONFIG.loudnessTargetLra}`,
+		`TP=${CONFIG.loudnessTargetTp}`,
+	]
+
+	// Only use analysis if all values are valid (not -inf/inf)
+	// input_i must be in range [-99, 0] per ffmpeg loudnorm filter
+	if (options.analysis) {
+		const hasValidAnalysis =
+			isValidLoudnessValue(options.analysis.input_i, -99, 0) &&
+			isValidLoudnessValue(options.analysis.input_tp) &&
+			isValidLoudnessValue(options.analysis.input_lra) &&
+			isValidLoudnessValue(options.analysis.input_thresh) &&
+			isValidLoudnessValue(options.analysis.target_offset)
+
+		if (hasValidAnalysis) {
+			loudnorm.push(
+				`measured_I=${options.analysis.input_i}`,
+				`measured_TP=${options.analysis.input_tp}`,
+				`measured_LRA=${options.analysis.input_lra}`,
+				`measured_thresh=${options.analysis.input_thresh}`,
+				`offset=${options.analysis.target_offset}`,
+				'linear=true',
+			)
+		} else {
+			logWarn(
+				`Audio analysis contains invalid values (input_i=${options.analysis.input_i}), skipping measured normalization. Using default loudnorm settings.`,
+			)
+		}
+	}
+
+	loudnorm.push(`print_format=${options.printFormat}`)
+
+	return `${prefilter}${loudnorm.join(':')}`
+}
+
+export async function analyzeLoudness(
+	inputPath: string,
+	absoluteStart: number,
+	absoluteEnd: number,
+): Promise<LoudnormAnalysis> {
+	const clipDuration = absoluteEnd - absoluteStart
+	if (clipDuration <= 0) {
+		throw new Error(
+			`Invalid analysis window (${formatSeconds(absoluteStart)} -> ${formatSeconds(
+				absoluteEnd,
+			)})`,
+		)
+	}
+
+	const filter = buildNormalizeAudioFilter({
+		printFormat: 'json',
+		analysis: null,
+	})
+	const result = await runCommand(
+		[
+			'ffmpeg',
+			'-hide_banner',
+			'-ss',
+			absoluteStart.toFixed(3),
+			'-t',
+			clipDuration.toFixed(3),
+			'-i',
+			inputPath,
+			'-vn',
+			'-sn',
+			'-dn',
+			'-af',
+			filter,
+			'-f',
+			'null',
+			'-',
+		],
+		true,
+	)
+
+	const analysisJson = result.stderr.match(/\{[\s\S]*?\}/)?.[0]
+	if (!analysisJson) {
+		throw new Error('Failed to parse loudnorm analysis output.')
+	}
+
+	const payload = JSON.parse(analysisJson)
+	return {
+		input_i: payload.input_i,
+		input_tp: payload.input_tp,
+		input_lra: payload.input_lra,
+		input_thresh: payload.input_thresh,
+		target_offset: payload.target_offset,
+	}
+}
+
+export async function renderChapter(options: {
+	inputPath: string
+	outputPath: string
+	absoluteStart: number
+	absoluteEnd: number
+	analysis: LoudnormAnalysis
+}) {
+	const clipDuration = options.absoluteEnd - options.absoluteStart
+	if (clipDuration <= 0) {
+		throw new Error(
+			`Invalid render window (${formatSeconds(options.absoluteStart)} -> ${formatSeconds(
+				options.absoluteEnd,
+			)})`,
+		)
+	}
+
+	const loudnorm = buildNormalizeAudioFilter({
+		printFormat: 'summary',
+		analysis: options.analysis,
+	})
+
+	const args = [
+		'ffmpeg',
+		'-hide_banner',
+		'-y',
+		'-ss',
+		options.absoluteStart.toFixed(3),
+		'-t',
+		clipDuration.toFixed(3),
+		'-i',
+		options.inputPath,
+		'-dn',
+		'-map_chapters',
+		'-1',
+		'-map',
+		'0:v?',
+		'-map',
+		'0:a?',
+		'-map',
+		'0:s?',
+	]
+
+	if (CONFIG.videoReencodeForAccurateTrim) {
+		args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18')
+	} else {
+		args.push('-c:v', 'copy')
+	}
+
+	args.push(
+		'-c:a',
+		CONFIG.audioCodec,
+		'-b:a',
+		CONFIG.audioBitrate,
+		'-af',
+		loudnorm,
+		'-c:s',
+		'copy',
+		options.outputPath,
+	)
+
+	await runCommand(args)
+	logInfo(`Wrote ${options.outputPath}`)
+}
+
+export async function extractChapterSegment(options: {
+	inputPath: string
+	outputPath: string
+	start: number
+	end: number
+}) {
+	const clipDuration = options.end - options.start
+	if (clipDuration <= 0) {
+		throw new Error(
+			`Invalid segment window (${formatSeconds(options.start)} -> ${formatSeconds(
+				options.end,
+			)})`,
+		)
+	}
+
+	const args = [
+		'ffmpeg',
+		'-hide_banner',
+		'-y',
+		'-ss',
+		options.start.toFixed(3),
+		'-t',
+		clipDuration.toFixed(3),
+		'-i',
+		options.inputPath,
+		'-dn',
+		'-map_chapters',
+		'-1',
+		'-map',
+		'0:v?',
+		'-map',
+		'0:a?',
+		'-map',
+		'0:s?',
+		'-c:v',
+		'copy',
+		'-c:a',
+		'copy',
+		'-c:s',
+		'copy',
+		options.outputPath,
+	]
+
+	await runCommand(args)
+}
+
+export async function extractChapterSegmentAccurate(options: {
+	inputPath: string
+	outputPath: string
+	start: number
+	end: number
+}) {
+	const clipDuration = options.end - options.start
+	if (clipDuration <= 0) {
+		throw new Error(
+			`Invalid segment window (${formatSeconds(options.start)} -> ${formatSeconds(
+				options.end,
+			)})`,
+		)
+	}
+
+	const args = [
+		'ffmpeg',
+		'-hide_banner',
+		'-y',
+		'-i',
+		options.inputPath,
+		'-ss',
+		options.start.toFixed(3),
+		'-t',
+		clipDuration.toFixed(3),
+		'-dn',
+		'-map_chapters',
+		'-1',
+		'-map',
+		'0:v?',
+		'-map',
+		'0:a?',
+		'-map',
+		'0:s?',
+		'-c:v',
+		'libx264',
+		'-preset',
+		'medium',
+		'-crf',
+		'18',
+		'-c:a',
+		CONFIG.audioCodec,
+		'-b:a',
+		CONFIG.audioBitrate,
+		'-c:s',
+		'copy',
+		options.outputPath,
+	]
+
+	await runCommand(args)
+}
+
+export async function extractTranscriptionAudio(options: {
+	inputPath: string
+	outputPath: string
+	start: number
+	end: number
+}) {
+	const clipDuration = options.end - options.start
+	if (clipDuration <= 0) {
+		throw new Error(
+			`Invalid transcription window (${formatSeconds(options.start)} -> ${formatSeconds(
+				options.end,
+			)})`,
+		)
+	}
+
+	const args = [
+		'ffmpeg',
+		'-hide_banner',
+		'-y',
+		'-ss',
+		options.start.toFixed(3),
+		'-t',
+		clipDuration.toFixed(3),
+		'-i',
+		options.inputPath,
+		'-vn',
+		'-sn',
+		'-dn',
+		'-ac',
+		'1',
+		'-ar',
+		String(TRANSCRIPTION_SAMPLE_RATE),
+		'-c:a',
+		'pcm_s16le',
+		options.outputPath,
+	]
+
+	await runCommand(args)
+}
+
+export async function concatSegments(options: {
+	segmentPaths: string[]
+	outputPath: string
+}) {
+	if (options.segmentPaths.length < 2) {
+		throw new Error('Splice requires at least two segments to concat.')
+	}
+	const args = ['ffmpeg', '-hide_banner', '-y']
+	for (const segmentPath of options.segmentPaths) {
+		args.push('-i', segmentPath)
+	}
+	const inputLabels = options.segmentPaths
+		.map((_, index) => `[${index}:v:0][${index}:a:0]`)
+		.join('')
+	const concatFilter = `${inputLabels}concat=n=${options.segmentPaths.length}:v=1:a=1[v][a]`
+	const filter = `${concatFilter};[a]aresample=async=1:first_pts=0[aout]`
+	args.push('-filter_complex', filter, '-map', '[v]', '-map', '[aout]')
+	if (CONFIG.commandSpliceReencode) {
+		args.push('-c:v', 'libx264', '-preset', 'medium', '-crf', '18')
+	} else {
+		args.push('-c:v', 'copy')
+	}
+	args.push('-c:a', CONFIG.audioCodec, '-b:a', CONFIG.audioBitrate)
+	args.push(options.outputPath)
+	await runCommand(args)
+}

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

@@ -0,0 +1,71 @@
+import { CONFIG } from '../config'
+import { countTranscriptWords } from '../utils/transcript'
+import type { TranscriptCommand, CommandAnalysisResult } from './types'
+
+/**
+ * Analyze commands and determine chapter processing behavior.
+ */
+export function analyzeCommands(
+	commands: TranscriptCommand[],
+	transcript: string,
+): CommandAnalysisResult {
+	const filenameCommand = commands.find(
+		(command) => command.type === 'filename' && command.value?.trim(),
+	)
+	const filenameOverride = filenameCommand?.value ?? null
+
+	const hasBadTake = commands.some((command) => command.type === 'bad-take')
+	const hasEdit = commands.some((command) => command.type === 'edit')
+	const hasCombinePrevious = commands.some(
+		(command) => command.type === 'combine-previous',
+	)
+
+	const notes = commands
+		.filter((command) => command.type === 'note' && command.value?.trim())
+		.map((command) => ({
+			value: command.value!,
+			window: command.window,
+		}))
+
+	const splits = commands
+		.filter((command) => command.type === 'split')
+		.map((command) => ({
+			window: command.window,
+		}))
+
+	const transcriptWordCount = countTranscriptWords(transcript)
+
+	// Determine if we should skip this chapter
+	let shouldSkip = false
+	let skipReason: string | undefined
+
+	if (
+		transcriptWordCount <= CONFIG.minTranscriptWords &&
+		commands.length === 0
+	) {
+		shouldSkip = true
+		skipReason = `transcript too short (${transcriptWordCount} words)`
+	} else if (hasBadTake) {
+		shouldSkip = true
+		skipReason = 'bad take command detected'
+	}
+
+	return {
+		commands,
+		filenameOverride,
+		hasBadTake,
+		hasEdit,
+		hasCombinePrevious,
+		notes,
+		splits,
+		shouldSkip,
+		skipReason,
+	}
+}
+
+/**
+ * Get command types as a comma-separated string for logging.
+ */
+export function formatCommandTypes(commands: TranscriptCommand[]): string {
+	return commands.map((command) => command.type).join(', ')
+}

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

@@ -0,0 +1,14 @@
+// Public API for jarvis commands module
+
+export { extractTranscriptCommands, scaleTranscriptSegments } from './parser'
+export { buildCommandWindows, refineCommandWindows } from './windows'
+export { analyzeCommands, formatCommandTypes } from './handlers'
+
+export type {
+	CommandType,
+	TranscriptCommand,
+	TranscriptWord,
+	CommandExtractionOptions,
+	CommandWindowOptions,
+	CommandAnalysisResult,
+} from './types'