Upload folder using huggingface_hub

.dockerignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+.env
+.git/
+.gitignore
+.gitattributes
+*.wav
+*.mp3
+*.opus
+*.aac
+*.flac
+*.pcm
+*.pt
+*.gguf
+*.onnx
+**/custom/*
+.vscode/
+.idea/

.env

@@ -0,0 +1,14 @@
+NEUTTS_HOST=0.0.0.0
+NEUTTS_PORT=7860
+NEUTTS_DEFAULT_MODELS=neutts-nano-q4-gguf
+NEUTTS_DEFAULT_CODEC=neuphonic/neucodec-onnx-decoder
+NEUTTS_DEFAULT_BACKBONE_DEVICE=cpu
+NEUTTS_DEFAULT_CODEC_DEVICE=cpu
+NEUTTS_DEFAULT_VOICE=jo
+NEUTTS_SAMPLE_RATE=24000
+NEUTTS_DEFAULT_RESPONSE_FORMAT=mp3
+NEUTTS_CORS_ENABLED=true
+NEUTTS_CORS_ORIGINS=["*"]
+NEUTTS_LOG_LEVEL=INFO
+NEUTTS_MAX_INFERENCE_WORKERS=4
+NEUTTS_ALLOW_VOICE_UPLOAD=true

.gitattributes

@@ -33,3 +33,8 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+api/src/voices/builtin/dave.wav filter=lfs diff=lfs merge=lfs -text
+api/src/voices/builtin/greta.wav filter=lfs diff=lfs merge=lfs -text
+api/src/voices/builtin/jo.wav filter=lfs diff=lfs merge=lfs -text
+api/src/voices/builtin/juliette.wav filter=lfs diff=lfs merge=lfs -text
+api/src/voices/builtin/mateo.wav filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,41 @@
+FROM python:3.10-slim
+
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    espeak-ng libespeak-ng-dev \
+    ffmpeg libsndfile1 \
+    git curl \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV PHONEMIZER_ESPEAK_LIBRARY=/usr/lib/x86_64-linux-gnu/libespeak-ng.so.1
+ENV ESPEAK_DATA_PATH=/usr/lib/x86_64-linux-gnu/espeak-ng-data
+
+ENV HF_HOME=/data/huggingface
+ENV NEUTTS_HOST=0.0.0.0
+ENV NEUTTS_PORT=7860
+ENV NEUTTS_DEFAULT_MODELS=neutts-nano-q4-gguf
+ENV NEUTTS_DEFAULT_CODEC=neuphonic/neucodec-onnx-decoder
+ENV NEUTTS_DEFAULT_BACKBONE_DEVICE=cpu
+ENV NEUTTS_DEFAULT_CODEC_DEVICE=cpu
+ENV NEUTTS_DEFAULT_VOICE=jo
+ENV NEUTTS_LOG_LEVEL=INFO
+ENV NEUTTS_CORS_ENABLED=true
+ENV NEUTTS_CORS_ORIGINS=["*"]
+
+RUN pip install --no-cache-dir uv
+
+WORKDIR /app
+
+COPY pyproject.toml .
+
+RUN uv pip install --system --no-cache-dir ".[cpu]"
+
+COPY . .
+
+RUN mkdir -p /data/huggingface /app/api/src/voices/custom
+
+EXPOSE 7860
+
+ENTRYPOINT ["bash", "entrypoint.sh"]

README.md

@@ -7,4 +7,36 @@ sdk: docker
 pinned: false
 ---
 
+# NeuTTS API on Hugging Face Spaces
+
+OpenAI-compatible Text-to-Speech API powered by NeuTTS.
+
+## Environment Variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `NEUTTS_DEFAULT_MODELS` | `neutts-nano-q4-gguf` | Comma-separated model IDs |
+| `NEUTTS_DEFAULT_CODEC` | `neuphonic/neucodec-onnx-decoder` | Codec model |
+| `NEUTTS_DEFAULT_VOICE` | `jo` | Default voice name |
+| `NEUTTS_DEFAULT_BACKBONE_DEVICE` | `cpu` | Device for backbone |
+| `NEUTTS_DEFAULT_CODEC_DEVICE` | `cpu` | Device for codec |
+| `NEUTTS_LOG_LEVEL` | `INFO` | Log level |
+| `NEUTTS_CORS_ENABLED` | `true` | Enable CORS |
+
+## API Usage
+
+The API is OpenAI-compatible:
+
+```bash
+curl -X POST "https://{your-space}.hf.space/v1/audio/speech" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "neutts-nano-q4-gguf",
+    "input": "Hello, world!",
+    "voice": "jo",
+    "response_format": "mp3"
+  }' \
+  --output speech.mp3
+```
+
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

api/src/core/config.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+import json
+from typing import Literal
+
+from pydantic import Field, field_validator
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    model_config = {"env_prefix": "NEUTTS_", "env_file": ".env", "extra": "ignore"}
+
+    # Server
+    host: str = "0.0.0.0"
+    port: int = 8880
+
+    # Models
+    default_models: str = "neutts-nano-q4-gguf"
+    default_codec: str = "neuphonic/neucodec-onnx-decoder"
+    default_backbone_device: Literal["auto", "cpu", "cuda"] = "auto"
+    default_codec_device: Literal["cpu", "cuda"] = "cpu"
+
+    # Voice
+    default_voice: str = "jo"
+
+    # Audio
+    sample_rate: int = 24000
+    default_response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] = "mp3"
+
+    # CORS
+    cors_enabled: bool = True
+    cors_origins: str = '["*"]'
+
+    # Logging
+    log_level: str = "INFO"
+
+    # Performance
+    max_inference_workers: int = 4
+
+    # Voice Upload
+    allow_voice_upload: bool = True
+
+    @field_validator("cors_origins", mode="before")
+    @classmethod
+    def parse_cors_origins(cls, v: str | list) -> str:
+        if isinstance(v, list):
+            return json.dumps(v)
+        return v
+
+    @property
+    def cors_origins_list(self) -> list[str]:
+        return json.loads(self.cors_origins)
+
+    @property
+    def default_models_list(self) -> list[str]:
+        return [m.strip() for m in self.default_models.split(",") if m.strip()]
+
+    @property
+    def resolved_backbone_device(self) -> str:
+        if self.default_backbone_device == "auto":
+            try:
+                import torch
+
+                return "cuda" if torch.cuda.is_available() else "cpu"
+            except ImportError:
+                return "cpu"
+        return self.default_backbone_device
+
+
+settings = Settings()

api/src/core/model_config.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class BackendType(str, Enum):
+    TORCH = "torch"
+    GGUF = "gguf"
+    ONNX = "onnx"
+
+
+@dataclass(frozen=True)
+class BackboneModelInfo:
+    model_id: str
+    repo: str
+    language: str
+    backend: BackendType
+    supports_streaming: bool
+    description: str
+
+
+@dataclass(frozen=True)
+class CodecModelInfo:
+    codec_id: str
+    repo: str
+    codec_type: str
+    description: str
+
+
+BACKBONE_MODELS: dict[str, BackboneModelInfo] = {
+    # NeuTTS-Air (English)
+    "neutts-air": BackboneModelInfo(
+        model_id="neutts-air",
+        repo="neuphonic/neutts-air",
+        language="en-us",
+        backend=BackendType.TORCH,
+        supports_streaming=False,
+        description="NeuTTS Air ~748M params, PyTorch",
+    ),
+    "neutts-air-q4-gguf": BackboneModelInfo(
+        model_id="neutts-air-q4-gguf",
+        repo="neuphonic/neutts-air-q4-gguf",
+        language="en-us",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Air Q4 quantized, GGUF",
+    ),
+    "neutts-air-q8-gguf": BackboneModelInfo(
+        model_id="neutts-air-q8-gguf",
+        repo="neuphonic/neutts-air-q8-gguf",
+        language="en-us",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Air Q8 quantized, GGUF",
+    ),
+    "neutts-air-onnx": BackboneModelInfo(
+        model_id="neutts-air-onnx",
+        repo="neuphonic/neutts-air-onnx",
+        language="en-us",
+        backend=BackendType.ONNX,
+        supports_streaming=False,
+        description="NeuTTS Air ONNX runtime",
+    ),
+    # NeuTTS-Nano (English)
+    "neutts-nano": BackboneModelInfo(
+        model_id="neutts-nano",
+        repo="neuphonic/neutts-nano",
+        language="en-us",
+        backend=BackendType.TORCH,
+        supports_streaming=False,
+        description="NeuTTS Nano ~120M params, PyTorch",
+    ),
+    "neutts-nano-q4-gguf": BackboneModelInfo(
+        model_id="neutts-nano-q4-gguf",
+        repo="neuphonic/neutts-nano-q4-gguf",
+        language="en-us",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano Q4 quantized, GGUF",
+    ),
+    "neutts-nano-q8-gguf": BackboneModelInfo(
+        model_id="neutts-nano-q8-gguf",
+        repo="neuphonic/neutts-nano-q8-gguf",
+        language="en-us",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano Q8 quantized, GGUF",
+    ),
+    # NeuTTS-Nano German
+    "neutts-nano-german": BackboneModelInfo(
+        model_id="neutts-nano-german",
+        repo="neuphonic/neutts-nano-german",
+        language="de",
+        backend=BackendType.TORCH,
+        supports_streaming=False,
+        description="NeuTTS Nano German, PyTorch",
+    ),
+    "neutts-nano-german-q4-gguf": BackboneModelInfo(
+        model_id="neutts-nano-german-q4-gguf",
+        repo="neuphonic/neutts-nano-german-q4-gguf",
+        language="de",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano German Q4 quantized, GGUF",
+    ),
+    "neutts-nano-german-q8-gguf": BackboneModelInfo(
+        model_id="neutts-nano-german-q8-gguf",
+        repo="neuphonic/neutts-nano-german-q8-gguf",
+        language="de",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano German Q8 quantized, GGUF",
+    ),
+    # NeuTTS-Nano French
+    "neutts-nano-french": BackboneModelInfo(
+        model_id="neutts-nano-french",
+        repo="neuphonic/neutts-nano-french",
+        language="fr-fr",
+        backend=BackendType.TORCH,
+        supports_streaming=False,
+        description="NeuTTS Nano French, PyTorch",
+    ),
+    "neutts-nano-french-q4-gguf": BackboneModelInfo(
+        model_id="neutts-nano-french-q4-gguf",
+        repo="neuphonic/neutts-nano-french-q4-gguf",
+        language="fr-fr",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano French Q4 quantized, GGUF",
+    ),
+    "neutts-nano-french-q8-gguf": BackboneModelInfo(
+        model_id="neutts-nano-french-q8-gguf",
+        repo="neuphonic/neutts-nano-french-q8-gguf",
+        language="fr-fr",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano French Q8 quantized, GGUF",
+    ),
+    # NeuTTS-Nano Spanish
+    "neutts-nano-spanish": BackboneModelInfo(
+        model_id="neutts-nano-spanish",
+        repo="neuphonic/neutts-nano-spanish",
+        language="es",
+        backend=BackendType.TORCH,
+        supports_streaming=False,
+        description="NeuTTS Nano Spanish, PyTorch",
+    ),
+    "neutts-nano-spanish-q4-gguf": BackboneModelInfo(
+        model_id="neutts-nano-spanish-q4-gguf",
+        repo="neuphonic/neutts-nano-spanish-q4-gguf",
+        language="es",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano Spanish Q4 quantized, GGUF",
+    ),
+    "neutts-nano-spanish-q8-gguf": BackboneModelInfo(
+        model_id="neutts-nano-spanish-q8-gguf",
+        repo="neuphonic/neutts-nano-spanish-q8-gguf",
+        language="es",
+        backend=BackendType.GGUF,
+        supports_streaming=True,
+        description="NeuTTS Nano Spanish Q8 quantized, GGUF",
+    ),
+}
+
+CODEC_MODELS: dict[str, CodecModelInfo] = {
+    "neuphonic/neucodec": CodecModelInfo(
+        codec_id="neuphonic/neucodec",
+        repo="neuphonic/neucodec",
+        codec_type="pytorch",
+        description="NeuCodec PyTorch (cpu/cuda)",
+    ),
+    "neuphonic/distill-neucodec": CodecModelInfo(
+        codec_id="neuphonic/distill-neucodec",
+        repo="neuphonic/distill-neucodec",
+        codec_type="pytorch",
+        description="Distilled NeuCodec PyTorch (cpu/cuda)",
+    ),
+    "neuphonic/neucodec-onnx-decoder": CodecModelInfo(
+        codec_id="neuphonic/neucodec-onnx-decoder",
+        repo="neuphonic/neucodec-onnx-decoder",
+        codec_type="onnx",
+        description="NeuCodec ONNX decoder (cpu)",
+    ),
+    "neuphonic/neucodec-onnx-decoder-int8": CodecModelInfo(
+        codec_id="neuphonic/neucodec-onnx-decoder-int8",
+        repo="neuphonic/neucodec-onnx-decoder-int8",
+        codec_type="onnx_int8",
+        description="NeuCodec ONNX INT8 decoder (cpu)",
+    ),
+}
+
+BUILTIN_VOICES: dict[str, dict] = {
+    "dave": {"language": "en-us", "gender": "male", "description": "English male voice"},
+    "jo": {"language": "en-us", "gender": "female", "description": "English female voice"},
+    "greta": {"language": "de", "gender": "female", "description": "German female voice"},
+    "hans": {"language": "de", "gender": "male", "description": "German male voice"},
+    "mateo": {"language": "es", "gender": "male", "description": "Spanish male voice"},
+    "elena": {"language": "es", "gender": "female", "description": "Spanish female voice"},
+    "juliette": {"language": "fr-fr", "gender": "female", "description": "French female voice"},
+    "pierre": {"language": "fr-fr", "gender": "male", "description": "French male voice"},
+}
+
+
+def get_backbone_info(model_id: str) -> BackboneModelInfo | None:
+    return BACKBONE_MODELS.get(model_id)
+
+
+def get_codec_info(codec_id: str) -> CodecModelInfo | None:
+    return CODEC_MODELS.get(codec_id)
+
+
+def get_voice_language(voice_name: str) -> str | None:
+    info = BUILTIN_VOICES.get(voice_name)
+    return info["language"] if info else None

api/src/core/paths.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+API_ROOT = PROJECT_ROOT / "api"
+SRC_ROOT = API_ROOT / "src"
+VOICES_DIR = SRC_ROOT / "voices"
+BUILTIN_VOICES_DIR = VOICES_DIR / "builtin"
+CUSTOM_VOICES_DIR = VOICES_DIR / "custom"
+
+
+def ensure_voice_dirs() -> None:
+    BUILTIN_VOICES_DIR.mkdir(parents=True, exist_ok=True)
+    CUSTOM_VOICES_DIR.mkdir(parents=True, exist_ok=True)
+
+
+def get_voice_wav(voice_name: str) -> Path | None:
+    for base in (BUILTIN_VOICES_DIR, CUSTOM_VOICES_DIR):
+        wav = base / f"{voice_name}.wav"
+        if wav.exists():
+            return wav
+    return None
+
+
+def get_voice_text(voice_name: str) -> Path | None:
+    for base in (BUILTIN_VOICES_DIR, CUSTOM_VOICES_DIR):
+        txt = base / f"{voice_name}.txt"
+        if txt.exists():
+            return txt
+    return None
+
+
+def get_voice_codes(voice_name: str, codec_id: str) -> Path | None:
+    codec_suffix = codec_id.replace("/", "_")
+    for base in (BUILTIN_VOICES_DIR, CUSTOM_VOICES_DIR):
+        pt = base / f"{voice_name}_{codec_suffix}.pt"
+        if pt.exists():
+            return pt
+    return None
+
+
+def voice_codes_path(voice_name: str, codec_id: str, custom: bool = False) -> Path:
+    codec_suffix = codec_id.replace("/", "_")
+    base = CUSTOM_VOICES_DIR if custom else BUILTIN_VOICES_DIR
+    return base / f"{voice_name}_{codec_suffix}.pt"
+
+
+def is_custom_voice(voice_name: str) -> bool:
+    return (CUSTOM_VOICES_DIR / f"{voice_name}.wav").exists()

api/src/inference/model_manager.py

@@ -0,0 +1,411 @@
+from __future__ import annotations
+
+import asyncio
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import AsyncGenerator
+
+import numpy as np
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.core.model_config import (
+    BACKBONE_MODELS,
+    BackendType,
+    get_backbone_info,
+)
+
+
+class ModelLoadStatus(str, Enum):
+    PENDING = "pending"
+    DOWNLOADING = "downloading"
+    LOADING = "loading"
+    READY = "ready"
+    ERROR = "error"
+
+
+@dataclass
+class ModelLoadingTask:
+    task_id: str
+    model_id: str
+    status: ModelLoadStatus = ModelLoadStatus.PENDING
+    progress_message: str = ""
+    error_message: str = ""
+    started_at: float = 0.0
+    completed_at: float = 0.0
+
+
+@dataclass
+class LoadedModel:
+    model_id: str
+    codec_id: str
+    tts_instance: object  # NeuTTS instance
+    lock: asyncio.Lock = field(default_factory=asyncio.Lock)
+    backbone_device: str = "cpu"
+    codec_device: str = "cpu"
+
+
+class ModelManager:
+    _instance: ModelManager | None = None
+
+    def __init__(self) -> None:
+        self._models: dict[str, LoadedModel] = {}
+        self._loading_tasks: dict[str, ModelLoadingTask] = {}
+        self._executor = ThreadPoolExecutor(max_workers=settings.max_inference_workers)
+
+    @classmethod
+    def get_instance(cls) -> ModelManager:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    @property
+    def loaded_models(self) -> dict[str, LoadedModel]:
+        return self._models
+
+    @property
+    def loading_tasks(self) -> dict[str, ModelLoadingTask]:
+        return self._loading_tasks
+
+    def is_loaded(self, model_id: str) -> bool:
+        return model_id in self._models
+
+    def get_task(self, task_id: str) -> ModelLoadingTask | None:
+        return self._loading_tasks.get(task_id)
+
+    async def load_model_async(
+        self,
+        model_id: str,
+        codec_id: str | None = None,
+        backbone_device: str | None = None,
+        codec_device: str | None = None,
+    ) -> ModelLoadingTask:
+        """Start loading a model in the background. Returns a task for polling."""
+        # Already loaded -> return READY task immediately
+        if model_id in self._models:
+            task = ModelLoadingTask(
+                task_id=str(uuid.uuid4()),
+                model_id=model_id,
+                status=ModelLoadStatus.READY,
+                progress_message="Already loaded",
+                started_at=time.time(),
+                completed_at=time.time(),
+            )
+            self._loading_tasks[task.task_id] = task
+            return task
+
+        # Already loading -> return existing task
+        for task in self._loading_tasks.values():
+            if task.model_id == model_id and task.status in (
+                ModelLoadStatus.PENDING,
+                ModelLoadStatus.DOWNLOADING,
+                ModelLoadStatus.LOADING,
+            ):
+                return task
+
+        info = get_backbone_info(model_id)
+        if info is None:
+            raise ValueError(f"Unknown model: {model_id}. Available: {list(BACKBONE_MODELS.keys())}")
+
+        task = ModelLoadingTask(
+            task_id=str(uuid.uuid4()),
+            model_id=model_id,
+            status=ModelLoadStatus.PENDING,
+            progress_message="Queued",
+            started_at=time.time(),
+        )
+        self._loading_tasks[task.task_id] = task
+
+        asyncio.ensure_future(
+            self._background_load(task, codec_id, backbone_device, codec_device)
+        )
+        return task
+
+    async def _background_load(
+        self,
+        task: ModelLoadingTask,
+        codec_id: str | None,
+        backbone_device: str | None,
+        codec_device: str | None,
+    ) -> None:
+        """Background coroutine that loads a model and updates task status."""
+        try:
+            task.status = ModelLoadStatus.DOWNLOADING
+            task.progress_message = "Downloading / checking cache..."
+
+            info = get_backbone_info(task.model_id)
+            if info is None:
+                raise ValueError(f"Unknown model: {task.model_id}")
+
+            codec = codec_id or settings.default_codec
+            bb_device = backbone_device or settings.resolved_backbone_device
+            cc_device = codec_device or settings.default_codec_device
+
+            # GGUF models only support CPU (llama.cpp limitation)
+            if info.backend == BackendType.GGUF:
+                bb_device = "cpu"
+
+            logger.info(
+                f"[Task {task.task_id[:8]}] Loading {task.model_id} "
+                f"(backbone_device={bb_device}, codec_device={cc_device})"
+            )
+
+            # Schedule status transition after 3s (heuristic for download vs load)
+            async def _mark_loading() -> None:
+                await asyncio.sleep(3)
+                if task.status == ModelLoadStatus.DOWNLOADING:
+                    task.status = ModelLoadStatus.LOADING
+                    task.progress_message = "Initializing model..."
+
+            timer_task = asyncio.ensure_future(_mark_loading())
+
+            loop = asyncio.get_event_loop()
+            tts = await loop.run_in_executor(
+                self._executor,
+                self._create_tts_instance,
+                info.repo,
+                codec,
+                bb_device,
+                cc_device,
+            )
+
+            timer_task.cancel()
+
+            loaded = LoadedModel(
+                model_id=task.model_id,
+                codec_id=codec,
+                tts_instance=tts,
+                backbone_device=bb_device,
+                codec_device=cc_device,
+            )
+            self._models[task.model_id] = loaded
+
+            task.status = ModelLoadStatus.READY
+            task.progress_message = "Model ready"
+            task.completed_at = time.time()
+            logger.info(f"[Task {task.task_id[:8]}] {task.model_id} loaded successfully")
+
+        except Exception as e:
+            task.status = ModelLoadStatus.ERROR
+            task.error_message = str(e)
+            task.progress_message = "Failed"
+            task.completed_at = time.time()
+            logger.error(f"[Task {task.task_id[:8]}] Failed to load {task.model_id}: {e}")
+
+    async def load_model(
+        self,
+        model_id: str,
+        codec_id: str | None = None,
+        backbone_device: str | None = None,
+        codec_device: str | None = None,
+    ) -> LoadedModel:
+        """Synchronous load (blocks until done). Used by startup."""
+        if model_id in self._models:
+            logger.info(f"Model {model_id} already loaded")
+            return self._models[model_id]
+
+        info = get_backbone_info(model_id)
+        if info is None:
+            raise ValueError(f"Unknown model: {model_id}. Available: {list(BACKBONE_MODELS.keys())}")
+
+        codec = codec_id or settings.default_codec
+        bb_device = backbone_device or settings.resolved_backbone_device
+        cc_device = codec_device or settings.default_codec_device
+
+        if info.backend == BackendType.GGUF:
+            bb_device = "cpu"
+
+        logger.info(
+            f"Loading model {model_id} (repo={info.repo}, codec={codec}, "
+            f"backbone_device={bb_device}, codec_device={cc_device})"
+        )
+
+        loop = asyncio.get_event_loop()
+        tts = await loop.run_in_executor(
+            self._executor,
+            self._create_tts_instance,
+            info.repo,
+            codec,
+            bb_device,
+            cc_device,
+        )
+
+        loaded = LoadedModel(
+            model_id=model_id,
+            codec_id=codec,
+            tts_instance=tts,
+            backbone_device=bb_device,
+            codec_device=cc_device,
+        )
+        self._models[model_id] = loaded
+        logger.info(f"Model {model_id} loaded successfully")
+        return loaded
+
+    @staticmethod
+    def _create_tts_instance(
+        backbone_repo: str,
+        codec_repo: str,
+        backbone_device: str,
+        codec_device: str,
+    ) -> object:
+        from neutts import NeuTTS
+
+        return NeuTTS(
+            backbone_repo=backbone_repo,
+            backbone_device=backbone_device,
+            codec_repo=codec_repo,
+            codec_device=codec_device,
+        )
+
+    async def unload_model(self, model_id: str) -> None:
+        if model_id not in self._models:
+            raise ValueError(f"Model {model_id} is not loaded")
+
+        loaded = self._models.pop(model_id)
+        async with loaded.lock:
+            del loaded.tts_instance
+        logger.info(f"Model {model_id} unloaded")
+
+    async def switch_device(
+        self,
+        model_id: str,
+        backbone_device: str | None = None,
+        codec_device: str | None = None,
+    ) -> ModelLoadingTask:
+        """Unload model and reload on a different device."""
+        if model_id not in self._models:
+            raise ValueError(f"Model {model_id} is not loaded")
+
+        loaded = self._models[model_id]
+        info = get_backbone_info(model_id)
+
+        if info and info.backend == BackendType.GGUF:
+            raise ValueError(
+                f"Model {model_id} is GGUF (llama.cpp) and only supports CPU. "
+                "Device switching is not available for GGUF models."
+            )
+
+        codec_id = loaded.codec_id
+        bb_device = backbone_device or loaded.backbone_device
+        cc_device = codec_device or loaded.codec_device
+
+        logger.info(f"Switching {model_id} device to backbone={bb_device}, codec={cc_device}")
+        await self.unload_model(model_id)
+
+        return await self.load_model_async(
+            model_id=model_id,
+            codec_id=codec_id,
+            backbone_device=bb_device,
+            codec_device=cc_device,
+        )
+
+    def cleanup_old_tasks(self, max_age_seconds: float = 3600) -> int:
+        """Remove completed/errored tasks older than max_age_seconds."""
+        now = time.time()
+        to_remove = [
+            tid
+            for tid, t in self._loading_tasks.items()
+            if t.status in (ModelLoadStatus.READY, ModelLoadStatus.ERROR)
+            and t.completed_at > 0
+            and (now - t.completed_at) > max_age_seconds
+        ]
+        for tid in to_remove:
+            del self._loading_tasks[tid]
+        return len(to_remove)
+
+    async def infer(
+        self,
+        model_id: str,
+        text: str,
+        ref_codes: object,
+        ref_text: str,
+    ) -> np.ndarray:
+        loaded = self._get_loaded(model_id)
+
+        async with loaded.lock:
+            loop = asyncio.get_event_loop()
+            wav = await loop.run_in_executor(
+                self._executor,
+                loaded.tts_instance.infer,
+                text,
+                ref_codes,
+                ref_text,
+            )
+        return wav
+
+    async def infer_stream(
+        self,
+        model_id: str,
+        text: str,
+        ref_codes: object,
+        ref_text: str,
+    ) -> AsyncGenerator[np.ndarray, None]:
+        loaded = self._get_loaded(model_id)
+        info = get_backbone_info(model_id)
+
+        if info is None or not info.supports_streaming:
+            raise ValueError(
+                f"Model {model_id} does not support streaming. "
+                "Only GGUF models support infer_stream()."
+            )
+
+        queue: asyncio.Queue[np.ndarray | None] = asyncio.Queue()
+
+        def _stream_worker() -> None:
+            try:
+                for chunk in loaded.tts_instance.infer_stream(text, ref_codes, ref_text):
+                    queue.put_nowait(chunk)
+            except Exception as e:
+                logger.error(f"Streaming error for {model_id}: {e}")
+            finally:
+                queue.put_nowait(None)
+
+        async with loaded.lock:
+            loop = asyncio.get_event_loop()
+            loop.run_in_executor(self._executor, _stream_worker)
+
+            while True:
+                chunk = await queue.get()
+                if chunk is None:
+                    break
+                yield chunk
+
+    async def encode_reference(self, model_id: str, audio_path: str) -> object:
+        loaded = self._get_loaded(model_id)
+
+        async with loaded.lock:
+            loop = asyncio.get_event_loop()
+            ref_codes = await loop.run_in_executor(
+                self._executor,
+                loaded.tts_instance.encode_reference,
+                audio_path,
+            )
+        return ref_codes
+
+    def _get_loaded(self, model_id: str) -> LoadedModel:
+        loaded = self._models.get(model_id)
+        if loaded is None:
+            raise ValueError(
+                f"Model {model_id} is not loaded. "
+                f"Loaded models: {list(self._models.keys())}"
+            )
+        return loaded
+
+    async def startup(self) -> None:
+        for model_id in settings.default_models_list:
+            try:
+                await self.load_model(model_id)
+            except Exception as e:
+                logger.error(f"Failed to load default model {model_id}: {e}")
+
+    async def shutdown(self) -> None:
+        model_ids = list(self._models.keys())
+        for model_id in model_ids:
+            try:
+                await self.unload_model(model_id)
+            except Exception:
+                pass
+        self._executor.shutdown(wait=False)

api/src/inference/text_chunker.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import re
+
+
+def split_into_sentences(text: str) -> list[str]:
+    """Split text into sentences at sentence boundaries."""
+    # Split on sentence-ending punctuation followed by whitespace
+    parts = re.split(r'(?<=[.!?;])\s+', text.strip())
+    return [p.strip() for p in parts if p.strip()]
+
+
+def chunk_text(text: str, max_chars: int = 500) -> list[str]:
+    """Split text into chunks suitable for TTS inference.
+
+    First splits by sentences, then groups sentences into chunks
+    that don't exceed max_chars. If a single sentence exceeds
+    max_chars, it's split at clause boundaries or word boundaries.
+    """
+    sentences = split_into_sentences(text)
+    if not sentences:
+        return [text] if text.strip() else []
+
+    chunks: list[str] = []
+    current = ""
+
+    for sentence in sentences:
+        if len(sentence) > max_chars:
+            # Flush current
+            if current:
+                chunks.append(current)
+                current = ""
+            # Split long sentence at clause boundaries
+            sub_parts = _split_long_sentence(sentence, max_chars)
+            chunks.extend(sub_parts)
+        elif len(current) + len(sentence) + 1 > max_chars:
+            if current:
+                chunks.append(current)
+            current = sentence
+        else:
+            current = f"{current} {sentence}".strip() if current else sentence
+
+    if current:
+        chunks.append(current)
+
+    return chunks
+
+
+def _split_long_sentence(sentence: str, max_chars: int) -> list[str]:
+    """Split a long sentence at commas or word boundaries."""
+    # Try splitting at commas first
+    parts = re.split(r',\s*', sentence)
+    if len(parts) > 1:
+        result: list[str] = []
+        current = ""
+        for part in parts:
+            candidate = f"{current}, {part}".strip(", ") if current else part
+            if len(candidate) > max_chars and current:
+                result.append(current)
+                current = part
+            else:
+                current = candidate
+        if current:
+            result.append(current)
+        return result
+
+    # Fallback: split at word boundaries
+    words = sentence.split()
+    result = []
+    current = ""
+    for word in words:
+        candidate = f"{current} {word}".strip() if current else word
+        if len(candidate) > max_chars and current:
+            result.append(current)
+            current = word
+        else:
+            current = candidate
+    if current:
+        result.append(current)
+
+    return result

api/src/inference/voice_manager.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+import torch
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.core.model_config import BUILTIN_VOICES
+from api.src.core.paths import (
+    BUILTIN_VOICES_DIR,
+    CUSTOM_VOICES_DIR,
+    ensure_voice_dirs,
+    get_voice_codes,
+    get_voice_text,
+    get_voice_wav,
+    is_custom_voice,
+    voice_codes_path,
+)
+
+
+class VoiceManager:
+    _instance: VoiceManager | None = None
+
+    def __init__(self) -> None:
+        self._voices: dict[str, dict] = {}
+
+    @classmethod
+    def get_instance(cls) -> VoiceManager:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    def scan_voices(self) -> None:
+        ensure_voice_dirs()
+        self._voices.clear()
+
+        # Built-in voices
+        for name, info in BUILTIN_VOICES.items():
+            wav_exists = get_voice_wav(name) is not None
+            txt_exists = get_voice_text(name) is not None
+            self._voices[name] = {
+                "name": name,
+                "language": info["language"],
+                "gender": info["gender"],
+                "description": info["description"],
+                "custom": False,
+                "available": wav_exists and txt_exists,
+            }
+
+        # Custom voices: scan for .wav files
+        for wav in CUSTOM_VOICES_DIR.glob("*.wav"):
+            name = wav.stem
+            if name not in self._voices:
+                txt_exists = get_voice_text(name) is not None
+                self._voices[name] = {
+                    "name": name,
+                    "language": "unknown",
+                    "gender": "unknown",
+                    "description": "Custom uploaded voice",
+                    "custom": True,
+                    "available": txt_exists,
+                }
+
+        available = sum(1 for v in self._voices.values() if v.get("available", True))
+        logger.info(
+            f"Scanned {len(self._voices)} voices ({len(BUILTIN_VOICES)} builtin, {available} available)"
+        )
+
+    @property
+    def voices(self) -> dict[str, dict]:
+        return self._voices
+
+    def voice_exists(self, voice_name: str) -> bool:
+        return voice_name in self._voices
+
+    def get_ref_text(self, voice_name: str) -> str:
+        txt_path = get_voice_text(voice_name)
+        if txt_path is None:
+            raise FileNotFoundError(f"No reference text found for voice '{voice_name}'")
+        return txt_path.read_text(encoding="utf-8").strip()
+
+    def get_ref_codes(self, voice_name: str, codec_id: str) -> torch.Tensor | None:
+        codes_path = get_voice_codes(voice_name, codec_id)
+        if codes_path is None:
+            return None
+        return torch.load(codes_path, map_location="cpu", weights_only=True)
+
+    async def get_or_encode_ref_codes(
+        self,
+        voice_name: str,
+        codec_id: str,
+        model_manager: object,
+        model_id: str,
+    ) -> object:
+        codes = self.get_ref_codes(voice_name, codec_id)
+        if codes is not None:
+            return codes
+
+        wav_path = get_voice_wav(voice_name)
+        if wav_path is None:
+            raise FileNotFoundError(f"No WAV file found for voice '{voice_name}'")
+
+        logger.info(f"Encoding reference for voice '{voice_name}' with codec '{codec_id}'")
+        ref_codes = await model_manager.encode_reference(model_id, str(wav_path))
+
+        # Cache the encoded reference
+        custom = is_custom_voice(voice_name)
+        save_path = voice_codes_path(voice_name, codec_id, custom=custom)
+        torch.save(ref_codes, save_path)
+        logger.info(f"Cached reference codes at {save_path}")
+
+        return ref_codes
+
+    def upload_voice(
+        self,
+        voice_name: str,
+        wav_data: bytes,
+        ref_text: str,
+        language: str = "unknown",
+        gender: str = "unknown",
+    ) -> Path:
+        ensure_voice_dirs()
+        wav_path = CUSTOM_VOICES_DIR / f"{voice_name}.wav"
+        txt_path = CUSTOM_VOICES_DIR / f"{voice_name}.txt"
+
+        wav_path.write_bytes(wav_data)
+        txt_path.write_text(ref_text, encoding="utf-8")
+
+        self._voices[voice_name] = {
+            "name": voice_name,
+            "language": language,
+            "gender": gender,
+            "description": "Custom uploaded voice",
+            "custom": True,
+            "available": True,
+        }
+
+        logger.info(f"Uploaded custom voice '{voice_name}' (lang={language}, gender={gender})")
+        return wav_path
+
+    def delete_voice(self, voice_name: str) -> None:
+        if voice_name in BUILTIN_VOICES:
+            raise ValueError(f"Cannot delete built-in voice '{voice_name}'")
+
+        if voice_name not in self._voices:
+            raise ValueError(f"Voice '{voice_name}' not found")
+
+        # Remove all files for this voice
+        for pattern in (f"{voice_name}.wav", f"{voice_name}.txt", f"{voice_name}_*.pt"):
+            for f in CUSTOM_VOICES_DIR.glob(pattern):
+                f.unlink()
+
+        self._voices.pop(voice_name, None)
+        logger.info(f"Deleted custom voice '{voice_name}'")

api/src/main.py

@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import FileResponse
+from fastapi.staticfiles import StaticFiles
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.voice_manager import VoiceManager
+from api.src.services.temp_manager import cleanup_temp
+
+# Configure loguru
+logger.remove()
+logger.add(
+    sys.stderr,
+    level=settings.log_level,
+    format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | <level>{level: <8}</level> | <cyan>{name}</cyan>:<cyan>{function}</cyan> - <level>{message}</level>",
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Application startup and shutdown events."""
+    logger.info("NeuTTS-FastAPI starting up...")
+
+    # Initialize voice manager
+    voice_manager = VoiceManager.get_instance()
+    voice_manager.scan_voices()
+
+    # GPU startup diagnostics
+    try:
+        import torch
+
+        torch_cuda_ok = torch.cuda.is_available()
+        if not torch_cuda_ok:
+            try:
+                result = subprocess.run(
+                    ["nvidia-smi", "--query-gpu=name,driver_version", "--format=csv,noheader,nounits"],
+                    capture_output=True, text=True, timeout=5,
+                )
+                if result.returncode == 0 and result.stdout.strip():
+                    from api.src.routers.debug import _build_gpu_fix_instructions
+                    line = result.stdout.strip().split("\n")[0]
+                    parts = [p.strip() for p in line.split(",")]
+                    gpu_name = parts[0]
+                    driver_ver = parts[1] if len(parts) > 1 else "unknown"
+                    fix = _build_gpu_fix_instructions(
+                        gpu_name, driver_ver, torch.__version__, torch.version.cuda,
+                    )
+                    logger.warning(f"GPU detected but unusable! Running on CPU only.\n{fix}")
+            except (FileNotFoundError, subprocess.TimeoutExpired):
+                pass
+    except ImportError:
+        pass
+
+    # Load default models
+    model_manager = ModelManager.get_instance()
+    await model_manager.startup()
+
+    logger.info(
+        f"Ready! Models: {list(model_manager.loaded_models.keys())}, "
+        f"Voices: {list(voice_manager.voices.keys())}"
+    )
+
+    yield
+
+    # Shutdown
+    logger.info("Shutting down...")
+    await model_manager.shutdown()
+    cleanup_temp()
+    logger.info("Shutdown complete")
+
+
+app = FastAPI(
+    title="NeuTTS-FastAPI",
+    description="OpenAI-compatible Text-to-Speech API powered by NeuTTS",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+# CORS
+if settings.cors_enabled:
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=settings.cors_origins_list,
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+# Register routers
+from api.src.routers import (
+    debug,
+    health,
+    model_management,
+    openai_compatible,
+    voice_management,
+    websocket,
+)
+
+# model_management first so /v1/models/registry is matched before /v1/models/{model_id}
+app.include_router(model_management.router)
+app.include_router(openai_compatible.router)
+app.include_router(voice_management.router)
+app.include_router(websocket.router)
+app.include_router(health.router)
+app.include_router(debug.router)
+
+# Serve Web UI
+_static_dir = Path(__file__).parent / "static"
+
+
+@app.get("/", include_in_schema=False)
+async def web_ui():
+    return FileResponse(_static_dir / "index.html")
+
+
+app.mount("/static", StaticFiles(directory=str(_static_dir)), name="static")
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    uvicorn.run(
+        "api.src.main:app",
+        host=settings.host,
+        port=settings.port,
+        log_level=settings.log_level.lower(),
+    )

api/src/routers/debug.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import platform
+import subprocess
+import sys
+
+import psutil
+from fastapi import APIRouter
+
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.voice_manager import VoiceManager
+from api.src.structures.schemas import SystemDebugResponse
+
+router = APIRouter(prefix="/debug", tags=["Debug"])
+
+
+def _nvidia_smi_info() -> dict | None:
+    """Run nvidia-smi and return GPU name + driver version, or None."""
+    try:
+        result = subprocess.run(
+            ["nvidia-smi", "--query-gpu=name,driver_version", "--format=csv,noheader,nounits"],
+            capture_output=True, text=True, timeout=5,
+        )
+        if result.returncode == 0 and result.stdout.strip():
+            line = result.stdout.strip().split("\n")[0]
+            parts = [p.strip() for p in line.split(",")]
+            return {"gpu_name": parts[0], "driver_version": parts[1] if len(parts) > 1 else "unknown"}
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        pass
+    return None
+
+
+def _build_gpu_fix_instructions(
+    gpu_name: str,
+    driver_version: str,
+    torch_ver: str | None,
+    cuda_ver: str | None,
+) -> str:
+    """Build OS-specific GPU fix instructions."""
+    os_name = platform.system()  # "Windows", "Linux", "Darwin"
+    is_docker = _is_running_in_docker()
+    python_ver = f"{sys.version_info.major}.{sys.version_info.minor}"
+
+    # Detect GPU generation from name
+    is_blackwell = any(x in gpu_name.upper() for x in ("RTX 50", "RTX50", "BLACKWELL", "GB2"))
+    is_ada = any(x in gpu_name.upper() for x in ("RTX 40", "RTX40", "ADA"))
+    needs_cu128 = is_blackwell
+    min_torch = "2.6.0" if is_blackwell else "2.1.0"
+    cu_tag = "cu128" if needs_cu128 else "cu124"
+
+    # Diagnosis
+    lines = [
+        f"GPU '{gpu_name}' detected (driver {driver_version}) but PyTorch cannot use it.",
+        f"Installed: torch=={torch_ver or 'not installed'}, CUDA=={cuda_ver or 'none'}.",
+    ]
+
+    if torch_ver is None:
+        lines.append("PyTorch is not installed at all.")
+    elif cuda_ver is None:
+        lines.append("PyTorch is installed but was built without CUDA (CPU-only build).")
+    elif is_blackwell and cuda_ver and cuda_ver < "12.8":
+        lines.append(f"RTX 50xx (Blackwell) requires CUDA >= 12.8, but torch has CUDA {cuda_ver}.")
+    else:
+        lines.append("PyTorch CUDA version may not match your GPU architecture.")
+
+    lines.append("")
+
+    # OS-specific fix
+    if is_docker:
+        lines.append("Fix (Docker): Rebuild with the updated Dockerfile (CUDA 12.8.0 base image):")
+        lines.append("  docker build -f docker/gpu/Dockerfile -t neutts-gpu .")
+    elif os_name == "Windows":
+        lines.append(f"Fix (Windows, Python {python_ver}):")
+        lines.append(f"  pip install torch>={min_torch} --index-url https://download.pytorch.org/whl/{cu_tag}")
+        lines.append("")
+        lines.append("Make sure you have the latest NVIDIA driver installed:")
+        lines.append("  https://www.nvidia.com/Download/index.aspx")
+        if is_blackwell:
+            lines.append("  RTX 50xx requires driver >= 572.16")
+    elif os_name == "Linux":
+        lines.append(f"Fix (Linux, Python {python_ver}):")
+        lines.append(f"  pip install torch>={min_torch} --index-url https://download.pytorch.org/whl/{cu_tag}")
+        lines.append("")
+        lines.append("Or with conda:")
+        lines.append(f"  conda install pytorch>={min_torch} pytorch-cuda=12.8 -c pytorch -c nvidia")
+        lines.append("")
+        lines.append("Verify NVIDIA driver: nvidia-smi")
+        if is_blackwell:
+            lines.append("  RTX 50xx requires driver >= 572.16")
+    else:
+        lines.append(f"Fix: pip install torch>={min_torch} --index-url https://download.pytorch.org/whl/{cu_tag}")
+
+    lines.append("")
+    lines.append("After installing, restart NeuTTS-FastAPI.")
+
+    return "\n".join(lines)
+
+
+def _is_running_in_docker() -> bool:
+    """Check if we're running inside a Docker container."""
+    try:
+        with open("/proc/1/cgroup", "r") as f:
+            return "docker" in f.read()
+    except (FileNotFoundError, PermissionError):
+        pass
+    try:
+        from pathlib import Path
+        return Path("/.dockerenv").exists()
+    except Exception:
+        pass
+    return False
+
+
+@router.get("/system", response_model=SystemDebugResponse)
+async def system_info() -> SystemDebugResponse:
+    """Return system resource usage and loaded model info."""
+    model_manager = ModelManager.get_instance()
+    voice_manager = VoiceManager.get_instance()
+
+    mem = psutil.virtual_memory()
+
+    gpu_available = False
+    gpu_info = None
+    torch_version = None
+    cuda_version = None
+    cuda_driver_version = None
+    gpu_detected_but_unusable = False
+    gpu_fix_instructions = None
+
+    try:
+        import torch
+
+        torch_version = torch.__version__
+        cuda_version = torch.version.cuda
+
+        if torch.cuda.is_available():
+            gpu_available = True
+            gpu_info = []
+            for i in range(torch.cuda.device_count()):
+                props = torch.cuda.get_device_properties(i)
+                allocated = torch.cuda.memory_allocated(i) / (1024**3)
+                total = props.total_mem / (1024**3)
+                gpu_info.append({
+                    "index": i,
+                    "name": props.name,
+                    "total_gb": round(total, 2),
+                    "allocated_gb": round(allocated, 2),
+                })
+    except ImportError:
+        pass
+
+    # Check nvidia-smi for GPU detection even if torch can't use it
+    smi = _nvidia_smi_info()
+    if smi:
+        cuda_driver_version = smi["driver_version"]
+        if not gpu_available:
+            gpu_detected_but_unusable = True
+            gpu_fix_instructions = _build_gpu_fix_instructions(
+                smi["gpu_name"], smi["driver_version"], torch_version, cuda_version,
+            )
+
+    return SystemDebugResponse(
+        cpu_count=psutil.cpu_count() or 0,
+        cpu_percent=psutil.cpu_percent(),
+        memory_total_gb=round(mem.total / (1024**3), 2),
+        memory_used_gb=round(mem.used / (1024**3), 2),
+        memory_percent=mem.percent,
+        gpu_available=gpu_available,
+        gpu_info=gpu_info,
+        torch_version=torch_version,
+        cuda_version=cuda_version,
+        cuda_driver_version=cuda_driver_version,
+        gpu_detected_but_unusable=gpu_detected_but_unusable,
+        gpu_fix_instructions=gpu_fix_instructions,
+        models_loaded=list(model_manager.loaded_models.keys()),
+        voices_available=len(voice_manager.voices),
+    )

api/src/routers/health.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from fastapi import APIRouter
+
+from api.src.inference.model_manager import ModelManager
+from api.src.structures.schemas import HealthResponse
+
+router = APIRouter(tags=["Health"])
+
+
+@router.get("/health", response_model=HealthResponse)
+async def health_check() -> HealthResponse:
+    model_manager = ModelManager.get_instance()
+    return HealthResponse(
+        status="ok",
+        version="0.1.0",
+        models_loaded=len(model_manager.loaded_models),
+    )

api/src/routers/model_management.py

@@ -0,0 +1,166 @@
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter, HTTPException
+from loguru import logger
+
+from api.src.core.model_config import BACKBONE_MODELS, CODEC_MODELS, get_backbone_info
+from api.src.inference.model_manager import ModelLoadingTask, ModelManager
+from api.src.structures.schemas import (
+    LoadedModelInfo,
+    LoadedModelsResponse,
+    LoadModelRequest,
+    ModelLoadTaskResponse,
+    ModelRegistryResponse,
+    RegistryModelInfo,
+    SwitchDeviceRequest,
+    UnloadModelResponse,
+    make_error,
+)
+
+router = APIRouter(prefix="/v1/models", tags=["Model Management"])
+
+
+def _task_to_response(task: ModelLoadingTask) -> ModelLoadTaskResponse:
+    elapsed = 0.0
+    if task.started_at > 0:
+        end = task.completed_at if task.completed_at > 0 else time.time()
+        elapsed = round(end - task.started_at, 2)
+    return ModelLoadTaskResponse(
+        task_id=task.task_id,
+        model_id=task.model_id,
+        status=task.status.value,
+        progress_message=task.progress_message,
+        error_message=task.error_message,
+        elapsed_seconds=elapsed,
+    )
+
+
+@router.post("/load", response_model=ModelLoadTaskResponse)
+async def load_model(request: LoadModelRequest) -> ModelLoadTaskResponse:
+    """Start loading a model (non-blocking). Returns a task for polling."""
+    model_manager = ModelManager.get_instance()
+    info = get_backbone_info(request.model_id)
+
+    if info is None:
+        raise HTTPException(
+            status_code=400,
+            detail=make_error(
+                f"Unknown model '{request.model_id}'. "
+                f"Available: {list(BACKBONE_MODELS.keys())}"
+            ),
+        )
+
+    try:
+        task = await model_manager.load_model_async(
+            model_id=request.model_id,
+            codec_id=request.codec,
+            backbone_device=request.backbone_device,
+            codec_device=request.codec_device,
+        )
+        # Cleanup old tasks opportunistically
+        model_manager.cleanup_old_tasks()
+        return _task_to_response(task)
+    except Exception as e:
+        logger.error(f"Failed to start loading model {request.model_id}: {e}")
+        raise HTTPException(status_code=500, detail=make_error(str(e), "server_error", 500))
+
+
+@router.get("/load/{task_id}", response_model=ModelLoadTaskResponse)
+async def get_load_status(task_id: str) -> ModelLoadTaskResponse:
+    """Poll the status of a model loading task."""
+    model_manager = ModelManager.get_instance()
+    task = model_manager.get_task(task_id)
+
+    if task is None:
+        raise HTTPException(
+            status_code=404,
+            detail=make_error(f"Task '{task_id}' not found"),
+        )
+
+    return _task_to_response(task)
+
+
+@router.get("/loaded", response_model=LoadedModelsResponse)
+async def get_loaded_models() -> LoadedModelsResponse:
+    """List all loaded models with device details."""
+    model_manager = ModelManager.get_instance()
+    models = []
+
+    for model_id, loaded in model_manager.loaded_models.items():
+        info = get_backbone_info(model_id)
+        models.append(LoadedModelInfo(
+            model_id=model_id,
+            codec=loaded.codec_id,
+            backbone_device=loaded.backbone_device,
+            codec_device=loaded.codec_device,
+            language=info.language if info else None,
+            backend=info.backend.value if info else None,
+            supports_streaming=info.supports_streaming if info else False,
+        ))
+
+    return LoadedModelsResponse(models=models)
+
+
+@router.post("/{model_id}/switch-device", response_model=ModelLoadTaskResponse)
+async def switch_device(model_id: str, request: SwitchDeviceRequest) -> ModelLoadTaskResponse:
+    """Switch a loaded model to a different device (CPU <-> GPU)."""
+    model_manager = ModelManager.get_instance()
+
+    try:
+        task = await model_manager.switch_device(
+            model_id=model_id,
+            backbone_device=request.backbone_device,
+            codec_device=request.codec_device,
+        )
+        return _task_to_response(task)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=make_error(str(e)))
+    except Exception as e:
+        logger.error(f"Failed to switch device for {model_id}: {e}")
+        raise HTTPException(status_code=500, detail=make_error(str(e), "server_error", 500))
+
+
+@router.delete("/{model_id}", response_model=UnloadModelResponse)
+async def unload_model(model_id: str) -> UnloadModelResponse:
+    """Unload a model from memory."""
+    model_manager = ModelManager.get_instance()
+
+    try:
+        await model_manager.unload_model(model_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=make_error(str(e)))
+
+    return UnloadModelResponse(model_id=model_id, status="unloaded")
+
+
+@router.get("/registry", response_model=ModelRegistryResponse)
+async def get_registry() -> ModelRegistryResponse:
+    """List all available models (not just loaded ones)."""
+    model_manager = ModelManager.get_instance()
+
+    backbones = [
+        RegistryModelInfo(
+            model_id=info.model_id,
+            repo=info.repo,
+            language=info.language,
+            backend=info.backend.value,
+            supports_streaming=info.supports_streaming,
+            description=info.description,
+            loaded=model_manager.is_loaded(info.model_id),
+        )
+        for info in BACKBONE_MODELS.values()
+    ]
+
+    codecs = [
+        {
+            "codec_id": c.codec_id,
+            "repo": c.repo,
+            "type": c.codec_type,
+            "description": c.description,
+        }
+        for c in CODEC_MODELS.values()
+    ]
+
+    return ModelRegistryResponse(backbones=backbones, codecs=codecs)

api/src/routers/openai_compatible.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import time
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import Response, StreamingResponse
+from loguru import logger
+
+from api.src.core.model_config import get_backbone_info
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.voice_manager import VoiceManager
+from api.src.services.streaming_audio_writer import get_content_type
+from api.src.services.tts_service import TTSService
+from api.src.structures.schemas import (
+    ModelDetailResponse,
+    ModelInfo,
+    ModelListResponse,
+    OpenAISpeechRequest,
+    VoiceInfo,
+    VoiceListResponse,
+    make_error,
+)
+
+router = APIRouter(prefix="/v1", tags=["OpenAI Compatible"])
+
+
+@router.post("/audio/speech")
+async def create_speech(request: OpenAISpeechRequest) -> Response:
+    """OpenAI-compatible TTS endpoint."""
+    model_manager = ModelManager.get_instance()
+    voice_manager = VoiceManager.get_instance()
+    tts_service = TTSService.get_instance()
+
+    # Validate model
+    if not model_manager.is_loaded(request.model):
+        raise HTTPException(status_code=400, detail=make_error(
+            f"Model '{request.model}' is not loaded. "
+            f"Available: {list(model_manager.loaded_models.keys())}"
+        ))
+
+    # Validate voice
+    if not voice_manager.voice_exists(request.voice):
+        raise HTTPException(status_code=400, detail=make_error(
+            f"Voice '{request.voice}' not found. "
+            f"Available: {list(voice_manager.voices.keys())}"
+        ))
+
+    content_type = get_content_type(request.response_format)
+
+    try:
+        if request.stream:
+            return StreamingResponse(
+                tts_service.stream_speech(request),
+                media_type=content_type,
+                headers={
+                    "Content-Type": content_type,
+                    "Transfer-Encoding": "chunked",
+                },
+            )
+        else:
+            start = time.perf_counter()
+            audio_data = await tts_service.generate_speech(request)
+            elapsed = time.perf_counter() - start
+            logger.info(
+                f"TTS: model={request.model} voice={request.voice} "
+                f"format={request.response_format} chars={len(request.input)} "
+                f"time={elapsed:.2f}s size={len(audio_data)} bytes"
+            )
+            return Response(
+                content=audio_data,
+                media_type=content_type,
+                headers={"Content-Type": content_type},
+            )
+    except Exception as e:
+        logger.error(f"TTS generation failed: {e}")
+        raise HTTPException(status_code=500, detail=make_error(str(e), "server_error", 500))
+
+
+@router.get("/audio/voices", response_model=VoiceListResponse)
+async def list_voices() -> VoiceListResponse:
+    """List available voices."""
+    voice_manager = VoiceManager.get_instance()
+    voices = [
+        VoiceInfo(
+            voice_id=name,
+            name=name,
+            language=info["language"],
+            gender=info["gender"],
+            custom=info.get("custom", False),
+            available=info.get("available", True),
+        )
+        for name, info in voice_manager.voices.items()
+    ]
+    return VoiceListResponse(voices=voices)
+
+
+@router.get("/models", response_model=ModelListResponse)
+async def list_models() -> ModelListResponse:
+    """List loaded models (OpenAI-compatible)."""
+    model_manager = ModelManager.get_instance()
+    models = []
+    for model_id, loaded in model_manager.loaded_models.items():
+        info = get_backbone_info(model_id)
+        models.append(ModelInfo(
+            id=model_id,
+            language=info.language if info else None,
+            backend=info.backend.value if info else None,
+            supports_streaming=info.supports_streaming if info else False,
+            backbone_device=loaded.backbone_device,
+            codec_device=loaded.codec_device,
+        ))
+    return ModelListResponse(data=models)
+
+
+@router.get("/models/{model_id}", response_model=ModelDetailResponse)
+async def get_model(model_id: str) -> ModelDetailResponse:
+    """Get details about a specific model."""
+    model_manager = ModelManager.get_instance()
+    info = get_backbone_info(model_id)
+
+    if info is None:
+        raise HTTPException(status_code=404, detail=make_error(f"Model '{model_id}' not found"))
+
+    loaded = model_manager.loaded_models.get(model_id)
+    return ModelDetailResponse(
+        id=model_id,
+        language=info.language,
+        backend=info.backend.value,
+        supports_streaming=info.supports_streaming,
+        loaded=loaded is not None,
+        codec=loaded.codec_id if loaded else None,
+    )

api/src/routers/voice_management.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException, UploadFile, File, Form
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.voice_manager import VoiceManager
+from api.src.services.audio_utils import validate_reference_audio
+from api.src.structures.schemas import (
+    VoiceDeleteResponse,
+    VoiceEncodeRequest,
+    VoiceEncodeResponse,
+    VoiceUploadResponse,
+    make_error,
+)
+
+router = APIRouter(prefix="/v1/audio/voices", tags=["Voice Management"])
+
+
+@router.post("/upload", response_model=VoiceUploadResponse)
+async def upload_voice(
+    voice_id: str = Form(...),
+    ref_text: str = Form(...),
+    audio: UploadFile = File(...),
+    language: str = Form("unknown"),
+    gender: str = Form("unknown"),
+) -> VoiceUploadResponse:
+    """Upload a custom voice reference (WAV + transcription text)."""
+    if not settings.allow_voice_upload:
+        raise HTTPException(status_code=403, detail=make_error("Voice upload is disabled"))
+
+    voice_manager = VoiceManager.get_instance()
+
+    # Check name is valid
+    if not voice_id.isalnum() and not all(c.isalnum() or c in "-_" for c in voice_id):
+        raise HTTPException(
+            status_code=400,
+            detail=make_error("Voice ID must be alphanumeric (hyphens/underscores allowed)"),
+        )
+
+    if voice_manager.voice_exists(voice_id):
+        raise HTTPException(
+            status_code=409,
+            detail=make_error(f"Voice '{voice_id}' already exists"),
+        )
+
+    # Read and validate audio
+    wav_data = await audio.read()
+    try:
+        props = validate_reference_audio(wav_data)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=make_error(str(e)))
+
+    voice_manager.upload_voice(voice_id, wav_data, ref_text, language=language, gender=gender)
+
+    return VoiceUploadResponse(
+        voice_id=voice_id,
+        status="uploaded",
+        message=f"Voice uploaded ({props['duration']:.1f}s, {props['sample_rate']}Hz)",
+        language=language,
+        gender=gender,
+    )
+
+
+@router.post("/{voice_id}/encode", response_model=VoiceEncodeResponse)
+async def encode_voice(voice_id: str, request: VoiceEncodeRequest | None = None) -> VoiceEncodeResponse:
+    """Pre-encode a voice reference for a specific codec."""
+    voice_manager = VoiceManager.get_instance()
+    model_manager = ModelManager.get_instance()
+
+    if not voice_manager.voice_exists(voice_id):
+        raise HTTPException(status_code=404, detail=make_error(f"Voice '{voice_id}' not found"))
+
+    # Use first loaded model to encode
+    if not model_manager.loaded_models:
+        raise HTTPException(
+            status_code=400,
+            detail=make_error("No models loaded. Load a model first."),
+        )
+
+    model_id = next(iter(model_manager.loaded_models))
+    loaded = model_manager.loaded_models[model_id]
+    codec = (request.codec if request and request.codec else loaded.codec_id)
+
+    try:
+        await voice_manager.get_or_encode_ref_codes(
+            voice_id, codec, model_manager, model_id
+        )
+    except Exception as e:
+        raise HTTPException(status_code=500, detail=make_error(str(e), "server_error", 500))
+
+    return VoiceEncodeResponse(voice_id=voice_id, codec=codec, status="encoded")
+
+
+@router.delete("/{voice_id}", response_model=VoiceDeleteResponse)
+async def delete_voice(voice_id: str) -> VoiceDeleteResponse:
+    """Delete a custom voice."""
+    voice_manager = VoiceManager.get_instance()
+
+    try:
+        voice_manager.delete_voice(voice_id)
+    except ValueError as e:
+        raise HTTPException(status_code=400, detail=make_error(str(e)))
+
+    return VoiceDeleteResponse(voice_id=voice_id, status="deleted")

api/src/routers/websocket.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import base64
+import json
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.voice_manager import VoiceManager
+from api.src.services.streaming_audio_writer import StreamingAudioWriter
+from api.src.structures.websocket_schemas import (
+    WSResponseMessage,
+    WSStartMessage,
+)
+
+router = APIRouter(tags=["WebSocket"])
+
+
+@router.websocket("/v1/audio/speech/stream")
+async def websocket_tts(ws: WebSocket) -> None:
+    """WebSocket endpoint for real-time TTS streaming.
+
+    Protocol:
+    1. Client sends: {"type": "start", "model": "...", "voice": "...", "response_format": "pcm"}
+    2. Client sends: {"type": "text", "text": "Hello world"}
+    3. Server streams: {"type": "audio", "data": "<base64>", "format": "pcm"}
+    4. Server sends: {"type": "done"}
+    5. Client sends: {"type": "stop"} or more text messages
+    """
+    await ws.accept()
+    logger.info("WebSocket connection accepted")
+
+    model_manager = ModelManager.get_instance()
+    voice_manager = VoiceManager.get_instance()
+
+    session_config: WSStartMessage | None = None
+
+    try:
+        while True:
+            raw = await ws.receive_text()
+            msg = json.loads(raw)
+            msg_type = msg.get("type")
+
+            if msg_type == "ping":
+                await ws.send_text(json.dumps({"type": "pong"}))
+                continue
+
+            if msg_type == "start":
+                session_config = WSStartMessage(**msg)
+
+                # Validate model
+                if not model_manager.is_loaded(session_config.model):
+                    await _send_error(ws, f"Model '{session_config.model}' is not loaded")
+                    continue
+
+                if not voice_manager.voice_exists(session_config.voice):
+                    await _send_error(ws, f"Voice '{session_config.voice}' not found")
+                    continue
+
+                logger.info(
+                    f"WS session started: model={session_config.model} "
+                    f"voice={session_config.voice} format={session_config.response_format}"
+                )
+                continue
+
+            if msg_type == "text":
+                if session_config is None:
+                    await _send_error(ws, "Send a 'start' message first")
+                    continue
+
+                text = msg.get("text", "").strip()
+                if not text:
+                    await _send_error(ws, "Empty text")
+                    continue
+
+                await _handle_text(ws, session_config, text, model_manager, voice_manager)
+
+            elif msg_type == "stop":
+                logger.info("WS session stopped by client")
+                break
+
+    except WebSocketDisconnect:
+        logger.info("WebSocket disconnected")
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+        try:
+            await _send_error(ws, str(e))
+        except Exception:
+            pass
+
+
+async def _handle_text(
+    ws: WebSocket,
+    config: WSStartMessage,
+    text: str,
+    model_manager: ModelManager,
+    voice_manager: VoiceManager,
+) -> None:
+    loaded = model_manager.loaded_models[config.model]
+    ref_codes = await voice_manager.get_or_encode_ref_codes(
+        config.voice, loaded.codec_id, model_manager, config.model
+    )
+    ref_text = voice_manager.get_ref_text(config.voice)
+
+    from api.src.core.model_config import get_backbone_info
+
+    info = get_backbone_info(config.model)
+    writer = StreamingAudioWriter(config.response_format, settings.sample_rate)
+
+    try:
+        if info and info.supports_streaming:
+            async for chunk in model_manager.infer_stream(
+                config.model, text, ref_codes, ref_text
+            ):
+                encoded = writer.write_chunk(chunk)
+                if encoded:
+                    await ws.send_text(json.dumps({
+                        "type": "audio",
+                        "data": base64.b64encode(encoded).decode(),
+                        "format": config.response_format,
+                    }))
+        else:
+            wav = await model_manager.infer(config.model, text, ref_codes, ref_text)
+            encoded = writer.write_chunk(wav)
+            if encoded:
+                await ws.send_text(json.dumps({
+                    "type": "audio",
+                    "data": base64.b64encode(encoded).decode(),
+                    "format": config.response_format,
+                }))
+
+        final = writer.finalize()
+        if final:
+            await ws.send_text(json.dumps({
+                "type": "audio",
+                "data": base64.b64encode(final).decode(),
+                "format": config.response_format,
+            }))
+
+        await ws.send_text(json.dumps({"type": "done"}))
+
+    finally:
+        writer.close()
+
+
+async def _send_error(ws: WebSocket, message: str) -> None:
+    await ws.send_text(json.dumps({"type": "error", "message": message}))

api/src/services/audio_utils.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import io
+
+import numpy as np
+import soundfile as sf
+
+
+def validate_wav(data: bytes) -> dict:
+    """Validate a WAV file and return its properties."""
+    buf = io.BytesIO(data)
+    try:
+        info = sf.info(buf)
+    except Exception as e:
+        raise ValueError(f"Invalid WAV file: {e}") from e
+
+    return {
+        "sample_rate": info.samplerate,
+        "channels": info.channels,
+        "duration": info.duration,
+        "frames": info.frames,
+        "format": info.format,
+    }
+
+
+def validate_reference_audio(data: bytes) -> dict:
+    """Validate reference audio for voice cloning.
+
+    Requirements:
+    - Mono channel
+    - 16-44 kHz sample rate
+    - 3-15 seconds duration
+    """
+    props = validate_wav(data)
+
+    if props["channels"] != 1:
+        raise ValueError(
+            f"Reference audio must be mono (1 channel), got {props['channels']} channels"
+        )
+
+    if not (8000 <= props["sample_rate"] <= 48000):
+        raise ValueError(
+            f"Reference audio sample rate must be 8-48 kHz, got {props['sample_rate']} Hz"
+        )
+
+    if props["duration"] < 1.0:
+        raise ValueError(
+            f"Reference audio too short ({props['duration']:.1f}s), minimum 1 second"
+        )
+
+    if props["duration"] > 30.0:
+        raise ValueError(
+            f"Reference audio too long ({props['duration']:.1f}s), maximum 30 seconds"
+        )
+
+    return props
+
+
+def pcm_to_wav_bytes(pcm_data: np.ndarray, sample_rate: int = 24000) -> bytes:
+    """Convert float32 PCM numpy array to WAV bytes."""
+    buf = io.BytesIO()
+    sf.write(buf, pcm_data, sample_rate, format="WAV", subtype="PCM_16")
+    buf.seek(0)
+    return buf.read()

api/src/services/streaming_audio_writer.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+import io
+from typing import Literal
+
+import av
+import numpy as np
+
+AudioFormat = Literal["mp3", "opus", "aac", "flac", "wav", "pcm"]
+
+# Mapping from our format names to PyAV codec/container names
+FORMAT_CONFIG: dict[str, dict] = {
+    "mp3": {"codec": "mp3", "container": "mp3", "content_type": "audio/mpeg"},
+    "opus": {"codec": "libopus", "container": "ogg", "content_type": "audio/ogg"},
+    "aac": {"codec": "aac", "container": "adts", "content_type": "audio/aac"},
+    "flac": {"codec": "flac", "container": "flac", "content_type": "audio/flac"},
+    "wav": {"codec": "pcm_s16le", "container": "wav", "content_type": "audio/wav"},
+    "pcm": {"codec": None, "container": None, "content_type": "audio/pcm"},
+}
+
+
+def get_content_type(fmt: AudioFormat) -> str:
+    return FORMAT_CONFIG[fmt]["content_type"]
+
+
+class StreamingAudioWriter:
+    """Encodes raw PCM audio (float32, mono) into various formats using PyAV."""
+
+    def __init__(self, fmt: AudioFormat, sample_rate: int = 24000) -> None:
+        self.format = fmt
+        self.sample_rate = sample_rate
+        self._buffer = io.BytesIO()
+
+        if fmt == "pcm":
+            # No encoding needed for raw PCM
+            self._container = None
+            self._stream = None
+        else:
+            config = FORMAT_CONFIG[fmt]
+            self._container = av.open(self._buffer, mode="w", format=config["container"])
+            self._stream = self._container.add_stream(config["codec"], rate=sample_rate)
+            self._stream.layout = "mono"
+            if fmt == "opus":
+                self._stream.rate = 48000  # Opus requires 48kHz
+
+    def write_chunk(self, pcm_data: np.ndarray) -> bytes:
+        """Encode a chunk of float32 PCM audio and return the encoded bytes."""
+        if self.format == "pcm":
+            # Convert float32 to int16 PCM
+            pcm_int16 = (pcm_data * 32767).astype(np.int16)
+            return pcm_int16.tobytes()
+
+        # Convert float32 [-1.0, 1.0] to int16
+        pcm_int16 = (np.clip(pcm_data, -1.0, 1.0) * 32767).astype(np.int16)
+
+        frame = av.AudioFrame.from_ndarray(
+            pcm_int16.reshape(1, -1),
+            format="s16",
+            layout="mono",
+        )
+        frame.sample_rate = self.sample_rate
+        if self.format == "opus":
+            frame.sample_rate = 48000
+
+        start_pos = self._buffer.tell()
+        for packet in self._stream.encode(frame):
+            self._container.mux(packet)
+
+        # Read newly written bytes
+        self._buffer.seek(start_pos)
+        data = self._buffer.read()
+        return data
+
+    def finalize(self) -> bytes:
+        """Flush remaining encoded data and close the container."""
+        if self.format == "pcm" or self._container is None:
+            return b""
+
+        start_pos = self._buffer.tell()
+
+        # Flush encoder
+        for packet in self._stream.encode(None):
+            self._container.mux(packet)
+
+        self._container.close()
+
+        self._buffer.seek(start_pos)
+        data = self._buffer.read()
+        return data
+
+    def close(self) -> None:
+        if self._container is not None:
+            try:
+                self._container.close()
+            except Exception:
+                pass
+        self._buffer.close()
+
+
+def encode_audio_complete(
+    pcm_data: np.ndarray,
+    fmt: AudioFormat,
+    sample_rate: int = 24000,
+) -> bytes:
+    """Encode a complete PCM float32 array to the specified audio format."""
+    if fmt == "pcm":
+        return (pcm_data * 32767).astype(np.int16).tobytes()
+
+    buf = io.BytesIO()
+    config = FORMAT_CONFIG[fmt]
+    container = av.open(buf, mode="w", format=config["container"])
+    stream = container.add_stream(config["codec"], rate=sample_rate)
+    stream.layout = "mono"
+
+    actual_rate = 48000 if fmt == "opus" else sample_rate
+    if fmt == "opus":
+        stream.rate = 48000
+
+    pcm_int16 = (np.clip(pcm_data, -1.0, 1.0) * 32767).astype(np.int16)
+    frame = av.AudioFrame.from_ndarray(
+        pcm_int16.reshape(1, -1),
+        format="s16",
+        layout="mono",
+    )
+    frame.sample_rate = actual_rate
+
+    for packet in stream.encode(frame):
+        container.mux(packet)
+    for packet in stream.encode(None):
+        container.mux(packet)
+    container.close()
+
+    buf.seek(0)
+    return buf.read()

api/src/services/temp_manager.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from loguru import logger
+
+_temp_dir: Path | None = None
+
+
+def get_temp_dir() -> Path:
+    global _temp_dir
+    if _temp_dir is None:
+        _temp_dir = Path(tempfile.mkdtemp(prefix="neutts_"))
+        logger.info(f"Created temp directory: {_temp_dir}")
+    _temp_dir.mkdir(parents=True, exist_ok=True)
+    return _temp_dir
+
+
+def cleanup_temp() -> None:
+    global _temp_dir
+    if _temp_dir is not None and _temp_dir.exists():
+        import shutil
+
+        shutil.rmtree(_temp_dir, ignore_errors=True)
+        logger.info(f"Cleaned up temp directory: {_temp_dir}")
+        _temp_dir = None

api/src/services/tts_service.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import AsyncGenerator
+
+import numpy as np
+from loguru import logger
+
+from api.src.core.config import settings
+from api.src.core.model_config import BackendType, get_backbone_info
+from api.src.inference.model_manager import ModelManager
+from api.src.inference.text_chunker import chunk_text
+from api.src.inference.voice_manager import VoiceManager
+from api.src.services.streaming_audio_writer import (
+    AudioFormat,
+    StreamingAudioWriter,
+    encode_audio_complete,
+)
+from api.src.structures.schemas import OpenAISpeechRequest
+
+
+def _apply_speed(wav: np.ndarray, speed: float) -> np.ndarray:
+    """Adjust audio playback speed via resampling."""
+    if speed == 1.0:
+        return wav
+    # Resample: fewer samples = faster, more samples = slower
+    new_length = int(len(wav) / speed)
+    indices = np.linspace(0, len(wav) - 1, new_length)
+    return np.interp(indices, np.arange(len(wav)), wav).astype(np.float32)
+
+
+class TTSService:
+    _instance: TTSService | None = None
+
+    def __init__(self) -> None:
+        self._model_manager = ModelManager.get_instance()
+        self._voice_manager = VoiceManager.get_instance()
+
+    @classmethod
+    def get_instance(cls) -> TTSService:
+        if cls._instance is None:
+            cls._instance = cls()
+        return cls._instance
+
+    async def generate_speech(self, request: OpenAISpeechRequest) -> bytes:
+        """Generate complete audio from text."""
+        model_id = request.model
+        voice = request.voice
+        fmt: AudioFormat = request.response_format
+
+        # Ensure model is loaded
+        if not self._model_manager.is_loaded(model_id):
+            raise ValueError(f"Model '{model_id}' is not loaded")
+
+        loaded = self._model_manager.loaded_models[model_id]
+
+        # Get voice reference
+        ref_codes = await self._voice_manager.get_or_encode_ref_codes(
+            voice, loaded.codec_id, self._model_manager, model_id
+        )
+        ref_text = self._voice_manager.get_ref_text(voice)
+
+        # For short text, single inference
+        text = request.input.strip()
+        info = get_backbone_info(model_id)
+
+        if len(text) <= 500 or info is None:
+            wav = await self._model_manager.infer(model_id, text, ref_codes, ref_text)
+            wav = _apply_speed(wav, request.speed)
+            return encode_audio_complete(wav, fmt, settings.sample_rate)
+
+        # For long text, chunk and concatenate
+        chunks = chunk_text(text)
+        wav_parts: list[np.ndarray] = []
+
+        for chunk in chunks:
+            wav = await self._model_manager.infer(model_id, chunk, ref_codes, ref_text)
+            wav_parts.append(wav)
+
+        full_wav = np.concatenate(wav_parts)
+        full_wav = _apply_speed(full_wav, request.speed)
+        return encode_audio_complete(full_wav, fmt, settings.sample_rate)
+
+    async def stream_speech(
+        self, request: OpenAISpeechRequest
+    ) -> AsyncGenerator[bytes, None]:
+        """Stream audio chunks as they are generated."""
+        model_id = request.model
+        voice = request.voice
+        fmt: AudioFormat = request.response_format
+
+        if not self._model_manager.is_loaded(model_id):
+            raise ValueError(f"Model '{model_id}' is not loaded")
+
+        loaded = self._model_manager.loaded_models[model_id]
+        info = get_backbone_info(model_id)
+
+        ref_codes = await self._voice_manager.get_or_encode_ref_codes(
+            voice, loaded.codec_id, self._model_manager, model_id
+        )
+        ref_text = self._voice_manager.get_ref_text(voice)
+
+        text = request.input.strip()
+        writer = StreamingAudioWriter(fmt, settings.sample_rate)
+
+        speed = request.speed
+
+        try:
+            if info and info.supports_streaming:
+                # Real streaming with GGUF models
+                async for chunk in self._model_manager.infer_stream(
+                    model_id, text, ref_codes, ref_text
+                ):
+                    chunk = _apply_speed(chunk, speed)
+                    encoded = writer.write_chunk(chunk)
+                    if encoded:
+                        yield encoded
+            else:
+                # Pseudo-streaming: chunk text, infer per chunk
+                chunks = chunk_text(text)
+                for chunk in chunks:
+                    wav = await self._model_manager.infer(
+                        model_id, chunk, ref_codes, ref_text
+                    )
+                    wav = _apply_speed(wav, speed)
+                    encoded = writer.write_chunk(wav)
+                    if encoded:
+                        yield encoded
+
+            # Finalize
+            final = writer.finalize()
+            if final:
+                yield final
+        finally:
+            writer.close()

api/src/static/index.html

@@ -0,0 +1,1693 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>NeuTTS-FastAPI</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+    <style>
+        :root {
+            --bg: #0f172a;
+            --fg: #7c6aef;
+            --fg2: #a78bfa;
+            --surface: rgba(30, 41, 59, 1);
+            --surface2: rgba(15, 23, 42, 0.5);
+            --text: #f8fafc;
+            --text-dim: #94a3b8;
+            --border: rgba(148, 163, 184, 0.15);
+            --success: #4ade80;
+            --error: #f87171;
+            --warning: #fbbf24;
+            --radius: 12px;
+            --font: 'Inter', system-ui, -apple-system, sans-serif;
+        }
+        * { margin: 0; padding: 0; box-sizing: border-box; }
+        html { width: 100%; height: 100%; overflow-x: hidden; }
+        body {
+            font-family: var(--font);
+            background: var(--bg);
+            color: var(--text);
+            min-height: 100vh;
+            line-height: 1.5;
+        }
+
+        /* Background effects */
+        .bg-glow {
+            position: fixed; inset: 0; pointer-events: none; z-index: 0;
+            background: radial-gradient(ellipse at 20% 0%, rgba(124,106,239,0.15) 0%, transparent 60%),
+                        radial-gradient(ellipse at 80% 100%, rgba(167,139,250,0.08) 0%, transparent 50%);
+        }
+        .bg-grid {
+            position: fixed; inset: 0; pointer-events: none; z-index: 0;
+            background-image:
+                repeating-linear-gradient(0deg, rgba(255,255,255,0.02) 0px, rgba(255,255,255,0.02) 1px, transparent 1px, transparent 24px),
+                repeating-linear-gradient(90deg, rgba(255,255,255,0.02) 0px, rgba(255,255,255,0.02) 1px, transparent 1px, transparent 24px);
+        }
+
+        .app { position: relative; z-index: 1; max-width: 1100px; margin: 0 auto; padding: 2rem 1.5rem; }
+
+        /* Header */
+        header { text-align: center; margin-bottom: 2rem; }
+        .logo {
+            font-size: 2.2rem; font-weight: 700;
+            background: linear-gradient(135deg, var(--fg), var(--fg2), #c084fc);
+            -webkit-background-clip: text; -webkit-text-fill-color: transparent;
+        }
+        .subtitle { color: var(--text-dim); font-size: 0.9rem; margin-top: 4px; }
+        .badges { display: flex; gap: 8px; justify-content: center; margin-top: 12px; flex-wrap: wrap; }
+        .badge {
+            display: flex; align-items: center; gap: 6px;
+            background: var(--surface); border: 1px solid var(--border);
+            border-radius: 20px; padding: 5px 12px; font-size: 0.75rem; color: var(--text-dim);
+        }
+        .dot { width: 7px; height: 7px; border-radius: 50%; }
+        .dot-ok { background: var(--success); box-shadow: 0 0 6px var(--success); }
+        .dot-off { background: var(--error); }
+        .dot-warn { background: var(--warning); }
+
+        /* Device badge */
+        .device-badge {
+            display: inline-flex; align-items: center; gap: 5px;
+            padding: 5px 12px; border-radius: 20px; font-size: 0.75rem; font-weight: 600;
+            background: var(--surface); border: 1px solid var(--border);
+        }
+        .device-badge.gpu {
+            color: #4ade80; border-color: rgba(74,222,128,0.3);
+            background: rgba(74,222,128,0.08);
+        }
+        .device-badge.cpu {
+            color: var(--text-dim); border-color: var(--border);
+        }
+        .device-badge svg { width: 14px; height: 14px; }
+
+        /* GPU Warning Banner */
+        .gpu-warning {
+            background: rgba(251,191,36,0.1); border: 1px solid rgba(251,191,36,0.3);
+            border-radius: var(--radius); padding: 14px 18px; margin-bottom: 1.5rem;
+            display: flex; align-items: flex-start; gap: 12px;
+            font-size: 0.85rem; color: var(--warning); line-height: 1.5;
+        }
+        .gpu-warning-icon { font-size: 1.2rem; flex-shrink: 0; margin-top: 1px; }
+        .gpu-warning-content { flex: 1; }
+        .gpu-warning-title { font-weight: 700; margin-bottom: 4px; }
+        .gpu-warning-text { font-size: 0.78rem; opacity: 0.9; white-space: pre-wrap; font-family: 'Consolas', 'Monaco', monospace; }
+        .gpu-warning-dismiss {
+            background: none; border: 1px solid rgba(251,191,36,0.3); border-radius: 4px;
+            color: var(--warning); cursor: pointer; padding: 2px 8px; font-size: 0.72rem;
+            font-family: var(--font); flex-shrink: 0; transition: all 0.2s;
+        }
+        .gpu-warning-dismiss:hover { background: rgba(251,191,36,0.15); }
+
+        /* Layout */
+        .main-grid {
+            display: grid;
+            grid-template-columns: 1fr 340px;
+            gap: 1.5rem;
+            align-items: start;
+        }
+        @media (max-width: 860px) {
+            .main-grid { grid-template-columns: 1fr; }
+        }
+
+        /* Cards */
+        .card {
+            background: var(--surface);
+            border: 1px solid var(--border);
+            border-radius: var(--radius);
+            padding: 1.25rem;
+        }
+        .card-label {
+            font-size: 0.72rem; font-weight: 600; text-transform: uppercase;
+            letter-spacing: 0.6px; color: var(--text-dim); margin-bottom: 12px;
+        }
+
+        /* Text Editor */
+        .text-editor textarea {
+            width: 100%; min-height: 180px;
+            background: var(--surface2); border: 1px solid var(--border);
+            border-radius: 8px; padding: 14px; color: var(--text);
+            font-size: 0.95rem; font-family: var(--font); resize: vertical;
+            transition: border-color 0.2s;
+        }
+        .text-editor textarea:focus { outline: none; border-color: var(--fg); }
+        .text-meta {
+            display: flex; justify-content: space-between; align-items: center;
+            margin-top: 6px; font-size: 0.72rem; color: var(--text-dim);
+        }
+        .text-meta kbd {
+            background: var(--surface2); border: 1px solid var(--border);
+            border-radius: 4px; padding: 1px 5px; font-size: 0.68rem;
+        }
+
+        /* Player */
+        .player { margin-top: 1.25rem; }
+        .player-bar {
+            display: flex; align-items: center; gap: 10px;
+            background: var(--surface2); border: 1px solid var(--border);
+            border-radius: 10px; padding: 8px 12px; height: 48px;
+        }
+        .player-btn {
+            width: 36px; height: 36px; border-radius: 50%;
+            background: var(--fg); border: none; cursor: pointer;
+            display: flex; align-items: center; justify-content: center;
+            transition: all 0.2s; flex-shrink: 0;
+        }
+        .player-btn:hover { transform: scale(1.08); box-shadow: 0 0 16px rgba(124,106,239,0.3); }
+        .player-btn svg { fill: white; width: 16px; height: 16px; }
+        .seek-wrap { flex: 1; min-width: 0; }
+        .seek-slider {
+            -webkit-appearance: none; width: 100%; height: 4px;
+            background: rgba(124,106,239,0.2); border-radius: 2px;
+            outline: none; cursor: pointer;
+        }
+        .seek-slider::-webkit-slider-thumb {
+            -webkit-appearance: none; width: 14px; height: 14px;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+            transition: transform 0.15s;
+        }
+        .seek-slider::-webkit-slider-thumb:hover { transform: scale(1.2); }
+        .seek-slider::-moz-range-thumb {
+            width: 14px; height: 14px; border: none;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+        }
+        .time-display {
+            font-size: 0.78rem; color: var(--text-dim); min-width: 80px;
+            text-align: center; font-variant-numeric: tabular-nums;
+            border-left: 1px solid var(--border); padding-left: 10px;
+        }
+        .vol-group {
+            display: flex; align-items: center; gap: 6px;
+            border-left: 1px solid var(--border); padding-left: 10px;
+        }
+        .vol-icon { color: var(--fg); opacity: 0.7; flex-shrink: 0; }
+        .vol-slider {
+            -webkit-appearance: none; width: 70px; height: 4px;
+            background: rgba(124,106,239,0.2); border-radius: 2px;
+            outline: none; cursor: pointer;
+        }
+        .vol-slider::-webkit-slider-thumb {
+            -webkit-appearance: none; width: 12px; height: 12px;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+        }
+        .vol-slider::-moz-range-thumb {
+            width: 12px; height: 12px; border: none;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+        }
+
+        /* Wave visualizer */
+        .wave-box {
+            position: relative; width: 100%; height: 56px;
+            background: var(--surface2); border-radius: 8px;
+            overflow: hidden; margin-top: 8px;
+        }
+        .wave-box canvas { width: 100%; height: 100%; }
+        .gen-progress {
+            position: absolute; bottom: 0; left: 0; height: 3px;
+            background: var(--fg); border-radius: 2px; transition: width 0.3s;
+        }
+
+        /* Download button */
+        .dl-wrap {
+            position: absolute; bottom: 8px; right: 8px; z-index: 5;
+            opacity: 0; pointer-events: none; transition: opacity 0.3s;
+        }
+        .dl-wrap.ready { opacity: 1; pointer-events: auto; }
+        .dl-btn {
+            width: 34px; height: 34px; border-radius: 6px;
+            background: var(--surface); border: 1px solid var(--border);
+            display: flex; align-items: center; justify-content: center;
+            cursor: pointer; color: var(--text); transition: all 0.2s;
+            position: relative; overflow: visible;
+        }
+        .dl-btn:hover { box-shadow: 0 0 12px rgba(124,106,239,0.3); transform: scale(1.05); }
+        .dl-glow {
+            position: absolute; inset: -4px; border-radius: 8px;
+            background: conic-gradient(from 0deg, var(--fg), #a78bfa, var(--fg));
+            animation: glow-spin 3s linear infinite; filter: blur(6px); opacity: 0.4; z-index: -1;
+        }
+        @keyframes glow-spin { to { transform: rotate(360deg); } }
+
+        /* Right panel controls */
+        .controls-panel { display: flex; flex-direction: column; gap: 1rem; }
+
+        /* Voice selector */
+        .voice-list { max-height: 160px; overflow-y: auto; }
+        .voice-item {
+            display: flex; align-items: center; gap: 8px;
+            padding: 8px 10px; border-radius: 6px; cursor: pointer;
+            transition: background 0.15s; font-size: 0.85rem;
+        }
+        .voice-item:hover { background: rgba(124,106,239,0.1); }
+        .voice-item.active { background: rgba(124,106,239,0.2); border: 1px solid rgba(124,106,239,0.3); }
+        .voice-item .v-name { font-weight: 500; }
+        .voice-item .v-meta { font-size: 0.72rem; color: var(--text-dim); margin-left: auto; }
+        .voice-item .v-lang {
+            font-size: 0.65rem; background: rgba(124,106,239,0.15);
+            color: var(--fg2); border-radius: 4px; padding: 1px 6px;
+        }
+        .voice-item .v-delete {
+            font-size: 0.72rem; color: var(--error); cursor: pointer; opacity: 0.5;
+            font-weight: 700; transition: opacity 0.2s; margin-left: 4px;
+        }
+        .voice-item .v-delete:hover { opacity: 1; }
+        .voice-item.voice-unavailable {
+            opacity: 0.4; cursor: not-allowed; pointer-events: none;
+        }
+        .voice-item.voice-unavailable .v-name::after {
+            content: ' (no audio)'; font-size: 0.65rem; font-weight: 400; color: var(--text-dim);
+        }
+
+        /* Voice Upload Panel */
+        .voice-upload-toggle {
+            width: 100%; padding: 10px; margin-top: 10px;
+            background: transparent; border: 2px dashed var(--border);
+            border-radius: 8px; color: var(--text-dim); font-size: 0.82rem;
+            cursor: pointer; font-family: var(--font); transition: all 0.2s;
+        }
+        .voice-upload-toggle:hover { border-color: var(--fg); color: var(--fg2); }
+        .voice-upload-panel {
+            display: none; margin-top: 10px; padding: 12px;
+            background: var(--surface2); border: 1px solid var(--border);
+            border-radius: 8px;
+        }
+        .voice-upload-panel.open { display: block; }
+        .voice-upload-panel input[type="text"],
+        .voice-upload-panel textarea,
+        .voice-upload-panel select {
+            width: 100%; padding: 8px 10px;
+            background: var(--bg); border: 1px solid var(--border);
+            border-radius: 6px; color: var(--text); font-size: 0.82rem;
+            font-family: var(--font); margin-bottom: 8px; transition: border-color 0.2s;
+        }
+        .voice-upload-panel input:focus,
+        .voice-upload-panel textarea:focus,
+        .voice-upload-panel select:focus { outline: none; border-color: var(--fg); }
+        .voice-upload-panel textarea { min-height: 60px; resize: vertical; }
+        .voice-upload-panel .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-bottom: 8px; }
+
+        .drop-zone {
+            border: 2px dashed var(--border); border-radius: 8px;
+            padding: 20px; text-align: center; cursor: pointer;
+            color: var(--text-dim); font-size: 0.8rem; transition: all 0.2s;
+            margin-bottom: 8px;
+        }
+        .drop-zone:hover, .drop-zone.dragover {
+            border-color: var(--fg); color: var(--fg2);
+            background: rgba(124,106,239,0.05);
+        }
+        .drop-zone.has-file {
+            border-color: var(--success); color: var(--success);
+            background: rgba(74,222,128,0.05);
+        }
+
+        .record-section {
+            text-align: center; margin: 8px 0;
+            padding: 8px 0; border-top: 1px solid var(--border);
+        }
+        .record-section-label { font-size: 0.7rem; color: var(--text-dim); margin-bottom: 6px; }
+        .record-btn {
+            width: 44px; height: 44px; border-radius: 50%;
+            background: rgba(248,113,113,0.15); border: 2px solid rgba(248,113,113,0.3);
+            color: var(--error); cursor: pointer; font-size: 0.7rem; font-weight: 600;
+            font-family: var(--font); transition: all 0.2s;
+            display: inline-flex; align-items: center; justify-content: center;
+        }
+        .record-btn:hover { background: rgba(248,113,113,0.25); transform: scale(1.05); }
+        .record-btn.recording {
+            background: var(--error); color: white; border-color: var(--error);
+            animation: record-pulse 1.2s ease-in-out infinite;
+        }
+        @keyframes record-pulse {
+            0%, 100% { box-shadow: 0 0 0 0 rgba(248,113,113,0.5); }
+            50% { box-shadow: 0 0 0 8px rgba(248,113,113,0); }
+        }
+        .record-timer {
+            display: inline-block; margin-left: 8px;
+            font-size: 0.82rem; font-variant-numeric: tabular-nums;
+            color: var(--text-dim); min-width: 36px;
+        }
+
+        .voice-upload-progress {
+            height: 4px; background: var(--border); border-radius: 2px;
+            overflow: hidden; margin-bottom: 8px; display: none;
+        }
+        .voice-upload-progress-bar {
+            height: 100%; background: linear-gradient(90deg, var(--fg), var(--fg2));
+            border-radius: 2px; width: 0%; transition: width 0.3s;
+        }
+
+        .btn-upload {
+            width: 100%; padding: 10px; border: none; border-radius: 6px;
+            background: linear-gradient(135deg, var(--fg), #6d5ce7);
+            color: white; font-size: 0.85rem; font-weight: 600;
+            cursor: pointer; font-family: var(--font); transition: all 0.2s;
+        }
+        .btn-upload:hover:not(:disabled) { transform: translateY(-1px); box-shadow: 0 4px 12px rgba(124,106,239,0.3); }
+        .btn-upload:disabled { opacity: 0.4; cursor: not-allowed; transform: none; }
+
+        .voice-upload-status {
+            margin-top: 8px; padding: 8px; border-radius: 6px;
+            font-size: 0.78rem; text-align: center; display: none;
+        }
+        .voice-upload-status.upload-success {
+            display: block; background: rgba(74,222,128,0.1);
+            border: 1px solid rgba(74,222,128,0.2); color: var(--success);
+        }
+        .voice-upload-status.upload-error {
+            display: block; background: rgba(248,113,113,0.1);
+            border: 1px solid rgba(248,113,113,0.2); color: var(--error);
+        }
+
+        /* Selects & inputs */
+        select, input[type="text"] {
+            width: 100%; padding: 9px 10px;
+            background: var(--surface2); border: 1px solid var(--border);
+            border-radius: 8px; color: var(--text); font-size: 0.85rem;
+            font-family: var(--font); cursor: pointer; transition: border-color 0.2s;
+        }
+        select:focus, input[type="text"]:focus { outline: none; border-color: var(--fg); }
+
+        .field { margin-bottom: 12px; }
+        .field-label {
+            font-size: 0.75rem; font-weight: 500; color: var(--text-dim);
+            margin-bottom: 5px; display: block;
+        }
+        .field-row { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
+
+        /* Speed slider */
+        .speed-row { display: flex; align-items: center; gap: 10px; }
+        .speed-range {
+            flex: 1; -webkit-appearance: none; height: 5px;
+            background: rgba(124,106,239,0.2); border-radius: 3px; outline: none;
+            accent-color: var(--fg);
+        }
+        .speed-range::-webkit-slider-thumb {
+            -webkit-appearance: none; width: 16px; height: 16px;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+        }
+        .speed-range::-moz-range-thumb {
+            width: 16px; height: 16px; border: none;
+            border-radius: 50%; background: var(--fg); cursor: pointer;
+        }
+        .speed-val {
+            font-weight: 600; color: var(--fg2); min-width: 42px; text-align: center;
+            font-size: 0.9rem;
+        }
+
+        /* Checkboxes */
+        .check-row {
+            display: flex; align-items: center; gap: 7px;
+            font-size: 0.82rem; color: var(--text-dim); cursor: pointer;
+        }
+        .check-row input { accent-color: var(--fg); width: 15px; height: 15px; cursor: pointer; }
+
+        /* Buttons */
+        .btn {
+            width: 100%; padding: 12px 20px; border: none; border-radius: 8px;
+            font-size: 0.95rem; font-weight: 600; cursor: pointer;
+            transition: all 0.2s; font-family: var(--font);
+            display: flex; align-items: center; justify-content: center; gap: 8px;
+        }
+        .btn-gen {
+            background: linear-gradient(135deg, var(--fg), #6d5ce7);
+            color: white; position: relative; overflow: hidden;
+        }
+        .btn-gen:hover:not(:disabled) {
+            transform: translateY(-1px);
+            box-shadow: 0 6px 20px rgba(124,106,239,0.35);
+        }
+        .btn-gen:disabled { opacity: 0.5; cursor: not-allowed; transform: none; }
+        .btn-cancel {
+            background: rgba(248,113,113,0.15); color: var(--error);
+            border: 1px solid rgba(248,113,113,0.3); margin-top: 8px;
+        }
+        .btn-cancel:hover { background: rgba(248,113,113,0.25); }
+
+        /* Spinner */
+        .spinner {
+            width: 18px; height: 18px; border: 2px solid rgba(255,255,255,0.3);
+            border-top-color: white; border-radius: 50%;
+            animation: spin 0.7s linear infinite; display: none;
+        }
+        .spinning .spinner { display: block; }
+        .spinning .btn-label { display: none; }
+        @keyframes spin { to { transform: rotate(360deg); } }
+
+        /* Model management panel */
+        .model-panel { margin-top: 1rem; }
+        .model-tag {
+            display: inline-flex; align-items: center; gap: 6px;
+            background: rgba(74,222,128,0.1); border: 1px solid rgba(74,222,128,0.2);
+            border-radius: 6px; padding: 4px 10px; font-size: 0.78rem;
+            color: var(--success); margin: 3px;
+        }
+        .model-tag .unload-x {
+            cursor: pointer; opacity: 0.6; font-weight: 700;
+            transition: opacity 0.2s;
+        }
+        .model-tag .unload-x:hover { opacity: 1; }
+        .model-load-row { display: flex; gap: 8px; margin-top: 8px; }
+        .btn-sm {
+            padding: 7px 14px; border-radius: 6px; border: 1px solid var(--border);
+            background: var(--surface2); color: var(--text); font-size: 0.8rem;
+            cursor: pointer; font-family: var(--font); transition: all 0.2s;
+        }
+        .btn-sm:hover { border-color: var(--fg); color: var(--fg2); }
+
+        /* Model tag expanded (with device info) */
+        .model-tag-expanded {
+            display: flex; align-items: center; gap: 8px;
+            background: rgba(74,222,128,0.06); border: 1px solid rgba(74,222,128,0.15);
+            border-radius: 8px; padding: 8px 12px; font-size: 0.8rem;
+            color: var(--text); margin-bottom: 6px;
+        }
+        .model-tag-expanded .model-name { font-weight: 600; color: var(--success); }
+        .model-tag-expanded .model-device-badge {
+            font-size: 0.68rem; font-weight: 600; padding: 2px 7px;
+            border-radius: 4px; text-transform: uppercase;
+        }
+        .model-device-badge.gpu-badge {
+            background: rgba(74,222,128,0.15); color: #4ade80; border: 1px solid rgba(74,222,128,0.25);
+        }
+        .model-device-badge.cpu-badge {
+            background: rgba(148,163,184,0.1); color: var(--text-dim); border: 1px solid var(--border);
+        }
+        .model-tag-expanded .model-lang {
+            font-size: 0.65rem; background: rgba(124,106,239,0.12);
+            color: var(--fg2); border-radius: 4px; padding: 1px 6px;
+        }
+        .model-tag-expanded .model-actions { margin-left: auto; display: flex; gap: 4px; }
+        .model-tag-expanded .toggle-device-btn {
+            padding: 3px 8px; border-radius: 4px; border: 1px solid var(--border);
+            background: var(--surface2); color: var(--text-dim); font-size: 0.68rem;
+            cursor: pointer; font-family: var(--font); transition: all 0.2s;
+        }
+        .model-tag-expanded .toggle-device-btn:hover { border-color: var(--fg); color: var(--fg2); }
+        .model-tag-expanded .unload-btn {
+            padding: 3px 8px; border-radius: 4px; border: 1px solid rgba(248,113,113,0.2);
+            background: rgba(248,113,113,0.06); color: var(--error); font-size: 0.68rem;
+            cursor: pointer; font-family: var(--font); transition: all 0.2s; font-weight: 600;
+        }
+        .model-tag-expanded .unload-btn:hover { background: rgba(248,113,113,0.15); }
+
+        /* Loading card */
+        .loading-card {
+            display: flex; align-items: center; gap: 10px;
+            background: rgba(124,106,239,0.06); border: 1px solid rgba(124,106,239,0.15);
+            border-radius: 8px; padding: 10px 12px; margin-bottom: 6px;
+            font-size: 0.8rem; color: var(--text-dim); flex-wrap: wrap;
+        }
+        .loading-spinner-sm {
+            width: 16px; height: 16px; border: 2px solid rgba(124,106,239,0.2);
+            border-top-color: var(--fg); border-radius: 50%;
+            animation: spin 0.8s linear infinite; flex-shrink: 0;
+        }
+        .loading-card .loading-model { font-weight: 600; color: var(--fg2); }
+        .loading-card .loading-phase { color: var(--text-dim); font-size: 0.72rem; }
+        .loading-card .loading-time { margin-left: auto; font-size: 0.72rem; font-variant-numeric: tabular-nums; }
+        .loading-card.error-card {
+            background: rgba(248,113,113,0.06); border-color: rgba(248,113,113,0.2);
+        }
+        .loading-card.error-card .loading-model { color: var(--error); }
+        .loading-card.ready-card {
+            background: rgba(74,222,128,0.06); border-color: rgba(74,222,128,0.2);
+        }
+        .loading-card.ready-card .loading-model { color: var(--success); }
+
+        .loading-progress-bar {
+            width: 100%; height: 3px; background: rgba(124,106,239,0.1);
+            border-radius: 2px; margin-top: 4px; overflow: hidden;
+            flex-basis: 100%;
+        }
+        .loading-progress-bar-fill {
+            height: 100%; border-radius: 2px; transition: width 0.5s, background 0.5s;
+        }
+
+        /* Language filter pills */
+        .lang-filter { display: flex; gap: 4px; flex-wrap: wrap; margin-bottom: 8px; }
+        .lang-pill {
+            padding: 3px 10px; border-radius: 12px; font-size: 0.7rem;
+            border: 1px solid var(--border); background: var(--surface2);
+            color: var(--text-dim); cursor: pointer; transition: all 0.2s;
+            font-family: var(--font);
+        }
+        .lang-pill:hover { border-color: var(--fg); color: var(--fg2); }
+        .lang-pill.active {
+            background: rgba(124,106,239,0.15); border-color: rgba(124,106,239,0.3);
+            color: var(--fg2); font-weight: 600;
+        }
+
+        /* Voice hint */
+        .voice-hint {
+            background: rgba(251,191,36,0.08); border: 1px solid rgba(251,191,36,0.2);
+            border-radius: 6px; padding: 8px 10px; font-size: 0.75rem;
+            color: var(--warning); margin-top: 8px; line-height: 1.4;
+        }
+
+        /* Status message */
+        .status-msg {
+            padding: 10px 14px; border-radius: 8px;
+            font-size: 0.82rem; font-weight: 500; text-align: center;
+            margin-top: 10px; transition: all 0.3s; opacity: 0;
+        }
+        .status-msg.info { opacity: 1; background: rgba(124,106,239,0.1); border: 1px solid rgba(124,106,239,0.2); }
+        .status-msg.error { opacity: 1; background: rgba(248,113,113,0.1); border: 1px solid rgba(248,113,113,0.2); color: var(--error); }
+        .status-msg.success { opacity: 1; background: rgba(74,222,128,0.1); border: 1px solid rgba(74,222,128,0.2); color: var(--success); }
+
+        /* Scrollbar */
+        ::-webkit-scrollbar { width: 6px; }
+        ::-webkit-scrollbar-track { background: transparent; }
+        ::-webkit-scrollbar-thumb { background: rgba(124,106,239,0.3); border-radius: 3px; }
+
+        /* Mobile player */
+        @media (max-width: 860px) {
+            .player-bar { flex-wrap: wrap; height: auto; gap: 8px; padding: 10px; }
+            .seek-wrap { order: 10; flex-basis: 100%; }
+            .vol-group { border: none; padding: 0; }
+            .time-display { border: none; padding: 0; min-width: 60px; }
+            .wave-box { height: 40px; }
+        }
+    </style>
+</head>
+<body>
+    <div class="bg-glow"></div>
+    <div class="bg-grid"></div>
+
+    <div class="app">
+        <header>
+            <div class="logo">NeuTTS-FastAPI</div>
+            <p class="subtitle">OpenAI-compatible Text-to-Speech powered by Neuphonic NeuTTS</p>
+            <div class="badges">
+                <div class="badge"><span class="dot dot-off" id="srv-dot"></span><span id="srv-text">Connecting...</span></div>
+                <div class="badge" id="model-badge">Models: ...</div>
+                <div class="badge" id="voice-badge">Voices: ...</div>
+                <div class="device-badge cpu" id="device-badge">
+                    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="4" y="4" width="16" height="16" rx="2"/><path d="M9 1v3M15 1v3M9 20v3M15 20v3M1 9h3M1 15h3M20 9h3M20 15h3"/></svg>
+                    <span id="device-badge-text">CPU Only</span>
+                </div>
+            </div>
+        </header>
+
+        <div id="gpu-warning-banner" style="display:none"></div>
+
+        <div class="main-grid">
+            <!-- Left Column: Editor + Player -->
+            <div class="left-col">
+                <div class="card text-editor">
+                    <div class="card-label">Text Input</div>
+                    <textarea id="tts-text" placeholder="Enter text to synthesize..." maxlength="10000">Hello, this is a test of the NeuTTS text-to-speech system. It supports multiple languages including English, German, French and Spanish.</textarea>
+                    <div class="text-meta">
+                        <span><span id="char-cnt">0</span> / 10,000 characters</span>
+                        <span><kbd>Ctrl</kbd>+<kbd>Enter</kbd> to generate</span>
+                    </div>
+                </div>
+
+                <div class="card player">
+                    <div class="card-label">Audio Player</div>
+                    <div class="player-bar">
+                        <button class="player-btn" id="play-btn" title="Play/Pause">
+                            <svg id="play-icon" viewBox="0 0 24 24"><path d="M8 5v14l11-7z"/></svg>
+                            <svg id="pause-icon" viewBox="0 0 24 24" style="display:none"><path d="M6 19h4V5H6v14zm8-14v14h4V5h-4z"/></svg>
+                        </button>
+                        <div class="seek-wrap">
+                            <input type="range" class="seek-slider" id="seek-slider" min="0" max="1000" value="0">
+                        </div>
+                        <div class="time-display" id="time-disp">0:00 / 0:00</div>
+                        <div class="vol-group">
+                            <svg class="vol-icon" width="18" height="18" viewBox="0 0 24 24"><path fill="currentColor" d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02zM14 3.23v2.06c2.89.86 5 3.54 5 6.71s-2.11 5.85-5 6.71v2.06c4.01-.91 7-4.49 7-8.77s-2.99-7.86-7-8.77z"/></svg>
+                            <input type="range" class="vol-slider" id="vol-slider" min="0" max="100" value="100">
+                        </div>
+                    </div>
+                    <div class="wave-box" id="wave-box">
+                        <canvas id="wave-canvas"></canvas>
+                        <div class="gen-progress" id="gen-progress" style="width:0%"></div>
+                        <div class="dl-wrap" id="dl-wrap">
+                            <a class="dl-btn" id="dl-btn" download title="Download audio">
+                                <div class="dl-glow"></div>
+                                <svg width="14" height="14" viewBox="0 0 16 16" fill="none">
+                                    <path d="M8 10L4.5 6.5h7L8 10z" fill="currentColor"/>
+                                    <path d="M8 2v8M3 13h10" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/>
+                                </svg>
+                            </a>
+                        </div>
+                    </div>
+                </div>
+            </div>
+
+            <!-- Right Column: Controls -->
+            <div class="controls-panel">
+                <!-- Voice Selection -->
+                <div class="card">
+                    <div class="card-label">Voice</div>
+                    <input type="text" id="voice-search" placeholder="Search voices..." autocomplete="off">
+                    <div class="voice-list" id="voice-list"></div>
+                    <div id="voice-hint-container"></div>
+                    <button class="voice-upload-toggle" id="voice-upload-toggle">+ Clone a Voice (Upload or Record)</button>
+                    <div class="voice-upload-panel" id="voice-upload-panel">
+                        <input type="text" id="upload-voice-id" placeholder="Voice ID (e.g. my-voice)" autocomplete="off">
+                        <div class="field-row">
+                            <select id="upload-language">
+                                <option value="unknown">Language...</option>
+                                <option value="en-us">English (en-us)</option>
+                                <option value="de">German (de)</option>
+                                <option value="fr-fr">French (fr-fr)</option>
+                                <option value="es">Spanish (es)</option>
+                                <option value="other">Other</option>
+                            </select>
+                            <select id="upload-gender">
+                                <option value="unknown">Gender...</option>
+                                <option value="male">Male</option>
+                                <option value="female">Female</option>
+                                <option value="other">Other</option>
+                            </select>
+                        </div>
+                        <div class="drop-zone" id="upload-drop-zone">Drop WAV file here or click to browse
+                            <input type="file" id="upload-file-input" accept=".wav,audio/wav" style="display:none">
+                        </div>
+                        <div class="record-section">
+                            <div class="record-section-label">or record from microphone</div>
+                            <button class="record-btn" id="record-btn" title="Record from microphone">REC</button>
+                            <span class="record-timer" id="record-timer">0:00</span>
+                        </div>
+                        <textarea id="upload-ref-text" placeholder="Exact transcription of the audio..."></textarea>
+                        <div class="voice-upload-progress" id="upload-progress">
+                            <div class="voice-upload-progress-bar" id="upload-progress-bar"></div>
+                        </div>
+                        <button class="btn-upload" id="upload-btn" disabled>Upload & Clone Voice</button>
+                        <div class="voice-upload-status" id="upload-status"></div>
+                    </div>
+                </div>
+
+                <!-- Settings -->
+                <div class="card">
+                    <div class="card-label">Settings</div>
+                    <div class="field-row">
+                        <div class="field">
+                            <label class="field-label">Format</label>
+                            <select id="fmt-select">
+                                <option value="mp3" selected>MP3</option>
+                                <option value="wav">WAV</option>
+                                <option value="opus">Opus (OGG)</option>
+                                <option value="flac">FLAC</option>
+                                <option value="aac">AAC</option>
+                                <option value="pcm">PCM (raw)</option>
+                            </select>
+                        </div>
+                        <div class="field">
+                            <label class="field-label">Model</label>
+                            <select id="model-select"></select>
+                        </div>
+                    </div>
+                    <div class="field">
+                        <label class="field-label">Speed</label>
+                        <div class="speed-row">
+                            <span style="font-size:0.7rem;color:var(--text-dim)">0.25x</span>
+                            <input type="range" class="speed-range" id="speed-range" min="0.25" max="4.0" step="0.05" value="1.0">
+                            <span style="font-size:0.7rem;color:var(--text-dim)">4.0x</span>
+                            <span class="speed-val" id="speed-val">1.00x</span>
+                        </div>
+                    </div>
+                    <div style="display:flex;gap:16px;flex-wrap:wrap">
+                        <label class="check-row"><input type="checkbox" id="stream-chk"> Streaming</label>
+                        <label class="check-row"><input type="checkbox" id="autoplay-chk" checked> Auto-play</label>
+                    </div>
+                </div>
+
+                <!-- Generate -->
+                <div class="card">
+                    <button class="btn btn-gen" id="gen-btn" disabled>
+                        <span class="btn-label">Generate Speech</span>
+                        <div class="spinner"></div>
+                    </button>
+                    <button class="btn btn-cancel" id="cancel-btn" style="display:none">Cancel</button>
+                    <div class="status-msg" id="status-msg"></div>
+                </div>
+
+                <!-- Model Management -->
+                <div class="card model-panel">
+                    <div class="card-label">Model Management</div>
+                    <div id="loaded-models-list"></div>
+                    <div id="loading-tasks-list"></div>
+                    <div class="lang-filter" id="lang-filter"></div>
+                    <div class="model-load-row">
+                        <select id="registry-select" style="font-size:0.8rem"></select>
+                        <button class="btn-sm" id="load-btn">Load</button>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <audio id="audio-el" preload="none"></audio>
+
+    <script>
+    (function() {
+        const API = location.origin;
+
+        // DOM
+        const $ = id => document.getElementById(id);
+        const ttsText = $('tts-text');
+        const charCnt = $('char-cnt');
+        const voiceSearch = $('voice-search');
+        const voiceList = $('voice-list');
+        const modelSelect = $('model-select');
+        const fmtSelect = $('fmt-select');
+        const speedRange = $('speed-range');
+        const speedVal = $('speed-val');
+        const streamChk = $('stream-chk');
+        const autoplayChk = $('autoplay-chk');
+        const genBtn = $('gen-btn');
+        const cancelBtn = $('cancel-btn');
+        const statusMsg = $('status-msg');
+        const srvDot = $('srv-dot');
+        const srvText = $('srv-text');
+        const modelBadge = $('model-badge');
+        const voiceBadge = $('voice-badge');
+        const deviceBadge = $('device-badge');
+        const deviceBadgeText = $('device-badge-text');
+        const playBtn = $('play-btn');
+        const playIcon = $('play-icon');
+        const pauseIcon = $('pause-icon');
+        const seekSlider = $('seek-slider');
+        const timeDisp = $('time-disp');
+        const volSlider = $('vol-slider');
+        const waveCanvas = $('wave-canvas');
+        const genProgress = $('gen-progress');
+        const dlWrap = $('dl-wrap');
+        const dlBtn = $('dl-btn');
+        const loadedModelsList = $('loaded-models-list');
+        const loadingTasksList = $('loading-tasks-list');
+        const langFilter = $('lang-filter');
+        const registrySelect = $('registry-select');
+        const loadBtn = $('load-btn');
+        const voiceHintContainer = $('voice-hint-container');
+        const gpuWarningBanner = $('gpu-warning-banner');
+        const audio = $('audio-el');
+
+        // Upload elements
+        const uploadToggle = $('voice-upload-toggle');
+        const uploadPanel = $('voice-upload-panel');
+        const uploadVoiceId = $('upload-voice-id');
+        const uploadLanguage = $('upload-language');
+        const uploadGender = $('upload-gender');
+        const uploadDropZone = $('upload-drop-zone');
+        const uploadFileInput = $('upload-file-input');
+        const uploadRefText = $('upload-ref-text');
+        const uploadProgress = $('upload-progress');
+        const uploadProgressBar = $('upload-progress-bar');
+        const uploadBtn = $('upload-btn');
+        const uploadStatus = $('upload-status');
+        const recordBtn = $('record-btn');
+        const recordTimer = $('record-timer');
+
+        let voices = [];
+        let selectedVoice = '';
+        let loadedModels = [];
+        let abortCtrl = null;
+        let waveCtx = waveCanvas.getContext('2d');
+        let waveAnim = null;
+        let analyser = null;
+        let audioCtx = null;
+        let audioSource = null;
+        let currentBlobUrl = null;
+        let gpuAvailable = false;
+        let gpuName = '';
+        let loadingTaskTimers = {};
+        let registryData = [];
+        let activeLangFilter = 'all';
+        let gpuWarningDismissed = false;
+
+        // Upload state
+        let uploadFile = null;
+        let mediaRecorder = null;
+        let recordChunks = [];
+        let recordTimerInterval = null;
+        let recordStartTime = 0;
+
+        // --- Audio Context & Analyser ---
+        function ensureAudioCtx() {
+            if (!audioCtx) {
+                audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+                analyser = audioCtx.createAnalyser();
+                analyser.fftSize = 256;
+                analyser.smoothingTimeConstant = 0.8;
+                audioSource = audioCtx.createMediaElementSource(audio);
+                audioSource.connect(analyser);
+                analyser.connect(audioCtx.destination);
+            }
+        }
+
+        // --- Wave Visualization ---
+        function resizeCanvas() {
+            const box = $('wave-box');
+            waveCanvas.width = box.clientWidth * window.devicePixelRatio;
+            waveCanvas.height = box.clientHeight * window.devicePixelRatio;
+            waveCtx.scale(window.devicePixelRatio, window.devicePixelRatio);
+        }
+        resizeCanvas();
+        window.addEventListener('resize', resizeCanvas);
+
+        function drawWave() {
+            const w = waveCanvas.width / window.devicePixelRatio;
+            const h = waveCanvas.height / window.devicePixelRatio;
+            waveCtx.clearRect(0, 0, w, h);
+
+            if (analyser && !audio.paused) {
+                const data = new Uint8Array(analyser.frequencyBinCount);
+                analyser.getByteFrequencyData(data);
+
+                const barCount = Math.min(data.length, 80);
+                const barW = w / barCount;
+                const grad = waveCtx.createLinearGradient(0, h, 0, 0);
+                grad.addColorStop(0, 'rgba(124,106,239,0.2)');
+                grad.addColorStop(1, 'rgba(167,139,250,0.8)');
+                waveCtx.fillStyle = grad;
+
+                for (let i = 0; i < barCount; i++) {
+                    const barH = (data[i] / 255) * h * 0.85;
+                    const x = i * barW;
+                    waveCtx.fillRect(x + 1, h - barH, barW - 2, barH);
+                }
+            } else {
+                // Idle wave
+                const t = Date.now() / 1000;
+                waveCtx.strokeStyle = 'rgba(124,106,239,0.3)';
+                waveCtx.lineWidth = 1.5;
+                waveCtx.beginPath();
+                for (let x = 0; x < w; x++) {
+                    const y = h/2 + Math.sin(x/30 + t*2) * 6 + Math.sin(x/15 + t*3) * 3;
+                    x === 0 ? waveCtx.moveTo(x, y) : waveCtx.lineTo(x, y);
+                }
+                waveCtx.stroke();
+            }
+            waveAnim = requestAnimationFrame(drawWave);
+        }
+        drawWave();
+
+        // --- Char counter ---
+        ttsText.addEventListener('input', () => { charCnt.textContent = ttsText.value.length; });
+        charCnt.textContent = ttsText.value.length;
+
+        // --- Speed ---
+        speedRange.addEventListener('input', () => {
+            speedVal.textContent = parseFloat(speedRange.value).toFixed(2) + 'x';
+        });
+
+        // --- Model change: check language compatibility ---
+        modelSelect.addEventListener('change', () => {
+            if (!selectedVoice) return;
+            const voice = voices.find(v => v.name === selectedVoice);
+            const model = loadedModels.find(m => m.id === modelSelect.value);
+            if (voice && model && voice.language && model.language
+                && voice.language !== model.language) {
+                showLangMismatchWarning(voice.language);
+            } else {
+                clearLangMismatchWarning();
+            }
+        });
+
+        // --- Format time ---
+        function fmtTime(s) {
+            if (!s || !isFinite(s)) return '0:00';
+            const m = Math.floor(s / 60);
+            const sec = Math.floor(s % 60);
+            return m + ':' + String(sec).padStart(2, '0');
+        }
+
+        // --- Audio player ---
+        audio.addEventListener('timeupdate', () => {
+            if (audio.duration) {
+                seekSlider.value = Math.floor((audio.currentTime / audio.duration) * 1000);
+                timeDisp.textContent = fmtTime(audio.currentTime) + ' / ' + fmtTime(audio.duration);
+            }
+        });
+        audio.addEventListener('play', () => {
+            playIcon.style.display = 'none'; pauseIcon.style.display = 'block';
+            ensureAudioCtx(); if (audioCtx.state === 'suspended') audioCtx.resume();
+        });
+        audio.addEventListener('pause', () => {
+            playIcon.style.display = 'block'; pauseIcon.style.display = 'none';
+        });
+        audio.addEventListener('ended', () => {
+            playIcon.style.display = 'block'; pauseIcon.style.display = 'none';
+            seekSlider.value = 0;
+        });
+        playBtn.addEventListener('click', () => {
+            ensureAudioCtx();
+            if (audio.paused && audio.src) audio.play(); else audio.pause();
+        });
+        seekSlider.addEventListener('input', () => {
+            if (audio.duration) audio.currentTime = (seekSlider.value / 1000) * audio.duration;
+        });
+        volSlider.addEventListener('input', () => { audio.volume = volSlider.value / 100; });
+
+        // --- Fetch server state ---
+        async function refreshState() {
+            try {
+                const [hR, vR, mR, rR, sR, lR] = await Promise.all([
+                    fetch(API + '/health'), fetch(API + '/v1/audio/voices'),
+                    fetch(API + '/v1/models'), fetch(API + '/v1/models/registry'),
+                    fetch(API + '/debug/system'), fetch(API + '/v1/models/loaded')
+                ]);
+                const health = await hR.json();
+                const vData = await vR.json();
+                const mData = await mR.json();
+                const rData = await rR.json();
+                const sData = await sR.json();
+                const lData = await lR.json();
+
+                // Status
+                srvDot.className = 'dot dot-ok';
+                srvText.textContent = 'Online v' + health.version;
+
+                // GPU Badge
+                gpuAvailable = sData.gpu_available || false;
+                if (gpuAvailable && sData.gpu_info && sData.gpu_info.length > 0) {
+                    gpuName = sData.gpu_info[0].name || 'GPU';
+                    deviceBadge.className = 'device-badge gpu';
+                    deviceBadgeText.textContent = gpuName;
+                } else {
+                    gpuName = '';
+                    deviceBadge.className = 'device-badge cpu';
+                    deviceBadgeText.textContent = 'CPU Only';
+                }
+
+                // GPU Warning Banner
+                if (sData.gpu_detected_but_unusable && !gpuWarningDismissed) {
+                    gpuWarningBanner.style.display = 'block';
+                    gpuWarningBanner.innerHTML = '<div class="gpu-warning">'
+                        + '<span class="gpu-warning-icon">&#9888;</span>'
+                        + '<div class="gpu-warning-content">'
+                        + '<div class="gpu-warning-title">GPU Detected but Unusable</div>'
+                        + '<div class="gpu-warning-text">'
+                        + (sData.gpu_fix_instructions || 'GPU detected but PyTorch cannot use it.')
+                        + '</div></div>'
+                        + '<button class="gpu-warning-dismiss" id="gpu-dismiss-btn">Dismiss</button>'
+                        + '</div>';
+                    const dismissBtn = $('gpu-dismiss-btn');
+                    if (dismissBtn) dismissBtn.addEventListener('click', () => {
+                        gpuWarningDismissed = true;
+                        gpuWarningBanner.style.display = 'none';
+                    });
+                } else if (!sData.gpu_detected_but_unusable) {
+                    gpuWarningBanner.style.display = 'none';
+                }
+
+                // Voices
+                voices = vData.voices || [];
+                voiceBadge.textContent = 'Voices: ' + voices.length;
+                renderVoices(voices);
+                if (!selectedVoice && voices.length) {
+                    const firstAvailable = voices.find(v => v.available !== false);
+                    if (firstAvailable) selectVoice(firstAvailable.name);
+                }
+
+                // Models (for select dropdown) - preserve current selection
+                const prevModel = modelSelect.value;
+                loadedModels = mData.data || [];
+                modelBadge.textContent = 'Models: ' + loadedModels.length + ' loaded';
+                modelSelect.innerHTML = '';
+                loadedModels.forEach(m => {
+                    const o = document.createElement('option');
+                    o.value = m.id; o.textContent = m.id;
+                    modelSelect.appendChild(o);
+                });
+                // Restore previous selection if still loaded
+                if (prevModel && loadedModels.some(m => m.id === prevModel)) {
+                    modelSelect.value = prevModel;
+                }
+                genBtn.disabled = loadedModels.length === 0;
+
+                // Loaded models (detailed)
+                const loadedDetailed = lData.models || [];
+                renderLoadedModels(loadedDetailed);
+
+                // Voice hint
+                updateVoiceHint(loadedDetailed);
+
+                // Registry
+                registryData = rData.backbones || [];
+                renderLangFilter();
+                renderRegistryDropdown(activeLangFilter);
+            } catch {
+                srvDot.className = 'dot dot-off';
+                srvText.textContent = 'Offline';
+                genBtn.disabled = true;
+            }
+        }
+
+        // --- Voice hint ---
+        function updateVoiceHint(loadedDetailed) {
+            voiceHintContainer.innerHTML = '';
+            const loadedLangs = new Set(loadedDetailed.map(m => m.language));
+            loadedLangs.forEach(lang => {
+                if (!lang) return;
+                const langVoices = voices.filter(v => v.language === lang && v.available !== false);
+                if (langVoices.length <= 1) {
+                    const langLabel = {de:'German',es:'Spanish','fr-fr':'French','en-us':'English'}[lang] || lang;
+                    const hint = document.createElement('div');
+                    hint.className = 'voice-hint';
+                    hint.textContent = 'Only ' + langVoices.length + ' ' + langLabel
+                        + ' voice' + (langVoices.length !== 1 ? 's' : '') + ' available. '
+                        + "Use 'Clone a Voice' above to record or upload a custom voice.";
+                    voiceHintContainer.appendChild(hint);
+                }
+            });
+        }
+
+        // --- Loaded models rendering ---
+        function renderLoadedModels(models) {
+            loadedModelsList.innerHTML = '';
+            models.forEach(m => {
+                const div = document.createElement('div');
+                div.className = 'model-tag-expanded';
+
+                const isCuda = m.backbone_device && m.backbone_device.startsWith('cuda');
+                const deviceLabel = isCuda ? 'GPU' : 'CPU';
+                const deviceClass = isCuda ? 'gpu-badge' : 'cpu-badge';
+                const isGGUF = m.backend === 'gguf';
+
+                let actionsHtml = '<button class="unload-btn" data-id="' + m.model_id + '">&times;</button>';
+                if (!isGGUF && gpuAvailable) {
+                    const targetDevice = isCuda ? 'cpu' : 'cuda';
+                    const toggleLabel = isCuda ? 'CPU' : 'GPU';
+                    actionsHtml = '<button class="toggle-device-btn" data-id="' + m.model_id + '" data-target="' + targetDevice + '">'
+                        + toggleLabel + '</button>' + actionsHtml;
+                }
+
+                div.innerHTML = '<span class="model-name">' + m.model_id + '</span>'
+                    + '<span class="model-device-badge ' + deviceClass + '">' + deviceLabel + '</span>'
+                    + (m.language ? '<span class="model-lang">' + m.language + '</span>' : '')
+                    + '<span class="model-actions">' + actionsHtml + '</span>';
+
+                loadedModelsList.appendChild(div);
+            });
+
+            // Event listeners
+            loadedModelsList.querySelectorAll('.unload-btn').forEach(el => {
+                el.addEventListener('click', () => unloadModel(el.dataset.id));
+            });
+            loadedModelsList.querySelectorAll('.toggle-device-btn').forEach(el => {
+                el.addEventListener('click', () => switchDevice(el.dataset.id, el.dataset.target));
+            });
+        }
+
+        // --- Language filter ---
+        function renderLangFilter() {
+            const langs = new Set(registryData.map(b => b.language));
+            const allLangs = ['all', ...Array.from(langs).sort()];
+            langFilter.innerHTML = '';
+            allLangs.forEach(lang => {
+                const pill = document.createElement('button');
+                pill.className = 'lang-pill' + (activeLangFilter === lang ? ' active' : '');
+                pill.textContent = lang === 'all' ? 'All' : lang;
+                pill.addEventListener('click', () => {
+                    activeLangFilter = lang;
+                    renderLangFilter();
+                    renderRegistryDropdown(lang);
+                });
+                langFilter.appendChild(pill);
+            });
+        }
+
+        function renderRegistryDropdown(langFilterVal) {
+            const loadedIds = new Set(loadedModels.map(m => m.id));
+            registrySelect.innerHTML = '';
+            registryData.forEach(b => {
+                if (loadedIds.has(b.model_id)) return;
+                if (langFilterVal !== 'all' && b.language !== langFilterVal) return;
+                const o = document.createElement('option');
+                o.value = b.model_id;
+                o.textContent = b.model_id + ' (' + b.language + ', ' + b.backend + ')';
+                registrySelect.appendChild(o);
+            });
+        }
+
+        // --- Voice rendering ---
+        function renderVoices(list) {
+            voiceList.innerHTML = '';
+            list.forEach(v => {
+                const isUnavailable = v.available === false;
+                const div = document.createElement('div');
+                div.className = 'voice-item'
+                    + (v.name === selectedVoice ? ' active' : '')
+                    + (isUnavailable ? ' voice-unavailable' : '');
+
+                let html = '<span class="v-name">' + v.name + '</span>'
+                    + '<span class="v-lang">' + v.language + '</span>'
+                    + '<span class="v-meta">' + v.gender + '</span>';
+
+                if (v.custom && !isUnavailable) {
+                    html += '<span class="v-delete" data-name="' + v.name + '" title="Delete voice">&times;</span>';
+                }
+
+                div.innerHTML = html;
+                if (!isUnavailable) {
+                    div.addEventListener('click', (e) => {
+                        if (e.target.classList.contains('v-delete')) return;
+                        selectVoice(v.name);
+                    });
+                }
+                voiceList.appendChild(div);
+            });
+
+            // Delete listeners
+            voiceList.querySelectorAll('.v-delete').forEach(el => {
+                el.addEventListener('click', (e) => {
+                    e.stopPropagation();
+                    deleteVoice(el.dataset.name);
+                });
+            });
+        }
+        function selectVoice(name) {
+            selectedVoice = name;
+            voiceSearch.value = name;
+            document.querySelectorAll('.voice-item').forEach(el => {
+                el.classList.toggle('active', el.querySelector('.v-name').textContent === name);
+            });
+            // Auto-select a language-compatible model
+            autoSelectModelForVoice(name);
+        }
+        function autoSelectModelForVoice(voiceName) {
+            const voice = voices.find(v => v.name === voiceName);
+            if (!voice || !voice.language || loadedModels.length === 0) return;
+            // Check if current model already matches
+            const currentModel = loadedModels.find(m => m.id === modelSelect.value);
+            if (currentModel && currentModel.language === voice.language) {
+                clearLangMismatchWarning();
+                return;
+            }
+            // Find a loaded model that matches the voice language
+            const match = loadedModels.find(m => m.language === voice.language);
+            if (match) {
+                modelSelect.value = match.id;
+                clearLangMismatchWarning();
+            } else {
+                showLangMismatchWarning(voice.language);
+            }
+        }
+        function getLanguageLabel(code) {
+            const labels = { 'en-us': 'English', 'de': 'German', 'fr-fr': 'French', 'es': 'Spanish' };
+            return labels[code] || code;
+        }
+        function showLangMismatchWarning(voiceLang) {
+            let w = $('lang-mismatch-warning');
+            if (!w) {
+                w = document.createElement('div');
+                w.id = 'lang-mismatch-warning';
+                w.style.cssText = 'background:rgba(251,191,36,0.15);border:1px solid var(--warning);color:var(--warning);padding:8px 12px;border-radius:8px;font-size:0.82rem;margin-top:8px;';
+                modelSelect.parentElement.appendChild(w);
+            }
+            const label = getLanguageLabel(voiceLang);
+            w.textContent = 'No ' + label + ' model loaded! Load a matching model from the registry below.';
+            w.style.display = 'block';
+        }
+        function clearLangMismatchWarning() {
+            const w = $('lang-mismatch-warning');
+            if (w) w.style.display = 'none';
+        }
+        voiceSearch.addEventListener('input', () => {
+            const q = voiceSearch.value.toLowerCase();
+            renderVoices(voices.filter(v =>
+                v.name.toLowerCase().includes(q) || v.language.toLowerCase().includes(q)
+            ));
+        });
+        voiceSearch.addEventListener('focus', () => {
+            voiceSearch.select();
+            renderVoices(voices);
+        });
+
+        // --- Delete custom voice ---
+        async function deleteVoice(name) {
+            if (!confirm('Delete custom voice "' + name + '"?')) return;
+            try {
+                const r = await fetch(API + '/v1/audio/voices/' + encodeURIComponent(name), { method: 'DELETE' });
+                if (!r.ok) { const e = await r.json(); throw new Error(e.detail?.error?.message || 'Delete failed'); }
+                if (selectedVoice === name) selectedVoice = '';
+                refreshState();
+            } catch (e) { showStatus('Delete failed: ' + e.message, 'error'); }
+        }
+
+        // --- Voice Upload Logic ---
+        uploadToggle.addEventListener('click', () => {
+            uploadPanel.classList.toggle('open');
+            uploadToggle.textContent = uploadPanel.classList.contains('open')
+                ? '- Hide Clone Panel' : '+ Clone a Voice (Upload or Record)';
+        });
+
+        // Drag-and-drop
+        uploadDropZone.addEventListener('click', () => uploadFileInput.click());
+        uploadDropZone.addEventListener('dragover', (e) => { e.preventDefault(); uploadDropZone.classList.add('dragover'); });
+        uploadDropZone.addEventListener('dragleave', () => uploadDropZone.classList.remove('dragover'));
+        uploadDropZone.addEventListener('drop', (e) => {
+            e.preventDefault();
+            uploadDropZone.classList.remove('dragover');
+            if (e.dataTransfer.files.length) handleUploadFile(e.dataTransfer.files[0]);
+        });
+        uploadFileInput.addEventListener('change', () => {
+            if (uploadFileInput.files.length) handleUploadFile(uploadFileInput.files[0]);
+        });
+
+        function handleUploadFile(file) {
+            if (!file.name.toLowerCase().endsWith('.wav') && file.type !== 'audio/wav') {
+                setUploadStatus('Only WAV files are supported', 'error');
+                return;
+            }
+            uploadFile = file;
+            uploadDropZone.textContent = file.name + ' (' + (file.size / 1024).toFixed(1) + ' KB)';
+            uploadDropZone.classList.add('has-file');
+            validateUploadForm();
+        }
+
+        // Form validation
+        function validateUploadForm() {
+            const hasId = uploadVoiceId.value.trim().length > 0;
+            const hasFile = uploadFile !== null;
+            const hasText = uploadRefText.value.trim().length > 0;
+            uploadBtn.disabled = !(hasId && hasFile && hasText);
+        }
+        uploadVoiceId.addEventListener('input', validateUploadForm);
+        uploadRefText.addEventListener('input', validateUploadForm);
+
+        // Upload
+        uploadBtn.addEventListener('click', async () => {
+            if (!uploadFile || uploadBtn.disabled) return;
+            uploadBtn.disabled = true;
+            uploadBtn.textContent = 'Uploading...';
+            uploadProgress.style.display = 'block';
+            uploadProgressBar.style.width = '0%';
+            setUploadStatus('', '');
+
+            const formData = new FormData();
+            formData.append('voice_id', uploadVoiceId.value.trim());
+            formData.append('ref_text', uploadRefText.value.trim());
+            formData.append('audio', uploadFile);
+            formData.append('language', uploadLanguage.value);
+            formData.append('gender', uploadGender.value);
+
+            try {
+                const xhr = new XMLHttpRequest();
+                await new Promise((resolve, reject) => {
+                    xhr.upload.addEventListener('progress', (e) => {
+                        if (e.lengthComputable) {
+                            uploadProgressBar.style.width = Math.round((e.loaded / e.total) * 100) + '%';
+                        }
+                    });
+                    xhr.addEventListener('load', () => {
+                        if (xhr.status >= 200 && xhr.status < 300) resolve(JSON.parse(xhr.responseText));
+                        else reject(new Error(JSON.parse(xhr.responseText)?.detail?.error?.message || 'Upload failed'));
+                    });
+                    xhr.addEventListener('error', () => reject(new Error('Network error')));
+                    xhr.open('POST', API + '/v1/audio/voices/upload');
+                    xhr.send(formData);
+                });
+
+                setUploadStatus('Voice uploaded successfully!', 'success');
+                // Reset form
+                uploadVoiceId.value = '';
+                uploadRefText.value = '';
+                uploadFile = null;
+                uploadFileInput.value = '';
+                uploadDropZone.textContent = 'Drop WAV file here or click to browse';
+                uploadDropZone.classList.remove('has-file');
+                uploadLanguage.value = 'unknown';
+                uploadGender.value = 'unknown';
+                refreshState();
+            } catch (e) {
+                setUploadStatus(e.message, 'error');
+            } finally {
+                uploadBtn.disabled = false;
+                uploadBtn.textContent = 'Upload & Clone Voice';
+                uploadProgress.style.display = 'none';
+                validateUploadForm();
+            }
+        });
+
+        function setUploadStatus(msg, type) {
+            uploadStatus.textContent = msg;
+            uploadStatus.className = 'voice-upload-status' + (type ? ' upload-' + type : '');
+            if (msg && type) {
+                setTimeout(() => { uploadStatus.className = 'voice-upload-status'; }, 5000);
+            }
+        }
+
+        // --- Browser Voice Recording ---
+        recordBtn.addEventListener('click', async () => {
+            if (mediaRecorder && mediaRecorder.state === 'recording') {
+                mediaRecorder.stop();
+                return;
+            }
+
+            try {
+                const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+                recordChunks = [];
+                mediaRecorder = new MediaRecorder(stream, { mimeType: 'audio/webm' });
+
+                mediaRecorder.addEventListener('dataavailable', (e) => {
+                    if (e.data.size > 0) recordChunks.push(e.data);
+                });
+
+                mediaRecorder.addEventListener('stop', async () => {
+                    stream.getTracks().forEach(t => t.stop());
+                    recordBtn.classList.remove('recording');
+                    recordBtn.textContent = 'REC';
+                    clearInterval(recordTimerInterval);
+
+                    const webmBlob = new Blob(recordChunks, { type: 'audio/webm' });
+                    try {
+                        const wavBlob = await convertToWav(webmBlob);
+                        uploadFile = new File([wavBlob], 'recording.wav', { type: 'audio/wav' });
+                        uploadDropZone.textContent = 'Recording (' + (wavBlob.size / 1024).toFixed(1) + ' KB)';
+                        uploadDropZone.classList.add('has-file');
+                        validateUploadForm();
+                    } catch (err) {
+                        setUploadStatus('Failed to convert recording: ' + err.message, 'error');
+                    }
+                });
+
+                mediaRecorder.start();
+                recordBtn.classList.add('recording');
+                recordBtn.textContent = 'STOP';
+                recordStartTime = Date.now();
+                recordTimer.textContent = '0:00';
+                recordTimerInterval = setInterval(() => {
+                    const elapsed = Math.floor((Date.now() - recordStartTime) / 1000);
+                    recordTimer.textContent = Math.floor(elapsed / 60) + ':' + String(elapsed % 60).padStart(2, '0');
+                    if (elapsed >= 30) mediaRecorder.stop(); // Auto-stop at 30s
+                }, 1000);
+
+            } catch (err) {
+                setUploadStatus('Microphone access denied: ' + err.message, 'error');
+            }
+        });
+
+        // --- WAV Conversion (WebM -> WAV via AudioContext) ---
+        async function convertToWav(webmBlob) {
+            const convCtx = new (window.AudioContext || window.webkitAudioContext)();
+            const arrayBuf = await webmBlob.arrayBuffer();
+            const audioBuf = await convCtx.decodeAudioData(arrayBuf);
+            convCtx.close();
+
+            // Downmix to mono
+            const numFrames = audioBuf.length;
+            const sampleRate = audioBuf.sampleRate;
+            let mono;
+            if (audioBuf.numberOfChannels === 1) {
+                mono = audioBuf.getChannelData(0);
+            } else {
+                mono = new Float32Array(numFrames);
+                for (let ch = 0; ch < audioBuf.numberOfChannels; ch++) {
+                    const chData = audioBuf.getChannelData(ch);
+                    for (let i = 0; i < numFrames; i++) mono[i] += chData[i];
+                }
+                for (let i = 0; i < numFrames; i++) mono[i] /= audioBuf.numberOfChannels;
+            }
+
+            // Write WAV header + 16-bit PCM data
+            const dataLen = mono.length * 2;
+            const buffer = new ArrayBuffer(44 + dataLen);
+            const view = new DataView(buffer);
+
+            function writeStr(offset, str) { for (let i = 0; i < str.length; i++) view.setUint8(offset + i, str.charCodeAt(i)); }
+
+            writeStr(0, 'RIFF');
+            view.setUint32(4, 36 + dataLen, true);
+            writeStr(8, 'WAVE');
+            writeStr(12, 'fmt ');
+            view.setUint32(16, 16, true);
+            view.setUint16(20, 1, true); // PCM
+            view.setUint16(22, 1, true); // mono
+            view.setUint32(24, sampleRate, true);
+            view.setUint32(28, sampleRate * 2, true); // byte rate
+            view.setUint16(32, 2, true); // block align
+            view.setUint16(34, 16, true); // bits per sample
+            writeStr(36, 'data');
+            view.setUint32(40, dataLen, true);
+
+            for (let i = 0; i < mono.length; i++) {
+                const s = Math.max(-1, Math.min(1, mono[i]));
+                view.setInt16(44 + i * 2, s < 0 ? s * 0x8000 : s * 0x7FFF, true);
+            }
+
+            return new Blob([buffer], { type: 'audio/wav' });
+        }
+
+        // --- Model load/unload ---
+        async function unloadModel(id) {
+            showStatus('Unloading ' + id + '...', 'info');
+            try {
+                const r = await fetch(API + '/v1/models/' + id, { method: 'DELETE' });
+                if (!r.ok) throw new Error(await r.text());
+                showStatus(id + ' unloaded', 'success');
+                refreshState();
+            } catch (e) { showStatus('Unload failed: ' + e.message, 'error'); }
+        }
+
+        async function switchDevice(modelId, targetDevice) {
+            showStatus('Switching ' + modelId + ' to ' + targetDevice + '...', 'info');
+            try {
+                const r = await fetch(API + '/v1/models/' + modelId + '/switch-device', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ backbone_device: targetDevice, codec_device: targetDevice })
+                });
+                if (!r.ok) {
+                    const e = await r.json();
+                    throw new Error(e.detail?.error?.message || 'Switch failed');
+                }
+                const task = await r.json();
+                startPollingTask(task.task_id);
+                showStatus('Switching ' + modelId + ' to ' + targetDevice + '...', 'info');
+            } catch (e) { showStatus('Switch failed: ' + e.message, 'error'); }
+        }
+
+        // --- Task polling ---
+        function startPollingTask(taskId) {
+            if (loadingTaskTimers[taskId]) return;
+            renderLoadingTask({ task_id: taskId, model_id: '...', status: 'pending', progress_message: 'Starting...', elapsed_seconds: 0 });
+            const timer = setInterval(async () => {
+                try {
+                    const r = await fetch(API + '/v1/models/load/' + taskId);
+                    if (!r.ok) { clearInterval(timer); delete loadingTaskTimers[taskId]; return; }
+                    const task = await r.json();
+                    renderLoadingTask(task);
+                    if (task.status === 'ready') {
+                        clearInterval(timer);
+                        delete loadingTaskTimers[taskId];
+                        showStatus(task.model_id + ' loaded!', 'success');
+                        refreshState();
+                    } else if (task.status === 'error') {
+                        clearInterval(timer);
+                        delete loadingTaskTimers[taskId];
+                        showStatus('Failed to load ' + task.model_id + ': ' + task.error_message, 'error');
+                        setTimeout(() => { removeLoadingCard(taskId); }, 5000);
+                    }
+                } catch {
+                    clearInterval(timer);
+                    delete loadingTaskTimers[taskId];
+                }
+            }, 1500);
+            loadingTaskTimers[taskId] = timer;
+        }
+
+        function renderLoadingTask(task) {
+            let card = document.querySelector('[data-task-id="' + task.task_id + '"]');
+            if (!card) {
+                card = document.createElement('div');
+                card.className = 'loading-card';
+                card.setAttribute('data-task-id', task.task_id);
+                loadingTasksList.appendChild(card);
+            }
+
+            const statusLabels = {
+                pending: 'Queued',
+                downloading: 'Downloading',
+                loading: 'Loading',
+                ready: 'Ready',
+                error: 'Error'
+            };
+
+            card.className = 'loading-card'
+                + (task.status === 'error' ? ' error-card' : '')
+                + (task.status === 'ready' ? ' ready-card' : '');
+
+            const spinnerHtml = (task.status === 'pending' || task.status === 'downloading' || task.status === 'loading')
+                ? '<div class="loading-spinner-sm"></div>' : '';
+
+            // Progress bar percentages by phase
+            const progressPct = { pending: 10, downloading: 40, loading: 75, ready: 100, error: 0 };
+            const progressColors = {
+                pending: 'rgba(148,163,184,0.5)',
+                downloading: 'linear-gradient(90deg, var(--fg), var(--fg2))',
+                loading: 'linear-gradient(90deg, #a78bfa, #c084fc)',
+                ready: 'var(--success)',
+                error: 'var(--error)'
+            };
+            const pct = progressPct[task.status] || 0;
+            const color = progressColors[task.status] || 'var(--fg)';
+
+            card.innerHTML = spinnerHtml
+                + '<span class="loading-model">' + task.model_id + '</span>'
+                + '<span class="loading-phase">' + (task.progress_message || statusLabels[task.status] || task.status) + '</span>'
+                + '<span class="loading-time">' + task.elapsed_seconds.toFixed(1) + 's</span>'
+                + '<div class="loading-progress-bar"><div class="loading-progress-bar-fill" style="width:' + pct + '%;background:' + color + '"></div></div>';
+        }
+
+        function removeLoadingCard(taskId) {
+            const card = document.querySelector('[data-task-id="' + taskId + '"]');
+            if (card) card.remove();
+        }
+
+        loadBtn.addEventListener('click', async () => {
+            const id = registrySelect.value;
+            if (!id) return;
+            loadBtn.disabled = true; loadBtn.textContent = 'Loading...';
+            showStatus('Loading ' + id + '...', 'info');
+            try {
+                const r = await fetch(API + '/v1/models/load', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ model_id: id })
+                });
+                if (!r.ok) { const e = await r.json(); throw new Error(e.detail?.error?.message || 'Load failed'); }
+                const task = await r.json();
+                if (task.status === 'ready') {
+                    showStatus(id + ' loaded!', 'success');
+                    refreshState();
+                } else {
+                    startPollingTask(task.task_id);
+                }
+            } catch (e) { showStatus('Load failed: ' + e.message, 'error'); }
+            finally { loadBtn.disabled = false; loadBtn.textContent = 'Load'; }
+        });
+
+        // --- Generate ---
+        async function generate() {
+            const text = ttsText.value.trim();
+            if (!text || !modelSelect.value) return;
+
+            // Language mismatch check
+            const selVoice = voices.find(v => v.name === selectedVoice);
+            const selModel = loadedModels.find(m => m.id === modelSelect.value);
+            if (selVoice && selModel && selVoice.language && selModel.language
+                && selVoice.language !== selModel.language) {
+                const vLang = getLanguageLabel(selVoice.language);
+                const mLang = getLanguageLabel(selModel.language);
+                if (!confirm('Language mismatch!\n\nVoice "' + selectedVoice + '" is ' + vLang
+                    + ' but model "' + selModel.id + '" is ' + mLang + '.\n\n'
+                    + 'This will likely produce wrong accent/pronunciation.\nContinue anyway?')) {
+                    return;
+                }
+            }
+
+            genBtn.classList.add('spinning');
+            genBtn.disabled = true;
+            cancelBtn.style.display = 'block';
+            dlWrap.classList.remove('ready');
+            genProgress.style.width = '0%';
+            showStatus('Generating...', 'info');
+
+            if (currentBlobUrl) { URL.revokeObjectURL(currentBlobUrl); currentBlobUrl = null; }
+
+            abortCtrl = new AbortController();
+            const t0 = performance.now();
+
+            try {
+                const res = await fetch(API + '/v1/audio/speech', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model: modelSelect.value,
+                        input: text,
+                        voice: selectedVoice,
+                        response_format: fmtSelect.value,
+                        speed: parseFloat(speedRange.value),
+                        stream: streamChk.checked,
+                    }),
+                    signal: abortCtrl.signal,
+                });
+
+                if (!res.ok) {
+                    const err = await res.json();
+                    throw new Error(err.detail?.error?.message || err.detail || 'Failed');
+                }
+
+                // Track progress for streaming with enhanced status
+                const reader = res.body.getReader();
+                const chunks = [];
+                let received = 0;
+
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) break;
+                    chunks.push(value);
+                    received += value.length;
+                    const elapsedNow = ((performance.now() - t0) / 1000).toFixed(1);
+                    const kbReceived = (received / 1024).toFixed(1);
+                    statusMsg.textContent = 'Generating... ' + kbReceived + ' KB | ' + elapsedNow + 's';
+                    genProgress.style.width = Math.min(90, received / 500) + '%';
+                }
+
+                genProgress.style.width = '100%';
+                const blob = new Blob(chunks);
+                const elapsed = ((performance.now() - t0) / 1000).toFixed(2);
+                const sizeKB = (blob.size / 1024).toFixed(1);
+
+                currentBlobUrl = URL.createObjectURL(blob);
+                audio.src = currentBlobUrl;
+                dlBtn.href = currentBlobUrl;
+                dlBtn.download = 'neutts_' + selectedVoice + '_' + Date.now() + '.' + fmtSelect.value;
+                dlBtn.title = 'Download (' + sizeKB + ' KB)';
+                dlWrap.classList.add('ready');
+
+                showStatus(
+                    'Done! ' + fmtSelect.value.toUpperCase() + ' | '
+                    + sizeKB + ' KB | '
+                    + elapsed + 's | ' + text.length + ' chars',
+                    'success'
+                );
+
+                if (autoplayChk.checked) {
+                    ensureAudioCtx();
+                    audio.play().catch(() => {});
+                }
+
+            } catch (e) {
+                if (e.name === 'AbortError') {
+                    showStatus('Cancelled', 'info');
+                } else {
+                    showStatus(e.message, 'error');
+                }
+            } finally {
+                genBtn.classList.remove('spinning');
+                genBtn.disabled = loadedModels.length === 0;
+                cancelBtn.style.display = 'none';
+                abortCtrl = null;
+                setTimeout(() => { genProgress.style.width = '0%'; }, 2000);
+            }
+        }
+
+        genBtn.addEventListener('click', generate);
+        cancelBtn.addEventListener('click', () => { if (abortCtrl) abortCtrl.abort(); });
+        ttsText.addEventListener('keydown', e => {
+            if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+                e.preventDefault();
+                if (!genBtn.disabled) generate();
+            }
+        });
+
+        // --- Status ---
+        function showStatus(msg, type) {
+            statusMsg.textContent = msg;
+            statusMsg.className = 'status-msg ' + type;
+        }
+
+        // --- Init ---
+        refreshState();
+        setInterval(refreshState, 20000);
+    })();
+    </script>
+</body>
+</html>

