implement v2 with docker support

This pull request represents a major version 2.0 refactoring of the Pocket-TTS OpenAI-compatible server. The PR restructures the monolithic codebase into a modular application architecture, adds comprehensive Docker support, improves logging and configuration management, and updates the port from 5002 to 49112.

Changes:

Complete architectural refactor from single-file (pocket_tts_openai_server.py, utils.py) to modular app/ package structure with separate services, routes, and configuration modules
Added Docker deployment with multi-stage builds, health checks, and docker-compose orchestration
Implemented comprehensive logging with rotation support
Added CI/CD workflows for linting, Docker builds, and Windows executable generation
Enhanced documentation with updated README, new AGENTS.md for developers, and inline API documentation in the web UI
Changed default port from 5002 to 49112

.dockerignore

@@ -0,0 +1,44 @@
+# Docker build artifacts
+.git
+.gitignore
+.env
+*.md
+!README.md
+*.pyc
+__pycache__
+*.pyo
+*.pyd
+.Python
+*.so
+.eggs
+*.egg-info
+*.egg
+dist
+build
+*.spec
+
+# PyInstaller
+*.exe
+*.bat
+
+# IDE
+.vscode
+.idea
+*.swp
+*.swo
+
+# Logs (we mount these as volume)
+logs/
+
+# Virtual environments
+venv/
+.venv/
+
+# Test files
+tests/
+*.test.py
+pytest.ini
+
+# Frozen requirements (use requirements.txt for Docker)
+frozen_requirements.txt
+pyinstaller_command.txt

.env.example

@@ -0,0 +1,14 @@
+# Docker environment configuration template
+# Copy to .env and customize as needed
+
+# Server settings
+POCKET_TTS_PORT=49112
+POCKET_TTS_LOG_LEVEL=INFO
+POCKET_TTS_STREAM_DEFAULT=true
+
+# Custom voices directory (mounted to container)
+# POCKET_TTS_VOICES_DIR=./my_custom_voices
+
+# Hugging Face token for voice cloning (optional)
+# Get your token from: https://huggingface.co/settings/tokens
+# HF_TOKEN=hf_xxxxxxxxxxxxx

.github/workflows/build-exe.yml

@@ -0,0 +1,74 @@
+# Build Windows Executable
+# Triggered on version tags (e.g., v1.0.0)
+
+name: Build Windows EXE
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch: # Allow manual trigger
+
+jobs:
+  build:
+    runs-on: windows-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt
+          pip install pyinstaller
+
+      - name: Build executable
+        run: |
+          pyinstaller --noconfirm --clean --onefile ^
+            --name "PocketTTS-Server" ^
+            --add-data "static;static" ^
+            --add-data "templates;templates" ^
+            --add-data "voices;voices" ^
+            --add-data "app;app" ^
+            --collect-all "pocket_tts" ^
+            --hidden-import "waitress" ^
+            --hidden-import "engineio.async_drivers.threading" ^
+            server.py
+        shell: cmd
+
+      - name: Create release package
+        run: |
+          mkdir release
+          copy dist\PocketTTS-Server.exe release\
+          copy run_pocket_tts_server_exe.bat release\
+          copy README.md release\
+          copy LICENSE release\
+        shell: cmd
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: PocketTTS-Server-Windows
+          path: release/
+          retention-days: 30
+
+      - name: Create GitHub Release
+        if: startsWith(github.ref, 'refs/tags/')
+        uses: softprops/action-gh-release@v1
+        with:
+          files: |
+            release/PocketTTS-Server.exe
+            release/run_pocket_tts_server_exe.bat
+            release/README.md
+          draft: false
+          prerelease: false
+          generate_release_notes: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+# Continuous Integration - Linting and Testing
+
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install ruff
+        run: pip install ruff
+
+      - name: Run ruff linter
+        run: ruff check .
+
+      - name: Run ruff formatter check
+        run: ruff format --check .

.github/workflows/docker.yml

@@ -0,0 +1,63 @@
+# Build and Push Docker Image
+
+name: Docker Build
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=sha
+
+      - name: Build and push
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          platforms: linux/amd64

.gitignore

@@ -3,6 +3,9 @@ __pycache__/
 *.py[cod]
 *$py.class
 
