Mlx Whisper Long

mlx-whisper-long

Transcribe audio/video of any length on Apple Silicon using mlx_whisper.

When to use

• Transcribing files longer than ~10 minutes with mlx_whisper
• When mlx_whisper produces repeated/looping output on long files
• When you need SRT/VTT/TXT output with correct timestamps
• When you want resumable transcription (crash-safe)

How it works

Long audio causes mlx_whisper to hallucinate — the model gets stuck and repeats the same text. This skill solves it by:

1. Splitting the file into 20-minute segments (with 10s overlap at boundaries)
2. Transcribing each segment with hallucination-resistant parameters
3. Merging all segments into a single output file with correct timestamps

Intermediate files are kept on disk so a crashed run can be resumed.

Usage

Run the transcription script:

python scripts/transcribe_long.py <input_file> [options]

# Basic
python scripts/transcribe_long.py lecture.mp4

# With domain prompt (improves accuracy for technical content)
python scripts/transcribe_long.py lecture.mp4 --prompt "Medical lecture about cancer immunotherapy and CRISPR."

# Specify output directory and format
python scripts/transcribe_long.py lecture.mp4 --output-dir ~/Desktop --output-format all

# Force language (skip auto-detection)
python scripts/transcribe_long.py lecture.mp4 --language zh

# Pass any mlx_whisper argument directly
python scripts/transcribe_long.py lecture.mp4 -- --temperature 0 --beam-size 1

Key parameters

Output

• <filename>.srt and <filename>.txt (default) in the output directory
• Intermediate _segments/ directory is automatically deleted after successful completion
• Use --keep-segments to retain it for resuming a crashed run