@gobing-ai/knowledge-kit 0.0.35 → 0.0.36

package/plugins/generations/voice-gen/package.json

@@ -15,6 +15,6 @@
         "zod": "4.4.3"
     },
     "devDependencies": {
-        "@types/bun": "1.3.14"
+        "@types/bun": "1.4.3"
     }
 }

package/plugins/generations/voxcpm-tts/README.md

@@ -0,0 +1,72 @@
+# voxcpm-tts
+
+Standalone VoxCPM voice generator plugin for [knowledge-kit](../../../README.md). A TypeScript
+generator that reuses **voice-gen's** pipeline (VoiceScript parsing, gaps, speed, WAV
+concatenation, QC, optional MP3) behind the existing `VoiceboxClient` contract, backed by a
+private **uv-managed Python worker** that runs `voxcpm==2.0.3` (ADR-036). The default daily
+drivers are unchanged: opt in with `vdriver: voxcpm` (wired by task 0257).
+
+`vendors/VoxCPM` is reference-only. No import, subprocess, dependency, cache, profile or model
+path in this plugin may resolve into `vendors/` — every configured path is canonicalized and
+refused, including symlinks and the Hugging Face cache tiers.
+
+## Requirements
+
+- `uv` on `PATH` (the worker is spawned as `uv run --project <plugin-root> --locked --no-dev`).
+- Python 3.12 (the frozen interpreter; `uv` provisions it from the lock).
+- `ffmpeg`/`ffprobe` only when `VOICE_GEN_MP3` requests an MP3 sibling.
+
+## Layout
+
+| Path | Purpose |
+| --- | --- |
+| `plugin.json` | `kk` manifest (`kind: generator`, entry `./src/index.ts` → bundled `./dist/index.js`) |
+| `src/index.ts` | `main(--in/--out)` entry; injects the adapter into `processGeneratorIO` and closes it in `finally` |
+| `src/voxcpm-client.ts` | registry/control/path validation + the bounded NDJSON worker adapter |
+| `python/worker.py` | private NDJSON worker: health/render, one model load per invocation |
+| `pyproject.toml` / `uv.lock` | independent uv project pinning `voxcpm==2.0.3` on Python 3.12 |
+| `profiles.json` | frozen profile registry (`profiles` array; `robin-news` instruct profile) |
+
+## Setup
+
+```bash
+uv lock --project plugins/generations/voxcpm-tts        # regenerate after editing pyproject.toml
+uv run --project plugins/generations/voxcpm-tts --locked --no-dev python plugins/generations/voxcpm-tts/python/worker.py
+```
+
+Step 0 (before live use) is the installed-import/API probe: confirm the locked `voxcpm==2.0.3`
+imports and exposes the expected signature. Source inspection does not prove hardware viability;
+that evidence belongs to task 0258.
+
+## Configuration (environment)
+
+| Var | Default | Notes |
+| --- | --- | --- |
+| `VOXCPM_MODEL` | `openbmb/VoxCPM2` | Hub id or a local snapshot directory. Hub models use the normal external cache; local paths pass canonical vendor exclusion |
+| `VOXCPM_DEVICE` | `auto` | `auto`/`cpu`/`cuda`/`mps`; an unavailable **requested** device fails |
+| `VOXCPM_PROFILES_PATH` | `<plugin-root>/profiles.json` | Profile registry |
+| `VOICEBOX_TIMEOUT_MS` | `600000` | Worker startup bound (shared with voice-gen) |
+| `VOICE_GEN_MAX_RUN_MS` | unset | Positive value bounds the whole invocation (startup + every render) |
+| `VOICE_GEN_MP3` | off | Request an MP3 sibling via ffmpeg |
+| `VOICE_GEN_FAIL_ON_QC` | off | Fail generation when the QC audit fails |
+
+## Profiles
+
+```json
+{ "profiles": [ { "id": "robin-news", "name": "robin-news", "mode": "instruct", "instruct": "清晰、自然、沉稳的中文新闻播报，语速适中。" } ] }
+```
+
+- `instruct`: needs a nonempty `instruct`; a per-request `instruct` overrides it.
+- `reference`: needs `reference_wav_path`.
+- `continuation`: needs `prompt_wav_path` + `prompt_text` together.
+- Relative assets resolve against the registry directory; serialized OmniVoice prompts, duplicate
+  ids/names, mixed mode fields and vendor paths are refused.
+
+## Control policy
+
+`normalize` maps directly; an explicit `seed` calls `torch.manual_seed` before synthesis (the
+2.0.3 API has no `seed`/`instruct` keyword); `language` is automatic multilingual inference with
+an advisory diagnostic; `max_chunk_chars`/`crossfade_ms` are advisory (one warning per invocation)
+— the shared VoiceScript segmentation remains the request boundary. A per-request `engine`,
+`personality=true` or an active `effects_chain` is rejected. Speed stays in shared postprocessing.
+Transcription is omitted, so ASR-dependent QC is reported unavailable (not passing evidence).