+# Logs
+logs/*.log
+
 # C extensions
 *.so
 
@@ -174,8 +177,8 @@ cython_debug/
 # PyPI configuration file
 .pypirc
 
-# Cursor  
-#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to 
+# Cursor
+#  Cursor is an AI-powered code editor.`.cursorignore` specifies files/directories to
 #  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
 #  refer to https://docs.cursor.com/context/ignore-files
 .cursorignore

.vscode/extensions.json

@@ -0,0 +1,7 @@
+{
+    "recommendations": [
+        "ms-python.python",
+        "charliermarsh.ruff",
+        "ms-python.debugpy"
+    ]
+}

.vscode/launch.json

@@ -0,0 +1,55 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "PocketTTS Server",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/server.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "env": {
+                "POCKET_TTS_LOG_LEVEL": "DEBUG",
+                "POCKET_TTS_PORT": "49112"
+            },
+            "args": []
+        },
+        {
+            "name": "PocketTTS Server (Custom Port)",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/server.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "args": [
+                "--port",
+                "8080",
+                "--log-level",
+                "DEBUG"
+            ]
+        },
+        {
+            "name": "PocketTTS Server (With Voices Dir)",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${workspaceFolder}/server.py",
+            "console": "integratedTerminal",
+            "justMyCode": true,
+            "args": [
+                "--voices-dir",
+                "${workspaceFolder}/voices",
+                "--stream",
+                "--log-level",
+                "DEBUG"
+            ]
+        },
+        {
+            "name": "Python: Current File",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": true
+        }
+    ]
+}

.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "python.defaultInterpreterPath": "${workspaceFolder}/venv/bin/python",
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.codeActionsOnSave": {
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit"
+        },
+        "editor.defaultFormatter": "charliermarsh.ruff"
+    }
+}

AGENTS.md

@@ -0,0 +1,102 @@
+# Project Overview
+
+**PocketTTS OpenAI-Compatible Server** wraps [pocket-tts](https://github.com/kyutai-labs/pocket-tts) to provide OpenAI-compatible TTS endpoints. Any OpenAI TTS client can use this for local, CPU-based text-to-speech.
+
+## Why This Exists
+
+The official `pocket-tts` has a FastAPI server with `/tts` endpoint, but it's **not OpenAI API compatible**. This project adds:
+
+- `/v1/audio/speech` matching OpenAI's schema
+- `/v1/voices` for voice listing
+- Docker deployment with voice mounting
+- Windows executable distribution
+
+## Architecture
+
+```
+server.py                    # Entry point, CLI, starts Waitress
+    └── app/__init__.py      # Flask app factory
+        ├── app/routes.py    # API endpoints
+        ├── app/config.py    # Environment config
+        └── app/services/
+            ├── tts.py       # TTSService: model, voice cache
+            └── audio.py     # Format conversion, streaming
+```
+
+## Key Files
+
+| File                  | Purpose                                                          |
+| --------------------- | ---------------------------------------------------------------- |
+| `server.py`           | Entry point, CLI args, Waitress server                           |
+| `app/routes.py`       | HTTP endpoints: `/`, `/health`, `/v1/voices`, `/v1/audio/speech` |
+| `app/services/tts.py` | Model loading, voice caching, generation                         |
+| `app/config.py`       | Environment variables, path resolution                           |
+
+## API Endpoints
+
+| Endpoint           | Method | Purpose                             |
+| ------------------ | ------ | ----------------------------------- |
+| `/`                | GET    | Web UI                              |
+| `/health`          | GET    | Health check for containers         |
+| `/v1/voices`       | GET    | List voices                         |
+| `/v1/audio/speech` | POST   | Generate speech (OpenAI-compatible) |
+
+### Speech Request
+
+```json
+{
+	"model": "tts-1",
+	"input": "Text to speak",
+	"voice": "alba",
+	"response_format": "mp3",
+	"stream": false
+}
+```
+
+## Configuration (Environment Variables)
+
+| Variable                    | Default   | Purpose            |
+| --------------------------- | --------- | ------------------ |
+| `POCKET_TTS_HOST`           | `0.0.0.0` | Bind address       |
+| `POCKET_TTS_PORT`           | `49112`   | Port               |
+| `POCKET_TTS_VOICES_DIR`     | None      | Custom voices path |
+| `POCKET_TTS_STREAM_DEFAULT` | `true`    | Default streaming  |
+| `POCKET_TTS_LOG_LEVEL`      | `INFO`    | Log verbosity      |
+
+## Voice Resolution Order
+
+1. Built-in names (`alba`, `marius`, etc.) → pass to pocket-tts
+2. HuggingFace models (`hf://` URLs) → pass to pocket-tts
+3. Files in `POCKET_TTS_VOICES_DIR`
+4. Absolute paths
+5. Fallback to pocket-tts
+
+**Security Note**: HTTP/HTTPS URLs are blocked to prevent SSRF attacks. Only `hf://` URLs are allowed for remote models.
+
+## Development
+
+```bash
+# Install
+pip install -r requirements.txt
+
+# Run
+python server.py --log-level DEBUG
+
+# Test
+curl http://localhost:49112/health
+curl -X POST http://localhost:49112/v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{"input": "Hello", "voice": "alba"}' -o test.mp3
+```
+
+## Code Style
+
+- Linter/formatter: `ruff` (config in `pyproject.toml`)
+- Line length: 100
+- Single quotes
+
+## Deployment
+
+- **Python**: `python server.py`
+- **Docker**: `docker compose up -d`
+- **Windows EXE**: Built via GitHub Actions on release tags

Dockerfile

@@ -0,0 +1,73 @@
+# Dockerfile for PocketTTS OpenAI-Compatible Server
+# Optimized for CPU inference (pocket-tts runs efficiently on CPU)
+# Uses CPU-only PyTorch for smaller image size (~700MB vs ~2GB)
+
+FROM python:3.10-slim AS builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Create virtual environment
+RUN python -m venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Install Python dependencies (requirements.txt specifies CPU-only PyTorch)
+COPY requirements.txt /tmp/requirements.txt
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -r /tmp/requirements.txt
+
+
+# Production image
+FROM python:3.10-slim
+
+# Install runtime dependencies for audio processing
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    libsndfile1 \
+    ffmpeg \
+    && rm -rf /var/lib/apt/lists/* \
+    && apt-get clean
+
+# Copy virtual environment from builder
+COPY --from=builder /opt/venv /opt/venv
+ENV PATH="/opt/venv/bin:$PATH"
+
+# Create non-root user
+RUN useradd --create-home --shell /bin/bash pockettts
+WORKDIR /app
+
+# Copy application code
+COPY --chown=pockettts:pockettts app/ ./app/
+COPY --chown=pockettts:pockettts static/ ./static/
+COPY --chown=pockettts:pockettts templates/ ./templates/
+COPY --chown=pockettts:pockettts voices/ ./voices/
+COPY --chown=pockettts:pockettts server.py ./
+
+# Create logs directory
+RUN mkdir -p /app/logs && chown pockettts:pockettts /app/logs
+
+# Create HuggingFace cache directory (for volume mount)
+RUN mkdir -p /home/pockettts/.cache/huggingface && \
+    chown -R pockettts:pockettts /home/pockettts/.cache
+
+# Switch to non-root user
+USER pockettts
+
+# Environment variables with defaults
+ENV POCKET_TTS_HOST=0.0.0.0 \
+    POCKET_TTS_PORT=49112 \
+    POCKET_TTS_VOICES_DIR=/app/voices \
+    POCKET_TTS_LOG_DIR=/app/logs \
+    POCKET_TTS_LOG_LEVEL=INFO \
+    PYTHONUNBUFFERED=1
+
+# Expose port
+EXPOSE 49112
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:49112/health')" || exit 1
+
+# Run server
+CMD ["python", "server.py"]

README.md

@@ -1,152 +1,316 @@
-# Pocket-TTS OpenAI Streaming Server
+# PocketTTS OpenAI-Compatible Server
 
-This project implements an [OpenAI-compatible API](https://platform.openai.com/docs/api-reference/audio/createSpeech) for the **Pocket-TTS** text-to-speech model. It supports real-time streaming, high-quality voice synthesis, and easy management of custom voices.
+An OpenAI-compatible Text-to-Speech API server powered by [Pocket-TTS](https://github.com/kyutai-labs/pocket-tts). Drop-in replacement for OpenAI's TTS API with support for streaming, custom voices, and voice cloning.
 
-Pocket-TTS Github repo: https://github.com/kyutai-labs/pocket-tts
+**Key Features:**
 
-Pocket-TTS Huggingface: https://huggingface.co/kyutai/pocket-tts
+- 🎯 **OpenAI API Compatible** - Works with any OpenAI TTS client
+- 🚀 **Real-time Streaming** - Low-latency audio generation
+- 🎤 **150+ Community Voices** - Ready-to-use voice library included
+- 🎭 **Voice Cloning** - Clone any voice from a short audio sample
+- 🐳 **Docker Ready** - One-command deployment
+- 💻 **Cross-platform** - Runs on Windows, macOS, and Linux
+- ⚡ **CPU Optimized** - No GPU required
 
-## Features
+## Quick Start
 
--   **OpenAI API Compatibility**: Drop-in replacement for `tts-1` endpoints.
--   **Streaming Support**: Real-time audio generation with low latency.
--   **Web Interface**: Simple built-in UI to test voices and generation.
--   **Custom Voices**: Easy addition of new voices by dragging and dropping `.wav` files.
--   **Flexible Configuration**: Run via command line or an interactive batch launcher.
--   **Windows EXE included**: If you want to use defaults (host: 0.0.0.0, port: 5002, streaming enabled, local model file and built-in voices) just double click on .exe and you're up and running!
+### Option 1: Docker (Recommended)
 
-## Prerequisites
-
--   **Python 3.10+**: Ensure Python is installed and added to your system PATH.
-
-## EXE Installation and Usage (Windows only)
-
--   Download latest release .zip from https://github.com/teddybear082/pocket-tts-openai_streaming_server/releases
--   Unzip to location on your computer that is not protected, like C://Pocket-TTS-Server/
--   To use all defaults for server (host: 0.0.0.0, port: 5002, streaming enabled, local model file and built-in voices) just double click on .exe and you're up and running!
--   To be able to input custom arguments for any of those, run the run_pocket_tts_server_exe.bat instead and follow the UI prompts.
--   To use the WebUI, navigate to the host and port you set in the .bat file, by default: http://localhost:5002
--   Supports cloning .wav, .mp3. and .flac files. To try out custom cloning, use the WebUI and in the voice list select the last option to upload a custom file and insert the path to the .wav, .mp3, or .flac with the voice you want to clone.
-
-## Python Installation
-
-1.  **Clone or Download** this repository to your local machine.
-
-2.  **Install Dependencies**:
-    It is recommended to use a virtual environment.
-
-    ```bash
-    # Create virtual environment
-    python -m venv venv
+```bash
+# Clone the repository
+git clone https://github.com/teddybear082/pocket-tts-openai_streaming_server.git
+cd pocket-tts-openai_streaming_server
 
-    # Activate virtual environment
-    # Windows:
-    venv\Scripts\activate
-    # Linux/Mac:
-    source venv/bin/activate
+# Start the server
+docker compose up -d
 
-    # Install requirements
-    pip install -r requirements.txt
-    ```
+# View logs
+docker compose logs -f
+```
 
-    *Note: If you do not have `requirements.txt`, you will need at least:*
-    ```bash
-    pip install flask pocket-tts torch torchaudio
-    ```
+The server will be available at `http://localhost:49112`
 
-3.  **Hugging Face Login (If required)**:
-    Until a workaround is found, to enable voice cloning of .wavs you will need to insert your hugging face token when prompted in the .bat file.
+**Custom Configuration:**
 
-## Python Usage
+```bash
+# Change port
+POCKET_TTS_PORT=8080 docker compose up -d
 
-### Method 1: Interactive Launcher (Windows)
+# Use custom voices directory
+POCKET_TTS_VOICES_DIR=/path/to/my/voices docker compose up -d
+```
 
-Double-click `run_pocket_tts_server.bat`. This interactive script handles the setup:
+### Option 2: Python (from source)
 
-1.  **Hugging Face Login**: It may ask for your HF Token if not already set (leave blank if voice cloning not needed).
-2.  **Environment**: Automatically looks for and activates your `venv`.
-3.  **Configuration**: detailed prompts allow you to customize the run:
-    -   **Host/Port**: Defaults to `0.0.0.0:5002`.
-    -   **Model Path**: Press ENTER for the default, or specify a custom path/variant.
-    -   **Voices Directory**: Defaults to `voices/` in the script's folder.
-    -   **Streaming**: Option to enable streaming by default for all requests.
+```bash
+# Clone the repository
+git clone https://github.com/teddybear082/pocket-tts-openai_streaming_server.git
+cd pocket-tts-openai_streaming_server
 
-### Method 2: Command Line
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
 
-Activate your virtual environment and run:
+# Install dependencies
+pip install -r requirements.txt
 
-```bash
-python pocket_tts_openai_server.py --host 0.0.0.0 --port 5002 --stream
+# Start the server
+python server.py
 ```
 
-**Arguments:**
--   `--host`: Host IP to bind to (default: `0.0.0.0`).
--   `--port`: Port to listen on (default: `5002`).
--   `--model_path`: Path to a local model file or a specific Hugging Face model variant.
--   `--voices_dir`: Directory to scan for custom voice `.wav` files (default: `voices/` in the project root if created, or as specified).
--   `--stream`: Enable streaming by default for all requests.
+**Command Line Options:**
 
-## Web Interface
+```bash
+python server.py --help
 
-Once the server is running, open your web browser and go to:
+# Custom port and voices
+python server.py --port 8080 --voices-dir ./my_voices
 
-> **http://localhost:5002** (or your configured host:port)
+# Enable streaming by default
+python server.py --stream
+```
 
-From here you can:
--   Select available voices (Built-in or Custom).
--   Type text to generate speech.
--   Listen to the output directly in the browser.
+### Option 3: Windows Executable
 
-## Custom Voices
+1. Download the latest release from [Releases](https://github.com/teddybear082/pocket-tts-openai_streaming_server/releases)
+2. Extract the ZIP file
+3. Double-click `PocketTTS-Server.exe` to run with defaults
+4. Or run `run_pocket_tts_server_exe.bat` for custom configuration
 
-You can easily add your own voices to the server.
-
-1.  **Create a folder** for your voices (e.g., `voices/`).
-2.  **Add Audio Files**: Place short, clear `.wav` files (3-10 seconds ideal) of the target speaker in this folder.
-3.  **Restart/Configure Server**:
-    -   If using the **Batch Launcher**, specify the full path to your `voices` folder when prompted.
-    -   If using **CLI**, add `--voices_dir "path/to/voices"`.
+## Web Interface
 
-**Naming**: The filename (e.g., `my_voice.wav`) will become the Voice ID.
--   Example Voice ID: `my_voice.wav`
--   In the Request: `"voice": "my_voice.wav"`
+Open `http://localhost:49112` in your browser to access the built-in web UI:
 
-### Built-in Voices
-The server comes with mappings for several default Pocket TTS voices:
-`alba`, `marius`, `javert`, `jean`, `fantine`, `cosette`, `eponine`, `azelma`.
+- Select from available voices
+- Enter text to synthesize
+- Listen to generated audio directly
 
 ## API Usage
 
-You can use this server with any OpenAI-compatible client.
+### Generate Speech
 
-**Endpoint**: `POST /v1/audio/speech`
+**Endpoint:** `POST /v1/audio/speech`
 
-**Example Request (cURL)**:
 ```bash
-curl http://localhost:5002/v1/audio/speech \
+curl http://localhost:49112/v1/audio/speech \
   -H "Content-Type: application/json" \
   -d '{
     "model": "tts-1",
-    "input": "The quick brown fox jumps over the lazy dog.",
+    "input": "Hello world! This is a test.",
     "voice": "alba"
   }' \
-  --output speech.wav
+  --output speech.mp3
 ```
 
-**Python (openai-python)**:
+### Python Client
+
 ```python
 from openai import OpenAI
 
 client = OpenAI(
-    base_url="http://localhost:5002/v1",
-    api_key="not-needed"
+    base_url="http://localhost:49112/v1",
+    api_key="not-needed"  # No authentication required
 )
 
+# Generate and save audio
 response = client.audio.speech.create(
     model="tts-1",
     voice="alba",
-    input="Hello world! This is a test of Pocket TTS."
+    input="Hello world! This is a test."
 )
+response.stream_to_file("output.mp3")
 
-response.stream_to_file("output.wav")
+# Streaming
+with client.audio.speech.with_streaming_response.create(
+    model="tts-1",
+    voice="alba",
+    input="This is streaming audio.",
+    response_format="pcm"
+) as response:
+    for chunk in response.iter_bytes():
+        # Process audio chunks in real-time
+        pass
 ```
+
+### API Reference
+
+| Endpoint           | Method | Description                              |
+| ------------------ | ------ | ---------------------------------------- |
+| `/`                | GET    | Web interface                            |
+| `/health`          | GET    | Health check for container orchestration |
+| `/v1/voices`       | GET    | List available voices                    |
+| `/v1/audio/speech` | POST   | Generate speech audio                    |
+
+**Speech Parameters:**
+
+| Parameter         | Type    | Required | Default | Description                                        |
+| ----------------- | ------- | -------- | ------- | -------------------------------------------------- |
+| `model`           | string  | No       | -       | Ignored (for OpenAI compatibility)                 |
+| `input`           | string  | Yes      | -       | Text to synthesize                                 |
+| `voice`           | string  | No       | `alba`  | Voice ID (see `/v1/voices`)                        |
+| `response_format` | string  | No       | `mp3`   | Output format: `mp3`, `wav`, `pcm`, `opus`, `flac` |
+| `stream`          | boolean | No       | `false` | Enable streaming response                          |
+
+## Custom Voices
+
+### Using Custom Voice Files
+
+1. **Create a voices directory** with your audio files (`.wav`, `.mp3`, `.flac`)
+2. **Configure the server** to use your directory:
+
+   **Docker:**
+
+   ```bash
+   POCKET_TTS_VOICES_DIR=/path/to/voices docker compose up -d
+   ```
+
+   **Python:**
+
+   ```bash
+   python server.py --voices-dir /path/to/voices
+   ```
+
+   **Windows EXE:**
+   Use the batch launcher and specify the voices directory when prompted.
+
+3. **Use your voice** by filename:
+   ```json
+   { "voice": "my_voice.wav", "input": "Hello!" }
+   ```
+
+### Voice File Guidelines
+
+- **Duration:** 3-10 seconds of clear speech works best
+- **Quality:** Clean audio without background noise
+- **Format:** WAV, MP3, or FLAC
+- **Tip:** Use [Adobe Podcast Enhance](https://podcast.adobe.com/enhance) to clean noisy samples
+
+### Built-in Voices
+
+The following voices are available by default:
+`alba`, `marius`, `javert`, `jean`, `fantine`, `cosette`, `eponine`, `azelma`
+
+The `voices/` directory includes 150+ community-contributed voices.
+
+## Configuration
+
+### Environment Variables
+
+| Variable                    | Default    | Description                            |
+| --------------------------- | ---------- | -------------------------------------- |
+| `POCKET_TTS_HOST`           | `0.0.0.0`  | Server bind address                    |
+| `POCKET_TTS_PORT`           | `49112`    | Server port                            |
+| `POCKET_TTS_VOICES_DIR`     | `./voices` | Custom voices directory                |
+| `POCKET_TTS_MODEL_PATH`     | -          | Custom model path                      |
+| `POCKET_TTS_STREAM_DEFAULT` | `true`     | Enable streaming by default            |
+| `POCKET_TTS_LOG_LEVEL`      | `INFO`     | Log level: DEBUG, INFO, WARNING, ERROR |
+| `POCKET_TTS_LOG_DIR`        | `./logs`   | Log files directory                    |
+| `HF_TOKEN`                  | -          | Hugging Face token (for voice cloning) |
+
+### Docker Compose Options
+
+See [docker-compose.yml](docker-compose.yml) for all available options including:
+
+- Volume mounts for custom voices
+- Resource limits
+- Health check configuration
+- HuggingFace cache persistence
+
+## Project Structure
+
+```
+pocket-tts-openai_streaming_server/
+├── app/                    # Application modules
+│   ├── __init__.py        # Flask app factory
+│   ├── config.py          # Configuration management
+│   ├── logging_config.py  # Logging setup
+│   ├── routes.py          # API endpoints
+│   └── services/          # Business logic
+│       ├── audio.py       # Audio conversion
+│       └── tts.py         # TTS service
+├── static/                 # Web UI assets
+├── templates/              # HTML templates
+├── voices/                 # Voice files
+├── server.py              # Main entry point
+├── Dockerfile             # Container build
+├── docker-compose.yml     # Container orchestration
+└── requirements.txt       # Python dependencies
+```
+
+## Development
+
+### Dependencies
+
+| File                   | Purpose                                              |
+| ---------------------- | ---------------------------------------------------- |
+| `requirements.txt`     | Runtime dependencies only (Flask, torch, pocket-tts) |
+| `requirements-dev.txt` | Adds dev tools: ruff (linting), pytest (testing)     |
+
+### Running Locally
+
+```bash
+# Install runtime dependencies only
+pip install -r requirements.txt
+
+# Or install with dev tools (recommended for contributors)
+pip install -r requirements-dev.txt
+
+# Run with debug logging
+python server.py --log-level DEBUG
+```
+
+### Linting
+
+```bash
+pip install ruff
+ruff check .
+ruff format .
+```
+
+### Building Windows EXE
+
+```bash
+pip install pyinstaller
+pyinstaller --onefile --name PocketTTS-Server \
+  --add-data "static;static" \
+  --add-data "templates;templates" \
+  --add-data "voices;voices" \
+  --add-data "app;app" \
+  server.py
+```
+
+## Troubleshooting
+
+### Model Loading Takes Long
+
+First run downloads the model (~500MB). Subsequent runs use cached model.
+
+**Docker:** Model cache is persisted in a Docker volume.
+
+### Voice Cloning Requires HF Token
+
+For voice cloning, you may need a Hugging Face token:
+
+1. Get token from https://huggingface.co/settings/tokens
+2. Set `HF_TOKEN` environment variable
+
+### Port Already in Use
+
+```bash
+# Use a different port
+python server.py --port 8080
+
+# Or with Docker
+POCKET_TTS_PORT=8080 docker compose up -d
+```
+
+## Credits
+
+- [Pocket-TTS](https://github.com/kyutai-labs/pocket-tts) by Kyutai Labs
+- Community voice contributors (see [voices/credits.txt](voices/credits.txt))
+
+## License
+
+This project is licensed under the MIT License - see [LICENSE](LICENSE) for details.
+
+Pocket-TTS is subject to its own license terms.

app/__init__.py

@@ -0,0 +1,76 @@
+"""
+PocketTTS OpenAI-Compatible Server
+
+Flask application factory and initialization.
+"""
+
+from flask import Flask
+
+from app.config import Config
+from app.logging_config import get_logger, setup_logging
+
+
+def create_app(config_overrides: dict = None) -> Flask:
+    """
+    Application factory for creating the Flask app.
+
+    Args:
+        config_overrides: Optional dictionary of config values to override
+
+    Returns:
+        Configured Flask application
+    """
+    # Setup logging first
+    setup_logging()
+    logger = get_logger()
+
+    # Create Flask app with correct paths
+    app = Flask(
+        __name__,
+        template_folder=Config.get_template_folder(),
+        static_folder=Config.get_static_folder(),
+    )
+
+    # Apply default config
+    app.config['STREAM_DEFAULT'] = Config.STREAM_DEFAULT
+
+    # Apply overrides
+    if config_overrides:
+        app.config.update(config_overrides)
+
+    # Register blueprints
+    from app.routes import api
+
+    app.register_blueprint(api)
+
+    logger.info('Flask application created')
+
+    return app
+
+
+def init_tts_service(model_path: str = None, voices_dir: str = None) -> None:
+    """
+    Initialize the TTS service with model and voices.
+
+    Args:
+        model_path: Optional path to model file
+        voices_dir: Optional path to voices directory
+    """
+    from app.services.tts import get_tts_service
+
+    logger = get_logger()
+    tts = get_tts_service()
+
+    # Load model
+    tts.load_model(model_path)
+
+    # Set voices directory
+    if voices_dir:
+        tts.set_voices_dir(voices_dir)
+    else:
+        # Check for bundled voices
+        bundle_voices, _ = Config.get_bundle_paths()
+        if bundle_voices:
+            tts.set_voices_dir(bundle_voices)
+
+    logger.info('TTS service initialized')

app/config.py

@@ -0,0 +1,95 @@
+"""
+Configuration management for PocketTTS OpenAI Server.
+Loads settings from environment variables with sensible defaults.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+
+def get_base_path() -> Path:
+    """Get the base path for the application, handling PyInstaller frozen state."""
+    if getattr(sys, 'frozen', False):
+        if hasattr(sys, '_MEIPASS'):
+            # One-file mode
+            return Path(sys._MEIPASS)
+        else:
+            # One-dir mode
+            return Path(sys.executable).parent
+    return Path(__file__).parent.parent
+
+
+class Config:
+    """Application configuration loaded from environment variables."""
+
+    # Base paths
+    BASE_PATH = get_base_path()
+    IS_FROZEN = getattr(sys, 'frozen', False)
+
+    # Server settings
+    HOST = os.environ.get('POCKET_TTS_HOST', '0.0.0.0')
+    PORT = int(os.environ.get('POCKET_TTS_PORT', '49112'))
+
+    # Model settings
+    MODEL_PATH = os.environ.get('POCKET_TTS_MODEL_PATH', None)
+    DEFAULT_VOICE = os.environ.get(
+        'POCKET_TTS_DEFAULT_VOICE', 'hf://kyutai/tts-voices/alba-mackenna/casual.wav'
+    )
+
+    # Voice directory
+    VOICES_DIR = os.environ.get('POCKET_TTS_VOICES_DIR', None)
+
+    # Streaming default
+    STREAM_DEFAULT = os.environ.get('POCKET_TTS_STREAM_DEFAULT', 'true').lower() == 'true'
+
+    # Docker detection
+    @staticmethod
+    def _is_docker() -> bool:
+        """Detect if running in a Docker container."""
+        # Check for .dockerenv file (most reliable)
+        if os.path.exists('/.dockerenv'):
+            return True
+        # Check cgroup for docker/containerd references
+        try:
+            with open('/proc/1/cgroup') as f:
+                return any('docker' in line or 'containerd' in line for line in f)
+        except (FileNotFoundError, PermissionError):
+            return False
+
+    IS_DOCKER = _is_docker.__func__()
+
+    # Logging
+    LOG_LEVEL = os.environ.get('POCKET_TTS_LOG_LEVEL', 'INFO')
+    LOG_DIR = os.environ.get('POCKET_TTS_LOG_DIR', str(BASE_PATH / 'logs'))
+    LOG_FILE = os.environ.get('POCKET_TTS_LOG_FILE', 'pocket_tts.log')
+    LOG_MAX_BYTES = int(os.environ.get('POCKET_TTS_LOG_MAX_BYTES', str(10 * 1024 * 1024)))  # 10MB
+    LOG_BACKUP_COUNT = int(os.environ.get('POCKET_TTS_LOG_BACKUP_COUNT', '5'))
+
+    # Built-in voice mappings (these are resolved by pocket-tts internally)
+    BUILTIN_VOICES = ['alba', 'marius', 'javert', 'jean', 'fantine', 'cosette', 'eponine', 'azelma']
+
+    # Supported audio extensions for custom voices
+    VOICE_EXTENSIONS = ('.wav', '.mp3', '.flac', '.safetensors')
+
+    @classmethod
+    def get_bundle_paths(cls) -> tuple:
+        """Get bundled paths for frozen executables."""
+        if cls.IS_FROZEN:
+            voices_dir = cls.BASE_PATH / 'voices'
+            model_path = cls.BASE_PATH / 'model' / 'b6369a24.yaml'
+            return (
+                str(voices_dir) if voices_dir.is_dir() else None,
+                str(model_path) if model_path.is_file() else None,
+            )
+        return None, None
+
+    @classmethod
+    def get_template_folder(cls) -> str:
+        """Get the templates folder path."""
+        return str(cls.BASE_PATH / 'templates')
+
+    @classmethod
+    def get_static_folder(cls) -> str:
+        """Get the static files folder path."""
+        return str(cls.BASE_PATH / 'static')

app/logging_config.py

@@ -0,0 +1,77 @@
+"""
+Logging configuration with file rotation support.
+"""
+
+import logging
+import sys
+from logging.handlers import RotatingFileHandler
+from pathlib import Path
+
+from app.config import Config
+
+
+def setup_logging(log_level: str = None) -> logging.Logger:
+    """
+    Configure application logging with console and rotating file handlers.
+
+    Args:
+        log_level: Override log level (default: from Config.LOG_LEVEL)
+
+    Returns:
+        Configured logger instance
+    """
+    level = getattr(logging, (log_level or Config.LOG_LEVEL).upper(), logging.INFO)
+
+    # Create logger
+    logger = logging.getLogger('PocketTTS')
+    logger.setLevel(level)
+
+    # Avoid duplicate handlers
+    if logger.handlers:
+        return logger
+
+    # Console handler - simple format
+    console_handler = logging.StreamHandler(sys.stdout)
+    console_handler.setLevel(level)
+    console_format = logging.Formatter(
+        '%(asctime)s - %(levelname)s - %(message)s', datefmt='%Y-%m-%d %H:%M:%S'
+    )
+    console_handler.setFormatter(console_format)
+    logger.addHandler(console_handler)
+
+    # File handler - detailed format with rotation
+    try:
+        log_dir = Path(Config.LOG_DIR)
+        log_dir.mkdir(parents=True, exist_ok=True)
+        log_path = log_dir / Config.LOG_FILE
+
+        file_handler = RotatingFileHandler(
+            log_path,
+            maxBytes=Config.LOG_MAX_BYTES,
+            backupCount=Config.LOG_BACKUP_COUNT,
+            encoding='utf-8',
+        )
+        file_handler.setLevel(level)
+        file_format = logging.Formatter(
+            '%(asctime)s - %(name)s - %(levelname)s - [%(filename)s:%(lineno)d] - %(message)s',
+            datefmt='%Y-%m-%d %H:%M:%S',
+        )
+        file_handler.setFormatter(file_format)
+        logger.addHandler(file_handler)
+
+    except Exception as e:
+        logger.warning(f'Could not set up file logging: {e}')
+
+    # Suppress noisy third-party loggers
+    logging.getLogger('werkzeug').setLevel(logging.WARNING)
+    logging.getLogger('urllib3').setLevel(logging.WARNING)
+
+    return logger
+
+
+def get_logger(name: str = None) -> logging.Logger:
+    """Get a logger instance, optionally with a child name."""
+    base_logger = logging.getLogger('PocketTTS')
+    if name:
+        return base_logger.getChild(name)
+    return base_logger

app/routes.py

@@ -0,0 +1,196 @@
+"""
+Flask routes for the OpenAI-compatible TTS API.
+"""
+
+import time
+
+from flask import (
+    Blueprint,
+    Response,
+    jsonify,
+    render_template,
+    request,
+    send_file,
+    stream_with_context,
+)
+
+from app.logging_config import get_logger
+from app.services.audio import (
+    convert_audio,
+    get_mime_type,
+    tensor_to_pcm_bytes,
+    validate_format,
+    write_wav_header,
+)
+from app.services.tts import get_tts_service
+
+logger = get_logger('routes')
+
+# Create blueprint
+api = Blueprint('api', __name__)
+
+
+@api.route('/')
+def home():
+    """Serve the web interface."""
+    from app.config import Config
+
+    return render_template('index.html', is_docker=Config.IS_DOCKER)
+
+
+@api.route('/health', methods=['GET'])
+def health():
+    """
+    Health check endpoint for container orchestration.
+
+    Returns service status and basic model info.
+    """
+    tts = get_tts_service()
+
+    # Validate a built-in voice quickly
+    voice_valid, voice_msg = tts.validate_voice('alba')
+
+    return jsonify(
+        {
+            'status': 'healthy' if tts.is_loaded else 'unhealthy',
+            'model_loaded': tts.is_loaded,
+            'device': tts.device if tts.is_loaded else None,
+            'sample_rate': tts.sample_rate if tts.is_loaded else None,
+            'voices_dir': tts.voices_dir,
+            'voice_check': {'valid': voice_valid, 'message': voice_msg},
+        }
+    ), 200 if tts.is_loaded else 503
+
+
+@api.route('/v1/voices', methods=['GET'])
+def list_voices():
+    """
+    List available voices.
+
+    Returns OpenAI-compatible voice list format.
+    """
+    tts = get_tts_service()
+    voices = tts.list_voices()
+
+    return jsonify(
+        {
+            'object': 'list',
+            'data': [{'id': v['id'], 'name': v['name'], 'object': 'voice'} for v in voices],
+        }
+    )
+
+
+@api.route('/v1/audio/speech', methods=['POST'])
+def generate_speech():
+    """
+    OpenAI-compatible speech generation endpoint.
+
+    Request body:
+        model: string (ignored, for compatibility)
+        input: string (required) - Text to synthesize
+        voice: string (optional) - Voice ID or path
+        response_format: string (optional) - Audio format
+        stream: boolean (optional) - Enable streaming
+
+    Returns:
+        Audio file or streaming audio response
+    """
+    from flask import current_app
+
+    data = request.json
+
+    if not data:
+        return jsonify({'error': 'Missing JSON body'}), 400
+
+    text = data.get('input')
+    if not text:
+        return jsonify({'error': "Missing 'input' text"}), 400
+
+    voice = data.get('voice', 'alba')
+    stream_request = data.get('stream', False)
+
+    # Determine format based on streaming
+    if stream_request:
+        response_format = data.get('response_format', 'pcm')
+    else:
+        response_format = data.get('response_format', 'mp3')
+
+    target_format = validate_format(response_format)
+
+    tts = get_tts_service()
+
+    # Validate voice first
+    is_valid, msg = tts.validate_voice(voice)
+    if not is_valid:
+        available = [v['id'] for v in tts.list_voices()]
+        return jsonify(
+            {
+                'error': f"Voice '{voice}' not found",
+                'available_voices': available[:10],  # Limit to first 10
+                'hint': 'Use /v1/voices to see all available voices',
+            }
+        ), 400
+
+    try:
+        voice_state = tts.get_voice_state(voice)
+
+        # Check if streaming should be used
+        use_streaming = stream_request or current_app.config.get('STREAM_DEFAULT', False)
+
+        if use_streaming:
+            return _stream_audio(tts, voice_state, text, target_format)
+        else:
+            return _generate_file(tts, voice_state, text, target_format)
+
+    except ValueError as e:
+        logger.warning(f'Voice loading failed: {e}')
+        return jsonify({'error': str(e)}), 400
+    except Exception as e:
+        logger.exception('Generation failed')
+        return jsonify({'error': str(e)}), 500
+
+
+def _generate_file(tts, voice_state, text: str, fmt: str):
+    """Generate complete audio and return as file."""
+    t0 = time.time()
+    audio_tensor = tts.generate_audio(voice_state, text)
+    generation_time = time.time() - t0
+
+    logger.info(f'Generated {len(text)} chars in {generation_time:.2f}s')
+
+    audio_buffer = convert_audio(audio_tensor, tts.sample_rate, fmt)
+    mimetype = get_mime_type(fmt)
+
+    return send_file(
+        audio_buffer, mimetype=mimetype, as_attachment=True, download_name=f'speech.{fmt}'
+    )
+
+
+def _stream_audio(tts, voice_state, text: str, fmt: str):
+    """Stream audio chunks."""
+    # Normalize streaming format: we always emit PCM bytes, optionally wrapped
+    # in a WAV container. For non-PCM/WAV formats (e.g. mp3, opus), coerce to
+    # raw PCM to avoid mismatched content-type vs. payload.
+    stream_fmt = fmt
+    if stream_fmt not in ('pcm', 'wav'):
+        logger.warning(
+            "Requested streaming format '%s' is not supported for streaming; "
+            "falling back to 'pcm'.",
+            stream_fmt,
+        )
+        stream_fmt = 'pcm'
+
+    def generate():
+        stream = tts.generate_audio_stream(voice_state, text)
+        for chunk_tensor in stream:
+            yield tensor_to_pcm_bytes(chunk_tensor)
+
+    def stream_with_header():
+        # Yield WAV header first if streaming as WAV
+        if stream_fmt == 'wav':
+            yield write_wav_header(tts.sample_rate, num_channels=1, bits_per_sample=16)
+        yield from generate()
+
+    mimetype = get_mime_type(stream_fmt)
+
+    return Response(stream_with_context(stream_with_header()), mimetype=mimetype)

app/services/__init__.py

@@ -0,0 +1,5 @@
+"""Services package."""
+
+from app.services.tts import TTSService, get_tts_service
+
+__all__ = ['TTSService', 'get_tts_service']

utils.py → app/services/audio.py

@@ -1,81 +1,110 @@
+"""
+Audio conversion and streaming utilities.
+"""
+
 import io
+import struct
+
 import torch
 import torchaudio
-import logging
 
-logger = logging.getLogger(__name__)
+from app.logging_config import get_logger
+
+logger = get_logger('audio')
+
+# Valid audio formats
+VALID_FORMATS = {'mp3', 'wav', 'opus', 'aac', 'flac', 'pcm'}
+
+
+def validate_format(fmt: str) -> str:
+    """
+    Normalize and validate the requested audio format.
+
+    Args:
+        fmt: Requested format string
+
+    Returns:
+        Validated format string
+    """
+    fmt = fmt.lower()
+
+    # OpenAI sometimes sends 'mpeg' for mp3
+    if fmt == 'mpeg':
+        return 'mp3'
+
+    if fmt not in VALID_FORMATS:
+        logger.warning(f"Unknown format '{fmt}', falling back to wav")
+        return 'wav'
 
-def convert_audio(audio_tensor: torch.Tensor, sample_rate: int, target_format: str = 'wav') -> io.BytesIO:
+    return fmt
+
+
+def convert_audio(
+    audio_tensor: torch.Tensor, sample_rate: int, target_format: str = 'wav'
+) -> io.BytesIO:
     """
     Convert a raw audio tensor to a byte buffer in the specified format.
-    
+
     Args:
-        audio_tensor (torch.Tensor): The audio waveform (1D or 2D).
-        sample_rate (int): The sample rate of the audio.
-        target_format (str): The target audio format (mp3, wav, opus, aac, flac).
-        
+        audio_tensor: The audio waveform (1D or 2D)
+        sample_rate: The sample rate of the audio
+        target_format: The target audio format
+
     Returns:
-        io.BytesIO: Buffer containing the encoded audio data.
+        Buffer containing the encoded audio data
     """
     buffer = io.BytesIO()
-    
+
     # Ensure tensor is CPU
     if audio_tensor.is_cuda:
         audio_tensor = audio_tensor.cpu()
-        
+
     # Ensure 2D (channels, time)
     if audio_tensor.dim() == 1:
         audio_tensor = audio_tensor.unsqueeze(0)
-        
-    # Validation/Normalization if needed
-    # torchaudio.save expects data in range [-1, 1] usually, confirm if normalization needed?
-    # PocketTTS output range is typically fine, but clipping is good practice.
-    # audio_tensor = torch.clamp(audio_tensor, -1.0, 1.0)
 
     try:
         torchaudio.save(buffer, audio_tensor, sample_rate, format=target_format)
         buffer.seek(0)
         return buffer
     except Exception as e:
-        logger.error(f"Error converting audio to {target_format}: {e}")
-        # Fallback to wav if conversion fails? Or re-raise?
-        # For now, let's try to handle common issues or re-raise
-        raise e
+        logger.error(f'Error converting audio to {target_format}: {e}')
+        raise
 
-def validate_format(fmt: str) -> str:
-    """Normalize and validate the requested audio format."""
-    fmt = fmt.lower()
-    valid_formats = {'mp3', 'wav', 'opus', 'aac', 'flac', 'pcm'}
-    
-    if fmt == 'mpeg': # OpenAI sometimes sends 'mpeg' aka mp3
-        return 'mp3'
-        
-    if fmt not in valid_formats:
-        return 'wav' # Default fallback
-    return fmt
 
-def write_wav_header(sample_rate: int, num_channels: int = 1, bits_per_sample: int = 16, num_frames: int = 0) -> bytes:
+def write_wav_header(
+    sample_rate: int, num_channels: int = 1, bits_per_sample: int = 16, num_frames: int = 0
+) -> bytes:
     """
-    Generate a WAV header. If num_frames is 0, set to 0xFFFFFFFF (unknown/large).
+    Generate a WAV header for streaming.
+
+    If num_frames is 0, set to max value (streaming/unknown length).
+
+    Args:
+        sample_rate: Audio sample rate
+        num_channels: Number of audio channels
+        bits_per_sample: Bits per sample
+        num_frames: Number of frames (0 for unknown/streaming)
+
+    Returns:
+        WAV header bytes
     """
-    import struct
-    
     byte_rate = sample_rate * num_channels * bits_per_sample // 8
     block_align = num_channels * bits_per_sample // 8
-    
-    # Data size: if unknown, max uint32 approximately
+
+    # Data size: if unknown, max uint32
     data_size = num_frames * block_align
     if num_frames == 0:
-        data_size = 0xFFFFFFFF - 36 # Max possible size remaining
-        
+        data_size = 0xFFFFFFFF - 36
+
     chunk_size = 36 + data_size
-    
+
     header = io.BytesIO()
     header.write(b'RIFF')
     header.write(struct.pack('<I', chunk_size))
     header.write(b'WAVE')
     header.write(b'fmt ')
-    header.write(struct.pack('<I', 16)) # Subchunk1Size (16 for PCM)
+    header.write(struct.pack('<I', 16))  # Subchunk1Size (16 for PCM)
     header.write(struct.pack('<H', 1))  # AudioFormat (1 for PCM)
     header.write(struct.pack('<H', num_channels))
     header.write(struct.pack('<I', sample_rate))
@@ -84,5 +113,47 @@ def write_wav_header(sample_rate: int, num_channels: int = 1, bits_per_sample: i
     header.write(struct.pack('<H', bits_per_sample))
     header.write(b'data')
     header.write(struct.pack('<I', data_size))
-    
+
     return header.getvalue()
+
+
+def tensor_to_pcm_bytes(chunk_tensor: torch.Tensor) -> bytes:
+    """
+    Convert audio tensor chunk to 16-bit PCM bytes.
+
+    Args:
+        chunk_tensor: Audio tensor chunk
+
+    Returns:
+        PCM audio bytes
+    """
+    if chunk_tensor.is_cuda:
+        chunk_tensor = chunk_tensor.cpu()
+
+    if chunk_tensor.dim() == 1:
+        chunk_tensor = chunk_tensor.unsqueeze(0)
+
+    # Convert to 16-bit PCM
+    pcm = (chunk_tensor * 32767).clamp(-32768, 32767).to(torch.int16)
+    return pcm.numpy().tobytes()
+
+
+def get_mime_type(fmt: str) -> str:
+    """
+    Get the MIME type for an audio format.
+
+    Args:
+        fmt: Audio format string
+
+    Returns:
+        MIME type string
+    """
+    mime_types = {
+        'wav': 'audio/wav',
+        'mp3': 'audio/mpeg',
+        'pcm': 'audio/L16',
+        'opus': 'audio/opus',
+        'aac': 'audio/aac',
+        'flac': 'audio/flac',
+    }
+    return mime_types.get(fmt, f'audio/{fmt}')

app/services/tts.py

@@ -0,0 +1,322 @@
+"""
+TTS Service - handles model loading, voice management, and audio generation.
+"""
+
+import os
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+import torch
+
+from app.config import Config
+from app.logging_config import get_logger
+
+logger = get_logger('tts')
+
+# Lazy import pocket_tts to allow for better error handling
+TTSModel = None
+
+
+def _ensure_pocket_tts():
+    """Ensure pocket-tts is imported."""
+    global TTSModel
+    if TTSModel is None:
+        try:
+            from pocket_tts import TTSModel as _TTSModel
+
+            TTSModel = _TTSModel
+        except ImportError as exc:
+            raise ImportError('pocket-tts not found. Install with: pip install pocket-tts') from exc
+
+
+class TTSService:
+    """
+    Service class for Text-to-Speech operations.
+    Manages model loading, voice caching, and audio generation.
+    """
+
+    def __init__(self):
+        self.model = None
+        self.voice_cache: dict = {}
+        self.voices_dir: str | None = None
+        self._model_loaded = False
+
+    @property
+    def is_loaded(self) -> bool:
+        """Check if the model is loaded."""
+        return self._model_loaded and self.model is not None
+
+    @property
+    def sample_rate(self) -> int:
+        """Get the model's sample rate."""
+        if self.model:
+            return self.model.sample_rate
+        return 24000  # Default pocket-tts sample rate
+
+    @property
+    def device(self) -> str:
+        """Get the model's device."""
+        if self.model:
+            return str(self.model.device)
+        return 'unknown'
+
+    def load_model(self, model_path: str | None = None) -> None:
+        """
+        Load the TTS model.
+
+        Args:
+            model_path: Optional path to model file or variant name
+        """
+        _ensure_pocket_tts()
+
+        logger.info('Loading Pocket TTS model...')
+        t0 = time.time()
+
+        # Determine model path
+        effective_path = model_path
+
+        if not effective_path:
+            # Check for bundled model in frozen executable
+            _, bundle_model = Config.get_bundle_paths()
+            if bundle_model and os.path.isfile(bundle_model):
+                effective_path = bundle_model
+                logger.info(f'Using bundled model: {effective_path}')
+
+        try:
+            if effective_path:
+                logger.info(f'Loading model from: {effective_path}')
+                self.model = TTSModel.load_model(variant=effective_path)
+            else:
+                logger.info('Loading default model from HuggingFace...')
+                self.model = TTSModel.load_model()
+
+            self._model_loaded = True
+            load_time = time.time() - t0
+            logger.info(
+                f'Model loaded in {load_time:.2f}s. '
+                f'Device: {self.device}, Sample Rate: {self.sample_rate}'
+            )
+
+        except Exception as e:
+            logger.error(f'Failed to load model: {e}')
+            raise
+
+    def set_voices_dir(self, voices_dir: str | None) -> None:
+        """
+        Set the directory for custom voice files.
+
+        Args:
+            voices_dir: Path to directory containing voice files
+        """
+        if voices_dir and os.path.isdir(voices_dir):
+            self.voices_dir = voices_dir
+            logger.info(f'Voices directory set to: {voices_dir}')
+        elif voices_dir:
+            logger.warning(f'Voices directory not found: {voices_dir}')
+            self.voices_dir = None
+        else:
+            self.voices_dir = None
+
+    def get_voice_state(self, voice_id_or_path: str) -> dict:
+        """
+        Resolve voice ID to a model state with caching.
+
+        Args:
+            voice_id_or_path: Voice identifier (name, file path, or URL)
+
+        Returns:
+            Model state dictionary for the voice
+
+        Raises:
+            ValueError: If voice cannot be loaded
+        """
+        if not self.is_loaded:
+            raise RuntimeError('Model not loaded. Call load_model() first.')
+
+        # Resolve the voice path
+        resolved_key = self._resolve_voice_path(voice_id_or_path)
+
+        # Check cache
+        if resolved_key in self.voice_cache:
+            logger.debug(f'Using cached voice state for: {resolved_key}')
+            return self.voice_cache[resolved_key]
+
+        # Load voice
+        logger.info(f'Loading voice: {resolved_key}')
+        t0 = time.time()
+
+        try:
+            state = self.model.get_state_for_audio_prompt(resolved_key)
+            self.voice_cache[resolved_key] = state
+            load_time = time.time() - t0
+            logger.info(f'Voice loaded in {load_time:.2f}s: {resolved_key}')
+            return state
+
+        except Exception as e:
+            logger.error(f"Failed to load voice '{voice_id_or_path}': {e}")
+            raise ValueError(f"Voice '{voice_id_or_path}' could not be loaded: {e}") from e
+
+    def _resolve_voice_path(self, voice_id_or_path: str) -> str:
+        """
+        Resolve a voice identifier to its actual path or ID.
+
+        Args:
+            voice_id_or_path: Voice identifier
+
+        Returns:
+            Resolved path or identifier
+
+        Raises:
+            ValueError: If unsafe URL scheme is used
+        """
+        # Block potentially dangerous URL schemes (SSRF protection)
+        if voice_id_or_path.startswith(('http://', 'https://')):
+            raise ValueError(
+                f'URL scheme not allowed for security reasons: {voice_id_or_path[:50]}. '
+                "Use 'hf://' for HuggingFace models or provide a local file path."
+            )
+
+        # Allow HuggingFace URLs
+        if voice_id_or_path.startswith('hf://'):
+            return voice_id_or_path
+
+        # Check if it's a built-in voice
+        if voice_id_or_path.lower() in Config.BUILTIN_VOICES:
+            return voice_id_or_path.lower()
+
+        # Check voices directory
+        if self.voices_dir:
+            for ext in Config.VOICE_EXTENSIONS:
+                # Try exact match first
+                possible_path = os.path.join(self.voices_dir, voice_id_or_path)
+                if os.path.exists(possible_path):
+                    return os.path.abspath(possible_path)
+
+                # Try with extension
+                if not voice_id_or_path.endswith(ext):
+                    possible_path = os.path.join(self.voices_dir, voice_id_or_path + ext)
+                    if os.path.exists(possible_path):
+                        return os.path.abspath(possible_path)
+
+        # Check if it's an absolute path that exists
+        if os.path.isabs(voice_id_or_path) and os.path.exists(voice_id_or_path):
+            return voice_id_or_path
+
+        # Return as-is, let pocket-tts handle it
+        return voice_id_or_path
+
+    def validate_voice(self, voice_id_or_path: str) -> tuple[bool, str]:
+        """
+        Validate if a voice can be loaded (fast check without full loading).
+
+        Args:
+            voice_id_or_path: Voice identifier
+
+        Returns:
+            Tuple of (is_valid, message)
+        """
+        # Block unsafe URL schemes first
+        if voice_id_or_path.startswith(('http://', 'https://')):
+            return (
+                False,
+                'HTTP/HTTPS URLs are not allowed for security reasons. Use hf:// for HuggingFace models.',
+            )
+
+        try:
+            resolved = self._resolve_voice_path(voice_id_or_path)
+        except ValueError as e:
+            return False, str(e)
+
+        # Built-in voices are always valid
+        if resolved.lower() in Config.BUILTIN_VOICES:
+            return True, f'Built-in voice: {resolved}'
+
+        # HuggingFace URLs - assume valid
+        if resolved.startswith('hf://'):
+            return True, f'HuggingFace voice: {resolved}'
+
+        # Local file - check existence
+        if os.path.exists(resolved):
+            return True, f'Local voice file: {resolved}'
+
+        return False, f'Voice not found: {voice_id_or_path}'
+
+    def generate_audio(self, voice_state: dict, text: str) -> torch.Tensor:
+        """
+        Generate complete audio for given text.
+
+        Args:
+            voice_state: Model state from get_voice_state()
+            text: Text to synthesize
+
+        Returns:
+            Audio tensor
+        """
+        if not self.is_loaded:
+            raise RuntimeError('Model not loaded')
+
+        t0 = time.time()
+        audio = self.model.generate_audio(voice_state, text)
+        gen_time = time.time() - t0
+
+        logger.info(f'Generated {len(text)} chars in {gen_time:.2f}s')
+        return audio
+
+    def generate_audio_stream(self, voice_state: dict, text: str) -> Iterator[torch.Tensor]:
+        """
+        Generate audio in streaming chunks.
+
+        Args:
+            voice_state: Model state from get_voice_state()
+            text: Text to synthesize
+
+        Yields:
+            Audio tensor chunks
+        """
+        if not self.is_loaded:
+            raise RuntimeError('Model not loaded')
+
+        logger.info(f'Starting streaming generation for {len(text)} chars')
+        yield from self.model.generate_audio_stream(voice_state, text)
+
+    def list_voices(self) -> list[dict]:
+        """
+        List all available voices.
+
+        Returns:
+            List of voice dictionaries with 'id' and 'name' keys
+        """
+        voices = []
+
+        # Built-in voices
+        for voice in Config.BUILTIN_VOICES:
+            voices.append({'id': voice, 'name': voice.capitalize(), 'type': 'builtin'})
+
+        # Custom voices from directory
+        if self.voices_dir and os.path.isdir(self.voices_dir):
+            for ext in Config.VOICE_EXTENSIONS:
+                pattern = f'*{ext}'
+                voice_dir = Path(self.voices_dir)
+                for voice_file in voice_dir.glob(pattern):
+                    voices.append(
+                        {
+                            'id': voice_file.name,
+                            'name': f'Custom: {voice_file.stem}',
+                            'type': 'custom',
+                        }
+                    )
+
+        return voices
+
+
+# Global service instance
+_tts_service: TTSService | None = None
+
+
+def get_tts_service() -> TTSService:
+    """Get the global TTS service instance."""
+    global _tts_service
+    if _tts_service is None:
+        _tts_service = TTSService()
+    return _tts_service

docker-compose.yml

@@ -0,0 +1,64 @@
+# Docker Compose for PocketTTS OpenAI-Compatible Server
+#
+# Usage:
+#   docker compose up -d          # Start the server
+#   docker compose logs -f        # View logs
+#   docker compose down           # Stop the server
+#
+# Custom voices:
+#   Mount your own voices directory to /app/voices
+
+services:
+  pockettts:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    image: pockettts-openai-server:latest
+    container_name: pockettts-server
+
+    ports:
+      - '${POCKET_TTS_PORT:-49112}:49112'
+
+    environment:
+      - POCKET_TTS_HOST=0.0.0.0
+      - POCKET_TTS_PORT=49112
+      - POCKET_TTS_VOICES_DIR=/app/voices
+      - POCKET_TTS_LOG_LEVEL=${POCKET_TTS_LOG_LEVEL:-INFO}
+      - POCKET_TTS_STREAM_DEFAULT=${POCKET_TTS_STREAM_DEFAULT:-true}
+      # Hugging Face token for voice cloning (optional)
+      - HF_TOKEN=${HF_TOKEN:-}
+
+    volumes:
+      # Mount custom voices (optional - overrides bundled voices)
+      - ${POCKET_TTS_VOICES_DIR:-./voices}:/app/voices:ro
+      # Persist logs
+      - ./logs:/app/logs
+      # Cache HuggingFace models to avoid re-downloading
+      - pockettts-cache:/home/pockettts/.cache/huggingface
+
+    restart: unless-stopped
+
+    # Resource limits (adjust based on your hardware)
+    deploy:
+      resources:
+        limits:
+          memory: 4G
+        reservations:
+          memory: 2G
+
+    healthcheck:
+      test:
+        [
+          'CMD',
+          'python',
+          '-c',
+          "import urllib.request; urllib.request.urlopen('http://localhost:49112/health')",
+        ]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 120s # Model loading takes time
+
+volumes:
+  pockettts-cache:
+    name: pockettts-huggingface-cache

logs/.gitkeep

@@ -0,0 +1 @@
+# Keep this directory in git (logs are gitignored but directory needed)

pocket_tts_openai_server.py

@@ -1,303 +0,0 @@
-import os
-import argparse
-import sys
-import logging
-import io
-import time
-import json
-import glob
-from pathlib import Path
-from flask import Flask, request, jsonify, send_file, render_template, Response, stream_with_context
-import torch
-import torchaudio
-
-# Import pocket-tts
-try:
-    from pocket_tts import TTSModel
-except ImportError:
-    print("Error: pocket-tts not found. Please install it using 'pip install pocket-tts'.")
-    sys.exit(1)
-
-from utils import validate_format, convert_audio, write_wav_header
-
-# Configure Logging
-logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(name)s - %(levelname)s - %(message)s')
-logger = logging.getLogger("PocketTTS-Server")
-
-app = Flask(__name__)
-
-# Global Variables
-model = None
-voice_cache = {} # Cache for voice states
-VOICES_DIR = None
-
-# --- PyInstaller Support ---
-if getattr(sys, 'frozen', False):
-    # If the application is run as a bundle, the PyInstaller bootloader
-    # extends the sys module by a flag frozen=True.
-    if hasattr(sys, '_MEIPASS'):
-        # One-file mode
-        base_path = sys._MEIPASS
-    else:
-        # One-dir mode
-        base_path = os.path.dirname(os.path.abspath(sys.executable))
-        
-    template_folder = os.path.join(base_path, 'templates')
-    static_folder = os.path.join(base_path, 'static')
-    app = Flask(__name__, template_folder=template_folder, static_folder=static_folder)
-    
-    # Default Voices Dir when frozen (bundled)
-    # We will assume 'voices' is bundled into the root of the executable
-    BUNDLE_VOICES_DIR = os.path.join(base_path, 'voices')
-    BUNDLE_MODEL_PATH = os.path.join(base_path, 'model', 'b6369a24.yaml')
-else:
-    app = Flask(__name__)
-    base_path = os.path.dirname(os.path.abspath(__file__))
-    BUNDLE_VOICES_DIR = None
-    BUNDLE_MODEL_PATH = None
-
-# --- Helpers ---
-def get_voice_state(voice_id_or_path):
-    """
-    Resolve voice ID to a model state with caching.
-    """
-    global voice_cache
-    
-    # 1. Normalize/Resolve the ID to its final path/form first
-    resolved_key = voice_id_or_path
-    if VOICES_DIR:
-        possible_path = os.path.join(VOICES_DIR, voice_id_or_path)
-        if os.path.exists(possible_path):
-            resolved_key = os.path.abspath(possible_path) # Use absolute path for consistency
-    elif os.path.exists(voice_id_or_path):
-        resolved_key = os.path.abspath(voice_id_or_path)
-
-    # 2. Check cache using the resolved key
-    if resolved_key in voice_cache:
-        logger.info(f"Using cached voice state for {resolved_key}")
-        return voice_cache[resolved_key]
-    
-    # 3. If not cached, load it
-    try:
-        if os.path.exists(resolved_key):
-            logger.info(f"Loading new voice state from file: {resolved_key}")
-        else:
-            logger.info(f"Loading new voice state from ID/URL: {resolved_key}")
-            
-        state = model.get_state_for_audio_prompt(resolved_key)
-        
-        # 4. Store in cache using the same resolved key
-        voice_cache[resolved_key] = state
-        return state
-        
-    except Exception as e:
-        logger.error(f"Failed to load voice {resolved_key}: {e}")
-        raise ValueError(f"Voice '{voice_id_or_path}' could not be loaded.")
-
-# --- Routes ---
-
-@app.route('/')
-def home():
-    """Serve the simple web interface."""
-    return render_template('index.html')
-
-@app.route('/v1/voices', methods=['GET'])
-def list_voices():
-    """List available voices: Built-ins + Scanned Directory."""
-    
-    # 1. Built-in defaults
-    # User requested specific voices: alba, marius, javert, jean, fantine, cosette, eponine, azelma
-    # We map them to potential IDs. Since we don't have exact URLs for all, we assume they are either
-    # resolved by pocket-tts or the user has these files/IDs.
-    
-    builtin_map = {
-       "alba": "alba",
-       "marius": "marius", 
-       "javert": "javert",
-       "jean": "jean",
-       "fantine": "fantine",
-       "cosette": "cosette",
-       "eponine": "eponine",
-       "azelma": "azelma"
-    }
-
-    voices = []
-    for name_id in ["alba", "marius", "javert", "jean", "fantine", "cosette", "eponine", "azelma"]:
-        # If we have a known mapping (like for alba), use it as ID? 
-        # Or just use the name as ID and let get_voice_state handle it?
-        # Specifying ID as the lookup key.
-        voices.append({
-            "id": builtin_map.get(name_id, name_id),
-            "name": name_id.capitalize()
-        })
-    
-    # 2. Scan Directory if configured
-    if VOICES_DIR and os.path.isdir(VOICES_DIR):
-        # Define supported extensions
-        extensions = ("*.wav", "*.mp3", "*.flac")
-        
-        # Gather all matching files
-        audio_files = []
-        for ext in extensions:
-            audio_files.extend(glob.glob(os.path.join(VOICES_DIR, ext)))
-
-        for f in audio_files:
-            name = os.path.basename(f)
-            # ID is the full path so the server can access it, or just filename if we handle resolution
-            # Using filename for UI consistency as per original logic
-            voices.append({
-                "id": name, 
-                "name": f"Local: {name}"
-            })
-
-    return jsonify({
-        "object": "list",
-        "data": [{"id": v["id"], "name": v["name"], "object": "voice"} for v in voices]
-    })
-
-@app.route('/v1/audio/speech', methods=['POST'])
-def generate_speech():
-    """OpenAI-compatible speech generation endpoint."""
-    data = request.json
-    
-    if not data:
-        return jsonify({"error": "Missing JSON body"}), 400
-        
-    text = data.get('input')
-    voice = data.get('voice', 'hf://kyutai/tts-voices/alba-mackenna/casual.wav')
-    
-    # Check stream flag
-    stream_request = data.get('stream', False)
-    
-    if stream_request:
-        response_format = data.get('response_format', 'pcm')
-    else:
-        response_format = data.get('response_format', 'mp3')
-
-    if not text:
-        return jsonify({"error": "Missing 'input' text"}), 400
-
-    target_format = validate_format(response_format)
-    
-    try:
-        # Load Voice (with cache)
-        voice_state = get_voice_state(voice)
-        
-        # Determine Generation Mode
-        if stream_request or app.config.get('CLI_STREAM_DEFAULT'):
-            return stream_audio(voice_state, text, target_format)
-        else:
-            return generate_file(voice_state, text, target_format)
-            
-    except Exception as e:
-        logger.exception("Generation failed")
-        return jsonify({"error": str(e)}), 500
-
-def generate_file(voice_state, text, fmt):
-    """Generate full audio and return as file."""
-    t0 = time.time()
-    audio_tensor = model.generate_audio(voice_state, text)
-    generation_time = time.time() - t0
-    logger.info(f"Generated {len(text)} chars in {generation_time:.2f}s")
-    
-    # Convert
-    audio_buffer = convert_audio(audio_tensor, model.sample_rate, fmt)
-    
-    mimetype = f"audio/{fmt}"
-    if fmt == 'wav': mimetype = 'audio/wav'
-    elif fmt == 'mp3': mimetype = 'audio/mpeg'
-    
-    return send_file(
-        audio_buffer,
-        mimetype=mimetype,
-        as_attachment=True,
-        download_name=f"speech.{fmt}"
-    )
-
-def stream_audio(voice_state, text, fmt):
-    """Stream audio chunks as WAV or raw PCM."""
-    
-    def generate():
-        # pocket-tts native streaming
-        stream = model.generate_audio_stream(voice_state, text)
-        
-        for chunk_tensor in stream:
-            if chunk_tensor.is_cuda: 
-                chunk_tensor = chunk_tensor.cpu()
-            if chunk_tensor.dim() == 1: 
-                chunk_tensor = chunk_tensor.unsqueeze(0)
-            
-            # Convert to 16-bit PCM
-            c = (chunk_tensor * 32767).clamp(-32768, 32767).to(torch.int16)
-            yield c.numpy().tobytes()
-
-    def stream_with_header():
-        # ONLY yield header if format is WAV
-        if fmt == 'wav':
-            yield write_wav_header(model.sample_rate, num_channels=1, bits_per_sample=16, num_frames=0)
-             
-        yield from generate()
-
-    # Match the MIME types
-    if fmt == 'pcm':
-        mimetype = "audio/L16"
-    elif fmt == 'wav':
-        mimetype = "audio/wav"
-    else:
-        mimetype = f"audio/{fmt}"
-    
-    return Response(stream_with_context(stream_with_header()), mimetype=mimetype)
-
-
-# --- startup ---
-def main():
-    parser = argparse.ArgumentParser(description="Pocket TTS OpenAI Compatible Server")
-    parser.add_argument("--model_path", type=str, default=None, help="Path to model file or variant name")
-    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host to run server")
-    parser.add_argument("--port", type=int, default=5002, help="Port to run server")
-    parser.add_argument("--stream", action="store_true", help="Enable streaming by default")
-    parser.add_argument("--voices_dir", type=str, default=None, help="Directory containing local voice .wav, .mp3 or .flac files")
-    
-    args = parser.parse_args()
-    
-    # Config
-    app.config['CLI_STREAM_DEFAULT'] = args.stream
-    global VOICES_DIR
-    if args.voices_dir:
-        VOICES_DIR = args.voices_dir
-    elif getattr(sys, 'frozen', False) and BUNDLE_VOICES_DIR and os.path.isdir(BUNDLE_VOICES_DIR):
-        VOICES_DIR = BUNDLE_VOICES_DIR
-    else:
-        VOICES_DIR = None
-    
-    global model
-    logger.info("Loading Pocket TTS Model...")
-    
-    # Use model_path as variant if provided, otherwise default
-    if args.model_path:
-        logger.info(f"Using custom model variant/path: {args.model_path}")
-        model = TTSModel.load_model(variant=args.model_path)
-    elif getattr(sys, 'frozen', False):
-        # Check if model is bundled in 'model' dir
-        if os.path.isfile(BUNDLE_MODEL_PATH):
-            logger.info(f"Using bundled model from: {BUNDLE_MODEL_PATH}")
-            try:
-                model = TTSModel.load_model(variant=BUNDLE_MODEL_PATH)
-            except Exception as e:
-                logging.error(f"Error trying to load models bundled with .exe: {e}. Returning to default model load.")
-                model = TTSModel.load_model()
-        else:
-            model = TTSModel.load_model()
-    else:
-        model = TTSModel.load_model()
-        
-    logger.info(f"Model loaded. Device: {model.device}, Sample Rate: {model.sample_rate}")
-    
-    if VOICES_DIR:
-        logger.info(f"Scanning voices from: {VOICES_DIR}")
-        
-    logger.info(f"Starting server on {args.host}:{args.port}")
-    app.run(host=args.host, port=args.port, debug=False, threaded=True)
-
-if __name__ == "__main__":
-    main()

pyinstaller_command.txt

@@ -1,15 +0,0 @@
-pyinstaller --noconfirm --clean --onefile --icon=NONE ^
- --name "PocketTTS-Server" ^
- --add-data "static;static" ^
- --add-data "templates;templates" ^
- --add-data "voices;voices" ^
- --add-data "model;model" ^
- --collect-all "pocket_tts" ^
- --hidden-import "engineio.async_drivers.threading" ^
- --hidden-import "flask" ^
- --hidden-import "torch" ^
- --hidden-import "torchaudio" ^
- --hidden-import "soundfile" ^
- pocket_tts_openai_server.py
- 
-pyinstaller --noconfirm --clean --onefile --icon=pocket-tts-logo.ico --name "PocketTTS-Server" --add-data "utils.py;utils.py" --add-data "static;static" --add-data "model;model" --add-data "templates;templates" --add-data "voices;voices" --collect-all "pocket_tts" --hidden-import "engineio.async_drivers.threading" --hidden-import "flask" --hidden-import "torch" --hidden-import "torchaudio" --hidden-import "soundfile" pocket_tts_openai_server.py

pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+description = "OpenAI-compatible TTS API server powered by Pocket-TTS"
+license = {text = "MIT"}
+name = "pocket-tts-openai-server"
+readme = "README.md"
+requires-python = ">=3.10"
+version = "2.0.0"
+
+dependencies = [
+  "flask>=3.0.0",
+  "waitress>=3.0.0",
+  "pocket-tts>=1.0.0",
+  "torch>=2.0.0,<=2.8.0",
+  "torchaudio>=2.0.0,<=2.8.0",
+  "scipy>=1.10.0",
+  "numpy>=1.24.0",
+  "soundfile>=0.12.0",
+]
+
+[project.optional-dependencies]
+build = ["pyinstaller"]
+dev = ["ruff", "pytest"]
+
+[project.scripts]
+pocket-tts-server = "server:main"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+ignore = ["E501", "B008", "B904"]
+select = ["E", "W", "F", "I", "B", "C4", "UP"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["app"]
+
+[tool.ruff.format]
+quote-style = "single"

requirements-dev.txt

@@ -0,0 +1,10 @@
+# Development dependencies
+# Install with: pip install -r requirements-dev.txt
+
+-r requirements.txt
+
+# Linting and formatting
+ruff
+
+# Testing
+pytest

requirements.txt

@@ -1,7 +1,14 @@
-flask
-torch<=2.8.0
-torchaudio<=2.8.0
-pocket-tts
-scipy
-numpy
-soundfile
+# CPU-only PyTorch (smaller, faster install - this project is CPU-only)
+--extra-index-url https://download.pytorch.org/whl/cpu
+
+# Core dependencies
+flask>=3.0.0
+waitress>=3.0.0
+pocket-tts>=1.0.0
+
+# Audio processing
+torch>=2.0.0,<=2.8.0
+torchaudio>=2.0.0,<=2.8.0
+scipy>=1.10.0
+numpy>=1.24.0
+soundfile>=0.12.0

run_pocket_tts_server.bat

@@ -37,7 +37,7 @@ set /p "INPUT_HOST=Host IP [%HOST%]: "
 if not "%INPUT_HOST%"=="" set "HOST=%INPUT_HOST%"
 
 :: 3. Port
-set "PORT=5002"
+set "PORT=49112"
 set /p "INPUT_PORT=Port [%PORT%]: "
 if not "%INPUT_PORT%"=="" set "PORT=%INPUT_PORT%"
 

run_pocket_tts_server_exe.bat

@@ -31,7 +31,7 @@ set /p "INPUT_HOST=Host IP [%HOST%]: "
 if not "%INPUT_HOST%"=="" set "HOST=%INPUT_HOST%"
 
 :: 2. Port
-set "PORT=5002"
+set "PORT=49112"
 set /p "INPUT_PORT=Port [%PORT%]: "
 if not "%INPUT_PORT%"=="" set "PORT=%INPUT_PORT%"
 

server.py

@@ -0,0 +1,123 @@
+#!/usr/bin/env python3
+"""
+PocketTTS OpenAI-Compatible Server
+
+A drop-in replacement for OpenAI's TTS API using the pocket-tts model.
+Supports streaming, custom voices, and runs on CPU.
+
+Usage:
+    python server.py [OPTIONS]
+
+    # Or with environment variables:
+    POCKET_TTS_PORT=8080 python server.py
+"""
+
+import argparse
+import os
+import sys
+
+from app import create_app, init_tts_service
+from app.config import Config
+from app.logging_config import get_logger
+
+
+def parse_args():
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(
+        description='PocketTTS OpenAI-Compatible Server',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+    # Start with defaults
+    python server.py
+
+    # Custom port and voices directory
+    python server.py --port 8080 --voices-dir ./my_voices
+
+    # Enable streaming by default
+    python server.py --stream
+
+Environment Variables:
+    POCKET_TTS_HOST         Server host (default: 0.0.0.0)
+    POCKET_TTS_PORT         Server port (default: 49112)
+    POCKET_TTS_MODEL_PATH   Path to model file
+    POCKET_TTS_VOICES_DIR   Path to voices directory
+    POCKET_TTS_STREAM_DEFAULT Enable streaming by default
+    POCKET_TTS_LOG_DIR      Log directory path
+        """,
+    )
+
+    parser.add_argument(
+        '--host', type=str, default=Config.HOST, help=f'Host to bind to (default: {Config.HOST})'
+    )
+    parser.add_argument(
+        '--port', type=int, default=Config.PORT, help=f'Port to listen on (default: {Config.PORT})'
+    )
+    parser.add_argument(
+        '--model-path',
+        type=str,
+        default=Config.MODEL_PATH,
+        dest='model_path',
+        help='Path to model file or variant name',
+    )
+    parser.add_argument(
+        '--voices-dir',
+        type=str,
+        default=Config.VOICES_DIR,
+        dest='voices_dir',
+        help='Directory containing voice files',
+    )
+    parser.add_argument(
+        '--stream',
+        action='store_true',
+        default=Config.STREAM_DEFAULT,
+        help='Enable streaming by default for all requests',
+    )
+    parser.add_argument(
+        '--log-level',
+        type=str,
+        default=Config.LOG_LEVEL,
+        choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
+        dest='log_level',
+        help='Logging level',
+    )
+
+    return parser.parse_args()
+
+
+def main():
+    """Main entry point."""
+    args = parse_args()
+
+    # Update config from args (environment takes precedence via Config class)
+    os.environ.setdefault('POCKET_TTS_LOG_LEVEL', args.log_level)
+
+    # Create app
+    app = create_app({'STREAM_DEFAULT': args.stream})
+
+    logger = get_logger()
+
+    # Initialize TTS service
+    try:
+        init_tts_service(model_path=args.model_path, voices_dir=args.voices_dir)
+    except Exception as e:
+        logger.error(f'Failed to initialize TTS service: {e}')
+        sys.exit(1)
+
+    # Start server with Waitress (production WSGI server)
+    try:
+        from waitress import serve
+
+        logger.info(f'Starting PocketTTS server on http://{args.host}:{args.port}')
+        logger.info('Press Ctrl+C to stop')
+
+        serve(app, host=args.host, port=args.port, threads=4, url_scheme='http')
+
+    except ImportError:
+        logger.warning('Waitress not installed, falling back to Flask dev server')
+        logger.warning('Install waitress for production: pip install waitress')
+        app.run(host=args.host, port=args.port, debug=False, threaded=True)
+
+
+if __name__ == '__main__':
+    main()

static/css/style.css

@@ -219,3 +219,201 @@ audio {
 .hidden {
     display: none;
 }
+
+/* API Documentation Styles */
+.api-docs {
+    margin-top: 3rem;
+    padding-top: 2rem;
+    border-top: 1px solid var(--border-color);
+}
+
+.api-docs h2 {
+    font-size: 1.5rem;
+    margin-bottom: 0.5rem;
+    color: var(--text-primary);
+}
+
+.api-intro {
+    color: var(--text-secondary);
+    margin-bottom: 2rem;
+    font-size: 0.95rem;
+}
+
+.endpoint {
+    background: var(--input-bg);
+    border: 1px solid var(--border-color);
+    border-radius: 12px;
+    padding: 1.5rem;
+    margin-bottom: 1.5rem;
+}
+
+.endpoint-header {
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    margin-bottom: 1rem;
+}
+
+.method {
+    padding: 0.25rem 0.75rem;
+    border-radius: 4px;
+    font-weight: 600;
+    font-size: 0.8rem;
+    text-transform: uppercase;
+}
+
+.method.get {
+    background: rgba(46, 160, 67, 0.2);
+    color: #3fb950;
+    border: 1px solid rgba(46, 160, 67, 0.4);
+}
+
+.method.post {
+    background: rgba(88, 166, 255, 0.2);
+    color: #58a6ff;
+    border: 1px solid rgba(88, 166, 255, 0.4);
+}
+
+.path {
+    font-family: 'SF Mono', 'Consolas', monospace;
+    font-size: 1rem;
+    color: var(--text-primary);
+    background: none;
+    padding: 0;
+}
+
+.endpoint-desc {
+    color: var(--text-secondary);
+    margin-bottom: 1rem;
+    font-size: 0.9rem;
+}
+
+.params-section,
+.example-section,
+.response-example,
+.error-section {
+    margin-top: 1rem;
+}
+
+.params-section strong,
+.example-section strong,
+.response-example strong,
+.error-section strong {
+    display: block;
+    color: var(--text-secondary);
+    font-size: 0.85rem;
+    margin-bottom: 0.5rem;
+}
+
+.params-table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 0.85rem;
+    margin-top: 0.5rem;
+}
+
+.params-table th,
+.params-table td {
+    padding: 0.6rem 0.75rem;
+    text-align: left;
+    border-bottom: 1px solid var(--border-color);
+}
+
+.params-table th {
+    color: var(--text-secondary);
+    font-weight: 500;
+    background: rgba(0, 0, 0, 0.2);
+}
+
+.params-table td {
+    color: var(--text-primary);
+}
+
+.params-table code {
+    background: rgba(88, 166, 255, 0.1);
+    color: var(--accent-color);
+    padding: 0.15rem 0.4rem;
+    border-radius: 4px;
+    font-size: 0.85em;
+}
+
+.api-docs pre {
+    background: rgba(0, 0, 0, 0.3);
+    border: 1px solid var(--border-color);
+    border-radius: 8px;
+    padding: 1rem;
+    overflow-x: auto;
+    font-family: 'SF Mono', 'Consolas', monospace;
+    font-size: 0.85rem;
+    color: var(--text-primary);
+    line-height: 1.5;
+}
+
+.voices-reference {
+    margin-top: 2rem;
+    padding: 1.5rem;
+    background: var(--input-bg);
+    border: 1px solid var(--border-color);
+    border-radius: 12px;
+}
+
+.voices-reference h3 {
+    font-size: 1.1rem;
+    margin-bottom: 0.5rem;
+    color: var(--text-primary);
+}
+
+.voices-reference p {
+    color: var(--text-secondary);
+    font-size: 0.9rem;
+    margin-bottom: 1rem;
+}
+
+.voice-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    margin-bottom: 1rem;
+}
+
+.voice-chip {
+    background: rgba(88, 166, 255, 0.15);
+    color: var(--accent-color);
+    padding: 0.4rem 0.8rem;
+    border-radius: 20px;
+    font-size: 0.85rem;
+    font-family: 'SF Mono', 'Consolas', monospace;
+    border: 1px solid rgba(88, 166, 255, 0.3);
+}
+
+.voice-note {
+    font-size: 0.85rem;
+    color: var(--text-secondary);
+    margin-top: 1rem;
+    margin-bottom: 0;
+}
+
+.voice-note a {
+    color: var(--accent-color);
+    text-decoration: none;
+}
+
+.voice-note a:hover {
+    text-decoration: underline;
+}
+
+/* Responsive adjustments */
+@media (max-width: 600px) {
+    .params-table {
+        font-size: 0.75rem;
+    }
+
+    .params-table th,
+    .params-table td {
+        padding: 0.4rem 0.5rem;
+    }
+
+    .endpoint-header {
+        flex-wrap: wrap;
+    }
+}

