MLX Dialogue Transcriber

Python CLI that transcribes MP3 audio logs using Apple's MLX runtime and the mlx-community/whisper-large-v3-turbo-8bit model. It also performs speaker diarization so each utterance is tagged with a speaker label and minute/second level timestamps.

Requirements

• macOS with Apple Silicon (MLX runtime).
• Python 3.10+
• LM Studio or MLX runtime with Metal drivers (optional but speeds up inference).
• Hugging Face account/token with access to pyannote/speaker-diarization-3.1 (or whichever diarization pipeline you select).

Installation

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .

Set your Hugging Face token so pyannote.audio can download diarization weights:

export PYANNOTE_AUTH_TOKEN=<hf_token>

Usage

python -m dialogue_transcriber.cli \
  --audio /path/to/log.mp3 \
  --output outputs/log-transcript \
  --format markdown

Or run the helper script that installs dependencies, shows the CLI usage text, and transcribes the included test.mp3 sample:

bash scripts/setup_and_demo.sh

Key options:

• --model: auto-detects LM Studio downloads (preferring the turbo 8-bit build in /Users/user/.lmstudio/models/mlx-community/whisper-large-v3-turbo-8bit, then other 8-bit/fp16 variants, otherwise the HF repo). You can also pass a path to config.json; it will resolve to the containing directory automatically.
• --diarization-model: defaults to pyannote/speaker-diarization-3.1.
• --max-speakers: upper bound for diarization clustering.
• --hf-token: optional Hugging Face token (falls back to PYANNOTE_AUTH_TOKEN).
• --format: json, markdown, or text.
• --language: force Whisper decoding language (defaults to Russian; set explicitly to override).
• --beam-size: optional; leave unset for greedy decoding since MLX beam search is not implemented.
• --no-diarization: skip speaker diarization (faster, but every segment is labeled as SPEAKER_STT).

Outputs include a machine-readable JSON file (.json) and optionally either Markdown (.md) or text (.txt) with lines like:

00:00-00:17  SPEAKER_00  Hello! Thanks for joining the call.

Notes

• The first run downloads ~3 GB of weights into the HF cache.
• If you've already downloaded the weights via LM Studio (e.g., /Users/user/.lmstudio/models/mlx-community/whisper-large-v3-turbo-fp16), the CLI will pick them up automatically; otherwise pass your custom folder to --model.
• Speaker diarization relies on PyAnnote (PyTorch). When MPS is available, the CLI automatically runs the diarization pipeline on the Apple GPU for extra speed.
• To use LM Studio's MLX runtime, ensure it is open so Metal kernels stay warmed up.