live: heartbeat sync 2026-10-18T18:51:41-07:00 (Refs #11)
This commit is contained in:
Frank committed
1 parent
7de07ee35c
commit
0ee08bc368
11 files changed
+201
-209
No files matched your search
@@ -1,125 +1,81 @@
|
||||
---
|
||||
name: frank-tts-add-cloned-voice
|
||||
description: "Add or repair a cloned voice on the dank fleet: /home/dank/voices/<name> pack, name rules, boot-warm registration, and the under-a-second proof"
|
||||
description: "Add or repair a cloned voice on the dank fleet: pack builder, the reference.wav contract, the boot warm hook (argv-cap and env-quote laws), and how to prove a voice really answers."
|
||||
---
|
||||
|
||||
Use for "give frank-tts a new voice", "voice X is missing/unknown", or "the first
|
||||
request of the day takes 5 s". Runbook of record: vault pages [[Frank TTS]] (voice
|
||||
packs, naming) and [[Frank TTS Engine]] (the warm registry). Everything below runs
|
||||
as the deploy user on **Dankclaw** (`ssh -o BatchMode=yes dankclaw '…'`); the
|
||||
containers are **rootless** (`systemctl --user …`, `podman …` without sudo).
|
||||
# Adding (or repairing) a cloned voice on the dank fleet
|
||||
|
||||
## Naming (the question that gets asked first)
|
||||
Repo law lives in `serverAppConfigs-docs/Dankclaw/Voice Packs.md` and
|
||||
`Frank TTS Engine.md` — read those for the pack format. This skill is the
|
||||
**operating sequence plus the traps that cost real time on 2026-10-18**.
|
||||
|
||||
A voice is addressed **by its directory name** — `voice=narrator1` on
|
||||
`POST /v1/audio/speech` (omp's TTS device may send `voice_id`, same value). Use:
|
||||
## Stack, fast
|
||||
|
||||
- `^[a-z0-9][a-z0-9._-]*$`, **lowercase**, ≤ 64 chars. No slash, no `..`, no
|
||||
space, no uppercase; must not start with `.`/`_`/`-`.
|
||||
- Why lowercase rather than just "alphanumeric": the shim accepts
|
||||
`[A-Za-z0-9][A-Za-z0-9._-]{0,63}` (`app.py`, `VOICE_NAME_RE`) but the **engine
|
||||
lowercases names**, so `Narrator1` resolves on one side and not the other. The
|
||||
boot warmer refuses a mixed-case pack loudly instead of half-working.
|
||||
- Names are user-visible: a 400 carries them in `available_voices`. Fleet
|
||||
convention is `narrator1`, `narrator2`, … for the open-notebook podcast
|
||||
speakers — open-notebook is configured with exactly `narrator1/2/3`, so renaming
|
||||
those breaks podcast rendering, not just TTS — and a lowercase personal name for
|
||||
a person's own voice.
|
||||
- `frank-tts-engine` — arm A `qwentts.cpp tts-server`, container-internal `:8880`,
|
||||
publishes **no port**. Reach it with `podman exec frank-tts-engine curl …`.
|
||||
- `frank-tts` — OpenAI façade on host `:7772`; resolves voice **by name**.
|
||||
- Packs: `/home/dank/voices/<name>/` with `reference.wav` (+ manifest, `.spk`,
|
||||
`.rvq`). Builder: `scripts/build-voice-pack.sh` (crop 19.84–25 s, first 10 s of
|
||||
any source is forbidden).
|
||||
- Weights: `/home/dank/models/Qwen3-TTS-GGUF/` —
|
||||
`scripts/download-frank-tts-engine-qwentts.sh [--verify-only]` (1.4 GiB, ~18 s
|
||||
on the LAN; verifies byte count + Hub LFS sha256).
|
||||
|
||||
## Pack layout (host state — never commit it)
|
||||
## Sequence
|
||||
|
||||
`/home/dank/voices/<name>/` is a voice **iff** it holds `reference.wav`:
|
||||
1. Build the pack (dry-run first — sizes are arithmetic and asserted).
|
||||
2. Deploy the engine only if its files changed:
|
||||
`./scripts/deploy.sh dankclaw --service frank-tts-engine`
|
||||
(first run builds the image: ~10 min recursive source clone).
|
||||
3. Register/warm: `podman exec frank-tts-engine /app/warm-voices.sh`
|
||||
— registers **every** pack each run (the engine replaces a name it already
|
||||
holds; `tools/tts-server.cpp:148`), then synthesizes twice per voice.
|
||||
4. Prove from the consumer side, not the config:
|
||||
`curl -s localhost:7772/v1/audio/voices` then a real
|
||||
`POST /v1/audio/speech` and listen to the bytes.
|
||||
|
||||
```
|
||||
reference.wav 24 kHz mono pcm_s16le, 18-25 s of clean single-speaker audio
|
||||
reference.spk engine x-vector: enc_dim 2048 f32 = 8192 B
|
||||
reference.rvq RVQ codes: 22 B per 12.5 Hz frame (5456-6864 B)
|
||||
manifest.json source path + sha256, crop start/end, engine commit, name
|
||||
```
|
||||
## Trap 1 — the kernel's argument cap (this broke the first deploy)
|
||||
|
||||
Build it; do not hand-assemble and never fabricate `.spk`/`.rvq` from a WAV:
|
||||
`/usr/bin/curl: Argument list too long` in the warm log ⇒ a request body was
|
||||
passed as **one argv string**. Linux caps a single argument at
|
||||
`MAX_ARG_STRLEN = 131 072 bytes`; a ~1 MB `reference.wav` base64's to ~1.27 MB.
|
||||
curl never runs, and hooks report it as `HTTP no response` while `/health` is
|
||||
green. Fix = write the body to a file and use `--data-binary @file`; feed the
|
||||
payload through a redirection, not `$(base64 …)`.
|
||||
Regression-test shape: **real** curl + real listener + a fixture >128 KB, so the
|
||||
kernel (not a stub) produces the failure. Any pack over ~96 KB trips it.
|
||||
|
||||
```bash
|
||||
scripts/build-voice-pack.sh --all /home/dank/voices # everything in VOICE_PACKS
|
||||
scripts/build-voice-pack.sh --source SRC --offset SEC --duration SEC --sha256 HEX NAME /home/dank/voices
|
||||
scripts/build-voice-pack.sh --dry-run ... # validate + crop, no extractor
|
||||
```
|
||||
## Trap 2 — two readers of the env file disagree about quotes
|
||||
|
||||
Knobs live in `scripts/voice-packs.env` (one `_SOURCE`/`_OFFSET`/`_DURATION`/
|
||||
`_SHA256` set per voice). Three things it enforces that an operator gets wrong:
|
||||
`bash set -a; source` strips `"…"`. podman's `--env-file` (how the unit really
|
||||
reads it) does **not**. A value interpolated into a JSON body therefore arrives
|
||||
quoted and invalidates it. Test both readers, not just `source`.
|
||||
|
||||
1. **The 10-second gate.** A crop starting inside the first 10 s of the source is
|
||||
refused before anything is written (project source-material law), and the
|
||||
manifest is re-checked against the source's sha256 afterwards.
|
||||
2. **The effective crop window is 19.84-25 s, not 18-25 s.** An 18.0 s crop is a
|
||||
legal `reference.wav` but yields only 22 × 225 = 4 950 B of `.rvq`, under the
|
||||
5 456 B floor the codec config implies — so the builder says so up front.
|
||||
3. **It never deletes.** An existing pack is refused unless `--force`, and
|
||||
`--force` moves the old directory to `$PACKS_DIR/.AGENTTRASH/<voice>-<UTC>/`.
|
||||
## Trap 3 — locally built images skip rebuilds on a stale hash
|
||||
|
||||
Files must be world-readable (the container runs as uid 10000): `644` files,
|
||||
`755` dirs. `mkdir -p /home/dank/voices` as the deploy user if it is absent —
|
||||
rootless podman auto-creates a missing bind source **root-owned**, and the
|
||||
endpoint then sees no voices at all.
|
||||
`build_compose_image` compares a `cfhash` label; it must cover every file the
|
||||
`Containerfile` `COPY`s, or an edited `app.py`/hook deploys "successfully" while
|
||||
the container runs old code.
|
||||
|
||||
## Register and warm (the part people forget)
|
||||
## Measured numbers (2026-10-18, deployed build — retire the trial's ladder)
|
||||
|
||||
The engine keeps its voice registry **in memory**, and the **first synthesis of a
|
||||
registered voice decodes the whole reference clip** to snapshot codec state:
|
||||
6.2-8.0 s, first audio byte at ~5 530 ms. Later requests restore in 0.5 ms.
|
||||
Re-registering does **not** warm — only synthesizing does. So:
|
||||
| thing | value |
|
||||
|---|---|
|
||||
| first synthesis of a freshly registered voice | 1 883 ms |
|
||||
| later short requests | 1 226–1 283 ms |
|
||||
| ~110-word request (repeat) | 9.4 s / 9.8 s — tracks generated audio, not state |
|
||||
| whole boot warm, 3 packs | 15.2 s |
|
||||
| engine resident | ~4.0 GiB |
|
||||
|
||||
```bash
|
||||
# registers every pack that has a reference.wav, then speaks the warm sentence once
|
||||
podman exec frank-tts-engine /app/warm-voices.sh
|
||||
systemctl --user --no-pager --full status frank-tts-engine.service | tail -20
|
||||
```
|
||||
The trial's `6.2–8.0 s cold → 0.5 ms warm` claim does **not** reproduce; warming
|
||||
is for registration (registry is memory-only, re-register ≠ warm) plus ~0.6 s.
|
||||
|
||||
The unit's
|
||||
`ExecStartPost=-/usr/bin/podman exec frank-tts-engine /app/warm-voices.sh` does
|
||||
the same at every boot, so a fresh boot is already warm; the explicit call above
|
||||
is for **adding one voice to a running engine** and needs no restart — a restart
|
||||
drops every registration and re-pays the cold cost for the whole library. The
|
||||
`podman exec` form is not cosmetic: the engine **publishes no port**, so there is
|
||||
no host address to curl.
|
||||
## Ops notes
|
||||
|
||||
## Proof (do not report "added" without it)
|
||||
|
||||
```bash
|
||||
curl -s localhost:7772/v1/audio/voices # name is listed
|
||||
time curl -s -o /tmp/a.wav localhost:7772/v1/audio/speech \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"model":"tts-1","voice":"NAME","input":"Checking the cloned voice.","response_format":"wav"}'
|
||||
time curl -s -o /tmp/b.wav localhost:7772/v1/audio/speech \
|
||||
-H 'content-type: application/json' \
|
||||
-d '{"model":"tts-1","voice":"NAME","input":"And the second request.","response_format":"wav"}'
|
||||
file /tmp/a.wav /tmp/b.wav # really audio
|
||||
```
|
||||
|
||||
The warmer's journal lines carry `voice NAME cold=…ms warm=…ms` — quote that pair.
|
||||
Note that streaming and buffered output differ at the same seed (92.2 % of samples,
|
||||
-41.6 dB RMS): never compare two paths or two "identical" renders, only that each
|
||||
is audio and that the second request is fast.
|
||||
|
||||
## Failure modes worth naming
|
||||
|
||||
- `400 unknown voice …; available voices: …` → the name is not a pack: wrong
|
||||
spelling/case, missing `reference.wav`, or `/home/dank/voices` root-owned/empty.
|
||||
Trust the 400's list over any manifest.
|
||||
- 400 with `(none: no voice pack with a reference.wav in /voices)` → mount problem,
|
||||
not a voice problem.
|
||||
- First request slow **after** a boot → the warm pass failed; read the unit's
|
||||
journal (the warmer exits 0 and logs when there is no voice directory, so
|
||||
silence there is not success either).
|
||||
- Endpoint answers but synthesis fails 502 → the façade must dial
|
||||
`http://frank-tts-engine:8880` over the shared bridge
|
||||
(`frank-tts-engine.network`); a `host.containers.internal` / `127.0.0.1:8880`
|
||||
upstream can never work between containers, because netavark DNATs published
|
||||
ports only.
|
||||
|
||||
## Never
|
||||
|
||||
Never write under `/voices` from the endpoint (mounted `:ro` by design), never
|
||||
`git add` a voice pack, never `rm` a pack (repo policy: move to `.AGENTTRASH/`),
|
||||
and never benchmark against this endpoint while it serves — stop and mask the
|
||||
units first.
|
||||
- `systemctl --user stop` **removes** the quadlet container — `podman start` then
|
||||
finds nothing. To run the engine without its `ExecStartPost` hook, use a
|
||||
separate container, not stop+start.
|
||||
- `podman cp` of a fixed script into a running container is a **trial only**: the
|
||||
layer dies with the container. Merge + redeploy to make it durable.
|
||||
- Nothing on the voice pair exposes `/metrics`; Prometheus can't scrape it (a
|
||||
blackbox HTTP probe on 7772 is the only honest option).
|
||||
Reference in new issue
Block a user