eprec 1.5.0 → 1.7.0

package/README.md

@@ -40,7 +40,7 @@ bun install
 ## Quick Start
 
 ```bash
-bun process-course-video.ts "/path/to/input.mp4" "/path/to/output" \
+bun src/process-course-video.ts "/path/to/input.mp4" "/path/to/output" \
   --enable-transcription \
   --keep-intermediates \
   --write-logs

package/app/assets/styles.css

@@ -33,12 +33,7 @@
 	--color-danger-text: #b91c1c;
 	--color-danger-border: #fecaca;
 	--color-danger-border-strong: #fca5a5;
-	--font-family:
-		'Inter',
-		'Segoe UI',
-		system-ui,
-		-apple-system,
-		sans-serif;
+	--font-family: 'Inter', 'Segoe UI', system-ui, -apple-system, sans-serif;
 	--font-size-xs: 12px;
 	--font-size-sm: 14px;
 	--font-size-base: 16px;
@@ -63,10 +58,8 @@
 	--radius-lg: 12px;
 	--radius-xl: 16px;
 	--radius-pill: 999px;
-	--shadow-sm: 0 1px 2px
-		color-mix(in srgb, var(--color-text) 12%, transparent);
-	--shadow-md: 0 6px 16px
-		color-mix(in srgb, var(--color-text) 14%, transparent);
+	--shadow-sm: 0 1px 2px color-mix(in srgb, var(--color-text) 12%, transparent);
+	--shadow-md: 0 6px 16px color-mix(in srgb, var(--color-text) 14%, transparent);
 	--shadow-lg: 0 18px 38px
 		color-mix(in srgb, var(--color-text) 16%, transparent);
 	--transition-fast: 150ms ease;
@@ -82,18 +75,18 @@
 @media (prefers-color-scheme: dark) {
 	:root {
 		color-scheme: dark;
-	--color-primary: #38bdf8;
-	--color-primary-hover: #0ea5e9;
-	--color-primary-active: #0284c7;
-	--color-on-primary: #0f172a;
-	--color-background: #0b1120;
-	--color-surface: #111827;
-	--color-surface-muted: #0f172a;
-	--color-surface-inverse: #f8fafc;
-	--color-text: #f8fafc;
-	--color-text-muted: #94a3b8;
-	--color-text-subtle: #cbd5e1;
-	--color-text-secondary: #e2e8f0;
+		--color-primary: #38bdf8;
+		--color-primary-hover: #0ea5e9;
+		--color-primary-active: #0284c7;
+		--color-on-primary: #0f172a;
+		--color-background: #0b1120;
+		--color-surface: #111827;
+		--color-surface-muted: #0f172a;
+		--color-surface-inverse: #f8fafc;
+		--color-text: #f8fafc;
+		--color-text-muted: #94a3b8;
+		--color-text-subtle: #cbd5e1;
+		--color-text-secondary: #e2e8f0;
 		--color-text-faint: #64748b;
 		--color-text-inverse: #0f172a;
 		--color-border: #334155;
@@ -110,12 +103,9 @@
 		--color-danger-text: #fecaca;
 		--color-danger-border: #ef4444;
 		--color-danger-border-strong: #fca5a5;
-		--shadow-sm: 0 1px 2px
-			color-mix(in srgb, #0f172a 12%, transparent);
-		--shadow-md: 0 6px 16px
-			color-mix(in srgb, #0f172a 14%, transparent);
-		--shadow-lg: 0 18px 38px
-			color-mix(in srgb, #0f172a 16%, transparent);
+		--shadow-sm: 0 1px 2px color-mix(in srgb, #0f172a 12%, transparent);
+		--shadow-md: 0 6px 16px color-mix(in srgb, #0f172a 14%, transparent);
+		--shadow-lg: 0 18px 38px color-mix(in srgb, #0f172a 16%, transparent);
 	}
 }
 

package/package.json

@@ -1,35 +1,30 @@
 {
   "name": "eprec",
   "type": "module",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/epicweb-dev/eprec"
   },
   "scripts": {
-    "app:start": "bun --watch ./cli.ts app start",
+    "app:start": "bun --watch ./src/cli.ts app start",
     "format": "prettier --write .",
-    "test": "bun test process-course utils.test.ts",
+    "test": "bun test process-course src/utils.test.ts",
     "test:e2e": "bun test ./e2e",
-    "test:smoke": "bunx playwright test -c playwright-smoke-config.ts",
+    "test:smoke": "bunx playwright test -c playwright/playwright-smoke-config.ts",
     "test:all": "bun test '**/*.test.ts'",
     "validate": "bun run test"
   },
   "bin": {
-    "eprec": "./cli.ts"
+    "eprec": "./src/cli.ts"
   },
   "files": [
     "app/**",
-    "app-server.ts",
-    "cli.ts",
     "process-course/**",
-    "process-course-video.ts",
     "public/**",
     "server/**",
-    "speech-detection.ts",
-    "utils.ts",
-    "whispercpp-transcribe.ts"
+    "src/**"
   ],
   "prettier": "@epic-web/config/prettier",
   "devDependencies": {
@@ -43,8 +38,10 @@
     "typescript": "^5"
   },
   "dependencies": {
+    "@inquirer/search": "^4.1.0",
     "get-port": "^7.1.0",
     "inquirer": "^13.2.1",
+    "match-sorter": "^8.2.0",
     "onnxruntime-node": "^1.23.2",
     "ora": "^9.1.0",
     "remix": "3.0.0-alpha.0",

package/process-course/chapter-processor.ts

@@ -1,7 +1,10 @@
 import path from 'node:path'
-import { detectSpeechBounds, checkSegmentHasSpeech } from '../speech-detection'
-import { transcribeAudio } from '../whispercpp-transcribe'
-import { clamp, formatSeconds } from '../utils'
+import {
+	detectSpeechBounds,
+	checkSegmentHasSpeech,
+} from '../src/speech-detection'
+import { transcribeAudio } from '../src/whispercpp-transcribe'
+import { clamp, formatSeconds } from '../src/utils'
 import {
 	COMMAND_CLOSE_WORD,
 	COMMAND_WAKE_WORD,
@@ -51,6 +54,14 @@ import type {
 } from './types'
 import { createEditWorkspace } from './edits'
 
+export type ChapterProgressReporter = {
+	start: (options: { stepCount: number; label?: string }) => void
+	step: (label: string) => void
+	setLabel: (label: string) => void
+	finish: (label?: string) => void
+	skip: (label: string) => void
+}
+
 export interface ChapterProcessingOptions {
 	inputPath: string
 	outputDir: string
@@ -64,6 +75,7 @@ export interface ChapterProcessingOptions {
 	writeLogs: boolean
 	dryRun: boolean
 	previousProcessedChapter?: ProcessedChapterInfo | null
+	progress?: ChapterProgressReporter
 }
 
 export interface ChapterProcessingResult {
@@ -97,11 +109,16 @@ export async function processChapter(
 		)
 	}
 
+	const progress = options.progress
+	const stepCount = options.dryRun ? 1 : options.enableTranscription ? 8 : 7
+
 	const outputBasePath = path.join(
 		options.outputDir,
 		`${formatChapterFilename(chapter)}${path.extname(options.inputPath)}`,
 	)
 
+	progress?.start({ stepCount, label: 'Starting' })
+
 	// Check minimum duration before processing
 	if (duration < options.minChapterDurationSeconds) {
 		logInfo(
@@ -118,6 +135,7 @@ export async function processChapter(
 			])
 			logWritten = true
 		}
+		progress?.skip('Skipped (short)')
 		return { status: 'skipped', skipReason: 'short-initial', logWritten }
 	}
 
@@ -126,6 +144,7 @@ export async function processChapter(
 		logInfo(
 			`[dry-run] Would process chapter ${chapter.index + 1}: ${chapter.title}`,
 		)
+		progress?.finish('Dry run')
 		return { status: 'processed', skipReason: 'dry-run', logWritten: false }
 	}
 
@@ -136,6 +155,7 @@ export async function processChapter(
 
 	try {
 		// Step 1: Extract raw segment with padding trimmed
+		progress?.step('Extracting segment')
 		const rawTrimStart = chapter.start + CONFIG.rawTrimPaddingSeconds
 		const rawTrimEnd = chapter.end - CONFIG.rawTrimPaddingSeconds
 		const rawDuration = rawTrimEnd - rawTrimStart
@@ -153,6 +173,7 @@ export async function processChapter(
 		})
 
 		// Step 2: Normalize audio
+		progress?.step('Normalizing audio')
 		const analysis = await analyzeLoudness(paths.rawPath, 0, rawDuration)
 		await renderChapter({
 			inputPath: paths.rawPath,
@@ -167,8 +188,10 @@ export async function processChapter(
 		let commandFilenameOverride: string | null = null
 		let hasEditCommand = false
 		let commandNotes: Array<{ value: string; window: TimeRange }> = []
+		let usedSpliceStep = false
 
 		if (options.enableTranscription) {
+			progress?.step('Transcribing audio')
 			const transcriptionResult = await transcribeAndAnalyze({
 				normalizedPath: paths.normalizedPath,
 				transcriptionAudioPath: paths.transcriptionAudioPath,
@@ -189,6 +212,7 @@ export async function processChapter(
 					logWritten = true
 				}
 				await safeUnlink(outputBasePath)
+				progress?.skip('Skipped (transcript)')
 				return {
 					status: 'skipped',
 					skipReason: transcriptionResult.hasBadTake
@@ -210,6 +234,8 @@ export async function processChapter(
 						`Combine previous command detected for chapter ${chapter.index + 1}, but no previous chapter available. Processing normally.`,
 					)
 				} else {
+					progress?.step('Combining previous')
+					usedSpliceStep = true
 					const combineResult = await handleCombinePrevious({
 						chapter,
 						previousProcessedChapter: options.previousProcessedChapter,
@@ -224,8 +250,10 @@ export async function processChapter(
 					})
 					// If combine failed (returned null), continue with normal processing
 					if (combineResult !== null) {
+						progress?.finish('Combined')
 						return combineResult
 					}
+					progress?.setLabel('Splicing commands')
 					// Otherwise, fall through to normal processing
 				}
 			}
@@ -239,6 +267,9 @@ export async function processChapter(
 		)
 
 		// Step 5: Handle command splicing
+		if (!usedSpliceStep) {
+			progress?.step('Splicing commands')
+		}
 		const spliceResult = await handleCommandSplicing({
 			commandWindows,
 			normalizedPath: paths.normalizedPath,
@@ -249,6 +280,7 @@ export async function processChapter(
 		})
 
 		// Step 6: Detect speech bounds
+		progress?.step('Detecting speech')
 		const speechBounds = await detectSpeechBounds(
 			spliceResult.sourcePath,
 			0,
@@ -272,6 +304,7 @@ export async function processChapter(
 		}
 
 		// Step 7: Apply speech padding
+		progress?.step('Trimming')
 		const paddedStart = clamp(
 			speechBounds.start - CONFIG.preSpeechPaddingSeconds,
 			0,
@@ -311,10 +344,12 @@ export async function processChapter(
 				logWritten = true
 			}
 			await safeUnlink(outputBasePath)
+			progress?.skip('Skipped (trimmed)')
 			return { status: 'skipped', skipReason: 'short-trimmed', logWritten }
 		}
 
 		// Step 9: Write final output
+		progress?.step('Writing output')
 		await extractChapterSegment({
 			inputPath: spliceResult.sourcePath,
 			outputPath: finalOutputPath,
@@ -323,6 +358,7 @@ export async function processChapter(
 		})
 
 		// Step 10: Verify no jarvis in final output
+		progress?.step('Verifying output')
 		let jarvisWarning: JarvisWarning | undefined
 		await extractTranscriptionAudio({
 			inputPath: finalOutputPath,
@@ -409,6 +445,7 @@ export async function processChapter(
 			processedDuration: trimmedDuration,
 		}
 
+		progress?.finish('Complete')
 		return {
 			status: 'processed',
 			jarvisWarning,

package/process-course/cli.ts

@@ -2,7 +2,7 @@ import path from 'node:path'
 import yargs from 'yargs/yargs'
 import { hideBin } from 'yargs/helpers'
 import type { Argv, Arguments } from 'yargs'
-import { getDefaultWhisperModelPath } from '../whispercpp-transcribe'
+import { getDefaultWhisperModelPath } from '../src/whispercpp-transcribe'
 import { DEFAULT_MIN_CHAPTER_SECONDS, TRANSCRIPTION_PHRASES } from './config'
 import { normalizeSkipPhrases } from './utils/transcript'
 import { parseChapterSelection } from './utils/chapter-selection'

package/process-course/edits/cli.ts

@@ -357,17 +357,26 @@ if (import.meta.main) {
 async function promptForEditsCommand(
 	prompter: Prompter,
 ): Promise<string[] | null> {
-	const selection = await prompter.select('Choose a command', [
+	const selection = await prompter.search('Choose a command (type to filter)', [
 		{
-			name: 'Edit a single video using transcript text edits',
+			name: 'edit-video - Edit a single video using transcript text edits',
 			value: 'edit-video',
+			description:
+				'edit-video --input <file> --transcript <json> --edited <txt>',
+			keywords: ['transcript', 'cuts', 'remove', 'trim'],
 		},
 		{
-			name: 'Combine two videos with speech-aligned padding',
+			name: 'combine-videos - Combine two videos with speech-aligned padding',
 			value: 'combine-videos',
+			description: 'combine-videos --video1 <file> --video2 <file>',
+			keywords: ['merge', 'join', 'splice', 'padding'],
 		},
-		{ name: 'Show help', value: 'help' },
-		{ name: 'Exit', value: 'exit' },
+		{
+			name: '--help - Show help',
+			value: 'help',
+			keywords: ['usage', '--help'],
+		},
+		{ name: 'exit - Exit', value: 'exit', keywords: ['quit', 'cancel'] },
 	])
 	if (selection === 'exit') {
 		return null

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

@@ -4,9 +4,9 @@ import { copyFile, mkdir, mkdtemp, rename, rm } from 'node:fs/promises'
 import {
 	detectSpeechBounds,
 	checkSegmentHasSpeech,
-} from '../../speech-detection'
+} from '../../src/speech-detection'
 import { extractChapterSegmentAccurate, concatSegments } from '../ffmpeg'
-import { clamp, getMediaDurationSeconds } from '../../utils'
+import { clamp, getMediaDurationSeconds } from '../../src/utils'
 import { EDIT_CONFIG } from '../config'
 import { editVideo } from './video-editor'
 import {

package/process-course/edits/edit-workspace.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { copyFile, mkdir } from 'node:fs/promises'
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 import {
 	buildTranscriptWordsWithIndices,
 	generateTranscriptJson,

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

@@ -5,7 +5,7 @@ import { mkdtemp, readdir, rm } from 'node:fs/promises'
 import yargs from 'yargs/yargs'
 import { hideBin } from 'yargs/helpers'
 import { extractTranscriptionAudio } from '../ffmpeg'
-import { transcribeAudio } from '../../whispercpp-transcribe'
+import { transcribeAudio } from '../../src/whispercpp-transcribe'
 import { scaleTranscriptSegments } from '../jarvis-commands/parser'
 import { EDIT_CONFIG } from '../config'
 import {
@@ -13,7 +13,7 @@ import {
 	generateTranscriptJson,
 	generateTranscriptText,
 } from './transcript-output'
-import { getMediaDurationSeconds } from '../../utils'
+import { getMediaDurationSeconds } from '../../src/utils'
 
 async function main() {
 	const argv = yargs(hideBin(process.argv))

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

@@ -6,7 +6,7 @@ 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 { clamp, getMediaDurationSeconds } from '../../src/utils'
 import type { TimeRange } from '../types'
 
 export type RemoveRangesOptions = {

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

@@ -1,6 +1,6 @@
 import { readAudioSamples } from '../ffmpeg'
 import { CONFIG, EDIT_CONFIG } from '../config'
-import { clamp } from '../../utils'
+import { clamp } from '../../src/utils'
 import { mergeTimeRanges } from '../utils/time-ranges'
 import { findLowestAmplitudeBoundaryProgressive } from '../utils/audio-analysis'
 import type { TimeRange } from '../types'

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

@@ -1,5 +1,5 @@
 import { test, expect } from 'bun:test'
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 import {
 	buildTranscriptWordsWithIndices,
 	generateTranscriptJson,

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

@@ -1,4 +1,4 @@
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 import { buildTranscriptWords } from '../jarvis-commands/parser'
 import type { TranscriptJson, TranscriptWordWithIndex } from './types'
 

package/process-course/ffmpeg.ts

@@ -2,7 +2,7 @@ import {
 	runCommand as runCommandBase,
 	runCommandBinary as runCommandBinaryBase,
 	formatSeconds,
-} from '../utils'
+} from '../src/utils'
 import { CONFIG, TRANSCRIPTION_SAMPLE_RATE } from './config'
 import { logCommand, logInfo, logWarn } from './logging'
 import type { Chapter, LoudnormAnalysis } from './types'

package/process-course/jarvis-commands/parser.test.ts

@@ -1,6 +1,6 @@
 import { test, expect } from 'bun:test'
 import { scaleTranscriptSegments, extractTranscriptCommands } from './parser'
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 
 // Factory functions for test data
 function createSegment(

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

@@ -1,4 +1,4 @@
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 import { CONFIG } from '../config'
 import type { TimeRange } from '../types'
 import { normalizeWords } from '../utils/transcript'

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

@@ -1,9 +1,9 @@
-import { clamp } from '../../utils'
-import { detectSpeechSegmentsWithVad } from '../../speech-detection'
+import { clamp } from '../../src/utils'
+import { detectSpeechSegmentsWithVad } from '../../src/speech-detection'
 import { readAudioSamples } from '../ffmpeg'
 import { CONFIG } from '../config'
 import { logInfo } from '../logging'
-import { formatSeconds } from '../../utils'
+import { formatSeconds } from '../../src/utils'
 import { mergeTimeRanges } from '../utils/time-ranges'
 import {
 	buildSilenceGapsFromSpeech,

package/process-course/logging.ts

@@ -1,4 +1,4 @@
-import { formatCommand } from '../utils'
+import { formatCommand } from '../src/utils'
 import { buildChapterLogPath } from './paths'
 
 type LogHook = () => void

package/process-course/summary.ts

@@ -1,5 +1,5 @@
 import path from 'node:path'
-import { formatSeconds } from '../utils'
+import { formatSeconds } from '../src/utils'
 import {
 	buildSummaryLogPath,
 	buildJarvisWarningLogPath,

package/process-course/utils/filename.ts

@@ -1,5 +1,5 @@
 import type { Chapter } from '../types'
-import { normalizeFilename, toKebabCase } from '../../utils'
+import { normalizeFilename, toKebabCase } from '../../src/utils'
 
 /**
  * Format a chapter into a filename-safe string.

package/process-course/utils/transcript.test.ts

@@ -7,7 +7,7 @@ import {
 	normalizeWords,
 } from './transcript'
 import { TRANSCRIPTION_PHRASES } from '../config'
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 
 function createPhrases(...phrases: string[]): string[] {
 	return phrases

package/process-course/utils/transcript.ts

@@ -1,4 +1,4 @@
-import type { TranscriptSegment } from '../../whispercpp-transcribe'
+import type { TranscriptSegment } from '../../src/whispercpp-transcribe'
 import type { TimeRange } from '../types'
 import { TRANSCRIPTION_PHRASES } from '../config'
 import { buildTranscriptWords } from '../jarvis-commands/parser'

package/{app-server.ts → src/app-server.ts}

@@ -1,9 +1,10 @@
-import './app/config/init-env.ts'
+import path from 'node:path'
+import '../app/config/init-env.ts'
 
 import getPort from 'get-port'
-import { getEnv } from './app/config/env.ts'
-import { createAppRouter } from './app/router.tsx'
-import { createBundlingRoutes } from './server/bundling.ts'
+import { getEnv } from '../app/config/env.ts'
+import { createAppRouter } from '../app/router.tsx'
+import { createBundlingRoutes } from '../server/bundling.ts'
 
 type AppServerOptions = {
 	host?: string
@@ -21,6 +22,7 @@ const SHORTCUT_COLORS: Record<string, string> = {
 	h: '\u001b[35m',
 }
 const ANSI_RESET = '\u001b[0m'
+const APP_ROOT = path.resolve(import.meta.dirname, '..')
 
 function colorizeShortcut(key: string) {
 	if (!COLOR_ENABLED) {
@@ -145,12 +147,12 @@ function setupShortcutHandling(options: {
 }
 
 function startServer(port: number, hostname: string) {
-	const router = createAppRouter(import.meta.dirname)
+	const router = createAppRouter(APP_ROOT)
 	return Bun.serve({
 		port,
 		hostname,
 		idleTimeout: 30,
-		routes: createBundlingRoutes(import.meta.dirname),
+		routes: createBundlingRoutes(APP_ROOT),
 		async fetch(request) {
 			try {
 				return await router.fetch(request)

package/{cli.ts → src/cli.ts}

@@ -4,20 +4,20 @@ import type { Arguments, CommandBuilder, CommandHandler } from 'yargs'
 import yargs from 'yargs/yargs'
 import { hideBin } from 'yargs/helpers'
 import { startAppServer } from './app-server'
-import { setLogHooks } from './process-course/logging'
-import { ensureFfmpegAvailable } from './process-course/ffmpeg'
+import { setLogHooks } from '../process-course/logging'
+import { ensureFfmpegAvailable } from '../process-course/ffmpeg'
 import {
 	VIDEO_EXTENSIONS,
 	normalizeProcessArgs,
 	configureProcessCommand,
-} from './process-course/cli'
+} from '../process-course/cli'
 import { runProcessCourse } from './process-course-video'
 import {
 	configureEditVideoCommand,
 	configureCombineVideosCommand,
 	createCombineVideosHandler,
 	createEditVideoHandler,
-} from './process-course/edits/cli'
+} from '../process-course/edits/cli'
 import { detectSpeechSegmentsForFile } from './speech-detection'
 import {
 	getDefaultWhisperModelPath,
@@ -34,7 +34,7 @@ import {
 	type PathPicker,
 	type Prompter,
 	withSpinner,
-} from './cli-ux'
+} from '../cli-ux'
 
 type CliUxContext = {
 	interactive: boolean
@@ -235,33 +235,49 @@ function createCliUxContext(): CliUxContext {
 }
 
 async function promptForCommand(prompter: Prompter): Promise<string[] | null> {
-	const selection = await prompter.select('Choose a command', [
+	const selection = await prompter.search('Choose a command (type to filter)', [
 		{
-			name: 'Process chapters into separate files',
+			name: 'process - Process chapters into separate files',
 			value: 'process',
+			description: 'process [input...]',
+			keywords: ['chapters', 'course', 'split', 'export'],
 		},
 		{
-			name: 'Edit a single video using transcript text edits',
+			name: 'edit - Edit a single video using transcript text edits',
 			value: 'edit',
+			description: 'edit --input <file> --transcript <json> --edited <txt>',
+			keywords: ['transcript', 'cuts', 'remove', 'trim'],
 		},
 		{
-			name: 'Combine two videos with speech-aligned padding',
+			name: 'combine - Combine two videos with speech-aligned padding',
 			value: 'combine',
+			description: 'combine --video1 <file> --video2 <file>',
+			keywords: ['merge', 'join', 'splice', 'padding'],
 		},
 		{
-			name: 'Start the web UI server',
+			name: 'app start - Start the web UI server',
 			value: 'app-start',
+			description: 'app start --port <number> --host <host>',
+			keywords: ['app', 'ui', 'server', 'web', 'dashboard'],
 		},
 		{
-			name: 'Transcribe a single audio/video file',
+			name: 'transcribe - Transcribe a single audio/video file',
 			value: 'transcribe',
+			description: 'transcribe [input]',
+			keywords: ['whisper', 'speech', 'audio', 'subtitles'],
 		},
 		{
-			name: 'Show detected speech segments for a file',
+			name: 'detect-speech - Show detected speech segments for a file',
 			value: 'detect-speech',
+			description: 'detect-speech [input]',
+			keywords: ['speech', 'vad', 'silence', 'segments'],
 		},
-		{ name: 'Show help', value: 'help' },
-		{ name: 'Exit', value: 'exit' },
+		{
+			name: '--help - Show help',
+			value: 'help',
+			keywords: ['usage', '--help'],
+		},
+		{ name: 'exit - Exit', value: 'exit', keywords: ['quit', 'cancel'] },
 	])
 	switch (selection) {
 		case 'exit':

package/{process-course-video.ts → src/process-course-video.ts}

@@ -1,25 +1,27 @@
 #!/usr/bin/env bun
 import path from 'node:path'
 import { mkdir } from 'node:fs/promises'
-import { ensureFfmpegAvailable, getChapters } from './process-course/ffmpeg'
-import { logInfo } from './process-course/logging'
-import { parseCliArgs, type CliArgs } from './process-course/cli'
-import { resolveChapterSelection } from './process-course/utils/chapter-selection'
-import { removeDirIfEmpty } from './process-course/utils/file-utils'
-import { writeJarvisLogs, writeSummaryLogs } from './process-course/summary'
+import { ensureFfmpegAvailable, getChapters } from '../process-course/ffmpeg'
+import { logInfo } from '../process-course/logging'
+import { parseCliArgs, type CliArgs } from '../process-course/cli'
+import { resolveChapterSelection } from '../process-course/utils/chapter-selection'
+import { removeDirIfEmpty } from '../process-course/utils/file-utils'
+import { writeJarvisLogs, writeSummaryLogs } from '../process-course/summary'
 import {
 	processChapter,
 	type ChapterProcessingOptions,
-} from './process-course/chapter-processor'
+	type ChapterProgressReporter,
+} from '../process-course/chapter-processor'
 import type {
 	JarvisEdit,
 	JarvisNote,
 	JarvisWarning,
 	ProcessedChapterInfo,
 	EditWorkspaceInfo,
-} from './process-course/types'
+} from '../process-course/types'
 import { formatSeconds } from './utils'
 import { checkSegmentHasSpeech } from './speech-detection'
+import { setActiveSpinnerText } from '../cli-ux'
 
 interface ProcessingSummary {
 	totalSelected: number
@@ -35,6 +37,137 @@ interface ProcessingSummary {
 
 export type ProcessCourseOptions = Omit<CliArgs, 'shouldExit'>
 
+const PROGRESS_BAR_WIDTH = 12
+
+type SpinnerProgressContext = {
+	fileIndex: number
+	fileCount: number
+	fileName: string
+	chapterCount: number
+}
+
+type ChapterProgressContext = {
+	chapterIndex: number
+	chapterTitle: string
+}
+
+function clampProgress(value: number) {
+	return Math.max(0, Math.min(1, value))
+}
+
+function formatPercent(value: number) {
+	return `${Math.round(clampProgress(value) * 100)}%`
+}
+
+function formatProgressBar(value: number, width = PROGRESS_BAR_WIDTH) {
+	const clamped = clampProgress(value)
+	const filled = Math.round(clamped * width)
+	return `[${'#'.repeat(filled)}${'-'.repeat(width - filled)}]`
+}
+
+function truncateLabel(value: string, maxLength: number) {
+	const trimmed = value.trim()
+	if (trimmed.length <= maxLength) {
+		return trimmed
+	}
+	return `${trimmed.slice(0, Math.max(0, maxLength - 3))}...`
+}
+
+function buildProgressText(params: {
+	fileIndex: number
+	fileCount: number
+	fileName: string
+	chapterIndex: number
+	chapterCount: number
+	chapterTitle: string
+	stepIndex: number
+	stepCount: number
+	stepLabel: string
+}) {
+	const chapterProgress =
+		params.stepCount > 0 ? params.stepIndex / params.stepCount : 0
+	const fileProgress =
+		params.chapterCount > 0
+			? (params.chapterIndex - 1 + chapterProgress) / params.chapterCount
+			: 1
+	const fileLabel =
+		params.fileCount > 1
+			? `File ${params.fileIndex}/${params.fileCount}`
+			: 'File'
+	const fileName = truncateLabel(params.fileName, 22)
+	const fileSegment = fileName ? `${fileLabel} ${fileName}` : fileLabel
+	const chapterLabel = `Chapter ${params.chapterIndex}/${params.chapterCount}`
+	const chapterTitle = truncateLabel(params.chapterTitle, 26)
+	const chapterSegment = chapterTitle
+		? `${chapterLabel} ${chapterTitle}`
+		: chapterLabel
+	const stepSegment = truncateLabel(params.stepLabel, 28) || 'Working'
+	return `Processing course | ${fileSegment} ${formatPercent(fileProgress)} ${formatProgressBar(fileProgress)} | ${chapterSegment} ${formatPercent(chapterProgress)} ${formatProgressBar(chapterProgress)} | ${stepSegment}`
+}
+
+function createSpinnerProgressReporter(context: SpinnerProgressContext) {
+	const chapterCount = Math.max(1, context.chapterCount)
+	return {
+		createChapterProgress({ chapterIndex, chapterTitle }: ChapterProgressContext) {
+			let stepIndex = 0
+			let stepCount = 1
+			let stepLabel = 'Starting'
+
+			const normalizeStepCount = (value: number) =>
+				Math.max(1, Math.round(value))
+
+			const update = () => {
+				setActiveSpinnerText(
+					buildProgressText({
+						fileIndex: context.fileIndex,
+						fileCount: context.fileCount,
+						fileName: context.fileName,
+						chapterIndex,
+						chapterCount,
+						chapterTitle,
+						stepIndex,
+						stepCount,
+						stepLabel,
+					}),
+				)
+			}
+
+			const progress: ChapterProgressReporter = {
+				start({ stepCount: initialCount, label }) {
+					stepCount = normalizeStepCount(initialCount)
+					stepIndex = 0
+					stepLabel = label ?? 'Starting'
+					update()
+				},
+				step(label) {
+					stepCount = normalizeStepCount(stepCount)
+					stepIndex = Math.min(stepIndex + 1, stepCount)
+					stepLabel = label
+					update()
+				},
+				setLabel(label) {
+					stepLabel = label
+					update()
+				},
+				finish(label) {
+					stepCount = normalizeStepCount(stepCount)
+					stepIndex = stepCount
+					stepLabel = label ?? 'Complete'
+					update()
+				},
+				skip(label) {
+					stepCount = normalizeStepCount(stepCount)
+					stepIndex = stepCount
+					stepLabel = label
+					update()
+				},
+			}
+
+			return progress
+		},
+	}
+}
+
 export async function runProcessCourse(options: ProcessCourseOptions) {
 	const {
 		inputPaths,
@@ -53,7 +186,7 @@ export async function runProcessCourse(options: ProcessCourseOptions) {
 	await ensureFfmpegAvailable()
 
 	// Process each input file in turn
-	for (const inputPath of inputPaths) {
+	for (const [fileIndex, inputPath] of inputPaths.entries()) {
 		// Determine output directory for this file
 		let fileOutputDir: string
 		if (outputDir) {
@@ -72,6 +205,8 @@ export async function runProcessCourse(options: ProcessCourseOptions) {
 		}
 
 		await processInputFile({
+			fileIndex: fileIndex + 1,
+			fileCount: inputPaths.length,
 			inputPath,
 			outputDir: fileOutputDir,
 			minChapterDurationSeconds,
@@ -97,19 +232,23 @@ export async function runProcessCourseCli(rawArgs?: string[]) {
 }
 
 async function processInputFile(options: {
+	fileIndex: number
+	fileCount: number
 	inputPath: string
 	outputDir: string
 	minChapterDurationSeconds: number
 	dryRun: boolean
 	keepIntermediates: boolean
 	writeLogs: boolean
-	chapterSelection: import('./process-course/types').ChapterSelection | null
+	chapterSelection: import('../process-course/types').ChapterSelection | null
 	enableTranscription: boolean
 	whisperModelPath: string
 	whisperLanguage: string
 	whisperBinaryPath: string | undefined
 }) {
 	const {
+		fileIndex,
+		fileCount,
 		inputPath,
 		outputDir,
 		minChapterDurationSeconds,
@@ -168,6 +307,13 @@ async function processInputFile(options: {
 		? chapters.filter((chapter) => chapterIndexes.includes(chapter.index))
 		: chapters
 
+	const progressReporter = createSpinnerProgressReporter({
+		fileIndex,
+		fileCount,
+		fileName: path.basename(inputPath),
+		chapterCount: selectedChapters.length,
+	})
+
 	const summary: ProcessingSummary = {
 		totalSelected: selectedChapters.length,
 		processed: 0,
@@ -203,7 +349,11 @@ async function processInputFile(options: {
 	const processedChaptersWithSpeech: ProcessedChapterInfo[] = []
 	let previousProcessedChapter: ProcessedChapterInfo | null = null
 
-	for (const chapter of selectedChapters) {
+	for (const [chapterOffset, chapter] of selectedChapters.entries()) {
+		const chapterProgress = progressReporter.createChapterProgress({
+			chapterIndex: chapterOffset + 1,
+			chapterTitle: chapter.title,
+		})
 		// Determine which chapter to combine with
 		// Always use the most recent processed chapter with speech (if any)
 		const chapterToCombineWith: ProcessedChapterInfo | null =
@@ -222,6 +372,7 @@ async function processInputFile(options: {
 		const result = await processChapter(chapter, {
 			...processingOptions,
 			previousProcessedChapter: chapterToCombineWith,
+			progress: chapterProgress,
 		})
 
 		// Update summary based on result

package/{speech-detection.ts → src/speech-detection.ts}

@@ -1,11 +1,11 @@
 import path from 'node:path'
 import { mkdir } from 'node:fs/promises'
 import * as ort from 'onnxruntime-node'
-import { readAudioSamples } from './process-course/ffmpeg'
-import { CONFIG } from './process-course/config'
+import { readAudioSamples } from '../process-course/ffmpeg'
+import { CONFIG } from '../process-course/config'
 import { formatSeconds, getMediaDurationSeconds } from './utils'
-import { speechFallback } from './process-course/utils/audio-analysis'
-import type { SpeechBounds } from './process-course/types'
+import { speechFallback } from '../process-course/utils/audio-analysis'
+import type { SpeechBounds } from '../process-course/types'
 
 export type VadConfig = {
 	vadWindowSamples: number

package/src/utils.test.ts

@@ -0,0 +1,71 @@
+import { test, expect } from 'bun:test'
+import {
+	clamp,
+	formatCommand,
+	formatSeconds,
+	normalizeFilename,
+	runCommand,
+	toKebabCase,
+} from './utils'
+
+test('formatCommand quotes parts that include spaces', () => {
+	expect(formatCommand(['ffmpeg', '-i', 'my file.mp4'])).toBe(
+		'ffmpeg -i "my file.mp4"',
+	)
+})
+
+test('formatCommand keeps parts without spaces unchanged', () => {
+	expect(formatCommand(['echo', 'hello'])).toBe('echo hello')
+})
+
+test('formatSeconds formats to two decimals with suffix', () => {
+	expect(formatSeconds(1)).toBe('1.00s')
+	expect(formatSeconds(1.234)).toBe('1.23s')
+})
+
+test('clamp keeps values within range', () => {
+	expect(clamp(5, 0, 10)).toBe(5)
+})
+
+test('clamp enforces minimum bound', () => {
+	expect(clamp(-2, 0, 10)).toBe(0)
+})
+
+test('clamp enforces maximum bound', () => {
+	expect(clamp(12, 0, 10)).toBe(10)
+})
+
+test('toKebabCase trims, lowercases, and removes punctuation', () => {
+	expect(toKebabCase('Hello, World!')).toBe('hello-world')
+})
+
+test('toKebabCase collapses repeated separators', () => {
+	expect(toKebabCase('  React   Hooks  ')).toBe('react-hooks')
+})
+
+test('toKebabCase returns untitled for empty input', () => {
+	expect(toKebabCase('   ')).toBe('untitled')
+})
+
+test('normalizeFilename converts number words and dots', () => {
+	expect(normalizeFilename('Lesson One point Five')).toBe('lesson 01.05')
+})
+
+test('normalizeFilename trims and lowercases', () => {
+	expect(normalizeFilename('  Intro  ')).toBe('intro')
+})
+
+test('runCommand captures stdout for successful command', async () => {
+	const result = await runCommand(['echo', 'hello'])
+	expect(result.exitCode).toBe(0)
+	expect(result.stdout.trim()).toBe('hello')
+})
+
+test('runCommand throws on non-zero exit without allowFailure', async () => {
+	await expect(runCommand(['false'])).rejects.toThrow('Command failed')
+})
+
+test('runCommand returns exit code when allowFailure is true', async () => {
+	const result = await runCommand(['false'], { allowFailure: true })
+	expect(result.exitCode).toBe(1)
+})