path: root/backends/audiocpp.py

#!/usr/bin/env python3
"""Set up the audio.cpp TTS backend for the audiobook generator.

This does the whole audio.cpp setup end-to-end as a full-screen DOS-style
TUI: locate or clone an audio.cpp checkout into ``./audio.cpp``, optionally
build ``audiocpp_server``, pick model families/packages from the checkout's
``model_specs`` catalog, transcribe reference .wav voices, write
``server.json``, sync ``converter/config.py``, download the models, and
print the exact command to start the server. It is driven by
``audiobook.py``'s TUI hub (``backends.REGISTRY``) but can also be run
directly for scripting — every value has a flag, and a non-interactive run
with all flags supplied never opens the TUI.

The converter is family-agnostic (it detects the family of the selected
entry from ``GET /v1/models`` at startup), so any TTS family listed in the
catalog works without further changes.

Usage:
    python -m backends.audiocpp [--wavs WAV_DIR] [--output PATH]
        [--audiocpp-dir PATH] [--clone] [--families FAM1,FAM2]
        [--all-packages] [--host HOST] [--port PORT]
        [--build-backend {cuda,vulkan,hip,cpu}] [--backend {cuda,vulkan,hip,cpu}]
        [--lazy-load] [--whisper-model NAME] [--force]
        [--download] [--no-sync-port] [--no-sync-model-ids]

With no flags and a terminal, the TUI wizard runs. Without a terminal
(or with all flags supplied), it runs non-interactively from the flags;
any missing required value is a hard error with a remediation hint.
"""

import argparse
import json
import os
import re
import subprocess
import sys
import urllib.parse
from pathlib import Path
from typing import Callable, Dict, List, Optional, Set, Tuple

# Allow running directly (python backends/audiocpp.py) from any cwd.
sys.path.insert(0, str(Path(__file__).resolve().parent.parent))

import tui
from backends import BackendStatus, ModifyAction
from backends import common
from backends.common import (
    CONFIG_PATH,
    PROMPT_TEXT_FILENAME,
    TTS_ROOT,
    detect_wav_dir,
    find_wav_files,
    normalize_dir_arg,
    read_prompt_text,
    resolve_wav_dir_arg,
    wav_dir_info as _wav_dir_info,
    wav_dir_preview as _wav_dir_preview,
    write_prompt_text,
)
from converter import config
from converter.tts import transcribe_reference_audio, whisper_backend_available

DEFAULT_HOST = "127.0.0.1"
FALLBACK_PORT = 8080

BACKENDS = ("cuda", "vulkan", "hip", "cpu")

TASK_TTS = "tts"
TASK_VDES = "vdes"

# audio.cpp is cloned into a sibling directory of the audiobook generator.
AUDIOCPP_DIR_NAME = "audio.cpp"
AUDIOCPP_GIT_URL = "https://github.com/0xShug0/audio.cpp"

# Sentinel returned by tui.confirm (via its cancel_value) when the user
# presses Esc on an overwrite prompt to go back to the checkout browser
# instead of aborting the wizard.
_GO_BACK = object()


class _GoBack(Exception):
    """Raised inside the TUI wizard to fall back to the previous screen group.

    Every wizard widget is passed ``back_value=_GO_BACK`` so Esc returns the
    sentinel instead of aborting; pickers and confirmations that call into
    callbacks (task/id pickers, the transcription plan, the download prompt)
    convert that sentinel into this exception so the enclosing step can catch
    it and step back. Only the first screen (the checkout browser) lets Esc
    abort the whole wizard.
    """

# Package names that mark a voice-design model (hosted with task "vdes").
DESIGN_PACKAGE_RE = re.compile(r"voice[\s_\-]?design", re.IGNORECASE)

# Short, friendly default entry ids for selected families. Other families
# derive an id from their family name (see default_model_id). All families
# are listed equally, in alphabetical order.
PREFERRED_IDS = {
    "qwen3_tts": "qwen",
    "higgs_audio_tts": "higgs",
    "voxcpm2": "voxcpm2",
    "index_tts2": "indextts2",
}


class _TuiError(Exception):
    """A fatal error raised from inside the TUI wizard.

    The message is reported to stderr after the terminal is restored; the
    process exits with code 2 (matching a parser error).
    """


def _interactive() -> bool:
    """True when the TUI wizard can run (curses importable + tty)."""
    try:
        import curses  # noqa: F401
    except ImportError:
        return False
    try:
        return sys.stdin.isatty() and sys.stdout.isatty()
    except (AttributeError, ValueError):
        return False


def _resolve_audiocpp_root(directory: Path) -> Optional[Path]:
    """Return the audio.cpp checkout root for DIRECTORY, or None.

    Accepts either the checkout root itself (it must contain a
    ``model_specs`` directory) or the ``model_specs`` directory inside
    it (the parent is used), so the file browser cannot pick the wrong
    one of the two.
    """
    if (directory / "model_specs").is_dir():
        return directory
    if directory.name == "model_specs" and directory.is_dir():
        return directory.parent
    return None


def _audiocpp_root_status(directory: Path) -> Tuple[str, str]:
    """TUI status describing the directory listed in the checkout browser."""
    if _resolve_audiocpp_root(directory) is not None:
        return ("model_specs/ found here", "ok")
    return ("No model_specs/ directory here", "warn")


def _audiocpp_root_preview(directory: Path) -> Optional[Tuple[str, str]]:
    """TUI status for a highlighted subdirectory in the checkout browser."""
    if (directory / "model_specs").is_dir():
        return ("contains model_specs/", "ok")
    return None


def _checkout_auto_select(entry: Path) -> Optional[Path]:
    """Auto-accept a highlighted checkout in the TUI browser.

    A subdirectory named ``audio.cpp`` that already contains a
    ``model_specs`` directory is the audio.cpp checkout root, so it is
    accepted immediately on Enter/Right (as if ``[ Use this directory ]``
    had been pressed) instead of being descended into. Anything else
    returns None so the user keeps browsing. This is only consulted
    while auto-accepting is still enabled; after the user presses Esc to
    go back, the browser is restarted inside the previously accepted
    checkout and this callback is no longer passed, so a wrong guess can
    be corrected.
    """
    if entry.name == "audio.cpp" and (entry / "model_specs").is_dir():
        return entry
    return None


# Backend display order, with short descriptions. The backend name is padded
# so the descriptions' dashes line up in the menu.
_BACKEND_DESCRIPTIONS = (
    ("cuda", "NVIDIA GPUs (fastest)"),
    ("vulkan", "cross-vendor GPU"),
    ("hip", "AMD GPUs"),
    ("cpu", "no GPU required"),
)


def _backend_options(detected: Optional[str] = None
                     ) -> Tuple[List[Tuple[str, str]], int]:
    """Build the aligned backend menu options and the default index.

    The backend names are padded to a common width so the ``-`` dashes
    before the descriptions line up. When DETECTED matches one of the
    options, that option gets ``[auto-detected]`` appended and is the
    default (cursor/start) selection; otherwise the first option is the
    default as before. Returns (options, default_index).
    """
    width = max(len(name) for name, _ in _BACKEND_DESCRIPTIONS)
    options: List[Tuple[str, str]] = []
    default_index = 0
    for index, (name, desc) in enumerate(_BACKEND_DESCRIPTIONS):
        label = f"{name.ljust(width)} - {desc}"
        if detected == name:
            label += " [auto-detected]"
            default_index = index
        options.append((label, name))
    return options, default_index


def config_port() -> int:
    """Return the port of AUDIOCPP_API_URL in converter/config.py."""
    try:
        return urllib.parse.urlsplit(config.AUDIOCPP_API_URL).port or FALLBACK_PORT
    except ValueError:
        return FALLBACK_PORT


