feat: Add automatic CPU/float32 fallback for macOS and updated docs

README.md

@@ -201,6 +201,28 @@ python scripts/train_voxcpm_finetune.py \
 
 ## 📚 More Information
 
+### 🍎 macOS Support (Apple Silicon)
+
+To run VoxCPM on macOS (Apple Silicon), we recommend following setup, using `uv`.
+We use `uv` to strictly manage dependencies and avoid version conflicts (like incompatible `torch` and `torchcodec` versions) that can occur with standard `pip`.
+
+You also need to install `ffmpeg` for audio processing:
+
+```bash
+brew install ffmpeg
+```
+
+Then, set up the Python environment:
+
+```bash
+uv sync
+source .venv/bin/activate
+```
+
+VoxCPM will then automatically detect macOS and run in CPU mode with float32 precision to ensure stability.
+
+> Running on CPU might be significantly slower than on GPU (CUDA). This mode is intended for Mac compatibility.
+
 ###  🌟 Community Projects
 We're excited to see the VoxCPM community growing! Here are some amazing projects and features built by our community:
 - **[ComfyUI-VoxCPM](https://github.com/wildminder/ComfyUI-VoxCPM)** A VoxCPM extension for ComfyUI.

pyproject.toml

@@ -23,11 +23,14 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
 ]
-requires-python = ">=3.10"
+requires-python = ">=3.10,<3.14"
 dependencies = [
-    "torch>=2.5.0",
-    "torchaudio>=2.5.0",
-    "torchcodec",
+    "torch>=2.5.0,<2.6.0; sys_platform == 'darwin'",
+    "torch>=2.5.0; sys_platform != 'darwin'",
+    "torchaudio>=2.5.0,<2.6.0; sys_platform == 'darwin'",
+    "torchaudio>=2.5.0; sys_platform != 'darwin'",
+    "torchcodec==0.2.0; sys_platform == 'darwin'",
+    "torchcodec; sys_platform != 'darwin'",
     "transformers>=4.36.2",
     "einops",
     "gradio<6",

src/voxcpm/model/voxcpm.py

@@ -121,6 +121,12 @@ def __init__(
                 self.device = "mps"
             else:
                 self.device = "cpu"
+
+        # [Fix] Force CPU on macOS to avoid MPS issues with bfloat16/complex ops
+        if sys.platform == "darwin":
+            print("Detected macOS environment. Forcing 'cpu' and 'float32' to ensure stability.", file=sys.stderr)
+            self.device = "cpu"
+            self.config.dtype = "float32"
         print(f"Running on device: {self.device}, dtype: {self.config.dtype}", file=sys.stderr)
 
         # Text-Semantic LM