rewrite backend documentation

1 files changed, 29 insertions, 93 deletions

diff --git a/app/docs/backend-audiocpp.md b/app/docs/backend-audiocpp.md
index aff8b12..b0367e1 100644
--- a/app/docs/backend-audiocpp.md
+++ b/app/docs/backend-audiocpp.md
@@ -1,32 +1,33 @@
-# Backend Option 1: audio.cpp
+# audio.cpp (`--backend audiocpp`)
 
-`--backend audiocpp` talks to `audiocpp_server` from [audio.cpp](https://github.com/0xShug0/audio.cpp), which hosts numerous TTS model families.
+Runs [audio.cpp](https://github.com/0xShug0/audio.cpp)'s `audiocpp_server`, a C++ TTS server hosting many model families. Installs into the `app/audio.cpp` checkout.
 
-The easiest way is the TUI: run `python audiobook.py`, choose **Configure Backends… → Install Backend → audio.cpp**, and it clones `audio.cpp` into `app/audio.cpp` (or reuses an existing checkout), installs `audiocpp_server` — by default downloading the prebuilt release binary on macOS and Windows (no compiler, no Xcode needed), or building from source elsewhere — lets you pick model families/packages from an expandable checkbox tree (reading the checkout's `model_specs/`), transcribes `.wav` voices with `whisper`, writes `server.json` into the checkout, syncs `app/converter/config.py`, and prints the launch command (the hub can also start the server for you via the **Start/Stop Backend Servers** menu or automatically when converting). The setup asks exactly two screens: first the model tree, then one combined options form (like **Generate Audiobooks**) for everything else — the inference backend and how to get the server binary (prebuilt download, source build, or skip), the voice-clone `.wav` directory and how to transcribe it, automatic model download, the default-model sync, and deleting models dropped on a re-run; rows that do not apply to your selection are hidden. The server always binds `127.0.0.1` on the port configured in `AUDIOCPP_API_URL` (edit it in **Settings**), so neither is ever asked. The clone, install, transcription and model downloads all run inside the TUI — each shows a status (and, where the tool can measure it, a progress bar), and can be cancelled — instead of dropping to console output. Run it directly with `python -m backends.audiocpp` from `app/` — flags like `--wavs`, `--families`, `--build-backend`, `--prebuilt auto|yes|no`, `--clone` skip the corresponding parts for scripting. The TUI runs in the managed `app/envs/tts` venv, which installs faster-whisper when wheels exist for your platform (it is tagged optional in `requirements.txt`: on platforms without compatible builds the setup skips it and voice-clone transcription degrades to manual transcripts). For a manual setup, make sure `whisper` or `faster_whisper` is installed in the environment you run the wizard from. The Qwen3-TTS model tree also offers hosting the VoiceDesign package as a `vdes` entry.
+Run all commands from the project root (next to `audiobook.py`).
 
-The hub's backend status table distinguishes how far audio.cpp is set up: `unavailable` (nothing present), `downloaded (not built)` (checkout cloned, `audiocpp_server` not installed), `built (not configured)` (binary installed, no `server.json`), `installed` (ready; or `installed (models missing)` when the config references undownloaded models), and `running` once its server answers. Whenever the checkout exists but `audiocpp_server` is missing, **Configure Backends… → Build audio.cpp Server** installs it from the TUI — asking whether to download the prebuilt release (recommended, macOS and Windows) or build from source (the wizard offers the same choice during setup), so a backend whose install you skipped is never stuck as "unavailable". On a fresh install the setup is one continuous flow: clone → configure → and then the install and the model downloads run **simultaneously** in a split view (half downloading/building, half downloading models). The setup steps are therefore ordered install > configure > download, and **Build audio.cpp Server** and **Download Missing Models (audio.cpp)** are never offered at the same time; **Build audio.cpp Server** downloads any missing models alongside the install, and **Download Missing Models (audio.cpp)** remains only as a fallback for when a download fails or is interrupted.
+## Requirements
 
-Prebuilt installs are tracked with a `prebuilt.json` marker inside the build directory. **Update Backends** then skips the git pull/rebuild flow for those and instead re-downloads when upstream publishes a newer release (and checks the checkout out at the release's tag, keeping its model catalog and tooling in sync with the binary). When that re-download fails (usually GitHub's API rate limit), **Update Backends** falls back to the same source-build route a source-built checkout uses — the installed binary is only replaced once a new one is in place, so it keeps working meanwhile — and a successful fallback build removes the now-stale marker so later updates take the git + rebuild route. A source-built checkout keeps updating by git pull + rebuild.
+- git
+- A C++ toolchain (gcc/clang + cmake on Linux, full Xcode on macOS, VS Build Tools with the C++ workload on Windows)
+- CUDA / Vulkan / HIP for GPU builds (or CPU)
 
-If you prefer to install the backend yourself (in your own environment, not the managed venv), the manual steps are below. Either way the hub detects a running server by its port, so a manually-installed backend works once its server is up.
+## Install
 
-### Download or build audiocpp_server
+1. Clone the repo:
 
-The wizard's default on macOS and Windows is to download a prebuilt `audiocpp_server` from [audio.cpp's releases](https://github.com/0xShug0/audio.cpp/releases) (checksum-verified, ~20–25 MB, no compiler or Xcode required — on Intel Macs the release runs on CPU only, and Windows CUDA builds come in 12.4/13.3 variants picked to match your NVIDIA driver). The newest version is resolved without GitHub's API, so the check rarely hits the API's rate limit; if the API *is* rate-limited when a download starts, the install proceeds without checksum verification (with a loud warning). If the download still fails, the TUI does not leave you half-installed: the same Build lane automatically falls back to building from source (a cancelled download, or an explicit `--prebuilt yes` — which exists to forbid source builds — do not fall back). **Update Backends** keeps a prebuilt install current automatically, and falls back to a source build the same way when its re-download fails. The manual build steps, if you prefer building from source, are below — build for your platform and backend `(cuda, vulkan, hip, cpu)`. Check [audio.cpp's readme](https://github.com/0xShug0/audio.cpp) for details. audio.cpp ships one helper script per platform, and the hub runs the one matching your OS:
+```bash
+git clone https://github.com/0xShug0/audio.cpp app/audio.cpp
+cd app/audio.cpp
+```
+
+2. Build `audiocpp_server` (macOS and Windows can instead download a prebuilt binary from [releases](https://github.com/0xShug0/audio.cpp/releases)):
 
 ```bash
-# Linux
-git clone https://github.com/0xShug0/audio.cpp
-cd audio.cpp
+# Linux (--backend: cuda, vulkan, hip, cpu)
 scripts/build_linux.sh --backend cuda --target audiocpp_server --deployment-build
 ```
 
 ```bash
-# macOS (Metal is the only buildable backend there; the hub records it as "cpu").
-# Needs full Xcode (build_metal.sh requires its offline Metal compiler). Without
-# Xcode, the hub builds with cmake directly — Apple's Command Line Tools
-# (clang) plus cmake suffice, because the Metal shaders are then compiled by
-# macOS itself at runtime on first use:
+# macOS (Metal)
 cmake -S . -B build/macos-metal-release -DCMAKE_BUILD_TYPE=RelWithDebInfo \
   -DENGINE_ENABLE_METAL=ON -DENGINE_ENABLE_CUDA=OFF -DENGINE_ENABLE_VULKAN=OFF \
   -DENGINE_ENABLE_OPENMP=OFF -DGGML_METAL_EMBED_LIBRARY=ON \
@@ -35,29 +36,19 @@ cmake --build build/macos-metal-release --parallel $(sysctl -n hw.logicalcpu) --
 ```
 
 ```powershell
-# Windows (needs VS Build Tools with the C++ workload; CUDA preset also needs
-# the CUDA Toolkit, Vulkan preset the Vulkan SDK — the script names what's missing)
+# Windows (presets: windows-cpu-release, windows-vulkan-release, windows-cuda-release)
 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\build_windows.ps1 -Preset windows-cuda-release -Target audiocpp_server -DeploymentBuild
-# presets: windows-cpu-release, windows-vulkan-release, windows-cuda-release (HIP: scripts\build_windows_hip.ps1)
 ```
 
-`--deployment-build` compiles the `model_specs/` catalog into the binary so every family resolves its model contract even when the server is started outside the checkout (GGUF packages whose embedded spec is legacy, such as today's Qwen3-TTS ones, otherwise need `model_specs/<family>.json` found relative to the working directory). The macOS script takes the same flag; the Windows PowerShell scripts take `-DeploymentBuild`.
-
-### Install models
-
-Download model packages with the python model manager script from the audio.cpp checkout. Each installs to `./models`. Here are two examples, Higgs Audio and Qwen3-TTS:
+3. Download models:
 
 ```bash
-python tools/model_manager_v2.py install higgs_audio_tts_4b_q8_0
+python tools/model_manager_v2.py list                     # see available models
 python tools/model_manager_v2.py install qwen3_tts_1_7b_base_q8_0
 python tools/model_manager_v2.py install qwen3_tts_1_7b_customvoice_q8_0
 ```
 
-You can run `python tools/model_manager_v2.py list` to see all available models. Inside the tool's setup the models are downloaded automatically from the TUI (models already on disk are reported and skipped); if you need to download them manually instead, decline the automatic download and it prints these commands for only the models that are still missing.
-
-### Create server.json
-
-Create a `server.json` config file. One server can host multiple models and multiple cloned voices. The `id:` fields are the model names you will set for `tts-audiobook-generator` with `--model` (the setup wizard names each entry after its model package directory).
+4. Create `server.json` in the checkout:
 
 ```json
 {
@@ -68,13 +59,6 @@ Create a `server.json` config file. One server can host multiple models and mult
   "voice_dir": "/path/to/clone/wavs",
   "models": [
     {
-      "id": "Higgs-Audio-v3-TTS-4B-GGUF",
-      "family": "higgs_audio_tts",
-      "path": "models/Higgs-Audio-v3-TTS-4B-GGUF",
-      "task": "tts",
-      "mode": "offline"
-    },
-    {
       "id": "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",
       "family": "qwen3_tts",
       "path": "models/Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",
@@ -99,68 +83,20 @@ Create a `server.json` config file. One server can host multiple models and mult
 }
 ```
 
-The `task` field decides which session type the server creates for the entry, and model families are picky about it: clone-only families — **Chatterbox**, **Confucius4-TTS** and **Echo-TTS** — reject plain-TTS sessions outright (every speech request fails with an HTTP 500 like `Chatterbox supports VoiceCloning and VoiceConversion`), so they must be hosted with `"task": "clon"`. Voice-design packages are hosted with `"task": "vdes"`; every other family keeps `"task": "tts"`, which serves plain TTS and (where the family supports it) voice cloning through the request's `voice` field alike. The setup wizard writes the right task automatically, and opening **Generate Audiobooks** re-hosts stale `tts`-tasked clone-only entries in an existing `server.json` (restarting the managed server to load the fix).
+- `id` is the value passed as `--model` to TAG.
+- `task`: `tts` for plain TTS/clone families, `clon` for clone-only families (Chatterbox, Confucius4-TTS, Echo-TTS), `vdes` for voice-design packages.
+- Voices referenced in `voice_dir` need a transcript file `prompt_text` alongside the wavs, one `<voice>|<transcript>` line per wav.
 
-### Run audio.cpp and the audiobook script
-
-Run the server with this config file. The `audiocpp_server` path will be slightly different depending on your platform and build options:
+## Run the server
 
 ```bash
 ./build/linux-cuda-release/bin/audiocpp_server --config server.json
 ```
 
-In a different terminal, run `audiobook.py`. Pick the TTS `--model` and `--voice` from server.json:
-
-```bash
-# Higgs Audio voice cloning (the family also does plain TTS: omit --voice)
-python audiobook.py --backend audiocpp --model Higgs-Audio-v3-TTS-4B-GGUF --voice narrator
+(The binary path differs by platform/build preset.)
 
-# Chatterbox (clone-only: a reference voice is required)
-python audiobook.py --backend audiocpp --model Chatterbox-GGUF --voice narrator
+## Use it
 
-# Supertonic (pure TTS: no voice needed, none can be cloned)
-python audiobook.py --backend audiocpp --model Supertonic-GGUF
-
-# Qwen3-TTS built-in speaker (pick one with --voice)
-python audiobook.py --backend audiocpp --model Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF --voice Vivian
-
-# Qwen3-TTS voice cloning
-python audiobook.py --backend audiocpp --model Qwen3-TTS-12Hz-1.7B-Base-GGUF --voice narrator
-
-# Qwen-TTS voice design
-python audiobook.py --backend audiocpp --model Qwen3-TTS-12Hz-1.7B-VoiceDesign-GGUF \
-    --instructions "A warm adult female narrator with a British accent"
-
-# Per-model options passed through to the family (--option KEY=VALUE, repeatable)
-python audiobook.py --backend audiocpp --model <id> --voice narrator \
-    --option emotion=neutral --option speed=1.1
+```bash
+python audiobook.py --backend audiocpp --api-url http://127.0.0.1:8080 --model <id> --voice <name>
 ```
-
-### Voice cloning transcripts (prompt_text)
-
-Some clone families require the **transcript of the reference audio** with
-every request (Qwen3-TTS's Base model clones in ICL mode and rejects each
-request without it: "voice clone ICL mode requires reference text"). The
-server supplies the transcript itself, from either of two places:
-
-- `prompt_text` in the configured `voice_dir`: one `<voice>|<transcript>` line
-  per wav (the setup wizard writes it from whisper transcriptions), or
-- `reference_text` on a `voice_presets` entry in `server.json`.
-
-An **empty or missing transcript makes every clone request for that voice
-fail**, so `audiobook.py` aborts on the first chunk with instructions instead
-of retrying. The setup warns loudly about any voice whose transcript came
-back empty — fill those in before converting (edit `prompt_text` by hand and
-restart nothing: the server re-reads it per request), or rerun the audio.cpp
-setup to re-transcribe. A re-transcription that fails keeps any existing
-non-empty transcript rather than overwriting it with a blank.
-
-If accurate transcripts are not available, cloning without one is possible
-per run with `--option x_vector_only_mode=true` (speaker-embedding-only
-cloning — no transcript needed, noticeably lower speaker similarity).
-
-In the hub's **Generate Audiobooks** form the Model picker reads as a table: each entry's id is padded to the widest one and its capabilities are rendered as fixed columns — `tts` in the first column (families that need no voice at all, or take a built-in speaker / preset voice), `clone` (the entry clones a reference voice) in the second, `design` (the entry can design a voice from an Instructions description) in the third — so every capability word lines up down its own column. The `design` column is filled for `vdes` design-model entries and for families whose audio.cpp spec advertises design (e.g. OmniVoice, VoxCPM2); Qwen3-TTS designs only through its separate VoiceDesign entry, so its Base/CustomVoice rows stay without it. The Voice field is labelled **Built-in voice** on CustomVoice entries (listing the model's speakers) and **Voice to clone** on clone-capable entries (listing the server's preset/voice_dir entries) — it is hidden entirely on pure-TTS families, and on mixed tts+clone families it leads with a **&lt;built-in&gt; (no clone)** pick that means plain TTS with the model's own default voice (no reference cloned; the default). Clone-only families keep the voice required. Instructions are shown for every entry: required for `vdes` design models, an optional style/delivery instruction elsewhere — and on families without built-in speakers that read instructions, a description alone can define the voice, so leaving Voice empty is fine there. A Request options field accepts the same `KEY=VALUE` items as `--option`, and appears only for model families whose audio.cpp checkout spec declares request options (e.g. Neutts, Outetts, F5-TTS — not Qwen3-TTS or Higgs Audio). Editing Instructions or Request options shows a short dim hint with an example (for Instructions: `"Speak in a calm, soothing, and happy tone."`). Language is a static picker over the languages of audio.cpp's WebUI menus (it shows the same "Check model documentation for supported languages." hint while editing) and overrides the global setting for this run only.
-
-The hub also works with an audio.cpp server that runs somewhere else (another checkout, another machine): set `AUDIOCPP_REMOTE_URL` in `app/converter/config.py` (or the TUI **Settings** → "audio.cpp remote URL") to its `host:port`. The hub probes that URL and, when it answers, offers an `audio.cpp [remote]` entry in **Generate Audiobooks…** whose models and voices are queried live (`GET /v1/models` and `GET /v1/audio/voices`) — alongside the managed `audio.cpp` entry, which keeps reading the local `server.json`. The remote URL defaults to `127.0.0.1:8080`, so a server started outside this tool on the local port is found automatically. On the CLI, pass `--api-url http://host:port` (and `--model`/`--voice` matching that server's config).
-
-Before converting, `audiobook.py` asks the server to unload all currently loaded models (`POST /v1/tasks/unload_all_models`) so models left resident by earlier runs free their memory (e.g. VRAM on GPU backends) and only the selected entry loads. A server without that endpoint, or one busy unloading, only produces a warning. This behavior is controlled by the **Settings** → "Unload models" option (or `AUDIOCPP_UNLOAD_MODELS` in `app/converter/config.py`), which defaults to **Yes**; set it to **No** to keep other models resident across runs.