def _url_with_port(url: str, port: int) -> str:
    parts = urllib.parse.urlsplit(url)
    host = parts.hostname or "127.0.0.1"
    return urllib.parse.urlunsplit(
        (parts.scheme or "http", f"{host}:{port}", parts.path, "", ""))


def update_config_api_url_port(port: int, config_path: Optional[Path] = None) -> bool:
    """Rewrite the port inside AUDIOCPP_API_URL in converter/config.py.

    Only the quoted URL literal is replaced; surrounding lines and the
    trailing comment are preserved. Returns True when the file was changed.
    """
    path = Path(config_path) if config_path is not None else CONFIG_PATH
    try:
        text = path.read_text(encoding="utf-8")
    except OSError:
        return False
    match = re.search(r'(?m)^(\s*AUDIOCPP_API_URL\s*=\s*")([^"]*)(")', text)
    if not match:
        return False
    new_url = _url_with_port(match.group(2), port)
    if new_url == match.group(2):
        return False
    text = text[:match.start(2)] + new_url + text[match.end(2):]
    try:
        path.write_text(text, encoding="utf-8")
    except OSError:
        return False
    return True


def update_config_model_ids(model_id: str,
                            clone_model_id: Optional[str] = None,
                            config_path: Optional[Path] = None) -> bool:
    """Rewrite AUDIOCPP_MODEL_ID (and AUDIOCPP_CLONE_MODEL_ID when given).

    Only the quoted id literals are replaced; surrounding lines and
    comments are preserved. Returns True when the file was changed.
    """
    path = Path(config_path) if config_path is not None else CONFIG_PATH
    try:
        text = path.read_text(encoding="utf-8")
    except OSError:
        return False
    updates: List[Tuple[str, str]] = [("AUDIOCPP_MODEL_ID", model_id)]
    if clone_model_id is not None:
        updates.append(("AUDIOCPP_CLONE_MODEL_ID", clone_model_id))
    changed = False
    for name, value in updates:
        match = re.search(r'(?m)^(\s*' + name + r'\s*=\s*")([^"]*)(")', text)
        if match and match.group(2) != value:
            text = text[:match.start(2)] + value + text[match.end(2):]
            changed = True
    if not changed:
        return False
    try:
        path.write_text(text, encoding="utf-8")
    except OSError:
        return False
    return True


def default_model_id(family: str) -> str:
    """Derive a default server entry id from a family name."""
    if family in PREFERRED_IDS:
        return PREFERRED_IDS[family]
    name = family
    if name.endswith("_tts"):
        name = name[:-4]
    return name.replace("_", "") or family


def detect_audiocpp_dir() -> Optional[Path]:
    """Best-effort location of a local audio.cpp checkout with model_specs.

    Checks the AUDIOCPP_DIR environment variable, then an ``audio.cpp``
    directory in or above the current working directory. Returns the path
    only when it contains a ``model_specs`` directory.
    """
    candidates: List[Path] = []
    env_dir = os.environ.get("AUDIOCPP_DIR")
    if env_dir:
        candidates.append(Path(os.path.expanduser(env_dir)))
    cwd = Path.cwd()
    candidates.append(cwd / "audio.cpp")
    candidates.append(cwd.parent / "audio.cpp")
    candidates.append(cwd.parent.parent / "audio.cpp")
    for candidate in candidates:
        try:
            resolved = candidate.resolve()
        except OSError:
            continue
        if (resolved / "model_specs").is_dir():
            return resolved
    return None


# audio.cpp build directories are named ``<platform>-<backend>-<type>`` (e.g.
# ``linux-cuda-release``, ``windows-vulkan-debug``, ``macos-metal-release``)
# and the built server lands in ``<that>/bin/audiocpp_server``. The Metal
# macOS backend is reported as "cpu" here since it is not a separate
# --backend choice for audiocpp_server.
_BACKEND_TOKEN_RE = re.compile(r"-(cuda|vulkan|hip|cpu|metal)(?:-|$)")


def detect_backend(audiocpp_dir: Path) -> Optional[str]:
    """Best-effort detection of the backend audiocpp_server was built for.

    Scans ``audiocpp_dir/build/*`` for build directories that contain a
    built ``bin/audiocpp_server`` (``.exe`` allowed on Windows) and reads
    the backend token out of the directory name (``-cuda-``, ``-vulkan-``,
    ``-hip-`` or ``-cpu-``; ``-metal-`` is mapped to ``cpu``). Returns the
    backend only when exactly one distinct backend was built, so a checkout
    with builds for several backends does not silently pick one. Returns
    None when there is no ``build/`` directory, no built server, or more
    than one distinct backend.
    """
    build_root = audiocpp_dir / "build"
    if not build_root.is_dir():
        return None
    backends: Set[str] = set()
    try:
        build_dirs = sorted(build_root.iterdir(),
                            key=lambda p: p.name.lower())
    except OSError:
        return None
    for build_dir in build_dirs:
        if not build_dir.is_dir():
            continue
        server = build_dir / "bin" / "audiocpp_server"
        if not server.exists():
            server_exe = build_dir / "bin" / "audiocpp_server.exe"
            if not server_exe.exists():
                continue
        match = _BACKEND_TOKEN_RE.search(build_dir.name.lower())
        if not match:
            continue
        token = match.group(1)
        backends.add("cpu" if token == "metal" else token)
    if len(backends) == 1:
        return next(iter(backends))
    return None


def _default_package(packages: List[dict]) -> Optional[dict]:
    """Pick the default package from a list of packages.

    Prefers the package flagged ``default: true``, then the first GGUF
    package, then the first package overall. Returns None for an empty list.
    """
    if not packages:
        return None
    for package in packages:
        if package.get("default"):
            return package
    for package in packages:
        if package.get("format") == "gguf":
            return package
    return packages[0]


def load_model_catalog(audiocpp_dir: Path) -> List[dict]:
    """Read model_specs/*.json and return the TTS-capable families.

    Each returned entry has: family, display_name, description, languages,
    clone_capable, packages (the full list from the spec), install_id
    (recommended package id), default_path (``models/<target_directory>``),
    and preferred_id. All families are treated equally and listed in
    alphabetical order by display name.
    """
    specs_dir = audiocpp_dir / "model_specs"
    if not specs_dir.is_dir():
        raise NotADirectoryError(
            f"{audiocpp_dir} has no model_specs/ directory; point "
            "--audiocpp-dir at an audio.cpp checkout")
    entries: List[dict] = []
    for spec_path in sorted(specs_dir.glob("*.json")):
        try:
            spec = json.loads(spec_path.read_text(encoding="utf-8"))
        except (OSError, ValueError):
            continue
        tasks = spec.get("tasks") or []
        if "tts" not in tasks and spec.get("category") != "tts":
            continue
        family = spec.get("family") or spec_path.stem
        packages = spec.get("packages") or []
        package = _default_package(packages)
        if package is None:
            # No installable package: skip (cannot be hosted from a path).
            continue
        target_directory = package.get("target_directory") or family
        languages = spec.get("languages") or []
        display_name = spec.get("display_name") or family
        description = spec.get("description") or ""
        entries.append({
            "family": family,
            "display_name": display_name,
            "description": description,
            "languages": languages,
            "tasks": list(tasks),
            "clone_capable": "clone" in tasks,
            "packages": packages,
            "install_id": package.get("id") or family,
            "default_path": f"models/{target_directory}",
            "preferred_id": default_model_id(family),
        })

    # All families are treated equally: alphabetical by display name.
    entries.sort(key=lambda entry: entry["display_name"].lower())
    return entries


def is_design_package(package: dict) -> bool:
    """Return True when a package's name marks it a voice-design model.

    audio.cpp voice-design packages (whose id, display name, or target
    directory mentions "voice design") are the only packages that must be
    hosted with task "vdes"; their role is not in the schema, only in those
    strings, so it is detected from them.
    """
    text = " ".join(str(package.get(key, ""))
                    for key in ("id", "display_name", "target_directory"))
    return bool(DESIGN_PACKAGE_RE.search(text))


