133 lines
3.3 KiB
Markdown
133 lines
3.3 KiB
Markdown
# 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.
|