# Kokoro-82M served via remsky/Kokoro-FastAPI — the de-facto OpenAI-
# compatible wrapper for hexgrad's Kokoro-82M TTS.
#
# Why this stack exists alongside the other TTS:
#   * Lowest-latency English in the fleet — ~300 ms TTFA on GPU,
#     RTF 35-100x on a 4060 Ti class card.
#   * Native streaming via OpenAI-compat `stream=true` over HTTP
#     chunked transfer (Kokoro's KPipeline is a per-phrase generator).
#   * Apache-2.0 weights + code; ~1 GB VRAM at fp16.
#   * 60+ built-in voices (no cloning — for that use IndexTTS-2 or
#     Chatterbox Turbo). Voices combinable via "voice(weight)+..." syntax.
#
# Image is a published GHCR build; no Dockerfile to maintain. Models
# baked into the image, no first-run download. Deploy is a pull + up.
#
# All tunables live in .env — edit that, not this file.

services:
  kokoro:
    image: ghcr.io/remsky/kokoro-fastapi-${KOKORO_VARIANT:-cpu}:${KOKORO_TAG}
    container_name: kokoro
    restart: unless-stopped
    # Only request GPU runtime when running the GPU variant. Toggling
    # `runtime: nvidia` from a YAML knob isn't possible directly; we
    # accomplish it by routing nvidia-only fields through the
    # NVIDIA_VISIBLE_DEVICES env var instead. The cpu variant ignores
    # that env var harmlessly; the gpu variant honors it.
    ports:
      - "${KOKORO_BIND:-0.0.0.0}:${KOKORO_PORT}:8880"
    # Persistent custom voices: the wrapper only enumerates one voice
    # directory (controlled by VOICES_DIR; default in-image is
    # /app/api/src/voices/v1_0 which is NOT bind-mounted). We point it
    # at /app/user_voices (which IS host-bind-mounted) and seed the
    # built-ins into it on every container start. Custom voices written
    # by scripts/blend_kokoro_voice.py land directly on the host bind
    # mount and survive `up --force-recreate` and image upgrade.
    # `cp -r` (no `-n`): always refresh built-ins from the image so
    # upgrades that add/change built-in voicepacks propagate.
    # Custom-named .pt files in user_voices that don't exist in v1_0
    # are NOT touched (cp -r only copies entries from src).
    command: ["/bin/bash", "-c", "cp -r /app/api/src/voices/v1_0/. /app/user_voices/ && exec ./entrypoint.sh"]
    environment:
      - NVIDIA_VISIBLE_DEVICES=${KOKORO_GPU_DEVICES:-}
      - USE_GPU=${KOKORO_USE_GPU:-false}
      - API_LOG_LEVEL=${KOKORO_LOG_LEVEL:-INFO}
      - VOICES_DIR=/app/user_voices
    volumes:
      # Host-bind-mounted voice directory. Hosts both the image's
      # built-ins (re-seeded on each container start by the command
      # shim above) and any custom voices created via the blend
      # script. Must be chowned to uid 1001 (appuser inside the
      # container) on the host so the shim's cp can write — handled
      # by playbooks/deploy-kokoro.yaml.
      - ${KOKORO_USER_VOICES_DIR}:/app/user_voices
    healthcheck:
      # The image is python-based with curl available. /v1/audio/voices
      # is a no-arg GET that exercises the full API path.
      test: ["CMD-SHELL", "curl -fsS -o /dev/null http://localhost:8880/v1/audio/voices || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 90s
    labels:
      - homepage.group=AI - Speech (TTS)
      - homepage.name=Kokoro
      - homepage.icon=mdi-microphone-message
      - homepage.description=Low-latency English TTS w/ streaming (irv-ml1)
      - homepage.href=http://irv-ml1.nh3.internal:${KOKORO_PORT}