def package_dir_options(entry: dict) -> List[dict]:
    """Return one option per distinct target_directory of a family's packages.

    Each option is a dict with: target_directory, install_id (the recommended
    package id inside that directory), design (voice-design package flag), and
    recommended (whether it holds the family's default package). Precisions
    that share a directory (q8_0/bf16/...) collapse to a single option.
    """
    packages = entry.get("packages") or []
    default_pkg = _default_package(packages)
    default_dir = (default_pkg or {}).get("target_directory") or entry["family"]
    by_dir: Dict[str, List[dict]] = {}
    order: List[str] = []
    for package in packages:
        directory = package.get("target_directory") or entry["family"]
        if directory not in by_dir:
            by_dir[directory] = []
            order.append(directory)
        by_dir[directory].append(package)
    options: List[dict] = []
    for directory in order:
        package = _default_package(by_dir[directory])
        options.append({
            "target_directory": directory,
            "install_id": (package or {}).get("id") or directory,
            "design": is_design_package(package or {}),
            "recommended": directory == default_dir,
        })
    # Put the recommended package first for a friendlier checklist.
    options.sort(key=lambda opt: not opt["recommended"])
    return options


def build_model_entry(family: str, model_id: str, model_path: str,
                      task: str = TASK_TTS) -> dict:
    """Assemble one server.json model entry.

    ``task`` defaults to "tts"; voice design packages are hosted with
    "vdes" so the server runs its design session for speech requests
    (audiobook.py then requires --instructions with that entry).
    """
    return {
        "id": model_id,
        "family": family,
        "path": model_path,
        "task": task,
        "mode": "offline",
    }


def build_server_config(host: str, port: int, backend: str, lazy_load: bool,
                        model_entries: List[dict],
                        voice_dir: Optional[str] = None) -> dict:
    """Assemble the server.json document.

    ``voice_dir`` is a server-level cloning voice library; when set, every
    hosted clone-capable family can use its voices with ``--voice``.
    """
    config_doc = {
        "host": host,
        "port": port,
        "backend": backend,
        "lazy_load": lazy_load,
        "models": model_entries,
    }
    if voice_dir:
        config_doc["voice_dir"] = voice_dir
    return config_doc


def transcribe_wav_dir(wav_files: list, whisper_model: str) -> Dict[str, str]:
    """Transcribe each wav file and return a mapping of stem -> transcript."""
    transcripts: Dict[str, str] = {}
    for wav_file in wav_files:
        name = wav_file.stem
        print(f"[INFO] Transcribing {wav_file.name} (voice '{name}')...")
        text = transcribe_reference_audio(str(wav_file), model_name=whisper_model)
        if text:
            print(f"[OK] {name}: {text}")
        else:
            print(f"[WARNING] No transcript for '{name}'; cloning works best "
                  "with an accurate transcript — consider editing prompt_text "
                  "by hand before starting the server")
        transcripts[name] = text or ""
    return transcripts


def print_empty_transcript_warning(transcripts: Dict[str, str]) -> None:
    """Print a loud, final warning for voices whose transcript is empty."""
    empty = sorted(name for name, text in transcripts.items() if not text)
    if not empty:
        return
    bar = "=" * 70
    print()
    print(bar)
    print("[WARNING] MANUAL TRANSCRIPTION REQUIRED")
    print(bar)
    listing = "  - " + "\n  - ".join(empty) if len(empty) > 1 else f"  - {empty[0]}"
    print(f"The following voice(s) have an EMPTY transcript in prompt_text:\n"
          f"{listing}")
    print("Those voices will NOT work until you add an accurate transcript.")
    print(f"Edit {PROMPT_TEXT_FILENAME} in your voice directory and fill in the "
          "text after '|' for each voice above.")
    print(bar)


def _apply_port_sync(port: int, accepted: bool) -> None:
    """Write the port into converter/config.py, or report when declined."""
    if accepted:
        if not update_config_api_url_port(port):
            print(f"[WARNING] Could not update {CONFIG_PATH}; edit "
                  "AUDIOCPP_API_URL by hand so audiobook.py uses the "
                  "new port")
    else:
        print("[WARNING] Left AUDIOCPP_API_URL unchanged; audiobook.py "
              f"will still use port {config_port()}")


def _decide_transcription(wav_files: list, existing: Dict[str, str],
                          prompt_exists: bool, force: bool,
                          confirm: Callable[[str, bool], bool]) -> dict:
    """Decide which voices to transcribe; CONFIRM asks the plan questions.

    Returns a plan dict: {"mode": "all"|"missing"|"keep", "missing":
    [...], "existing": {...}} — "existing" carries the prompt_text
    mapping read while deciding, so the caller can reuse it instead of
    reading the file again.
    """
    mode = "all"
    missing: List[Path] = []
    if prompt_exists and not force:
        missing = [wav for wav in wav_files
                   if not existing.get(wav.stem, "").strip()]
        if not missing:
            if confirm("All voices already transcribed in prompt_text. "
                       "Re-transcribe anyway?", False):
                mode = "all"
            else:
                mode = "keep"
        elif confirm("Existing transcription and new .wavs detected, "
                     "only transcribe new voices?", True):
            mode = "missing"
        else:
            mode = "all"
    return {"mode": mode, "missing": missing, "existing": existing}


def _transcribe(args: argparse.Namespace, include_clone: bool,
                plan: dict) -> Tuple[Dict[str, str], bool]:
    """Transcribe the wav directory into a stem -> transcript mapping.

    Returns the mapping and a flag indicating whether it should be written to
    prompt_text (False when an existing, complete prompt_text is kept as-is).
    PLAN is always pre-collected — by the TUI (via _decide_transcription and
    its confirm callbacks) or by _flag_plan for a non-interactive run — so no
    questions are asked here.
    """
    if not include_clone:
        print(f"[WARNING] Ignoring {args.input_dir}: no clone-capable family "
              "selected, so voice presets are not used")
        return {}, False

    wav_files = find_wav_files(args.input_dir)
    if not wav_files:
        print(f"[WARNING] No .wav files found in {args.input_dir}; writing the "
              "config without a voice_dir")
        return {}, False

    prompt_path = args.input_dir / PROMPT_TEXT_FILENAME
    existing = plan.get("existing") or {} if plan else {}

    if plan["mode"] == "keep":
        print(f"[INFO] Kept existing {prompt_path}; all voices were "
              "already transcribed, nothing new to transcribe")
        return existing, False

    if whisper_backend_available() is None:
        print("[WARNING] Neither faster_whisper nor whisper was found, so "
              "reference .wav files cannot be transcribed automatically and "
              "every transcript will be empty.")
        print("          Install whisper (or faster_whisper) in your "
              "audiobook environment to transcribe automatically; otherwise "
              "transcripts must be added by hand (see the warning at the end).")

    if plan["mode"] == "missing":
        new_transcripts = transcribe_wav_dir(plan["missing"], args.whisper_model)
        transcripts = dict(existing)
        transcripts.update(new_transcripts)
    else:
        transcripts = transcribe_wav_dir(wav_files, args.whisper_model)
    return transcripts, True


def _flag_plan(wav_files: list, prompt_path: Path, force: bool) -> dict:
    """Build a transcription plan for a non-interactive (flag-only) run.

    With --force everything is re-transcribed; otherwise an existing
    prompt_text is reused and only voices with an empty transcript are
    re-transcribed, mirroring what the TUI confirms interactively.
    """
    if prompt_path.exists() and not force:
        existing = read_prompt_text(prompt_path)
        missing = [wav for wav in wav_files
                   if not existing.get(wav.stem, "").strip()]
        if not missing:
            return {"mode": "keep", "missing": [], "existing": existing}
        return {"mode": "missing", "missing": missing, "existing": existing}
    return {"mode": "all", "missing": [], "existing": {}}


