# 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:

```bash
brew install python@3.11 ffmpeg
```

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

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

## 2. Create the runtime

The default runtime is:

```text
~/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:

```bash
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:

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

Expected SHA-256:

```text
c9c04352fe0e559b7b43129baae7035b25b48922e2296498efc53c39874d4e39
```

Install the wheel and runtime Python dependencies:

```bash
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:

```text
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:

```text
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:

```bash
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.