nmorgowicz-org
diff --git a/‎.env.example‎
Lines changed: 33 additions & 66 deletions b/‎.env.example‎
Lines changed: 33 additions & 66 deletions
diff --git a/‎Dockerfile‎
Lines changed: 3 additions & 0 deletions b/‎Dockerfile‎
Lines changed: 3 additions & 0 deletions
diff --git a/‎README.md‎
Lines changed: 10 additions & 20 deletions b/‎README.md‎
Lines changed: 10 additions & 20 deletions
diff --git a/‎compose.yml‎
Lines changed: 41 additions & 33 deletions b/‎compose.yml‎
Lines changed: 41 additions & 33 deletions
@@ -1,69 +1,36 @@
-# ── Required (set these before first use) ─────────────────────────────────────
-REF_AUDIO_PATH=/absolute/path/to/reference.wav
-REF_TEXT=Exact transcript of the reference audio
-MODEL_SIZE=1.7B
-
-# ── Recommended (most real deployments should set) ────────────────────────────
-# QWEN3_TTS_IMAGE=ghcr.io/nmorgowicz-org/qwen3-tts-openvino:<sha>
-# LOW_RAM_MODE=1
-
-# ── Service ───────────────────────────────────────────────────────────────────
-# QWEN3_TTS_PORT=8318            # Host port for the service
-# TZ=UTC                         # Log timestamps (UTC recommended for multi-timezone access)
-# FRONTEND_ENABLED=1             # Serve the web UI at / (set 0 for API-only deployments)
-
-# ── Memory limits ─────────────────────────────────────────────────────────────
-# TTS_MEMORY_LIMIT=10G           # Serving container cgroup memory limit (raise on larger hosts)
-# TTS_MEMORY_SWAP_LIMIT=11G      # Serving container cgroup memory+swap limit
-# EXPORT_MEMORY_LIMIT=13G        # Export container limit (stop serving first on 15 GiB hosts)
-# EXPORT_MEMORY_SWAP_LIMIT=14G   # Export container swap limit
-
-# ── Advanced (tune only if you have a reason; see HOW_TO_RUN.md for details) ──
-
-# CPU threading: set to your physical core count (not hyperthreads) for best latency.
-# OV_INFERENCE_THREADS=6
-
-# OpenVINO dynamic quantization: 0=disabled, 32=default, 64=faster with slightly
-# lower accuracy. Useful on very constrained hosts where a small latency gain matters.
-# OV_DYNAMIC_QUANT_GROUP_SIZE=32
+# Minimal Qwen3-TTS OpenVINO example.
+# Copy this to .env and edit the values you need.
+# For full reference, see docs/ENV_REFERENCE.md
 
-# OpenVINO compiled kernel cache directory. Leaving this default eliminates 60–120s
-# of JIT recompilation on every restart or idle-unload reload. Set to empty string to disable.
-# OV_CACHE_DIR=/ov/cache
+# Optional default voice -------------------------------------------------
+# If set, this WAV is mounted and promoted to the Voice Library.
+# REF_TEXT is optional; by default Whisper drafts it automatically.
+# REF_AUDIO_PATH=/absolute/path/to/reference.wav
+# REF_TEXT=Exact transcript audio
+# REF_TEXT_AUTO=whisper
 
