Speaches Setup Guide - ajgillis04/GillisDockerDepot GitHub Wiki

Speaches Setup Guide

Introduction

Speaches is a speech server with OpenAI-style endpoints:

  • Speech to text (faster-whisper): POST /v1/audio/transcriptions
  • Text to speech (Kokoro): POST /v1/audio/speech

Here it gives OpenWebUI Setup Guide (WSL2 Docker) voice input and spoken replies, and it's Mealie Setup Guide's audio provider for importing recipes from videos. It runs fine on a modest second machine's CPU.

Compose

compose/server8/speaches.yaml:

services:
  speaches:
    container_name: speaches.${HOST_NAME}
    image: ghcr.io/speaches-ai/speaches:0.8.3-cpu
    environment:
      TZ: ${TZ}
      WHISPER__INFERENCE_DEVICE: cpu
      WHISPER__COMPUTE_TYPE: int8
      STT_MODEL_TTL: "-1"     # keep models loaded
      TTS_MODEL_TTL: "-1"
    ports:
      - "${SPEACHES_PORT}:8000"
    volumes:
      - speaches_cache:/home/ubuntu/.cache/huggingface/hub
    restart: always
volumes:
  speaches_cache:
    name: speaches_cache

CPU vs GPU: on an older 4 GB card, GPU transcription crashed on the first request and the TTS GPU provider wouldn't load, so this uses the CPU image. CPU int8 transcribes a 6-second clip in about 5 seconds, which is fine for voice chat.

Download the Models

Models download on first use, or ahead of time:

curl -X POST http://<host>:<port>/v1/models/Systran/faster-distil-whisper-small.en
curl -X POST http://<host>:<port>/v1/models/speaches-ai/Kokoro-82M-v1.0-ONNX
curl http://<host>:<port>/v1/models     # list what's installed

Connecting Apps

  • Open WebUI (Admin Panel → Settings → Audio):
    • STT engine OpenAI, URL http://<host>:<port>/v1, any key, model Systran/faster-distil-whisper-small.en
    • TTS engine OpenAI, same URL, model speaches-ai/Kokoro-82M-v1.0-ONNX, a voice such as af_heart
  • Mealie: add it as an AI provider with the Whisper model, and assign it as the audio provider.

Browsers only allow the microphone on https pages, so use voice through your https address, not http://<ip>.

⚠️ **GitHub.com Fallback** ⚠️