v0.2.0: What's new (Kokoro Lite how-to, Lite vs Drama 3 table, fixes) near the top; Docker 0.2.0

Lite installs for DGX Spark and Mac, Docker VOICE_ENGINE=lite / both, the Full/Lite toggle, trade-offs, the Kokoro Lite vs Drama 3 (4-bit) table and the fixes since v0.1.0. The DGX Spark Drama 3 build now has TensorFold 1.1.4's silence guard flags.

README.md

@@ -25,6 +25,76 @@ Fourteen named voices for [Fish Audio Drama 3](https://huggingface.co/fishaudio/
 audio/visual agent in [drowzeys/keys-ghost-machine-audio-visual-agent](https://github.com/drowzeys/keys-ghost-machine-audio-visual-agent).
 Vesper is Boo's default.
 
+## What's new in v0.2.0
+
+**Kokoro Lite, a second voice for smaller machines.** [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M)
+(hexgrad, Apache-2.0) can now speak for Boo instead of Drama 3, or beside it with a switch in the page. It is for
+memory-constrained hardware: a DGX Spark that shares its memory with other work, or a Mac at the low end of the
+[requirements](#requirements). Everything else (Bolt, Cosmos3-Edge, Parakeet, Eyes of Kai, Hermes) stays the same.
+
+- **Install Lite, DGX Spark** (about 48 GB free memory):
+  `curl -fsSL https://raw.githubusercontent.com/drowzeys/keys-ghost-machine-audio-visual-agent/main/install.sh | bash -s -- --voice lite`
+- **Install Lite, Mac** (Apple silicon, macOS 26+; 96 GB comfortable, 64 GB tight): the same command,
+  `curl -fsSL https://raw.githubusercontent.com/drowzeys/keys-ghost-machine-audio-visual-agent/main/install.sh | bash -s -- --voice lite`
+- **Docker, Lite** (DGX Spark, no Drama 3 mount needed):
+  ```sh
+  docker run --gpus all --rm -p 8095:8095 -e VOICE_ENGINE=lite -e KAI=1 \
+    -v ~/keys-ghost-machine/models/NVIDIA-Nemotron-3.5-Bolt-74B-A9B-24GB:/models/bolt \
+    -v ~/keys-ghost-machine/models/cosmos3-tf:/models/cosmos3 -v ~/models/hf-cache:/models/hf-cache \
+    ghcr.io/drowzeys/keys-ghost-machine-audio-visual-agent:0.2.0
+  ```
+- **Both, with a Full/Lite toggle:** install with `--voice both` (or `-e VOICE_ENGINE=both` in Docker, with the
+  Drama 3 mount) and the page shows a **Full / Lite** switch per conversation; the voice list follows the engine.
+  On an existing install, `kgm voice full|lite|both` switches. Pick a Kokoro voice in the page's Voice list
+  (`bf_emma` by default, `af_heart` is Kokoro's best rated) or set `KOKORO_VOICE=af_heart` in Docker.
+- **Trade-off:** on a DGX Spark Lite answers in about 0.33–0.40 s voice to voice (Full 0.55–0.77 s) and uses about
+  40 GB less memory. On a Mac it is about as fast as Full and saves about 9 GB. Lite speaks English only in Boo and
+  has no voice cloning, emotion control or the 14 Drama 3 voices.
+
+**Kokoro Lite vs Drama 3 (4-bit)**
+
+| | Kokoro Lite | Drama 3 4-bit (NVFP4) |
+|---|---|---|
+| Model | 82M parameters, ~330 MB | Billions of parameters, 4-bit NVFP4 |
+| Voice-engine memory: DGX Spark | ~3.5 GB | ~42 GB |
+| Voice-engine memory: Mac | ~0.8 GB | ~10 GB |
+| Voice starts: Spark | 33–40 ms | 112–121 ms |
+| Voice starts: Mac | 51–54 ms | ~60 ms |
+| Voice to voice: Spark | 0.33–0.40 s | 0.55–0.77 s |
+| Voice to voice: Mac | 0.49–0.64 s | 0.43–0.61 s |
+| Naturalness (UTMOS) | 4.35 (bf_emma) – 4.52 (af_heart) | 4.53 (Vesper) |
+| Voices | 54 built in | 14 custom, incl. Vesper |
+| Voice cloning | No | Yes |
+| Emotion/style control | No | Yes |
+| Long-line stalls | None | Occasional; fixed by the silence guard + resume in v0.2.0 |
+| Streaming | Whole sentence (<0.13 s) | Streams within a sentence |
+| Languages | EN, ES, FR, IT, PT, HI, JA, ZH | Wider, incl. German |
+| Licence | Apache-2.0 | Fish Audio Community License (hosted commercial use needs a Fish licence) |
+
+Spark: Lite is twice as fast and frees ~40 GB. Mac: same speed, so run `both` and keep Vesper with a Lite toggle.
+Choose Drama for a signature voice, cloning, emotion or German; choose Kokoro for small or shared hardware, an Apache
+licence or the lowest delay.
+
+**Fixes**
+
+- **Drama 3 long-line stalls:** a long reply that went quiet after its first sentence (on about 1 in 5 paragraph-length
+  lines) is now caught. The DGX Spark's Drama 3 build gains TensorFold 1.1.4's silence guard (new in the v0.2.0
+  Linux archive and the Docker image), the Mac build already had it, and Boo itself drops a stalled take's quiet tail
+  and asks for the unspoken rest.
+- **Never deaf after a fast short reply:** a quick reply such as "I'm on it." could leave Boo marked as still
+  speaking, and the session stopped listening. Fixed (64 of 64 turns heard in testing).
+- **Drama 3 "speech output capacity is full" (503):** the keep-warm loop no longer outlives its page or a stopped
+  microphone (it stops on disconnect, after 2 s without audio and after 60 s), warms with one "Mm." at a time and never
+  while anything is being said; a refused line is asked again for up to `retry_s` (6 s) instead of being lost; a
+  stopped turn frees its speech slot at once.
+- **Bolt repetition loops:** a reply that starts repeating a sentence it already said ends there, unsaid.
+- **Interrupted replies** stopped before their first word no longer leave "(interrupted)" in the history for the
+  brain to copy.
+- The reference Mac now runs `voice_engine: both`, with the Full/Lite toggle tested live.
+
+Builds: [v0.2.0 release](https://github.com/drowzeys/keys-ghost-machine-audio-visual-agent/releases/tag/v0.2.0) ·
+`docker pull ghcr.io/drowzeys/keys-ghost-machine-audio-visual-agent:0.2.0`
+
 ## Requirements
 
 Drama 3 served by TensorFold with named voices (`--voices`): about 21 GB of weights (the
@@ -32,7 +102,8 @@ Drama 3 served by TensorFold with named voices (`--voices`): about 21 GB of weig
 silicon (macOS 26, Metal) or about 21 GB on an NVIDIA DGX Spark (CUDA 13). The full Boo stack needs about 79 GB on a Mac
 (96 GB minimum, 128 GB or more recommended) or about 61 GB on a DGX Spark; see the GitHub README. Software: TensorFold
 1.1.4 (the prebuilt builds in the GitHub release add NVFP4 pruned Drama 3, the voice-prefix cache and Cosmos3-Edge; the
-DGX Spark's Drama 3 runs on plotarmordev's NVFP4 fork, because stock 1.1.4 refuses the pruned checkpoint).
+DGX Spark's Drama 3 runs on plotarmordev's NVFP4 fork, because stock 1.1.4 refuses the pruned checkpoint; since v0.2.0
+it also has 1.1.4's silence guard flags).
 
 **Full or Lite.** Boo's optional lite voice, [Kokoro-82M](https://huggingface.co/hexgrad/Kokoro-82M) (hexgrad,
 Apache-2.0), replaces Drama 3; everything else is the same.
@@ -72,8 +143,8 @@ curl -fsSL https://raw.githubusercontent.com/drowzeys/keys-ghost-machine-audio-v
 curl -fsSL https://raw.githubusercontent.com/drowzeys/keys-ghost-machine-audio-visual-agent/main/install.sh | bash -s -- --voice lite
 ```
 
-Docker on a DGX Spark: `-e VOICE_ENGINE=lite` and no Drama 3 mount, with an image built from the current repository (the
-published 0.1.0 image has the full voice only). `--voice both` installs both with a Full/Lite switch in the page; `kgm
+Docker on a DGX Spark: `-e VOICE_ENGINE=lite` and no Drama 3 mount, with
+`ghcr.io/drowzeys/keys-ghost-machine-audio-visual-agent:0.2.0` (or `both` for the Full/Lite switch). `--voice both` installs both with a Full/Lite switch in the page; `kgm
 voice full|lite|both` switches later. Settings, the Docker alternative and uninstalling are in the
 [One-shot install](https://github.com/drowzeys/keys-ghost-machine-audio-visual-agent#one-shot-install) section of the
 GitHub README.
@@ -124,7 +195,7 @@ Boo's optional lite voice runs [Kokoro-82M](https://huggingface.co/hexgrad/Kokor
 
 | | DGX Spark, lite | DGX Spark, full | Mac, lite | Mac, full |
 |---|---|---|---|---|
-| Voice-to-voice, median | **0.33 s** | 0.55–0.77 s | 0.56–0.64 s | 0.47–0.60 s |
+| Voice-to-voice, median | **0.33–0.40 s** | 0.55–0.77 s | 0.49–0.64 s | 0.47–0.60 s |
 | Voice engine memory in use | **≈ 3.5 GB** | ≈ 42 GB | **≈ 0.7 GB** | ≈ 10 GB |
 | Whole stack in use | **≈ 62 GB** | ≈ 101 GB | **≈ 55 GB** | ≈ 64 GB |
 
@@ -162,8 +233,8 @@ curl -s http://127.0.0.1:8098/v1/audio/speech -H 'Content-Type: application/json
 ```
 
 Drama 3 sometimes goes quiet after the first sentence of a long line (about 1 in 5 paragraphs, the same input every
-time; [TensorFold#1275](https://github.com/ashhart/TensorFold/issues/1275)). On TensorFold 1.1.4 add its silence guard to
-`serve`: `--silence-floor-dbfs=-30 --silence-seconds=4 --silence-mid-s=2 --silence-mid-min-voiced-s=1
+time; [TensorFold#1275](https://github.com/ashhart/TensorFold/issues/1275)). On TensorFold 1.1.4 (and the v0.2.0 DGX
+Spark build) add its silence guard to `serve`: `--silence-floor-dbfs=-30 --silence-seconds=4 --silence-mid-s=2 --silence-mid-min-voiced-s=1
 --silence-redraws=3 --silence-redraw-budget-s=90`. Whole replies are redrawn; a stream ends at the silence instead, so
 a streaming client should ask again for the unspoken text, as Boo does.