api/src/structures/schemas.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+# --- OpenAI-compatible Request ---
+
+class OpenAISpeechRequest(BaseModel):
+    model: str = "neutts-nano-q4-gguf"
+    input: str = Field(..., min_length=1, max_length=10000)
+    voice: str = "jo"
+    response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] = "mp3"
+    speed: float = Field(default=1.0, ge=0.25, le=4.0)
+    stream: bool = False
+
+
+# --- OpenAI-compatible Responses ---
+
+class VoiceInfo(BaseModel):
+    voice_id: str
+    name: str
+    language: str
+    gender: str
+    custom: bool = False
+    available: bool = True
+    preview_url: str | None = None
+
+
+class VoiceListResponse(BaseModel):
+    voices: list[VoiceInfo]
+
+
+class ModelInfo(BaseModel):
+    id: str
+    object: str = "model"
+    created: int = 0
+    owned_by: str = "neuphonic"
+    language: str | None = None
+    backend: str | None = None
+    supports_streaming: bool = False
+    backbone_device: str | None = None
+    codec_device: str | None = None
+
+
+class ModelListResponse(BaseModel):
+    object: str = "list"
+    data: list[ModelInfo]
+
+
+class ModelDetailResponse(ModelInfo):
+    loaded: bool = False
+    codec: str | None = None
+
+
+# --- Model Management ---
+
+class LoadModelRequest(BaseModel):
+    model_id: str
+    codec: str | None = None
+    backbone_device: str | None = None
+    codec_device: str | None = None
+
+
+class UnloadModelResponse(BaseModel):
+    model_id: str
+    status: str = "unloaded"
+
+
+class ModelLoadTaskResponse(BaseModel):
+    task_id: str
+    model_id: str
+    status: str
+    progress_message: str = ""
+    error_message: str = ""
+    elapsed_seconds: float = 0.0
+
+
+class SwitchDeviceRequest(BaseModel):
+    backbone_device: str | None = None
+    codec_device: str | None = None
+
+
+class LoadedModelInfo(BaseModel):
+    model_id: str
+    codec: str
+    backbone_device: str
+    codec_device: str
+    language: str | None = None
+    backend: str | None = None
+    supports_streaming: bool = False
+
+
+class LoadedModelsResponse(BaseModel):
+    models: list[LoadedModelInfo]
+
+
+class RegistryModelInfo(BaseModel):
+    model_id: str
+    repo: str
+    language: str
+    backend: str
+    supports_streaming: bool
+    description: str
+    loaded: bool = False
+
+
+class ModelRegistryResponse(BaseModel):
+    backbones: list[RegistryModelInfo]
+    codecs: list[dict]
+
+
+# --- Voice Management ---
+
+class VoiceEncodeRequest(BaseModel):
+    codec: str | None = None
+
+
+class VoiceUploadResponse(BaseModel):
+    voice_id: str
+    status: str = "uploaded"
+    message: str = ""
+    language: str = "unknown"
+    gender: str = "unknown"
+
+
+class VoiceDeleteResponse(BaseModel):
+    voice_id: str
+    status: str = "deleted"
+
+
+class VoiceEncodeResponse(BaseModel):
+    voice_id: str
+    codec: str
+    status: str = "encoded"
+
+
+# --- Health & Debug ---
+
+class HealthResponse(BaseModel):
+    status: str = "ok"
+    version: str = "0.1.0"
+    models_loaded: int = 0
+
+
+class SystemDebugResponse(BaseModel):
+    cpu_count: int
+    cpu_percent: float
+    memory_total_gb: float
+    memory_used_gb: float
+    memory_percent: float
+    gpu_available: bool
+    gpu_info: list[dict] | None = None
+    torch_version: str | None = None
+    cuda_version: str | None = None
+    cuda_driver_version: str | None = None
+    gpu_detected_but_unusable: bool = False
+    gpu_fix_instructions: str | None = None
+    models_loaded: list[str]
+    voices_available: int
+
+
+# --- Error ---
+
+class ErrorResponse(BaseModel):
+    error: dict
+
+
+def make_error(message: str, error_type: str = "invalid_request_error", code: int = 400) -> dict:
+    return {
+        "error": {
+            "message": message,
+            "type": error_type,
+            "code": code,
+        }
+    }

