feat: add CW-026 Local Voice plugin
This commit is contained in:
Bryan Gilliom
@@ -0,0 +1,46 @@
|
||||
# Acceptance results
|
||||
|
||||
Fresh acceptance audio was generated on 2026-07-27 using Apple Silicon Metal,
|
||||
the production Candle model, the private authorized assets, and the unified
|
||||
renderer in Local Voice 0.1.0.
|
||||
|
||||
| Profile | Duration | Transcript coverage | Transcript precision | Click-risk seams |
|
||||
|---|---:|---:|---:|---:|
|
||||
| Donna | 17.49 s | 0.978 | 0.957 | 0 |
|
||||
| Chris Engineer | 14.73 s | 0.960 | 0.923 | 0 |
|
||||
| Grandpa Bomber | 21.79 s | 0.934 | 0.934 | 0 |
|
||||
| Val Holiday | 23.45 s | 0.964 | 0.946 | 0 |
|
||||
| Ryan Pitch Meeting | 16.62 s | 0.963 | 0.981 | 0 |
|
||||
|
||||
## What the suite verifies
|
||||
|
||||
- Every profile and both Ryan roles load from the private runtime.
|
||||
- Generated targets contain their expected beginning and final-word marker.
|
||||
- Final transcript coverage is at least 0.60.
|
||||
- Final transcript precision is at least 0.75, preventing sacrificial context
|
||||
from silently leaking into the finished audio.
|
||||
- Every join has a boundary step below the click-risk threshold.
|
||||
- Short frames remain at native tempo.
|
||||
- Val normalizes only sufficiently long substantive passages toward 170 WPM.
|
||||
- Chris uses 30-word safe blocks after a 42-word block proved vulnerable to
|
||||
model truncation.
|
||||
- Ryan uses fixed `Yes sir, I do`, `is tight`, and
|
||||
`super easy, barely an inconvenience / Oh really` assets in the acceptance
|
||||
dialogue.
|
||||
|
||||
## Human review
|
||||
|
||||
Objective acceptance cannot judge character similarity or comic timing.
|
||||
The packaged acceptance MP3s are retained for listening review. Future changes
|
||||
to reference audio, cadence thresholds, trimming, or asset selection should be
|
||||
compared against these files before release.
|
||||
|
||||
## Latest jobs
|
||||
|
||||
| Profile | Job ID |
|
||||
|---|---|
|
||||
| Donna | `acceptance-v2-donna` |
|
||||
| Chris Engineer | `acceptance-v6-chris-engineer` |
|
||||
| Grandpa Bomber | `acceptance-v7-grandpa-bomber` |
|
||||
| Val Holiday | `acceptance-v7-val-holiday` |
|
||||
| Ryan Pitch Meeting | `acceptance-v9-ryan-pitch-meeting` |
|
||||
@@ -0,0 +1,62 @@
|
||||
# Donna integration contract
|
||||
|
||||
Donna remains responsible for collecting organizational information, deciding
|
||||
priority, selecting a character, and writing the final canonical script. Local
|
||||
Voice is an optional audio dependency responsible for rendering and validating
|
||||
that script.
|
||||
|
||||
## Invocation
|
||||
|
||||
Donna supplies:
|
||||
|
||||
- voice profile ID;
|
||||
- canonical Markdown or Ryan-labelled dialogue;
|
||||
- absolute output path;
|
||||
- pronunciation overrides when needed;
|
||||
- optional delivery, role, signature-asset, and pause metadata.
|
||||
|
||||
Donna then asks Local Voice to:
|
||||
|
||||
1. run `doctor` if runtime health is unknown;
|
||||
2. build or validate the render plan;
|
||||
3. render with `--resume`;
|
||||
4. return the final audio and QA-report paths.
|
||||
|
||||
## Required behavior
|
||||
|
||||
- Do not send Markdown headings, numbered section titles, speaker labels, or
|
||||
stage directions as spoken text.
|
||||
- Keep greetings and closings as short standalone paragraphs so Local Voice can
|
||||
preserve native tempo.
|
||||
- Keep substantive paragraphs to complete sentence groups of roughly 20–42
|
||||
words unless a profile specifies otherwise.
|
||||
- Use canonical `text` for the written brief and `tts_text` only for local
|
||||
pronunciation corrections.
|
||||
- Do not silently fall back to ElevenLabs. If Local Voice fails, Donna should
|
||||
report the failure and apply the caller's configured fallback policy.
|
||||
- Attach or link the final audio alongside the full written organizational
|
||||
brief; the audio is a quick summary, not the sole record.
|
||||
|
||||
## Character mapping
|
||||
|
||||
| Donna character | Local Voice profile |
|
||||
|---|---|
|
||||
| Production Donna | `donna` |
|
||||
| Chris Engineer | `chris-engineer` |
|
||||
| Grandpa Bomber | `grandpa-bomber` |
|
||||
| Pitch Meeting | `ryan-pitch-meeting` |
|
||||
| Val Holiday | `val-holiday` |
|
||||
|
||||
## Example handoff
|
||||
|
||||
```json
|
||||
{
|
||||
"voice": "val-holiday",
|
||||
"script": "/absolute/path/val-brief.md",
|
||||
"output": "/absolute/path/val-brief.mp3",
|
||||
"fallback": "report-and-return-text"
|
||||
}
|
||||
```
|
||||
|
||||
Local Voice returns the final audio path, QA report path, duration, and
|
||||
segment-level completeness and cadence results.
|
||||
@@ -0,0 +1,132 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,31 @@
|
||||
# Recovery and private asset policy
|
||||
|
||||
CW-026 uses a split distribution:
|
||||
|
||||
- **Public Gitea:** redistributable source, profiles, schemas, tests, and docs.
|
||||
- **Private Google Drive:** authorized voice assets, the tested Metal wheel,
|
||||
installable plugin packages, checksums, and recovery manifests.
|
||||
- **External model source:** exact Candle model repository and verified hashes.
|
||||
|
||||
## Private recovery folder
|
||||
|
||||
`CW-026 — Local Voice`
|
||||
|
||||
https://drive.google.com/drive/folders/1bcgkABj-JGavyFHRqSj2gwZqhnPHBAhk
|
||||
|
||||
The private folder is visible only to authorized MPM staff. It is the recovery
|
||||
source of truth for the machine-specific configuration.
|
||||
|
||||
## Restore sequence
|
||||
|
||||
1. Restore the plugin source or installable package.
|
||||
2. Recreate the Python 3.11 environment.
|
||||
3. Install the tested platform wheel.
|
||||
4. Download and verify the exact model.
|
||||
5. Extract the authorized voice-assets archive into the runtime.
|
||||
6. Run `doctor`.
|
||||
7. Run the acceptance suite.
|
||||
8. Configure calling skills, such as Donna, to use the Local Voice dependency.
|
||||
|
||||
Never delete the working runtime during recovery preparation. Copy assets into
|
||||
the private archive and verify the archive before treating it as a backup.
|
||||
@@ -0,0 +1,52 @@
|
||||
# Windows and NVIDIA deployment notes
|
||||
|
||||
This path is a recommendation for the planned dedicated Windows/NVIDIA host.
|
||||
It has not yet passed the Local Voice acceptance suite and must be treated as
|
||||
provisional.
|
||||
|
||||
## Recommended host
|
||||
|
||||
- Windows 11
|
||||
- Current NVIDIA Studio or production driver
|
||||
- Python 3.11 x64
|
||||
- ffmpeg and Whisper available on `PATH`
|
||||
- Sufficient SSD space for the 4.7 GB model, jobs, and retained WAV files
|
||||
- NVIDIA GPU with supported CUDA capability and practical VRAM headroom
|
||||
|
||||
## Preferred deployment order
|
||||
|
||||
1. Start with native Windows and a CosyVoice3 wheel built for the installed CUDA
|
||||
runtime.
|
||||
2. If native dependency resolution is unreliable, use WSL2 with NVIDIA CUDA
|
||||
passthrough and the Linux CUDA build.
|
||||
3. Use `LOCAL_VOICE_RUNTIME` to point at a dedicated data directory, for example
|
||||
`D:\MPM-Local-Voice\runtime`.
|
||||
4. Copy the same private `voices` archive and model directory used on macOS.
|
||||
5. Run `doctor --device cuda`.
|
||||
6. Run the full acceptance suite before scheduling production briefings.
|
||||
|
||||
## Important differences
|
||||
|
||||
- The verified Metal wheel cannot run on Windows.
|
||||
- CUDA, driver, and wheel versions must agree.
|
||||
- Do not assume that a CUDA build exists merely because the NVIDIA driver is
|
||||
installed.
|
||||
- Keep ffmpeg path quoting and Windows long-path behavior in mind.
|
||||
- Compare transcript coverage, ending confidence, seam derivatives, duration,
|
||||
and subjective voice similarity against the macOS acceptance outputs.
|
||||
|
||||
## Fallback
|
||||
|
||||
CPU generation remains functionally possible but may be slower. It is suitable
|
||||
for overnight batches if CUDA setup is delayed, provided the acceptance suite
|
||||
passes on that host.
|
||||
|
||||
## Certification checklist
|
||||
|
||||
- [ ] `cosyvoice3`, NumPy, and SoundFile import
|
||||
- [ ] Candle model hashes match the recovery manifest
|
||||
- [ ] All authorized voice assets resolve
|
||||
- [ ] CUDA device loads successfully
|
||||
- [ ] Every acceptance output passes transcript QA
|
||||
- [ ] Ryan fixed assets and dialogue assembly are seamless
|
||||
- [ ] Five production briefs can complete inside the overnight window
|
||||
Reference in New Issue
Block a user