feat: manage venv for all backends

3 files changed, 101 insertions, 4 deletions

diff --git a/docs/backend-audiocpp.md b/docs/backend-audiocpp.md
new file mode 100644
index 0000000..ee511bb
--- /dev/null
+++ b/docs/backend-audiocpp.md
@@ -0,0 +1,91 @@
+# Backend Option 1: audio.cpp
+
+`--backend audiocpp` talks to `audiocpp_server` from [audio.cpp](https://github.com/0xShug0/audio.cpp), which hosts numerous TTS model families.
+
+The easiest way is the TUI: run `python audiobook.py`, choose **Set up a backend… → audio.cpp**, and it clones `audio.cpp` into `./audio.cpp` (or reuses an existing checkout), builds `audiocpp_server`, 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 `converter/config.py`, and prints the launch command (the hub can also start the server for you via the **Server** menu or automatically when converting). Run it directly with `python -m backends.audiocpp` (flags like `--wavs`, `--families`, `--build-backend`, `--clone` skip the corresponding screens for scripting). The TUI runs in the managed `envs/tts` venv, which includes `whisper` via `requirements.txt`; 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.
+
+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.
+
+### Download and build audiocpp_server
+
+Download and build `audiocpp_server` for your platform and backend `(cuda, vulkan, hip, cpu)`. Check [audio.cpp's readme](https://github.com/0xShug0/audio.cpp) for details. I'm using one of the helper scripts:
+
+```bash
+git clone https://github.com/0xShug0/audio.cpp
+cd audio.cpp
+scripts/build_linux.sh --backend cuda --target audiocpp_server
+```
+
+### 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:
+
+```bash
+python tools/model_manager_v2.py install higgs_audio_tts_4b_q8_0
+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.
+
+### 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`.
+
+```json
+{
+  "host": "127.0.0.1",
+  "port": 8080,
+  "backend": "cuda",
+  "lazy_load": true,
+  "voice_dir": "/path/to/clone/wavs",
+  "models": [
+    {
+      "id": "higgs",
+      "family": "higgs_audio_tts",
+      "path": "models/Higgs-Audio-v3-TTS-4B-GGUF",
+      "task": "tts",
+      "mode": "offline"
+    },
+    {
+      "id": "qwen",
+      "family": "qwen3_tts",
+      "path": "models/Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",
+      "task": "tts",
+      "mode": "offline"
+    },
+    {
+      "id": "qwen-clone",
+      "family": "qwen3_tts",
+      "path": "models/Qwen3-TTS-12Hz-1.7B-Base-GGUF",
+      "task": "tts",
+      "mode": "offline"
+    }
+  ]
+}
+```
+
+### 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:
+
+```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 (clone-only)
+python audiobook.py --backend audiocpp --model higgs --voice narrator
+
+# Qwen3-TTS built-in speaker
+python audiobook.py --backend audiocpp --model qwen
+
+# Qwen3-TTS voice cloning
+python audiobook.py --backend audiocpp --model qwen-clone --voice narrator
+
+# Qwen-TTS voice design
+python audiobook.py --backend audiocpp --model qwen-design \
+    --instructions "A warm adult female narrator with a British accent"
+```
diff --git a/docs/backend-faster.md b/docs/backend-faster.md
index 40b10f7..c407a70 100644
--- a/docs/backend-faster.md
+++ b/docs/backend-faster.md
@@ -2,7 +2,11 @@
 
 `--backend faster` talks to the OpenAI-compatible server from [faster-qwen3-tts](https://github.com/andimarafioti/faster-qwen3-tts), which uses CUDA graph capture for roughly 5-10x faster inference with the same models. **It requires an NVIDIA GPU**.
 
-Install into the **same `audiobook` conda environment** used for qwen-tts.
+The easiest way is to run `python audiobook.py` → **Set up a backend… → faster-qwen3-tts** (or `python -m backends.faster path/to/clone/wavs`): the TUI pip-installs `faster-qwen3-tts[demo]` into its managed venv (`envs/tts`), clones the repo, transcribes the `.wav` files with `whisper`, and writes `voices.json` for you. You can also start the server from the hub's **Server** menu, or let a conversion start it automatically.
+
+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 into your environment (the same one used for qwen-tts is fine):
 
 ```bash
 conda activate audiobook
@@ -19,7 +23,7 @@ git clone https://github.com/andimarafioti/faster-qwen3-tts
 cd faster-qwen3-tts
 ```
 
-Create a `voices.json` mapping names to reference configurations (.wav to clone, transcript, language). The TUI setup (`python audiobook.py` → **Set up a backend… → faster-qwen3-tts**, or `python -m backends.faster path/to/clone/wavs`) pip-installs the package, clones the repo, transcribes the `.wav` files with `whisper`, and writes `voices.json` for you.
+Create a `voices.json` mapping names to reference configurations (.wav to clone, transcript, language). The TUI setup writes this for you; manually it looks like:
 
 ```json
 {
diff --git a/docs/backend-qwen.md b/docs/backend-qwen.md
index 0c9dab0..028d6f3 100644
--- a/docs/backend-qwen.md
+++ b/docs/backend-qwen.md
@@ -1,8 +1,10 @@
 # Backend Option 2: Qwen3-TTS
 
-The TUI sets this up: run `python audiobook.py` → **Set up a backend… → qwen-tts**, or `python -m backends.qwen`. It pip-installs `qwen-tts` and configures the two ports and built-in speaker in `converter/config.py`, then prints the launch commands. Manual steps:
+The easiest way is to run `python audiobook.py` → **Set up a backend… → qwen-tts** (or `python -m backends.qwen`): the TUI pip-installs `qwen-tts` into its managed venv (`envs/tts`), configures the two ports and the built-in speaker in `converter/config.py`, and prints the launch commands. You can also start the server from the hub's **Server** menu, or let a conversion start it automatically.
 
-Install qwen-tts with pip:
+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 qwen-tts with pip into your environment:
 
 ```bash
 conda activate audiobook