api/src/structures/websocket_schemas.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class WSMessage(BaseModel):
+    type: Literal["start", "text", "stop", "ping"]
+
+
+class WSStartMessage(WSMessage):
+    type: Literal["start"] = "start"
+    model: str = "neutts-nano-q4-gguf"
+    voice: str = "jo"
+    response_format: Literal["mp3", "opus", "aac", "flac", "wav", "pcm"] = "pcm"
+    sample_rate: int = 24000
+
+
+class WSTextMessage(WSMessage):
+    type: Literal["text"] = "text"
+    text: str = Field(..., min_length=1)
+
+
+class WSStopMessage(WSMessage):
+    type: Literal["stop"] = "stop"
+
+
+class WSPingMessage(WSMessage):
+    type: Literal["ping"] = "ping"
+
+
+class WSResponseMessage(BaseModel):
+    type: Literal["audio", "error", "done", "pong"]
+    data: str | None = None
+    message: str | None = None
+    format: str | None = None

api/src/voices/builtin/dave.txt

@@ -0,0 +1 @@
+So I'm live on radio. And I say, well, my dear friend James here clearly, and the whole room just froze. Turns out I'd completely misspoken and mentioned our other friend.

api/src/voices/builtin/dave.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6c6b0e0c730ad0eddb53f321bd571ba55c3ed7ac4422610a17de7f62675c09e9
+size 1313748