def _offer_config_model_id_sync(model_id: str, accepted: Optional[bool]) -> None:
    """Point converter/config.py at a single hosted model entry.

    The converter requests the model id configured in AUDIOCPP_MODEL_ID,
    and single-model servers use the same id for the clone entry, so both
    ids are rewritten together. ACCEPTED is True/False (apply/skip the
    rewrite) or None when no single-entry sync applies (nothing to do).
    """
    if config.AUDIOCPP_MODEL_ID == model_id \
            and config.AUDIOCPP_CLONE_MODEL_ID == model_id:
        return
    if accepted is None:
        return
    if accepted:
        if not update_config_model_ids(model_id, model_id):
            print(f"[WARNING] Could not update {CONFIG_PATH}; edit "
                  "AUDIOCPP_MODEL_ID and AUDIOCPP_CLONE_MODEL_ID by hand so "
                  "audiobook.py uses this model")
    else:
        print("[WARNING] Left the model ids unchanged; audiobook.py will "
              f"still request model '{config.AUDIOCPP_MODEL_ID}'")


def _build_entries(family_keys: List[str], chosen: Dict[str, List[dict]],
                   catalog_by_family: Dict[str, dict],
                   task_picker: Callable[[str], str],
                   id_picker: Callable[[str, str, str], str]
                   ) -> Tuple[List[dict], List[str], List[Tuple[str, str]],
                              List[str], bool]:
    """Build server.json model entries from the selected families/packages.

    TASK_PICKER is called for each design package to choose vdes/tts;
    ID_PICKER resolves a duplicate server entry id. Returns (model_entries,
    entry_ids, install_guidance, design_entry_ids, include_clone).
    """
    model_entries: List[dict] = []
    entry_ids: List[str] = []
    install_guidance: List[Tuple[str, str]] = []
    design_entry_ids: List[str] = []
    include_clone = False
    for family in family_keys:
        entry = catalog_by_family[family]
        include_clone = include_clone or entry["clone_capable"]
        for opt in chosen[family]:
            task = task_picker(opt["install_id"]) if opt["design"] else TASK_TTS
            base_id = (f"{entry['preferred_id']}-design"
                       if task == TASK_VDES else entry["preferred_id"])
            model_id = base_id
            if model_id in entry_ids:
                model_id = id_picker(entry["display_name"], opt["install_id"],
                                     f"{base_id}-2")
            entry_ids.append(model_id)
            model_entries.append(build_model_entry(
                family, model_id, f"models/{opt['target_directory']}",
                task=task))
            install_guidance.append((entry["display_name"], opt["install_id"]))
            if task == TASK_VDES:
                design_entry_ids.append(model_id)
    return (model_entries, entry_ids, install_guidance,
            design_entry_ids, include_clone)


def _write_and_advise(audiocpp_dir: Path, wav_dir: Optional[Path],
                      output_path: Path, model_entries: List[dict],
                      install_guidance: List[Tuple[str, str]], host: str,
                      port: int, backend: str, lazy_load: bool,
                      transcripts: Dict[str, str], write_prompt: bool) -> None:
    """Console phase shared by both UI modes: write files, print summary.

    After a successful run the console output is the path of the written
    server.json. The model install commands (and optional automatic
    download) are handled separately by _install_models, called by both
    UI modes once the user has decided whether to download.
    """
    voice_dir: Optional[str] = None
    if transcripts:
        if write_prompt:
            prompt_path = wav_dir / PROMPT_TEXT_FILENAME
            write_prompt_text(wav_dir, transcripts)
            print(f"[OK] Wrote {prompt_path}")
        voice_dir = str(wav_dir.resolve())

    server_config = build_server_config(
        host=host, port=port, backend=backend, lazy_load=lazy_load,
        model_entries=model_entries, voice_dir=voice_dir)

    with output_path.open("w", encoding="utf-8") as handle:
        json.dump(server_config, handle, indent=2, ensure_ascii=False)
        handle.write("\n")

    count = len(model_entries)
    print(f"Wrote {output_path.resolve()} with {count} "
          f"{'entry' if count == 1 else 'entries'}.")


def _install_models(audiocpp_dir: Path,
                    install_guidance: List[Tuple[str, str]],
                    download: bool) -> None:
    """Print and optionally run the model install commands.

    One ``python <manager> install <id>`` command per hosted model (de-duped
    by install id). When DOWNLOAD is True each command is run in the audio.cpp
    checkout via ``subprocess.run`` so the models are downloaded automatically;
    a failing install is reported as a warning and does not abort the remaining
    downloads. When DOWNLOAD is False (or the model manager is missing) the
    commands are only printed, copy-pasteable as before.
    """
    manager = audiocpp_dir / "tools" / "model_manager_v2.py"
    seen: Set[str] = set()
    install_ids: List[str] = []
    for _, install_id in install_guidance:
        if install_id not in seen:
            seen.add(install_id)
            install_ids.append(install_id)

    if download and not manager.is_file():
        print(f"[WARNING] {manager} not found; printing the install commands "
              "instead of running them")
        download = False

    for install_id in install_ids:
        command = f"python {manager} install {install_id}"
        if not download:
            print(command)
            continue
        print(f"[INFO] Downloading {install_id}...")
        try:
            result = subprocess.run(
                [sys.executable, str(manager), "install", install_id],
                cwd=str(audiocpp_dir))
        except OSError as exc:
            print(f"[WARNING] Could not run {command}: {exc}")
            continue
        if result.returncode != 0:
            print(f"[WARNING] install {install_id} exited with code "
                  f"{result.returncode}; the model may need to be downloaded "
                  "by hand")


def _decide_download(audiocpp_dir: Path,
                     confirm: Callable[[str, bool], bool]) -> bool:
    """Ask whether to download the selected models now.

    CONFIRM asks the yes/no question (ask_bool for the line prompts, a TUI
    confirm for the wizard). When the audio.cpp model manager is missing the
    prompt is skipped and False is returned, so the install commands are only
    printed rather than offered to run.
    """
    manager = audiocpp_dir / "tools" / "model_manager_v2.py"
    if not manager.is_file():
        return False
    return confirm(
        "Automatically download the selected models with model_manager_v2.py "
        "now?", False)


def _build_tree_families(catalog: List[dict]) -> List[dict]:
    """Shape the catalog into the checkbox_tree widget's family list."""
    families: List[dict] = []
    for entry in catalog:
        capabilities = ["tts"]
        if "clone" in entry["tasks"]:
            capabilities.append("cloning")
        if "design" in entry["tasks"]:
            capabilities.append("design")
        name = entry["display_name"]
        if name != entry["family"]:
            name = f"{name} ({entry['family']})"
        options = []
        for opt in package_dir_options(entry):
            options.append({
                "key": opt["target_directory"],
                "label": opt["install_id"],
                "recommended": opt["recommended"],
            })
        families.append({
            "label": name,
            "detail": ", ".join(capabilities),
            "options": options,
        })
    return families


