mlx-whisper-long

name	mlx-whisper-long
description	Transcribe audio/video files of any length using mlx_whisper on Apple Silicon. Automatically splits long files into segments to prevent hallucination/repetition loops, then merges results into a single SRT/VTT/TXT file. Use when transcribing podcasts, lectures, interviews, or any long-form media locally without API keys.
license	MIT
compatibility	Apple Silicon (macOS). Requires mlx-whisper (pip) and ffmpeg (brew).
metadata	{"author":"1c7","version":"1.0.0","tags":"whisper, mlx, transcription, srt, subtitles, speech-to-text"}

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

Parameter	Default	Notes
--model	whisper-large-v3-turbo	Use mlx-community/whisper-large-v3 for max accuracy
--output-dir	same as input file	Output directory
--output-format	srt,txt	comma-separated: srt, txt, vtt, tsv, json, or all
--prompt	none	Domain hint, improves proper noun accuracy
--language	auto-detect	e.g. zh, en, ja
--segment-seconds	1200	Segment length in seconds
--overlap-seconds	10	Overlap between segments to avoid boundary word loss
--keep-segments	off	Keep intermediate segment files (for resuming crashed runs)
--verbose	off	Enable debug logging

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