-# Idle unload: set to N seconds to free the model after inactivity (e.g. 1800 = 30 min).
-# LOW_RAM_MODE=1 sets this automatically. Reload is transparent but adds ~5–30s latency.
-# IDLE_UNLOAD_SECONDS=0
+# HF_TOKEN is required only if the checkpoint is gated in your environment.
+# HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 
-# OPENVINO_KEEP_CODEC_ENCODER: set to 0 only if you'll never use VoiceDesign / voice library
-# / cloning any voice_id besides the one startup reference voice (e.g. a single-voice deployment).
-# - 1 (default): keeps codec resident; enables cloning any voice_id immediately, at a cost of ~0.3 GiB.
-# - 0: frees ~0.3 GiB after startup; uncached voice_id will fail with an error.
-# OPENVINO_KEEP_CODEC_ENCODER=1
-
-# TTS_MAX_SPEECH_SECONDS: max duration for a single request, baked into IR at export time.
-# Is a latency/safety cap, not a memory lever. Changing it requires re-exporting.
-# Default 64 is appropriate for most uses.
-# TTS_MAX_SPEECH_SECONDS=64
-
-# Rollback backend: set to 'pytorch' to run without OpenVINO IR (slower, useful if IR fails).
-# TTS_BACKEND=pytorch
-
-# Hugging Face token: required if the checkpoint is gated for your environment.
-# Never log or commit this.
-# HF_TOKEN=
-
-# Pin a specific Hugging Face revision; must match exported IR metadata.
-# MODEL_REVISION=
-
-# Silence trim: trim leading/trailing silence from output audio. Useful if output
-# sounds too short or is missing final consonants. Set SILENCE_TRIM=0 to disable.
-# SILENCE_TRIM=1
-# SILENCE_TRIM_THRESH=0.01       # Silence threshold (fraction of peak amplitude)
-# SILENCE_TRIM_PAD_MS=30         # Padding kept after detected silence boundary
-
-# ── VoiceDesign ────────────────────────────────────────────────────────────────
-# After Base export, run: docker compose run --rm export-voice-design
-# VOICE_DESIGN_MODEL_SIZE=1.7B
-# VOICE_DESIGN_MODEL_REPO=
-# VOICE_DESIGN_MAX_SPEECH_SECONDS=20 # Capacity baked into the VoiceDesign IR at export time
+# ── Recommended defaults ──────────────────────────────────────────────────────
+MODEL_SIZE=1.7B
+TTS_BACKEND=openvino
+
+# ── Data paths (override only if you need non-default locations) ────────────────
+# MODEL_CACHE_PATH=/var/data/autopirate/qwen3-tts/model
+# OV_DATA_PATH=/var/data/autopirate/qwen3-tts/openvino
+# VOICE_LIBRARY_PATH=/voices
+# SEGMENT_LIBRARY_PATH=/segments
+
+# ── Advanced / tuning ─────────────────────────────────────────────────────────
+# For full reference and all available options, see docs/ENV_REFERENCE.md.
+
+# LOW_RAM_MODE=1            # Recommended on 10–15 GiB hosts; enables idle unload and malloc tuning
+# FRONTEND_ENABLED=1        # Serve the web UI at / (0 = API-only)
+# VOICE_DESIGN_MODEL_SIZE=1.7B   # For VoiceDesign (run export-voice-design after Base export)
+
+# TTS_MAX_SPEECH_SECONDS=64     # Max speech length per request (requires re-export if changed)
+# SILENCE_TRIM=1                # Trim silence from output (0 = disable)
+# IDLE_UNLOAD_SECONDS=1800      # Free model after N seconds of inactivity (0 = disabled)
+# OV_INFERENCE_THREADS=6        # Use physical core count for best latency
+# TTS_BACKEND=pytorch           # Rollback to CPU-only PyTorch if OpenVINO fails
@@ -81,6 +81,9 @@ p.write_text(t)"
 RUN python -m pip install -r requirements/requirements-openvino.txt && \
     python -m pip install -r requirements/requirements-export.txt
 
+# Pocket TTS: lightweight CPU TTS backend
+RUN python -m pip install -r requirements/requirements-pocket-tts.txt
+
 COPY src/ src/
 COPY scripts/ scripts/
 COPY --from=frontend-build /frontend/dist frontend/dist
 
@@ -20,31 +20,21 @@ contains the export tooling.
 No authentication or TLS. Keep port 8318 on a trusted network or behind an authenticated reverse
 proxy (see SECURITY.md).
 
-## Quick start
+## Getting started
 
-Requirements: Linux AMD64, Docker Compose, Intel CPU, at least 10 GiB RAM for the service, a
-reference WAV, and its exact transcript.
+Prerequisites:
 
-```bash
-cp .env.example .env
-# Edit .env: set REF_AUDIO_PATH and REF_TEXT. MODEL_SIZE=1.7B is recommended.
+- Docker and Docker Compose
+- Optional: a reference WAV file for a default cloned voice
 
-docker compose run --rm export
-docker compose up -d qwen3-tts
-curl -fsS http://localhost:8318/health
-```
+Steps:
 