def _wizard(stdscr, args: argparse.Namespace, parser: argparse.ArgumentParser
            ) -> Optional[dict]:
    """Run every TUI screen; return the collected settings, or None to abort.

    The wizard is a step state machine; each screen group is one step, and
    Esc anywhere but the first step falls back to the previous group (the
    widget returns the _GO_BACK sentinel, or a callback raises _GoBack). On
    the first screen (the audio.cpp checkout browser) Esc aborts the whole
    wizard as before.
    """

    def ask_confirm(question: str, default: bool) -> bool:
        result = tui.confirm(stdscr, question, default=default,
                             cancel_value=_GO_BACK)
        if result is _GO_BACK:
            raise _GoBack()
        return result

    step = 0
    while True:
        if step == 0:
            # Checkout browser + the output path/overwrite confirmation. The
            # browser asks for the checkout root and finds model_specs/ inside
            # it (picking the model_specs directory itself works too — its
            # parent is used). A highlighted subdirectory named "audio.cpp"
            # that already contains model_specs/ is auto-accepted on
            # Enter/Right, skipping the "[ Use this directory ]" step.
            # Pressing Esc on an overwrite confirmation returns here instead
            # of aborting: the browser then restarts inside the previously
            # accepted checkout with auto-accept disabled, so a wrong guess
            # can be corrected. An explicit --audiocpp-dir flag has no
            # browser to return to, so Esc still aborts there. Esc on the
            # browser itself is the first step, so it aborts the wizard.
            auto_accept = True
            browser_start: Path = Path.cwd()
            force_browse = False

            def do_browse():
                return tui.browse_directory(
                    stdscr, "Select your audio.cpp directory",
                    validate=lambda p: None if _resolve_audiocpp_root(p)
                    else "No model_specs/ directory here",
                    info=_audiocpp_root_status,
                    preview=_audiocpp_root_preview,
                    help_lines=["The root folder of your audio.cpp "
                                "checkout;",
                                "it is the one that contains "
                                "model_specs/"],
                    start=browser_start,
                    auto_select=_checkout_auto_select if auto_accept
                    else None)

            while True:
                audiocpp_dir = args.audiocpp_dir
                if audiocpp_dir is None and not force_browse:
                    audiocpp_dir = find_local_checkout()
                if force_browse:
                    audiocpp_dir = None
                if audiocpp_dir is None:
                    if force_browse:
                        # Esc on an overwrite confirmation came back here: go
                        # straight back into the browser inside the previously
                        # accepted checkout (auto-accept disabled).
                        audiocpp_dir = do_browse()
                    else:
                        # No checkout found anywhere: offer to clone one into
                        # ./audio.cpp or browse for an existing checkout. Esc
                        # on this first menu aborts the wizard.
                        choice = tui.menu(
                            stdscr, "No audio.cpp checkout found",
                            [(f"Clone into ./{AUDIOCPP_DIR_NAME} "
                              f"(from {AUDIOCPP_GIT_URL})", "clone"),
                             ("Browse for an existing checkout", "browse")],
                            help_lines=[
                                "audio.cpp hosts the TTS model families "
                                "this generator uses.",
                                "Clone it into the project directory, or "
                                "point at an existing checkout."])
                        if choice == "clone":
                            target = TTS_ROOT / AUDIOCPP_DIR_NAME
                            with tui.suspend(stdscr):
                                rc = common.git_clone(AUDIOCPP_GIT_URL,
                                                      target)
                            if rc != 0:
                                raise _TuiError(
                                    f"git clone failed (exit {rc}). Clone "
                                    f"audio.cpp manually: git clone "
                                    f"{AUDIOCPP_GIT_URL} {target}")
                            audiocpp_dir = target
                        else:
                            audiocpp_dir = do_browse()
                audiocpp_dir = Path(audiocpp_dir).resolve()
                if not audiocpp_dir.is_dir():
                    raise _TuiError(f"audio.cpp checkout not found: "
                                    f"{audiocpp_dir}")
                root = _resolve_audiocpp_root(audiocpp_dir)
                if root is None:
                    raise _TuiError(
                        f"{audiocpp_dir} has no model_specs/ directory; "
                        "select the root of your audio.cpp checkout")
                audiocpp_dir = root
                try:
                    catalog = load_model_catalog(audiocpp_dir)
                except NotADirectoryError as exc:
                    raise _TuiError(str(exc))
                if not catalog:
                    raise _TuiError(f"No TTS model families found in "
                                    f"{audiocpp_dir}/model_specs; check the "
                                    "checkout is up to date")
                catalog_by_family = {entry["family"]: entry
                                     for entry in catalog}

                output_path = args.output if args.output is not None \
                    else audiocpp_dir / "server.json"
                esc_back = args.audiocpp_dir is None
                went_back = False
                if not args.force and output_path.exists():
                    decision = tui.confirm(
                        stdscr, f"{output_path} already exists. Overwrite?",
                        default=True,
                        cancel_value=_GO_BACK if esc_back else None)
                    if decision is _GO_BACK:
                        went_back = True
                    elif decision is False:
                        if args.output is None:
                            output_path = Path.cwd() / "server.json"
                            if output_path.exists():
                                decision = tui.confirm(
                                    stdscr,
                                    f"{output_path} already exists. "
                                    "Overwrite?",
                                    default=True,
                                    cancel_value=_GO_BACK if esc_back else None)
                                if decision is _GO_BACK:
                                    went_back = True
                                elif decision is False:
                                    return None
                        else:
                            return None
                if went_back:
                    auto_accept = False
                    browser_start = audiocpp_dir
                    force_browse = True
                    continue
                break
            detected_backend = detect_backend(audiocpp_dir)
            step = 1
            continue

        if step == 1:
            # Families and packages (flag or tree). Esc returns to the
            # checkout browser (step 0).
            chosen: Dict[str, List[dict]] = {}
            if args.families is not None:
                requested = [f.strip() for f in args.families.split(",")
                             if f.strip()]
                unknown = [f for f in requested if f not in catalog_by_family]
                if unknown:
                    raise _TuiError(
                        f"Unknown family in --families: {', '.join(unknown)}. "
                        f"Available: {', '.join(catalog_by_family)}")
                family_keys: List[str] = []
                for family in requested:
                    if family not in family_keys:
                        family_keys.append(family)
                        chosen[family] = [opt for opt in package_dir_options(
                            catalog_by_family[family]) if opt["recommended"]]
            else:
                tree_families = _build_tree_families(catalog)
                picked = tui.checkbox_tree(
                    stdscr, "Select TTS model families to host",
                    tree_families, expand_all=args.all_packages,
                    back_value=_GO_BACK)
                if picked is _GO_BACK:
                    step = 0
                    continue
                family_keys = []
                for family_index, option_key in picked:
                    family = catalog[family_index]["family"]
                    if family not in chosen:
                        chosen[family] = []
                        family_keys.append(family)
                    chosen[family].append(option_key)
                for family in list(chosen):
                    keyed = {opt["target_directory"]: opt
                             for opt in package_dir_options(
                                 catalog_by_family[family])}
                    chosen[family] = [keyed[key] for key in chosen[family]]
            step = 2
            continue

        if step == 2:
            # Design task menus and duplicate-id renames. Esc anywhere here
            # falls back to the families tree (step 1).
            def task_picker(install_id: str) -> str:
                result = tui.menu(
                    stdscr,
                    f"How should the '{install_id}' package be hosted?",
                    [
                        ("design (vdes) - describe the voice with "
                         "--instructions", TASK_VDES),
                        ("tts - normal synthesis", TASK_TTS),
                    ], default_index=0, back_value=_GO_BACK)
                if result is _GO_BACK:
                    raise _GoBack()
                return result

            def id_picker(display_name: str, install_id: str,
                          default: str) -> str:
                result = tui.line_edit(
                    stdscr,
                    f"Server model id for {display_name} package "
                    f"'{install_id}'", default, back_value=_GO_BACK)
                if result is _GO_BACK:
                    raise _GoBack()
                return result

            try:
                model_entries, entry_ids, install_guidance, \
                    design_entry_ids, include_clone = _build_entries(
                        family_keys, chosen, catalog_by_family,
                        task_picker, id_picker)
            except _GoBack:
                step = 1
                continue
            step = 3
            continue

        if step == 3:
            # Server settings (host, port, port-sync, backend, lazy). Esc on
            # any of them falls back to the previous group (step 2).
            if args.host:
                host = args.host
            else:
                host = tui.line_edit(
                    stdscr, "Bind host", DEFAULT_HOST,
                    help_lines=["The IP address audiocpp will be hosted on",
                                "127.0.0.1 (this machine) is probably "
                                "correct"], back_value=_GO_BACK)
                if host is _GO_BACK:
                    step = 2
                    continue
            if args.port is not None:
                port = args.port
            else:
                port_text = tui.line_edit(
                    stdscr, "Port", str(config_port()),
                    validate=lambda s: None if (s.isdigit()
                                                and 1 <= int(s) <= 65535)
                    else "Enter a port number between 1 and 65535",
                    help_lines=["The port audiocpp will be hosted on"],
                    back_value=_GO_BACK)
                if port_text is _GO_BACK:
                    step = 2
                    continue
                port = int(port_text)
            sync_port: Optional[bool] = None
            if port != config_port():
                sync_port = tui.confirm(
                    stdscr, f"Update AUDIOCPP_API_URL in converter/config.py "
                    f"to port {port} so audiobook.py talks to this server",
                    default=True, cancel_value=_GO_BACK)
                if sync_port is _GO_BACK:
                    step = 2
                    continue
            if args.build_backend:
                backend = args.build_backend
                build = detected_backend is None
            elif args.backend:
                backend = args.backend
                build = False
            elif detected_backend is not None:
                # Already built: use the detected backend, no menu, no build.
                backend = detected_backend
                build = False
            else:
                backend_options, backend_default = _backend_options(None)
                backend = tui.menu(
                    stdscr, "Which inference backend was audiocpp_server "
                    "built for?", backend_options,
                    default_index=backend_default, back_value=_GO_BACK)
                if backend is _GO_BACK:
                    step = 2
                    continue
                # Not built for any backend yet: offer to build it now. The
                # build itself runs in the console tail after the wizard.
                build = tui.confirm(
                    stdscr, f"audiocpp_server is not built for {backend}. "
                    f"Build it now (runs scripts/build_*)?",
                    default=True, cancel_value=_GO_BACK)
                if build is _GO_BACK:
                    step = 2
                    continue
            default_lazy = len(model_entries) > 1
            if args.lazy_load:
                lazy_load = True
            else:
                lazy_load = tui.confirm(
                    stdscr, "Load models lazily (on first use instead of at "
                    "startup)", default=default_lazy, cancel_value=_GO_BACK)
                if lazy_load is _GO_BACK:
                    step = 2
                    continue
            step = 4
            continue

        if step == 4:
            # Wav directory (flag, browsed when cloning, else skipped). Esc
            # falls back to the server settings (step 3).
            if args.input_dir is not None:
                wav_dir = args.input_dir
            elif include_clone:
                wav_start = detect_wav_dir(audiocpp_dir, TTS_ROOT)
                wav_dir = tui.browse_directory(
                    stdscr, "Select the directory with your .wav voices",
                    info=_wav_dir_info, preview=_wav_dir_preview,
                    start=wav_start if wav_start is not None else Path.cwd(),
                    back_value=_GO_BACK)
                if wav_dir is _GO_BACK:
                    step = 3
                    continue
            else:
                wav_dir = None
            step = 5
            continue

        if step == 5:
            # Transcription plan (questions only; transcription runs after).
            # Esc falls back to the wav browser (step 4).
            plan: Optional[dict] = None
            if include_clone and wav_dir is not None:
                wav_files = find_wav_files(wav_dir)
                if wav_files:
                    prompt_path = wav_dir / PROMPT_TEXT_FILENAME
                    existing = read_prompt_text(prompt_path) if (
                        prompt_path.exists() and not args.force) else {}
                    try:
                        plan = _decide_transcription(
                            wav_files, existing, prompt_path.exists(),
                            args.force, ask_confirm)
                    except _GoBack:
                        step = 4
                        continue
            step = 6
            continue

        if step == 6:
            # Single-model id sync decision. Esc falls back to the
            # transcription plan (step 5).
            sync_model_ids: Optional[bool] = None
            if len(entry_ids) == 1 and not (
                    config.AUDIOCPP_MODEL_ID == entry_ids[0]
                    and config.AUDIOCPP_CLONE_MODEL_ID == entry_ids[0]):
                sync_model_ids = tui.confirm(
                    stdscr, "Update AUDIOCPP_MODEL_ID and "
                    "AUDIOCPP_CLONE_MODEL_ID in converter/config.py to "
                    f"'{entry_ids[0]}' so audiobook.py uses this model",
                    default=True, cancel_value=_GO_BACK)
                if sync_model_ids is _GO_BACK:
                    step = 5
                    continue
            step = 8
            continue

        if step == 8:
            # Automatic model download (or print the install commands). Esc
            # falls back to the model-id sync (step 6).
            try:
                download = _decide_download(audiocpp_dir, ask_confirm)
            except _GoBack:
                step = 6
                continue
            return {
                "audiocpp_dir": audiocpp_dir,
                "catalog": catalog,
                "catalog_by_family": catalog_by_family,
                "output_path": output_path,
                "family_keys": family_keys,
                "chosen": chosen,
                "model_entries": model_entries,
                "entry_ids": entry_ids,
                "install_guidance": install_guidance,
                "design_entry_ids": design_entry_ids,
                "include_clone": include_clone,
                "host": host,
                "port": port,
                "backend": backend,
                "build": build,
                "lazy_load": lazy_load,
                "sync_port": sync_port,
                "sync_model_ids": sync_model_ids,
                "wav_dir": wav_dir,
                "plan": plan,
                "download": download,
            }


