# audio.cpp (`--backend audiocpp`)

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.

Run all commands from the project root (next to `audiobook.py`).

## Requirements

- 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)

## Install

1. Clone the repo:

```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 (--backend: cuda, vulkan, hip, cpu)
scripts/build_linux.sh --backend cuda --target audiocpp_server --deployment-build
```

```bash
# 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 \
  -DAUDIOCPP_DEPLOYMENT_BUILD=ON
cmake --build build/macos-metal-release --parallel $(sysctl -n hw.logicalcpu) --target audiocpp_server
```

```powershell
# 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
```

3. Download models:

```bash
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
```

4. Create `server.json` in the checkout:

```json
{
  "host": "127.0.0.1",
  "port": 8080,
  "backend": "cuda",
  "lazy_load": true,
  "voice_dir": "/path/to/clone/wavs",
  "models": [
    {
      "id": "Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",
      "family": "qwen3_tts",
      "path": "models/Qwen3-TTS-12Hz-1.7B-CustomVoice-GGUF",
      "task": "tts",
      "mode": "offline"
    },
    {
      "id": "Qwen3-TTS-12Hz-1.7B-Base-GGUF",
      "family": "qwen3_tts",
      "path": "models/Qwen3-TTS-12Hz-1.7B-Base-GGUF",
      "task": "tts",
      "mode": "offline"
    },
    {
      "id": "Chatterbox-GGUF",
      "family": "chatterbox",
      "path": "models/Chatterbox-GGUF",
      "task": "clon",
      "mode": "offline"
    }
  ]
}
```

- `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 the server

```bash
./build/linux-cuda-release/bin/audiocpp_server --config server.json
```

(The binary path differs by platform/build preset.)

## Use it

```bash
python audiobook.py --backend audiocpp --api-url http://127.0.0.1:8080 --model <id> --voice <name>
```