static/js/app.js

@@ -1,106 +1,120 @@
 document.addEventListener('DOMContentLoaded', async () => {
-    const voiceSelect = document.getElementById('voice-select');
-    const customVoiceGroup = document.getElementById('custom-voice-group');
-    const generateBtn = document.getElementById('generate-btn');
-    const textInput = document.getElementById('text-input');
-    const voiceFile = document.getElementById('voice-file');
-    const outputSection = document.getElementById('output-section');
-    const audioPlayer = document.getElementById('audio-player');
-    const downloadBtn = document.getElementById('download-btn');
-    const streamToggle = document.getElementById('stream-toggle');
-
-    // 1. Load Voices
-    async function loadVoices() {
-        try {
-            const res = await fetch('/v1/voices');
-            const data = await res.json();
-
-            // Clear existing except custom
-            voiceSelect.innerHTML = '<option value="custom">Custom (Upload .wav, .mp3, .flac)...</option>';
-
-            if (data.data) {
-                // Add built-ins first
-                data.data.forEach(voice => {
-                    const opt = document.createElement('option');
-                    opt.value = voice.id;
-                    opt.textContent = voice.name || voice.id;
-                    voiceSelect.insertBefore(opt, voiceSelect.firstChild); // Prepend
-                });
-
-                // Select first by default
-                if (voiceSelect.options.length > 0) {
-                    voiceSelect.selectedIndex = 0;
-                }
-            }
-        } catch (e) {
-            console.error("Failed to list voices:", e);
-        }
-    }
-
-    await loadVoices();
-
-    // 2. Handle Voice Selection Change
-    voiceSelect.addEventListener('change', (e) => {
-        if (e.target.value === 'custom') {
-            // Setup for Custom Path
-            document.querySelector('#custom-voice-group label').textContent = "Absolute Path to Audio File:";
-            voiceFile.type = 'text';
-            voiceFile.placeholder = "C:\\path\\to\\voice.wav";
-            customVoiceGroup.classList.remove('hidden');
-        } else {
-            customVoiceGroup.classList.add('hidden');
-        }
-    });
-
-    // 3. Generate Logic
-    generateBtn.addEventListener('click', async () => {
-        const text = textInput.value.trim();
-        if (!text) return alert("Please enter text");
-
-        const stream = streamToggle.checked;
-
-        let voice = voiceSelect.value;
-        if (voice === 'custom') {
-            voice = voiceFile.value.trim();
-            if (!voice) return alert("Please enter the path to the voice file.");
-        }
-
-        generateBtn.classList.add('loading');
-        generateBtn.disabled = true;
-        outputSection.classList.remove('active');
-
-        try {
-            const response = await fetch('/v1/audio/speech', {
-                method: 'POST',
-                headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({
-                    model: 'pocket-tts',
-                    input: text,
-                    voice: voice,
-                    response_format: 'wav',
-                    stream: stream
-                })
-            });
-
-            if (!response.ok) {
-                const err = await response.json();
-                throw new Error(err.error || response.statusText);
-            }
-
-            const blob = await response.blob();
-            const url = URL.createObjectURL(blob);
-            audioPlayer.src = url;
-            downloadBtn.href = url;
-            downloadBtn.download = "generated_speech.wav";
-
-            audioPlayer.play();
-            outputSection.classList.add('active');
-
-        } catch (e) {
-            alert("Error generating speech: " + e.message);
-        } finally {
-            generateBtn.classList.remove('loading');
-            generateBtn.disabled = false;
-        }
-    });
+	const voiceSelect = document.getElementById('voice-select');
+	const customVoiceGroup = document.getElementById('custom-voice-group');
+	const generateBtn = document.getElementById('generate-btn');
+	const textInput = document.getElementById('text-input');
+	const voiceFile = document.getElementById('voice-file');
+	const outputSection = document.getElementById('output-section');
+	const audioPlayer = document.getElementById('audio-player');
+	const downloadBtn = document.getElementById('download-btn');
+	const streamToggle = document.getElementById('stream-toggle');
+
+	// 1. Load Voices
+	async function loadVoices() {
+		try {
+			const res = await fetch('/v1/voices');
+			const data = await res.json();
+
+			// Clear existing
+			voiceSelect.innerHTML = '';
+
+			if (data.data) {
+				// Add voices in order (built-in first, then custom)
+				data.data.forEach((voice) => {
+					const opt = document.createElement('option');
+					opt.value = voice.id;
+					opt.textContent = voice.name || voice.id;
+					voiceSelect.appendChild(opt);
+				});
+
+				// Add custom upload option at the end
+				const customOpt = document.createElement('option');
+				customOpt.value = 'custom';
+				customOpt.textContent = 'Custom (Upload .wav, .mp3, .flac)...';
+				voiceSelect.appendChild(customOpt);
+
+				// Select first (alba) by default
+				if (voiceSelect.options.length > 0) {
+					voiceSelect.selectedIndex = 0;
+				}
+			}
+		} catch (e) {
+			console.error('Failed to list voices:', e);
+		}
+	}
+
+	await loadVoices();
+
+	// 2. Handle Voice Selection Change (hide custom option in Docker mode)
+	const isDocker = window.POCKET_TTS_CONFIG?.isDocker || false;
+
+	// Remove the "Custom" option when running in Docker (paths won't work)
+	if (isDocker) {
+		const customOption = voiceSelect.querySelector('option[value="custom"]');
+		if (customOption) customOption.remove();
+	}
+
+	voiceSelect.addEventListener('change', (e) => {
+		if (e.target.value === 'custom' && !isDocker) {
+			// Setup for Custom Path (only for native/exe mode)
+			document.querySelector('#custom-voice-group label').textContent =
+				'Absolute Path to Audio File:';
+			voiceFile.type = 'text';
+			voiceFile.placeholder = 'C:\\path\\to\\voice.wav';
+			customVoiceGroup.classList.remove('hidden');
+		} else {
+			customVoiceGroup.classList.add('hidden');
+		}
+	});
+
+	// 3. Generate Logic
+	generateBtn.addEventListener('click', async () => {
+		const text = textInput.value.trim();
+		if (!text) return alert('Please enter text');
+
+		const stream = streamToggle.checked;
+
+		let voice = voiceSelect.value;
+		if (voice === 'custom') {
+			voice = voiceFile.value.trim();
+			if (!voice) return alert('Please enter the path to the voice file.');
+		}
+
+		generateBtn.classList.add('loading');
+		generateBtn.disabled = true;
+		outputSection.classList.remove('active');
+
+		try {
+			const response = await fetch('/v1/audio/speech', {
+				method: 'POST',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({
+					model: 'pocket-tts',
+					input: text,
+					voice: voice,
+					response_format: 'wav',
+					stream: stream,
+				}),
+			});
+
+			if (!response.ok) {
+				const err = await response.json();
+				throw new Error(err.error || response.statusText);
+			}
+
+			const blob = await response.blob();
+			const url = URL.createObjectURL(blob);
+			audioPlayer.src = url;
+			downloadBtn.href = url;
+			downloadBtn.download = 'generated_speech.wav';
+
+			audioPlayer.play();
+			outputSection.classList.add('active');
+		} catch (e) {
+			alert('Error generating speech: ' + e.message);
+		} finally {
+			generateBtn.classList.remove('loading');
+			generateBtn.disabled = false;
+		}
+	});
 });