def find_local_checkout() -> Optional[Path]:
    """Best-effort location of an audio.cpp checkout with model_specs.

    Checks the AUDIOCPP_DIR environment variable, then ``./audio.cpp`` inside
    the tts-audiobook-generator root, then an ``audio.cpp`` directory in or
    above the current working directory. Returns the path only when it
    contains a ``model_specs`` directory.
    """
    candidates: List[Path] = []
    env_dir = os.environ.get("AUDIOCPP_DIR")
    if env_dir:
        candidates.append(Path(os.path.expanduser(env_dir)))
    candidates.append(TTS_ROOT / AUDIOCPP_DIR_NAME)
    cwd = Path.cwd()
    candidates.append(cwd / AUDIOCPP_DIR_NAME)
    candidates.append(cwd.parent / AUDIOCPP_DIR_NAME)
    candidates.append(cwd.parent.parent / AUDIOCPP_DIR_NAME)
    for candidate in candidates:
        try:
            resolved = candidate.resolve()
        except OSError:
            continue
        if (resolved / "model_specs").is_dir():
            return resolved
    return None


def find_audiocpp_server_bin(audiocpp_dir: Path) -> Optional[Path]:
    """Return the built audiocpp_server binary, or None when not built.

    Scans ``audiocpp_dir/build/*`` for a build directory containing
    ``bin/audiocpp_server`` (``.exe`` allowed on Windows). When several
    builds exist the first (alphabetical) is returned.
    """
    build_root = audiocpp_dir / "build"
    if not build_root.is_dir():
        return None
    try:
        build_dirs = sorted(build_root.iterdir(),
                            key=lambda p: p.name.lower())
    except OSError:
        return None
    for build_dir in build_dirs:
        if not build_dir.is_dir():
            continue
        for name in ("audiocpp_server", "audiocpp_server.exe"):
            server = build_dir / "bin" / name
            if server.exists():
                return server
    return None


def find_build_script(audiocpp_dir: Path) -> Optional[Path]:
    """Return the audio.cpp build helper script to run, or None.

    Prefers ``scripts/build_linux.sh``; otherwise the first
    ``scripts/build_*.sh`` it finds. (Windows ``.bat`` scripts are not run
    automatically — build manually there.)
    """
    scripts = audiocpp_dir / "scripts"
    if not scripts.is_dir():
        return None
    preferred = scripts / "build_linux.sh"
    if preferred.exists():
        return preferred
    try:
        candidates = sorted(scripts.glob("build_*.sh"),
                            key=lambda p: p.name.lower())
    except OSError:
        return None
    return candidates[0] if candidates else None