api/src/voices/builtin/dave_neuphonic_distill-neucodec.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9ffe2bdbece11d7a19df1e81eb34a4dd32b5da81988dac3afc8d0459c8777c56
+size 3281

api/src/voices/builtin/greta.txt

@@ -0,0 +1 @@
+Es wurde eine Untersuchung zur Aufklärung des Unfalls eingeleitet.

api/src/voices/builtin/greta.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:af9167fc76e824cc8e46ce1afecbc3144c6bc84195ba9fd9884de95716dd5534
+size 191566

api/src/voices/builtin/greta_neuphonic_distill-neucodec.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:52b08ae1537c430076d29f7ec3c607d18a1689cc54d7d1e6c757619a2649a432
+size 2584

api/src/voices/builtin/jo.txt

@@ -0,0 +1 @@
+So I just tried Neuphonic and I’m genuinely impressed. It's super responsive, it sounds clean, supports voice cloning, and the agent feature is fun to play with too. Highly recommend it for podcasts, conversations, or even just messing around with voiceovers.

api/src/voices/builtin/jo.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f789bc3799e64675a6324a978a3fffb0dd7850739d232cbe3d4bbbbc9973a314
+size 575990

api/src/voices/builtin/jo_neuphonic_distill-neucodec.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:788d04716eebc7abaf639dbab50750558535f1693832e1105576c4b45e89ca6c
+size 4419

