{"id":24052,"library":"mlx-whisper","title":"mlx-whisper","description":"mlx-whisper is a fast implementation of OpenAI's Whisper model optimized for Apple Silicon (M1/M2/M3) using Apple's MLX framework. Version 0.4.3 supports transcription, language detection, and word-level timestamps with Hugging Face Hub integration. Updates are frequent, roughly weekly.","status":"active","version":"0.4.3","language":"python","source_language":"en","source_url":"https://github.com/ml-explore/mlx-examples","tags":["whisper","speech-to-text","apple-silicon","mlx","huggingface"],"install":[{"cmd":"pip install mlx-whisper","lang":"bash","label":"pip"}],"dependencies":[{"reason":"Required; MLX is the core machine learning framework.","package":"mlx","optional":false},{"reason":"Required for audio processing.","package":"numpy","optional":false},{"reason":"Required for downloading models from Hugging Face Hub.","package":"huggingface_hub","optional":false}],"imports":[{"note":"load_audio is now exposed at the top level; submodule import may break.","wrong":"from mlx_whisper.audio import load_audio","symbol":"load_audio","correct":"from mlx_whisper import load_audio"},{"note":"Standard API.","wrong":null,"symbol":"transcribe","correct":"from mlx_whisper import transcribe"}],"quickstart":{"code":"from mlx_whisper import transcribe\nresult = transcribe(\"audio.mp3\")\nprint(result[\"text\"])","lang":"python","description":"Transcribe an audio file (supported formats: .mp3, .wav, .m4a, .flac, .ogg)."},"warnings":[{"fix":"Run on an Apple Silicon machine (M1/M2/M3/M4) or use a different Whisper implementation.","message":"mlx-whisper only works on Apple Silicon (arm64). It will fail on Intel Macs or non-Apple hardware with cryptic import errors about missing MLX.","severity":"gotcha","affected_versions":"all"},{"fix":"Provide a valid file path (e.g., 'audio.mp3') or download the file first.","message":"The audio file path must be a local file or a URL. Some users incorrectly pass a bytes/ndarray object; transcribe expects a file path string.","severity":"gotcha","affected_versions":"all"},{"fix":"Update code to use the new keys. Old code is backward-compatible but you may want to use the streamlined result['text'].","message":"In version 0.4.0, the return type of transcribe() changed from a dict with key 'segments' to a more detailed dict with 'text', 'segments', 'language', etc. Old code accessing e.g. result['segments'][0]['text'] still works, but result['text'] is now available.","severity":"breaking","affected_versions":">=0.4.0"},{"fix":"Use `word_timestamps=True` instead of `group_segments=True`.","message":"The function `mlx_whisper.transcribe()` no longer accepts `group_segments=True` (removed in 0.3.0). Pass `word_timestamps=True` for word-level timestamps.","severity":"deprecated","affected_versions":">=0.3.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Install MLX with `pip install mlx` and ensure you are on Apple Silicon (e.g., M1, M2, M3).","cause":"MLX is not installed or running on non-Apple Silicon hardware.","error":"ModuleNotFoundError: No module named 'mlx'"},{"fix":"Ensure the file exists and is one of the supported formats: .mp3, .wav, .m4a, .flac, .ogg. Use a proper file path string.","cause":"The file may be corrupted, unsupported format, or path is incorrect.","error":"ValueError: Audio file '<path>' is not a valid audio file"},{"fix":"Re-download the model (delete ~/.cache/huggingface/hub/models--mlx-community--whisper-* and run again) or check the audio file.","cause":"The audio file might be empty or the model failed to load properly.","error":"mlx.core.index_error: Index 0 is out of bounds for axis 0 with size 0"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}