def build_audiocpp(audiocpp_dir: Path, backend: str) -> int:
    """Build audiocpp_server for BACKEND, streaming output to the console.

    Returns the build script's exit code (non-zero when the script is
    missing). Run from a console context (after the TUI wizard returns, or
    inside ``tui.suspend``).
    """
    script = find_build_script(audiocpp_dir)
    if script is None:
        print(f"[ERROR] No build script found in {audiocpp_dir}/scripts; "
              "build audiocpp_server manually (see the audio.cpp README)")
        return 1
    print(f"[INFO] Building audiocpp_server for {backend} "
          f"({script} --backend {backend} --target audiocpp_server)...")
    return common.run_console_subprocess(
        ["sh", str(script), "--backend", backend, "--target",
         "audiocpp_server"],
        cwd=audiocpp_dir)


def _print_launch_hint(audiocpp_dir: Path, output_path: Path) -> None:
    """Print the exact command to start the server (or build guidance)."""
    binary = find_audiocpp_server_bin(audiocpp_dir)
    print()
    if binary is not None:
        print("Start the server with:")
        print(f"  {binary} --config {output_path}")
    else:
        print("[INFO] audiocpp_server binary not found. Build it first, e.g.:")
        script = find_build_script(audiocpp_dir)
        if script is not None:
            print(f"  sh {script} --backend <cuda|vulkan|hip|cpu> "
                  "--target audiocpp_server")
        print(f"  then run: ./build/<platform>-<backend>-release/bin/"
              f"audiocpp_server --config {output_path}")


def _execute(settings: dict, args: argparse.Namespace) -> int:
    """Shared console tail: build, sync, transcribe, write, install, advise.

    Runs after the TUI wizard returns (or after _collect_from_flags for a
    non-interactive run): the terminal is plain, so subprocess output and
    transcription progress appear normally.
    """
    audiocpp_dir = settings["audiocpp_dir"]

    # Build audiocpp_server first (the longest step), when requested.
    if settings.get("build"):
        rc = build_audiocpp(audiocpp_dir, settings["backend"])
        if rc != 0:
            print(f"[WARNING] build exited with code {rc}; the server.json "
                  "was still written — build audiocpp_server manually before "
                  "starting it")
        else:
            print("[OK] build complete")

    # Port sync (applied now that the terminal is back).
    if settings["sync_port"] is True:
        _apply_port_sync(settings["port"], True)
    elif settings["sync_port"] is False:
        _apply_port_sync(settings["port"], False)

    # Transcription (console; the questions were already answered).
    args.input_dir = settings["wav_dir"]
    if settings["include_clone"] and args.input_dir is not None:
        transcripts, write_prompt = _transcribe(args, True, plan=settings["plan"])
    elif args.input_dir is not None:
        print(f"[WARNING] Ignoring {args.input_dir}: no clone-capable family "
              "selected, so voice presets are not used")
        transcripts, write_prompt = {}, False
    else:
        transcripts, write_prompt = {}, False

    _write_and_advise(
        audiocpp_dir, settings["wav_dir"], settings["output_path"],
        settings["model_entries"], settings["install_guidance"],
        settings["host"], settings["port"], settings["backend"],
        settings["lazy_load"], transcripts, write_prompt)

    if len(settings["entry_ids"]) == 1:
        _offer_config_model_id_sync(settings["entry_ids"][0],
                                    settings["sync_model_ids"])
    print_empty_transcript_warning(transcripts)
    _install_models(audiocpp_dir, settings["install_guidance"],
                    settings["download"])
    _print_launch_hint(audiocpp_dir, settings["output_path"])
    return 0


def run_tui(args: Optional[argparse.Namespace] = None,
            parser: Optional[argparse.ArgumentParser] = None) -> int:
    """Run the audio.cpp setup wizard end-to-end.

    With no ARGS (the hub's call) a default namespace is built so the full
    wizard runs. Called from ``main`` after argparse when the terminal is
    interactive. Returns the process exit code.
    """
    import curses
    if args is None:
        parser = build_parser()
        args = parser.parse_args([])
        if args.input_dir is not None and not args.input_dir.is_dir():
            print(f"[ERROR] --wavs not found: {args.input_dir}",
                  file=sys.stderr)
            return 2
    try:
        settings = curses.wrapper(_wizard, args, parser)
    except _TuiError as exc:
        print(f"[ERROR] {exc}", file=sys.stderr)
        return 2
    except tui.WizardCancelled:
        print("\n[INFO] Cancelled; nothing was written")
        return 1
    try:
        curses.curs_set(1)  # restore the text cursor hidden by the TUI
    except curses.error:
        pass
    if settings is None:
        print("[INFO] Aborted; existing server.json kept")
        return 1
    return _execute(settings, args)


def _collect_from_flags(args: argparse.Namespace,
                        parser: argparse.ArgumentParser) -> Optional[dict]:
    """Build the settings dict from flags for a non-interactive run.

    Every required value must come from a flag (there are no prompts in a
    non-interactive run); a missing one is a hard ``parser.error``. Returns
    the settings dict, or None when the user declined an overwrite (the
    default-location fallback then also exists).
    """
    # Checkout: --audiocpp-dir, else a local checkout, else --clone clones one.
    audiocpp_dir = args.audiocpp_dir
    if audiocpp_dir is None:
        audiocpp_dir = find_local_checkout()
    if audiocpp_dir is None and args.clone:
        target = TTS_ROOT / AUDIOCPP_DIR_NAME
        rc = common.git_clone(AUDIOCPP_GIT_URL, target)
        if rc != 0:
            parser.error(f"git clone failed (exit {rc}); clone audio.cpp "
                         f"manually: git clone {AUDIOCPP_GIT_URL} {target}")
        audiocpp_dir = target
    if audiocpp_dir is None:
        parser.error(
            "An audio.cpp checkout is required. Pass --audiocpp-dir PATH, "
            "or --clone to clone ./audio.cpp, or run without flags for the "
            "TUI wizard.")
    audiocpp_dir = Path(audiocpp_dir).resolve()
    if not audiocpp_dir.is_dir():
        parser.error(f"audio.cpp checkout not found: {audiocpp_dir}")
    root = _resolve_audiocpp_root(audiocpp_dir)
    if root is None:
        parser.error(f"{audiocpp_dir} has no model_specs/ directory; point "
                     "--audiocpp-dir at the root of an audio.cpp checkout")
    audiocpp_dir = root
    try:
        catalog = load_model_catalog(audiocpp_dir)
    except NotADirectoryError as exc:
        parser.error(str(exc))
    if not catalog:
        parser.error(
            f"No TTS model families found in {audiocpp_dir}/model_specs; "
            "check the checkout is up to date")
    catalog_by_family = {entry["family"]: entry for entry in catalog}

    # Families: required from --families in a non-interactive run.
    if args.families is None:
        parser.error("--families is required in a non-interactive run (or run "
                     "without flags for the TUI wizard)")
    requested = [f.strip() for f in args.families.split(",") if f.strip()]
    unknown = [f for f in requested if f not in catalog_by_family]
    if unknown:
        parser.error(
            f"Unknown family in --families: {', '.join(unknown)}. "
            f"Available: {', '.join(catalog_by_family)}")
    family_keys: List[str] = []
    for fam in requested:
        if fam not in family_keys:
            family_keys.append(fam)

    chosen: Dict[str, List[dict]] = {}
    for family in family_keys:
        opts = package_dir_options(catalog_by_family[family])
        if args.all_packages:
            chosen[family] = opts
        else:
            chosen[family] = [opt for opt in opts if opt["recommended"]]

    # Non-interactive pickers: design packages default to vdes, dup ids get -2.
    def task_picker(install_id: str) -> str:
        return TASK_VDES

    def id_picker(display_name: str, install_id: str, default: str) -> str:
        return default

    model_entries, entry_ids, install_guidance, design_entry_ids, include_clone = \
        _build_entries(family_keys, chosen, catalog_by_family,
                       task_picker, id_picker)

    # Server settings.
    host = args.host or DEFAULT_HOST
    detected_backend = detect_backend(audiocpp_dir)
    if args.build_backend:
        backend = args.build_backend
        build = detected_backend is None
    elif args.backend:
        backend = args.backend
        build = False
    elif detected_backend is not None:
        backend = detected_backend
        build = False
    else:
        backend = "cuda"
        build = False
    port = args.port if args.port is not None else config_port()
    lazy_load = args.lazy_load if args.lazy_load else (len(model_entries) > 1)

    # Output path / overwrite (decline falls back to cwd, then aborts).
    output_path = args.output if args.output is not None \
        else audiocpp_dir / "server.json"
    if output_path.exists() and not args.force:
        if args.output is None:
            output_path = Path.cwd() / "server.json"
            if output_path.exists() and not args.force:
                print("[INFO] Aborted; existing server.json kept")
                return None
        else:
            print("[INFO] Aborted; existing server.json kept")
            return None

    # Config sync decisions (auto-apply unless explicitly declined).
    sync_port: Optional[bool] = None
    if port != config_port():
        sync_port = not args.no_sync_port
    sync_model_ids: Optional[bool] = None
    if len(entry_ids) == 1 and not (
            config.AUDIOCPP_MODEL_ID == entry_ids[0]
            and config.AUDIOCPP_CLONE_MODEL_ID == entry_ids[0]):
        sync_model_ids = not args.no_sync_model_ids

    # Wav dir + transcription plan.
    wav_dir = args.input_dir
    plan: Optional[dict] = None
    if include_clone and wav_dir is not None:
        wav_files = find_wav_files(wav_dir)
        if wav_files:
            prompt_path = wav_dir / PROMPT_TEXT_FILENAME
            plan = _flag_plan(wav_files, prompt_path, args.force)

    return {
        "audiocpp_dir": audiocpp_dir,
        "catalog": catalog,
        "catalog_by_family": catalog_by_family,
        "output_path": output_path,
        "family_keys": family_keys,
        "chosen": chosen,
        "model_entries": model_entries,
        "entry_ids": entry_ids,
        "install_guidance": install_guidance,
        "design_entry_ids": design_entry_ids,
        "include_clone": include_clone,
        "host": host,
        "port": port,
        "backend": backend,
        "build": build,
        "lazy_load": lazy_load,
        "sync_port": sync_port,
        "sync_model_ids": sync_model_ids,
        "wav_dir": wav_dir,
        "plan": plan,
        "download": args.download,
    }