api/src/voices/builtin/juliette.txt

@@ -0,0 +1 @@
+Dans les zones rurales où de nombreuses communautés n'ont pas accès à l'électricité, l'énergie solaire peut faire une énorme différence.

api/src/voices/builtin/juliette.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:22255eeb3fc4d49df09952ce59fde7d7b7de17ff117abcdb206f9bc276e64cde
+size 357254

api/src/voices/builtin/mateo.txt

@@ -0,0 +1 @@
+Además su eficiencia depende del clima. En días nublados o durante la noche producen menos energía.

api/src/voices/builtin/mateo.wav

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:73a7740c771191ab781df867ce6b39b14de8267cc6580711a956b202a4b645cb
+size 280520

docker/scripts/download_models.py

@@ -0,0 +1,48 @@
+"""Pre-download models during Docker build or startup."""
+from __future__ import annotations
+
+import os
+import sys
+
+
+def main() -> None:
+    models_str = os.environ.get("NEUTTS_DEFAULT_MODELS", "neutts-nano-q4-gguf")
+    codec = os.environ.get("NEUTTS_DEFAULT_CODEC", "neuphonic/neucodec-onnx-decoder")
+
+    models = [m.strip() for m in models_str.split(",") if m.strip()]
+
+    # Import model config to resolve repos
+    sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(__file__))))
+    from api.src.core.model_config import get_backbone_info
+
+    print(f"Pre-downloading {len(models)} model(s) and codec '{codec}'...")
+
+    for model_id in models:
+        info = get_backbone_info(model_id)
+        if info is None:
+            print(f"  WARNING: Unknown model '{model_id}', skipping")
+            continue
+
+        print(f"  Downloading backbone: {info.repo}")
+        try:
+            from huggingface_hub import snapshot_download
+
+            snapshot_download(info.repo)
+            print(f"  OK: {info.repo}")
+        except Exception as e:
+            print(f"  FAILED: {info.repo} - {e}")
+
+    print(f"  Downloading codec: {codec}")
+    try:
+        from huggingface_hub import snapshot_download
+
+        snapshot_download(codec)
+        print(f"  OK: {codec}")
+    except Exception as e:
+        print(f"  FAILED: {codec} - {e}")
+
+    print("Download complete.")
+
+
+if __name__ == "__main__":
+    main()