templates/index.html

@@ -1,61 +1,294 @@
-<!DOCTYPE html>
+<!doctype html>
 <html lang="en">
-<head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Pocket TTS - Local Streaming</title>
-    <link rel="stylesheet" href="/static/css/style.css">
-    <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">
-</head>
-<body>
-
-<div class="container">
-    <header>
-        <img src="/static/images/pocket-tts-logo.png" alt="Pocket TTS Logo" class="logo">
-        <h1>Pocket TTS</h1>
-        <p class="subtitle">Real-time local speech synthesis & voice cloning</p>
-    </header>
-
-    <div class="content">
-        <div class="control-group">
-            <label for="text-input">Text Prompt</label>
-            <textarea id="text-input" placeholder="Enter text to generate speech...">Hello! I am Pocket TTS, running locally on your machine. I can clone voices and stream audio in real-time.</textarea>
-        </div>
-
-        <div class="control-group">
-            <label for="voice-select">Voice Selection</label>
-            <select id="voice-select">
-                <!-- Populated by JS -->
-                <option value="custom">Custom (Upload .wav, .mp3, or .flac)...</option>
-            </select>
-        </div>
-
-        <div class="control-group hidden" id="custom-voice-group">
-             <label for="voice-file">Upload Reference Audio (WAV, MP3, FLAC)</label>
-             <input type="file" id="voice-file" accept=".wav,.mp3,.flac">
-        </div>
-
-        <div class="control-group">
-             <label for="stream-toggle" style="display:inline-flex; align-items:center; cursor:pointer;">
-                 <input type="checkbox" id="stream-toggle" style="width:auto; margin-right:8px;"> Enable Streaming Response
-             </label>
-        </div>
-
-        <button id="generate-btn" class="btn-primary">
-            <span>Generate Speech</span>
-            <div class="spinner"></div>
-        </button>
-
-        <div class="output-section" id="output-section">
-            <audio id="audio-player" controls></audio>
-            <br>
-            <a href="#" id="download-btn" class="download-link">Download Audio</a>
-        </div>
-    </div>
-</div>
-
-<script src="/static/js/app.js"></script>
-</body>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<title>Pocket TTS - Local Streaming</title>
+		<link rel="stylesheet" href="/static/css/style.css" />
+		<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"
+		/>
+	</head>
+	<body>
+		<script>
+			// Pass server config to JavaScript
+			window.POCKET_TTS_CONFIG = {
+			    isDocker: {{ 'true' if is_docker else 'false' }}
+			};
+		</script>
+
+		<div class="container">
+			<header>
+				<img
+					src="/static/images/pocket-tts-logo.png"
+					alt="Pocket TTS Logo"
+					class="logo"
+				/>
+				<h1>Pocket TTS</h1>
+				<p class="subtitle">Real-time local speech synthesis & voice cloning</p>
+			</header>
+
+			<div class="content">
+				<div class="control-group">
+					<label for="text-input">Text Prompt</label>
+					<textarea
+						id="text-input"
+						placeholder="Enter text to generate speech..."
+					>
+Hello! I am Pocket TTS, running locally on your machine. I can clone voices and stream audio in real-time.</textarea
+					>
+				</div>
+
+				<div class="control-group">
+					<label for="voice-select">Voice Selection</label>
+					<select id="voice-select">
+						<!-- Populated by JS -->
+						<option value="custom">
+							Custom (Upload .wav, .mp3, or .flac)...
+						</option>
+					</select>
+				</div>
+
+				<div class="control-group hidden" id="custom-voice-group">
+					<label for="voice-file"
+						>Upload Reference Audio (WAV, MP3, FLAC)</label
+					>
+					<input type="file" id="voice-file" accept=".wav,.mp3,.flac" />
+				</div>
+
+				<div class="control-group">
+					<label
+						for="stream-toggle"
+						style="display: inline-flex; align-items: center; cursor: pointer"
+					>
+						<input
+							type="checkbox"
+							id="stream-toggle"
+							checked
+							style="width: auto; margin-right: 8px"
+						/>
+						Enable Streaming Response
+					</label>
+				</div>
+
+				<button id="generate-btn" class="btn-primary">
+					<span>Generate Speech</span>
+					<div class="spinner"></div>
+				</button>
+
+				<div class="output-section" id="output-section">
+					<audio id="audio-player" controls></audio>
+					<br />
+					<a href="#" id="download-btn" class="download-link">Download Audio</a>
+				</div>
+			</div>
+
+			<!-- API Documentation -->
+			<div class="api-docs">
+				<h2>API Documentation</h2>
+				<p class="api-intro">
+					OpenAI-compatible TTS API. Use any OpenAI TTS client by pointing it to
+					this server.
+				</p>
+
+				<!-- Health Endpoint -->
+				<div class="endpoint">
+					<div class="endpoint-header">
+						<span class="method get">GET</span>
+						<code class="path">/health</code>
+					</div>
+					<p class="endpoint-desc">
+						Health check endpoint for container orchestration and monitoring.
+					</p>
+					<div class="response-example">
+						<strong>Response:</strong>
+						<pre>
+{
+  "status": "healthy",
+  "model_loaded": true,
+  "device": "cpu",
+  "sample_rate": 24000
+}</pre
+						>
+					</div>
+				</div>
+
+				<!-- List Voices Endpoint -->
+				<div class="endpoint">
+					<div class="endpoint-header">
+						<span class="method get">GET</span>
+						<code class="path">/v1/voices</code>
+					</div>
+					<p class="endpoint-desc">
+						List all available voices (built-in and custom).
+					</p>
+					<div class="response-example">
+						<strong>Response:</strong>
+						<pre>
+{
+  "object": "list",
+  "data": [
+    {"id": "alba", "name": "Alba", "object": "voice"},
+    {"id": "marius", "name": "Marius", "object": "voice"}
+  ]
+}</pre
+						>
+					</div>
+				</div>
+
+				<!-- Generate Speech Endpoint -->
+				<div class="endpoint">
+					<div class="endpoint-header">
+						<span class="method post">POST</span>
+						<code class="path">/v1/audio/speech</code>
+					</div>
+					<p class="endpoint-desc">
+						Generate speech audio from text. OpenAI-compatible endpoint.
+					</p>
+
+					<div class="params-section">
+						<strong>Request Body (JSON):</strong>
+						<table class="params-table">
+							<thead>
+								<tr>
+									<th>Parameter</th>
+									<th>Type</th>
+									<th>Required</th>
+									<th>Default</th>
+									<th>Description</th>
+								</tr>
+							</thead>
+							<tbody>
+								<tr>
+									<td><code>input</code></td>
+									<td>string</td>
+									<td>✓</td>
+									<td>-</td>
+									<td>The text to generate speech from (max 4096 chars)</td>
+								</tr>
+								<tr>
+									<td><code>voice</code></td>
+									<td>string</td>
+									<td></td>
+									<td><code>alba</code></td>
+									<td>
+										Voice ID, filename, or URL. See <code>/v1/voices</code>
+									</td>
+								</tr>
+								<tr>
+									<td><code>model</code></td>
+									<td>string</td>
+									<td></td>
+									<td>-</td>
+									<td>Ignored (for OpenAI compatibility)</td>
+								</tr>
+								<tr>
+									<td><code>response_format</code></td>
+									<td>string</td>
+									<td></td>
+									<td><code>mp3</code></td>
+									<td>
+										Audio format: <code>mp3</code>, <code>wav</code>,
+										<code>pcm</code>, <code>opus</code>, <code>flac</code>
+									</td>
+								</tr>
+								<tr>
+									<td><code>stream</code></td>
+									<td>boolean</td>
+									<td></td>
+									<td><code>true</code></td>
+									<td>Enable streaming response for real-time playback</td>
+								</tr>
+								<!-- <tr>
+									<td><code>speed</code></td>
+									<td>number</td>
+									<td></td>
+									<td><code>1.0</code></td>
+									<td>Playback speed (0.25 to 4.0)</td>
+								</tr> -->
+							</tbody>
+						</table>
+					</div>
+
+					<div class="example-section">
+						<strong>Example Request (curl):</strong>
+						<pre>
+curl -X POST http://localhost:49112/v1/audio/speech \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": "Hello world!",
+    "voice": "alba",
+    "response_format": "mp3"
+  }' \
+  --output speech.mp3</pre
+						>
+					</div>
+
+					<div class="example-section">
+						<strong>Example (Python with OpenAI client):</strong>
+						<pre>
+from openai import OpenAI
+
+client = OpenAI(
+    base_url="http://localhost:49112/v1",
+    api_key="not-needed"
+)
+
+response = client.audio.speech.create(
+    model="tts-1",
+    voice="alba",
+    input="Hello world!"
+)
+response.stream_to_file("output.mp3")</pre
+						>
+					</div>
+
+					<div class="response-example">
+						<strong>Response:</strong>
+						<p>Audio file in the requested format (binary stream).</p>
+						<p>
+							<strong>Content-Type:</strong> <code>audio/mpeg</code>,
+							<code>audio/wav</code>, <code>audio/opus</code>, etc.
+						</p>
+					</div>
+
+					<div class="error-section">
+						<strong>Error Response:</strong>
+						<pre>
+{
+  "error": "Missing required field: input"
+}</pre
+						>
+					</div>
+				</div>
+
+				<!-- Built-in Voices Reference -->
+				<div class="voices-reference">
+					<h3>Built-in Voices</h3>
+					<p>These voices work without authentication:</p>
+					<div class="voice-chips">
+						<span class="voice-chip">alba</span>
+						<span class="voice-chip">marius</span>
+						<span class="voice-chip">javert</span>
+						<span class="voice-chip">jean</span>
+						<span class="voice-chip">fantine</span>
+						<span class="voice-chip">cosette</span>
+						<span class="voice-chip">eponine</span>
+						<span class="voice-chip">azelma</span>
+					</div>
+					<p class="voice-note">
+						Custom voice cloning requires a
+						<a href="https://huggingface.co/kyutai/pocket-tts" target="_blank"
+							>HuggingFace token</a
+						>.
+					</p>
+				</div>
+			</div>
+		</div>
+
+		<script src="/static/js/app.js"></script>
+	</body>
 </html>