-Generate:
+1. Copy `.env.example` to `.env`; set `HF_TOKEN` only if your selected models are gated. Optional: set `REF_AUDIO_PATH` for a default voice; Whisper drafts its transcript automatically.
+2. `docker compose up --build qwen3-tts`
+3. Run once to generate model artifacts: `docker compose run --rm --profile export export`
+4. Open `http://localhost:8318`
 
-```bash
-curl -sS http://localhost:8318/v1/audio/speech \
-  -H 'Content-Type: application/json' \
-  -d '{"input":"Hello from Qwen three TTS.","response_format":"mp3"}' \
-  -o output.mp3
-```
-
-For full deployment details, environment variables, VoiceDesign setup, streaming, and memory
-tuning, see [HOW_TO_RUN.md](docs/HOW_TO_RUN.md).
+For advanced configuration, environment variables, and tuning, see [docs/ENV_REFERENCE.md](docs/ENV_REFERENCE.md).
 
 ## Model profiles
 
 
@@ -1,12 +1,24 @@
 name: qwen3-tts-openvino
 
+# Minimal setup:
+# - Create .env if you need to override defaults:
+#   HF_TOKEN="your token repo is gated"  # if needed
+#   REF_AUDIO_PATH=/path/to/reference.wav  # optional default voice
+#   REF_TEXT="exact transcript reference audio"  # optional override; Whisper drafts by default
+# - Then:
+#     docker compose up --build qwen3-tts
+#     docker compose run --rm --profile export export   (once, to generate IR)
+
+# All other knobs are optional and should be left at defaults.
+
+# Common model/volume settings (used by both qwen3-tts and export)
 x-model-environment: &model-environment
   MODEL_SIZE: ${MODEL_SIZE:-1.7B}
-  REF_TEXT: ${REF_TEXT:?Set REF_TEXT to the exact reference-audio transcript}
+  REF_TEXT: ${REF_TEXT:-}
+  REF_TEXT_AUTO: ${REF_TEXT_AUTO:-whisper}
   HF_TOKEN: ${HF_TOKEN:-}
   MODEL_REVISION: ${MODEL_REVISION:-}
-  # Must match between `export` and `qwen3-tts` — it selects which capacity-keyed IR file
-  # gets built and which one gets loaded. Unset uses the 64s default (unchanged behavior).
+  # Capacity baked into the IR at export time; changing it requires re-export.
   TTS_MAX_SPEECH_SECONDS: ${TTS_MAX_SPEECH_SECONDS:-}
 
 x-model-volumes: &model-volumes
@@ -15,7 +27,7 @@ x-model-volumes: &model-volumes
 
 services:
   qwen3-tts:
-    # Local builds: `docker compose up --build` creates the :local tag automatically.
+    # Local builds: docker compose up --build creates :local.
     # Production: set QWEN3_TTS_IMAGE to a pinned GHCR SHA or version tag.
     image: ${QWEN3_TTS_IMAGE:-qwen3-tts-openvino:local}
     build:
@@ -26,61 +38,57 @@ services:
       - "${QWEN3_TTS_PORT:-8318}:8318"
     environment:
       <<: *model-environment
+      # Core behavior
       TTS_BACKEND: ${TTS_BACKEND:-openvino}
       TZ: ${TZ:-America/Detroit}
