local-voice/docs/INSTALL_MACOS.md

Verified macOS installation

This procedure recreates the production configuration verified on an Apple Silicon MacBook Pro. It installs the software and model separately from the private authorized voice-asset archive.

Verified configuration

• Apple Silicon macOS
• Python 3.11
• CosyVoice3 0.1.0+metal
• 24 kHz Candle model: spensercai/CosyVoice3-0.5B-Candle
• ffmpeg and Whisper available on PATH
• Metal inference with full-precision weights

1. Install system prerequisites

Install Homebrew if it is not already present, then install:

brew install python@3.11 ffmpeg

Install the Whisper CLI into an isolated environment or with pipx. Confirm:

ffmpeg -version
whisper --help
python3.11 --version

2. Create the runtime

The default runtime is:

~/Library/Application Support/MPM Local Voice/runtime

Create its models, voices, jobs, and wheels directories. Create a Python 3.11 virtual environment beside or inside the runtime and activate it.

For a guided installation after downloading the model and private packages:

zsh scripts/install_macos.sh \
  --wheel /path/to/cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl \
  --assets /path/to/local-voice-authorized-assets-v0.1.0.tar.gz \
  --model-dir /path/to/CosyVoice3-0.5B-Candle

3. Install the tested Metal wheel

Copy this file from the private CW-026 recovery package:

cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl

Expected SHA-256:

c9c04352fe0e559b7b43129baae7035b25b48922e2296498efc53c39874d4e39

Install the wheel and runtime Python dependencies:

python -m pip install ./wheels/cosyvoice3-0.1.0+metal-cp310-abi3-macosx_11_0_arm64.whl
python -m pip install numpy==2.4.6 soundfile==0.14.0

4. Install the model

Download spensercai/CosyVoice3-0.5B-Candle from Hugging Face into:

runtime/models/CosyVoice3-0.5B-Candle

The private recovery manifest contains hashes for the production model files. At minimum the directory must contain:

• llm.safetensors
• flow.safetensors
• hift.safetensors
• campplus.onnx
• speech_tokenizer_v3.onnx
• config.json

The model is approximately 4.7 GB and is not bundled with the public plugin.

5. Install authorized voice assets

Extract the private archive so the runtime contains:

runtime/voices/donna
runtime/voices/chris-engineer
runtime/voices/grandpa-bomber
runtime/voices/ryan-pitch-meeting
runtime/voices/val-holiday

Do not publish or redistribute this archive.

6. Verify

From the plugin root:

python scripts/local_voice.py doctor --device metal
python scripts/verify_install.py --device metal

Every dependency, model, and voice profile must report PASS.

7. Install the plugin

For Claude CoWork, install local-voice-v0.1.0.plugin from the private CW-026 folder. For Codex, install from the MPM marketplace or use the same repository source containing .codex-plugin/plugin.json.

Start a new task after installation so the host loads the skill.

Restore policy

The public repository is authoritative for code and documentation. The private CW-026 folder is authoritative for the tested wheel, authorized voice assets, checksums, plugin packages, and recovery notes. The model is reproducible from its exact source and hashes; an optional offline model archive may be added later.