def build_parser() -> argparse.ArgumentParser:
    """The audio.cpp setup CLI (also used to build a default namespace)."""
    parser = argparse.ArgumentParser(
        description="Set up the audio.cpp TTS backend: clone/build, pick "
                    "models, write server.json, and sync converter/config.py.")
    parser.add_argument("--wavs", type=resolve_wav_dir_arg, default=None,
                        dest="input_dir", metavar="WAV_DIR",
                        help="Directory with .wav reference files to publish as "
                             "a server-level voice_dir cloning library (asked "
                             "for when omitted in the TUI)")
    parser.add_argument("--output", type=Path, default=None,
                        help="Output path for server.json (default: "
                             "server.json inside the audio.cpp checkout; an "
                             "existing file is overwritten only with --force "
                             "or a TUI confirm)")
    parser.add_argument("--audiocpp-dir", type=normalize_dir_arg, default=None,
                        help="Path to a local audio.cpp checkout containing a "
                             "model_specs/ directory (default: detected from "
                             "AUDIOCPP_DIR or ./audio.cpp; in the TUI you can "
                             "clone one instead)")
    parser.add_argument("--clone", action="store_true",
                        help="Non-interactive: clone audio.cpp into "
                             "./audio.cpp when no checkout is found")
    parser.add_argument("--families", type=str, default=None,
                        help="Comma-separated model families to host, as named "
                             "in the audio.cpp catalog (e.g. "
                             "qwen3_tts,higgs_audio_tts). Required in a "
                             "non-interactive run; skips the family tree in "
                             "the TUI")
    parser.add_argument("--all-packages", action="store_true",
                        help="Host every installable package of each selected "
                             "family (distinct target_directory) instead of "
                             "only the recommended one. Voice-design packages "
                             "are hosted with task 'vdes'")
    parser.add_argument("--host", type=str, default=None,
                        help="Bind host for the server (default: 127.0.0.1)")
    parser.add_argument("--port", type=int, default=None,
                        help="Port for the server (default: the port in "
                             "AUDIOCPP_API_URL from converter/config.py)")
    parser.add_argument("--backend", choices=BACKENDS, default=None,
                        help="Inference backend recorded in server.json "
                             "(default: auto-detected from the checkout's "
                             "build/ directory, else cuda)")
    parser.add_argument("--build-backend", choices=BACKENDS, default=None,
                        help="Build audiocpp_server for this backend when it "
                             "is not built yet, and use it in server.json")
    parser.add_argument("--lazy-load", action="store_true",
                        help="Load models on first use instead of at startup "
                             "(default: on when more than one model is hosted)")
    parser.add_argument("--whisper-model", type=str, default="base",
                        help="Whisper model size for transcription "
                             "(default: base)")
    parser.add_argument("--force", action="store_true",
                        help="Overwrite the output file (and prompt_text) "
                             "without prompting")
    parser.add_argument("--download", action="store_true",
                        help="Run model_manager_v2.py install for each hosted "
                             "model automatically (default: print the commands "
                             "only)")
    parser.add_argument("--no-sync-port", action="store_true",
                        help="Do not rewrite AUDIOCPP_API_URL in "
                             "converter/config.py when --port differs")
    parser.add_argument("--no-sync-model-ids", action="store_true",
                        help="Do not rewrite AUDIOCPP_MODEL_ID/"
                             "AUDIOCPP_CLONE_MODEL_ID for a single-entry server")
    return parser


def detect() -> BackendStatus:
    """Detect how far audio.cpp is set up, plus the command to start it."""
    checkout = find_local_checkout()
    details: List[str] = []
    launch = ""
    if checkout is None:
        return BackendStatus("audiocpp", "audio.cpp", installed=False,
                             configured=False,
                             details=["not cloned — run setup to clone "
                                      "./audio.cpp"])
    details.append(f"checkout: {checkout}")
    binary = find_audiocpp_server_bin(checkout)
    built = binary is not None
    if built:
        details.append(f"built: {binary}")
    else:
        details.append("not built — run setup to build audiocpp_server")
    server_json = checkout / "server.json"
    configured = server_json.exists()
    if configured:
        details.append(f"config: {server_json}")
        launch = (f"{binary} --config {server_json}"
                  if built else
                  f"./build/<platform>-<backend>-release/bin/"
                  f"audiocpp_server --config {server_json}")
    else:
        details.append("no server.json — run setup to configure models")
    return BackendStatus("audiocpp", "audio.cpp", installed=built,
                         configured=configured, details=details,
                         launch_hint=launch)


modify_actions: List[ModifyAction] = [
    ModifyAction("Reconfigure audio.cpp (models, voices, server.json)",
                 run_tui),
]


def main() -> int:
    parser = build_parser()
    args = parser.parse_args()

    if args.input_dir is not None and not args.input_dir.is_dir():
        parser.error(
            f"WAV directory not found: {args.input_dir}\n"
            f"      (resolved from the current working directory: "
            f"{Path.cwd()})\n"
            "      --wavs must be a directory containing the .wav "
            "reference files to use as voice cloning presets")

    if _interactive():
        return run_tui(args, parser)

    # Non-interactive (no terminal, or all flags supplied): flag-only path.
    settings = _collect_from_flags(args, parser)
    if settings is None:
        return 1
    return _execute(settings, args)


if __name__ == "__main__":
    sys.exit(main())