-      LOW_RAM_MODE: ${LOW_RAM_MODE:-0}
-      # Serves the built frontend/ static export at / (see src/qwen3_tts/app.py). Set to 0 to
-      # run this container as an API-only service with no web UI.
-      FRONTEND_ENABLED: ${FRONTEND_ENABLED:-1}
-      # Must match the export-voice-design service below — selects which VoiceDesign IR tree
-      # this container swaps into for POST /voice_design (see src/qwen3_tts/voice_design.py).
+
+      # LOW_RAM_MODE=1 is recommended on typical 10-15 GiB hosts:
+      # enables idle unload + malloc tuning so the container can coexist
+      # with other services without hogging memory.
+      LOW_RAM_MODE: 1
+
+      # Serve the built web UI at /. Set to 0 to run API-only.
+      FRONTEND_ENABLED: 1
+
+      # VoiceDesign (used for POST /voice_design).
+      # These must match whatever was used during export.
       VOICE_DESIGN_MODEL_SIZE: ${VOICE_DESIGN_MODEL_SIZE:-1.7B}
       VOICE_DESIGN_MODEL_REPO: ${VOICE_DESIGN_MODEL_REPO:-}
       VOICE_DESIGN_MAX_SPEECH_SECONDS: ${VOICE_DESIGN_MAX_SPEECH_SECONDS:-}
     volumes:
       - ${MODEL_CACHE_PATH:-./data/model}:/root/.cache/huggingface/hub:rw
       - ${OV_DATA_PATH:-./data/ov}:/ov:rw
-      - ${REF_AUDIO_PATH:?Set REF_AUDIO_PATH to the reference WAV file}:/voice/reference.wav:ro
+      - ${REF_AUDIO_PATH:-./data/reference.wav}:/voice/reference.wav:ro
       - ${VOICE_LIBRARY_PATH:-./data/voices}:/voices:rw
       - ${SEGMENT_LIBRARY_PATH:-./data/segments}:/segments:rw
     mem_limit: ${TTS_MEMORY_LIMIT:-10G}
     memswap_limit: ${TTS_MEMORY_SWAP_LIMIT:-11G}
     stop_grace_period: 45s
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:8318/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 5
+      start_period: 120s
 
+  # Unified export service: exports both Base and VoiceDesign IR in one run.
   export:
-    # Same single image as the service above; only the command differs.
     image: ${QWEN3_TTS_IMAGE:-qwen3-tts-openvino:local}
     build:
       context: .
     command: ["python", "scripts/export.py"]
     profiles: [export]
     environment:
       <<: *model-environment
+      # Tell export.py to run both targets (Base + VoiceDesign) in one shot.
+      EXPORT_TARGET: both
       OV_OUTPUT_ROOT: /ov
-    volumes: *model-volumes
-    # The FP32 export + INT4/INT8 quantization needs more headroom than serving; the 1.7B
-    # INT4 export can OOM at the 10G serving limit. Stop the serving container before exporting
-    # on the 15 GiB box — never run a 13G export and a 10G serve concurrently (OOM).
-    mem_limit: ${EXPORT_MEMORY_LIMIT:-13G}
-    memswap_limit: ${EXPORT_MEMORY_SWAP_LIMIT:-14G}
-
-  export-voice-design:
-    # Same image/command as `export`; EXPORT_TARGET selects the VoiceDesign checkpoint and
-    # its separate /ov/<size>-voicedesign/... output tree (see scripts/export.py, VOICE_DESIGN
-    # section of docs/dev/architecture/voice_design.md). Independent from the `export` service so a
-    # VoiceDesign export never overwrites a Base export for the same size.
-    image: ${QWEN3_TTS_IMAGE:-qwen3-tts-openvino:local}
-    build:
-      context: .
-    command: ["python", "scripts/export.py"]
-    profiles: [export]
-    environment:
-      HF_TOKEN: ${HF_TOKEN:-}
-      EXPORT_TARGET: voice_design
+      # VoiceDesign settings (must match qwen3-tts service)
       VOICE_DESIGN_MODEL_SIZE: ${VOICE_DESIGN_MODEL_SIZE:-1.7B}
       VOICE_DESIGN_MODEL_REPO: ${VOICE_DESIGN_MODEL_REPO:-}
       VOICE_DESIGN_MAX_SPEECH_SECONDS: ${VOICE_DESIGN_MAX_SPEECH_SECONDS:-}
-      OV_OUTPUT_ROOT: /ov
     volumes: *model-volumes
+    # FP32 export + INT4/INT8 quantization is memory-intensive.
+    # On a 15 GiB box, stop qwen3-tts before running this to avoid OOM.
     mem_limit: ${EXPORT_MEMORY_LIMIT:-13G}
     memswap_limit: ${EXPORT_MEMORY_SWAP_LIMIT:-14G}