entrypoint.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+set -e
+
+export PHONEMIZER_ESPEAK_LIBRARY=${PHONEMIZER_ESPEAK_LIBRARY:-/usr/lib/x86_64-linux-gnu/libespeak-ng.so.1}
+export ESPEAK_DATA_PATH=${ESPEAK_DATA_PATH:-/usr/lib/x86_64-linux-gnu/espeak-ng-data}
+
+if [ "${NEUTTS_PREDOWNLOAD_MODELS:-false}" = "true" ]; then
+    echo "Pre-downloading models..."
+    python -m docker.scripts.download_models
+fi
+
+echo "Starting NeuTTS-FastAPI server on port ${NEUTTS_PORT:-7860}..."
+exec uvicorn api.src.main:app \
+    --host "${NEUTTS_HOST:-0.0.0.0}" \
+    --port "${NEUTTS_PORT:-7860}" \
+    --workers 1 \
+    --log-level "${NEUTTS_LOG_LEVEL:-info}"

pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "neutts-fastapi-hf"
+version = "0.1.0"
+description = "NeuTTS TTS API for Hugging Face Spaces"
+requires-python = ">=3.10,<3.14"
+
+dependencies = [
+    "neutts>=1.1.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.30.0",
+    "pydantic-settings>=2.0.0",
+    "av>=12.0.0",
+    "loguru>=0.7.0",
+    "psutil>=5.9.0",
+    "python-multipart>=0.0.7",
+    "soundfile>=0.13.0",
+    "websockets>=12.0",
+    "setuptools>=70.0.0",
+]
+
+[project.optional-dependencies]
+gpu = ["neutts[all]", "onnxruntime-gpu", "torch>=2.6.0"]
+cpu = ["neutts[all]", "onnxruntime"]
+dev = ["pytest>=8.0.0", "pytest-asyncio>=0.23.0", "httpx>=0.27.0", "ruff>=0.4.0"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["api"]