media-transcriber

Transcribe audio and video files to text and subtitles using pluggable AI backends, including local Whisper and the OpenAI Whisper API.

Quick Start

# Run directly with npx (no install)
npx media-transcriber doctor

# Or install globally
npm install -g media-transcriber

# Check your machine
media-transcriber doctor

# Transcribe a single file
media-transcriber transcribe ./meeting.mp4

# Transcribe a folder
media-transcriber transcribe ./data/input ./data/output

Requirements

• Node.js >= 18
• FFmpeg and ffprobe in PATH
  • Windows: winget install ffmpeg or scoop install ffmpeg
  • macOS: brew install ffmpeg
  • Linux: sudo apt install ffmpeg

Backend requirements:

• whisper-local: A local Whisper installation available on your system. This can be managed with uv, pip, or another Python environment setup.
• whisper-api: OpenAI API key (OPENAI_API_KEY env var or --api-key)

Usage

Transcribe

# Single file, output written next to the input file
media-transcriber transcribe ./recordings/interview.mp4

# Single file, explicit output folder
media-transcriber transcribe ./recordings/interview.mp4 ./transcripts

# Folder input
media-transcriber transcribe ./recordings ./transcripts

# Model and device
media-transcriber transcribe ./data/input ./data/output -m medium -d cpu

# OpenAI API backend
media-transcriber transcribe ./data/input ./data/output -b whisper-api --api-key <key>

# Split long files before transcription
media-transcriber transcribe ./data/input ./data/output --split-threshold 900

# Enable audio enhancement
media-transcriber transcribe ./data/input ./data/output --enhance-audio

# Keep temporary files in ./data/output/temp
media-transcriber transcribe ./data/input ./data/output --keep-temp

# Output only subtitles
media-transcriber transcribe ./data/input ./data/output -f srt

# JSON output for agents
media-transcriber transcribe ./data/input ./data/output --json

Doctor

Check system dependencies and backend availability:

media-transcriber doctor

Execution Options

All parameters are passed at execution time (stateless CLI).

Field	Type	Default	Description
input	string	required	Input file or folder
output	string	optional for files, required for folders	Output folder
backend	string	whisper-local	Transcription backend
whisperModel	string	large-v2	Model name
device	cuda or cpu	cuda	Processing device
maxDurationSeconds	number	1200	Split files longer than this threshold
enableAudioEnhancement	boolean	false	Enable enhancement filters
keepIntermediateFiles	boolean	false	Keep temp files with --keep-temp
tempFolder	string	<outputFolder>/temp	Temp working folder
outputFormats	txt, srt, or both	txt,srt	Output transcript formats
openaiApiKey	string	env/flag	API key for OpenAI backend

Commands

transcribe <input> [output]

• Accepts either a single file or a directory.
• For a single input file, [output] is optional. If omitted, output files are written next to the source file.
• For a directory input, [output] is required.

Options:

• -m, --model <name>: Whisper model name
• -d, --device <type>: Processing device, typically cuda or cpu
• -b, --backend <name>: Transcription backend
• --split-threshold <seconds>: Split files longer than this duration before transcription
• --enhance-audio: Apply audio enhancement before transcription
• --keep-temp: Keep intermediate files in the temp folder
• --api-key <key>: API key for API-based backends
• -f, --format <formats>: Comma-separated output formats, such as txt, srt, or txt,srt
• --json: Emit machine-readable output to stdout and NDJSON progress events to stderr

doctor

• Checks ffmpeg and ffprobe
• Shows system information
• Checks registered backends and reports availability
• Exits with a non-zero code when required dependencies are missing

AI Agent Integration

Structured JSON

media-transcriber transcribe ./data/input ./data/output --json 2>/dev/null

Progress Events (stderr)

In --json mode, NDJSON progress events are emitted to stderr.

Example:

media-transcriber transcribe ./data/input ./data/output --json 1>result.json

Exit Codes

Code	Meaning
0	Success (all files transcribed)
1	General error
2	Missing dependency
3	Configuration/argument error
4	No input files found
10	Partial success

Supported Formats

Input: .m4a, .mp3, .mp4, .mkv, .wav, .flac, .ogg, .webm

Output: .txt, .srt

Development

npm install
npm run dev
npm run typecheck
npm test
npm run build

Development workflow:

# Terminal 1: rebuild dist/ on changes
npm run dev

# Terminal 2: run the built CLI
node dist/index.js --help
node dist/index.js doctor
node dist/index.js transcribe ./test/input ./test/output

Available scripts:

npm run dev        # tsup --watch
npm run typecheck
npm test
npm run build

License

MIT