Skip to content

Local AI BGM and sound effects for Claude Code and any MCP client. Stable Audio 3 on Apple Silicon (MLX) and Windows NVIDIA GPUs (PyTorch). No cloud, no API key.

macOS: use an arm64 Python and report Rosetta clearly

Kanaf8fee7542184
diff --git a/README.ja.md b/README.ja.md
index 776bc26..c7cbf72 100644
--- a/README.ja.md
+++ b/README.ja.md
@@ -270,6 +270,12 @@ Mac ではモデルを読み込んでいる間、約 5〜7 GB のメモリを使
**Intel Mac と AMD GPU** には対応していません。
</details>
+<details>
+<summary><b>Apple Silicon の Mac なのに「Intel Macs are not supported」と出ます</b></summary>
+
+Rosetta で動く x86_64 版の Python(たとえば `/usr/local` にある Intel 版 Homebrew の Python)で環境が作られ、MLX がインストールされなかったのが原因です。現在の `install.sh` は uv に arm64 の Python を指定し、そうした `.venv` は作り直すので、`./install.sh` を実行し直せば直ります。`UV_PYTHON` を自分で設定している場合は arm64 版を指定してください:`UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh`
+</details>
+
<details>
<summary><b>歌入りの曲は作れますか?</b></summary>
diff --git a/README.md b/README.md
index 6adfb05..1b07b9f 100644
--- a/README.md
+++ b/README.md
@@ -263,6 +263,12 @@ The full guide is also sent to the client as the server's instructions.
**Intel Macs and AMD GPUs** are not supported.
</details>
+<details>
+<summary><b>"Intel Macs are not supported" on an Apple Silicon Mac?</b></summary>
+
+The environment was built with an x86_64 Python (for example an old Intel Homebrew under `/usr/local`) that runs under Rosetta, so MLX was skipped. `install.sh` now asks uv for an arm64 Python and recreates such a `.venv`, so re-running `./install.sh` fixes it. If you set `UV_PYTHON` yourself, point it at an arm64 build: `UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh`.
+</details>
+
<details>
<summary><b>Can it make songs with vocals?</b></summary>
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 7600a9d..9c0394f 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -270,6 +270,12 @@ Windows + RTX 3060 12 GB,medium 模型:
**Intel Mac 和 AMD 显卡**不支持。
</details>
+<details>
+<summary><b>明明是 Apple Silicon Mac,却提示「Intel Macs are not supported」?</b></summary>
+
+环境是用 Rosetta 下运行的 x86_64 版 Python(例如 `/usr/local` 里旧的 Intel 版 Homebrew)建的,所以没有装上 MLX。现在的 `install.sh` 会让 uv 使用 arm64 的 Python,并重建这样的 `.venv`,重新运行 `./install.sh` 即可。如果你自己设置了 `UV_PYTHON`,请改成 arm64 版:`UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh`。
+</details>
+
<details>
<summary><b>能生成带人声的歌吗?</b></summary>
diff --git a/install.sh b/install.sh
index 1996e6e..5890475 100755
--- a/install.sh
+++ b/install.sh
@@ -4,7 +4,8 @@
#
# 1. checks for uv (offers to install it) and ffmpeg
# 2. clones the official Stable Audio 3 runtime into vendor/ at a pinned commit
-# 3. creates .venv/ and installs dependencies (uv sync --extra mlx)
+# 3. creates .venv/ with a native arm64 Python and installs dependencies
+# (uv sync --extra mlx), then checks that mlx imports
# 4. downloads model weights from Hugging Face (medium: ~5.9 GB)
# 5. prints the command that registers the server with Claude Code
#
@@ -54,6 +55,10 @@ for m in ${MODEL//,/ }; do
done
# ── platform ─────────────────────────────────────────────────────────────────
+if [[ "$(uname -s)" == "Darwin" && "$(uname -m)" != "arm64" \
+ && "$(sysctl -n hw.optional.arm64 2>/dev/null || true)" == "1" ]]; then
+ die "this shell runs under Rosetta (x86_64) on an Apple Silicon Mac. Run the installer natively: arch -arm64 ./install.sh"
+fi
if [[ "$(uname -s)" != "Darwin" || "$(uname -m)" != "arm64" ]]; then
die "this installer supports Apple Silicon macOS (on Windows with an NVIDIA GPU use install.ps1; detected $(uname -s)/$(uname -m))."
fi
@@ -112,8 +117,36 @@ ok "$UPSTREAM_DIR @ ${UPSTREAM_COMMIT:0:7}"
# ── Python environment ───────────────────────────────────────────────────────
step "Installing Python dependencies into .venv"
-(cd "$REPO_DIR" && uv sync --extra mlx)
-ok ".venv ready"
+# Ask uv for an arm64 Python explicitly: otherwise it may pick an x86_64 one
+# (e.g. an old Intel Homebrew under /usr/local), which runs under Rosetta and
+# silently skips mlx. A UV_PYTHON set by the user wins.
+if [[ -n "${UV_PYTHON:-}" ]]; then
+ (cd "$REPO_DIR" && uv sync --extra mlx)
+else
+ if [[ -e "$REPO_DIR/.venv" ]] \
+ && [[ "$("$REPO_DIR/.venv/bin/python" -c 'import platform; print(platform.machine())' 2>/dev/null || true)" != "arm64" ]]; then
+ warn "the existing .venv is not a native arm64 Python environment; recreating it."
+ rm -rf "$REPO_DIR/.venv"
+ fi
+ PY_VERSION="$(tr -d '[:space:]' < "$REPO_DIR/.python-version" 2>/dev/null || true)"
+ (cd "$REPO_DIR" && uv sync --extra mlx --python "cpython-${PY_VERSION:-3.11}-macos-aarch64")
+fi
+VENV_PY="$REPO_DIR/.venv/bin/python"
+VENV_ARCH="$("$VENV_PY" -c 'import platform; print(platform.machine())' 2>/dev/null || true)"
+if [[ "$VENV_ARCH" != "arm64" ]]; then
+ printf '%serror%s: .venv uses an %s Python (%s), but MLX needs a native arm64 Python.\n' \
+ "$R" "$N" "${VENV_ARCH:-unknown}" "$("$VENV_PY" -c 'import sys; print(sys.base_prefix)' 2>/dev/null || echo "$VENV_PY")" >&2
+ if [[ -n "${UV_PYTHON:-}" ]]; then
+ printf ' UV_PYTHON=%s selects it. Unset UV_PYTHON (or set it to cpython-3.11-macos-aarch64)\n' "$UV_PYTHON" >&2
+ printf ' and re-run ./install.sh.\n' >&2
+ else
+ printf ' Re-run with an arm64 Python: UV_PYTHON=cpython-3.11-macos-aarch64 ./install.sh\n' >&2
+ fi
+ exit 1
+fi
+"$VENV_PY" -c 'import mlx.core' 2>/dev/null \
+ || die "mlx failed to import in .venv. Remove .venv and re-run ./install.sh."
+ok ".venv ready (arm64, mlx)"
# ── weights ──────────────────────────────────────────────────────────────────
if [[ "$SKIP_WEIGHTS" -eq 1 ]]; then
diff --git a/src/audio_studio_mcp/backends/__init__.py b/src/audio_studio_mcp/backends/__init__.py
index c7d3f8f..f3d78f7 100644
--- a/src/audio_studio_mcp/backends/__init__.py
+++ b/src/audio_studio_mcp/backends/__init__.py
@@ -8,6 +8,8 @@ from __future__ import annotations
import os
import platform
+import subprocess
+import sys
from .base import Backend, GenerationRequest, GenerationResult
@@ -16,11 +18,27 @@ __all__ = ["Backend", "GenerationRequest", "GenerationResult", "create_backend",
BACKENDS = ("sa3-mlx", "sa3-torch")
+def _running_under_rosetta() -> bool:
+ """True when this (x86_64) process is translated by Rosetta 2 on an Apple Silicon Mac."""
+ try:
+ out = subprocess.run(["/usr/sbin/sysctl", "-n", "sysctl.proc_translated"],
+ capture_output=True, text=True, timeout=5)
+ except (OSError, subprocess.SubprocessError):
+ return False
+ return out.stdout.strip() == "1"
+
+
def resolve_backend_name(name: str | None = None) -> str:
name = (name or os.environ.get("AUDIO_STUDIO_BACKEND") or "auto").strip().lower()
if name == "auto":
if platform.system() == "Darwin" and platform.machine() == "arm64":
return "sa3-mlx"
+ if platform.system() == "Darwin" and _running_under_rosetta():
+ raise RuntimeError(
+ f"this Python ({sys.executable}) is an x86_64 build running under Rosetta on an "
+ "Apple Silicon Mac, so MLX is not available. Recreate the environment with an arm64 "
+ "Python: re-run ./install.sh (it picks one; unset UV_PYTHON if you set it to an x86_64 "
+ "Python), or run: uv sync --extra mlx --python cpython-3.11-macos-aarch64")
if platform.system() == "Darwin":
raise RuntimeError("Intel Macs are not supported; Audio Studio MCP needs Apple Silicon "
"(sa3-mlx) or an NVIDIA GPU (sa3-torch).")
diff --git a/tests/test_backends.py b/tests/test_backends.py
new file mode 100644
index 0000000..4191763
--- /dev/null
+++ b/tests/test_backends.py
@@ -0,0 +1,85 @@
+"""resolve_backend_name(): platform detection, including x86_64 Python under Rosetta."""
+import subprocess
+
+import pytest
+
+from audio_studio_mcp import backends
+
+
+def mac(monkeypatch):
+ """Pretend to run on macOS with the given machine and sysctl.proc_translated output."""
+ monkeypatch.delenv("AUDIO_STUDIO_BACKEND", raising=False)
+ calls = []
+
+ def setup(machine, translated=None, system="Darwin"):
+ monkeypatch.setattr(backends.platform, "system", lambda: system)
+ monkeypatch.setattr(backends.platform, "machine", lambda: machine)
+
+ def run(cmd, **kwargs):
+ calls.append(cmd)
+ if translated is None: # Intel Macs have no sysctl.proc_translated
+ return subprocess.CompletedProcess(cmd, 1, "", "unknown oid 'sysctl.proc_translated'")
+ return subprocess.CompletedProcess(cmd, 0, f"{translated}\n", "")
+
+ monkeypatch.setattr(backends.subprocess, "run", run)
+ return calls
+
+ return setup
+
+
+def test_apple_silicon_native_is_mlx(mac):
+ calls = mac("arm64")
+ assert backends.resolve_backend_name() == "sa3-mlx"
+ assert calls == []
+
+
+def test_x86_python_under_rosetta(mac):
+ calls = mac("x86_64", translated=1)
+ with pytest.raises(RuntimeError, match="Rosetta") as exc:
+ backends.resolve_backend_name()
+ assert "Intel Macs" not in str(exc.value)
+ assert "cpython-3.11-macos-aarch64" in str(exc.value)
+ assert calls == [["/usr/sbin/sysctl", "-n", "sysctl.proc_translated"]]
+
+
+def test_real_intel_mac(mac):
+ mac("x86_64", translated=None)
+ with pytest.raises(RuntimeError, match="Intel Macs are not supported"):
+ backends.resolve_backend_name()
+
+
+def test_native_x86_process_on_intel_mac(mac):
+ mac("x86_64", translated=0)
+ with pytest.raises(RuntimeError, match="Intel Macs are not supported"):
+ backends.resolve_backend_name()
+
+
+def test_sysctl_missing(mac, monkeypatch):
+ mac("x86_64")
+
+ def run(cmd, **kwargs):
+ raise FileNotFoundError(cmd[0])
+
+ monkeypatch.setattr(backends.subprocess, "run", run)
+ with pytest.raises(RuntimeError, match="Intel Macs are not supported"):
+ backends.resolve_backend_name()
+
+
[email protected]("system", ["Windows", "Linux"])
+def test_other_platforms_are_torch(mac, system):
+ calls = mac("AMD64", system=system)
+ assert backends.resolve_backend_name() == "sa3-torch"
+ assert calls == []
+
+
+def test_explicit_backend_skips_detection(mac):
+ calls = mac("x86_64", translated=1)
+ assert backends.resolve_backend_name("sa3-torch") == "sa3-torch"
+ assert calls == []
+
+
+def test_unknown_backend(mac):
+ mac("arm64")
+ with pytest.raises(RuntimeError, match="unknown AUDIO_STUDIO_BACKEND"):
+ backends.resolve_backend_name("cuda")