From 21dd3b8315da5054c58ea1ae8f2ca58c717ff33f Mon Sep 17 00:00:00 2001
From: Jamie Pine <32987599+jamiepine@users.noreply.github.com>
Date: Mon, 20 Apr 2026 04:20:40 -0700
Subject: [PATCH] fix(backend): pin miniaudio in requirements-mlx.txt (#505)
 (#506)

mlx-audio's STT path imports miniaudio, but we install mlx-audio
--no-deps to dodge its transformers>=5.x pin. Nothing else pulls
miniaudio transitively, so fresh Apple Silicon installs fail to
transcribe with ModuleNotFoundError: miniaudio. Listed explicitly
and updated the stale comments in requirements-mlx.txt and
release.yml that claimed it came from other engines.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .github/workflows/release.yml |  6 ++++--
 backend/requirements-mlx.txt  | 13 ++++++++++---
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 25e5a943..edf29609 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -106,8 +106,10 @@ jobs:
           # fine on transformers 4.57.x in practice (verified in dev), so install
           # them --no-deps. mlx-audio's other runtime deps (huggingface_hub,
           # librosa, numpy, numba, pyloudnorm) are already in requirements.txt;
-          # the rest (sounddevice, miniaudio, protobuf, sentencepiece, pyyaml,
-          # jinja2) are pulled in by other engines.
+          # miniaudio is in requirements-mlx.txt (needed by mlx_audio.stt,
+          # not transitively pulled by anything else — see issue #505); the
+          # rest (sounddevice, protobuf, sentencepiece, pyyaml, jinja2) are
+          # pulled in by other engines.
           pip install --no-deps mlx-lm==0.31.1
           pip install --no-deps mlx-audio==0.4.1
 
diff --git a/backend/requirements-mlx.txt b/backend/requirements-mlx.txt
index fb99faeb..b1a82d5d 100644
--- a/backend/requirements-mlx.txt
+++ b/backend/requirements-mlx.txt
@@ -3,6 +3,12 @@
 
 mlx>=0.30.0
 
+# miniaudio is a runtime dep of mlx-audio's STT path (mlx_audio.stt).
+# mlx-audio itself is installed --no-deps (see comment below), so we
+# must list miniaudio explicitly here or transcription fails on fresh
+# M1 installs with `ModuleNotFoundError: miniaudio` (issue #505).
+miniaudio>=1.59
+
 # NOTE: mlx-audio is intentionally not listed here. From 0.3.1 onward it
 # declares `transformers==5.0.0rc3` / `>=5.0.0`, which conflicts with the
 # `transformers<=4.57.6` cap in requirements.txt and breaks CI's clean
@@ -10,6 +16,7 @@ mlx>=0.30.0
 # mlx_audio.stt.load) works fine on transformers 4.57.x in practice.
 #
 # Install it via `pip install --no-deps mlx-audio==0.4.1` after this file
-# (see .github/workflows/release.yml). All other mlx-audio runtime deps
-# (huggingface_hub, librosa, miniaudio, mlx-lm, numba, numpy, protobuf,
-# pyloudnorm, sounddevice, tqdm) are already in requirements.txt.
+# (see .github/workflows/release.yml). Most other mlx-audio runtime deps
+# (huggingface_hub, librosa, mlx-lm, numba, numpy, protobuf, pyloudnorm,
+# sounddevice, tqdm) are already in requirements.txt or pulled in by
+# other engines.