# Mlx Whisper Long

> 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.

- Skill: `1c7/mlx-whisper-long` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 1c7/mlx-whisper-long`
- Raw SKILL.md: https://api.skillmd.com/api/skills/1c7/mlx-whisper-long/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- License: MIT
- Author: 1c7 (https://skillmd.com/u/1c7)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/1c7/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:

```bash
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