restructure and dockerize

.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,60 @@
+# 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 .
+
+  test:
+    runs-on: ubuntu-latest
+    needs: lint
+
+    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 pytest pytest-cov
+
+      - name: Run import test
+        run: |
+          python -c "from app import create_app; print('Import test passed')"
+
+      # Note: Full TTS tests require the model which is too large for CI
+      # Add more tests as the project grows

.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,100 @@
+# 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. URLs (`http://`, `https://`, `hf://`) → pass to pocket-tts
+2. Built-in names (`alba`, `marius`, etc.) → pass to pocket-tts
+3. Files in `POCKET_TTS_VOICES_DIR`
+4. Absolute paths
+5. Fallback to pocket-tts
+
+## 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 `ruff.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,68 @@
+# Dockerfile for PocketTTS OpenAI-Compatible Server
+# Optimized for CPU inference (pocket-tts runs efficiently on CPU)
+
+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
+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
+
+# 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,79 @@
+"""
+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'
+
+    # 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,183 @@
+"""
+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."""
+    return render_template('index.html')
+
+
+@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."""
+
+    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 format is WAV
+        if fmt == 'wav':
+            yield write_wav_header(tts.sample_rate, num_channels=1, bits_per_sample=16)
+        yield from generate()
+
+    mimetype = get_mime_type(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,302 @@
+"""
+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
+        """
+        # Check if it's a URL or HF path - pass through
+        if voice_id_or_path.startswith(('http://', 'https://', '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)
+        """
+        resolved = self._resolve_voice_path(voice_id_or_path)
+
+        # Built-in voices are always valid
+        if resolved.lower() in Config.BUILTIN_VOICES:
+            return True, f'Built-in voice: {resolved}'
+
+        # URLs - assume valid (we can't check without making a request)
+        if resolved.startswith(('http://', 'https://', 'hf://')):
+            return True, f'Remote 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,11 @@
-flask
-torch<=2.8.0
-torchaudio<=2.8.0
-pocket-tts
-scipy
-numpy
-soundfile
+# 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()