Docker Talkies MCP Server

talkies

Self-hosted speech services in one Docker image: OpenAI-compatible file transcription and text-to-speech, Talkies live ASR over WebSocket, file staging, model lifecycle controls, and an MCP endpoint for ASR workflows.

Start here

Restrict the first boot to the models you need; otherwise the entrypoint downloads every model in the bundled registry.

docker run --rm -it --name talkies \
  -p 127.0.0.1:8000:8000 \
  -v "$PWD/talkies-data:/data" \
  -e TALKIES_ENABLED_MODELS=whisper-large-v3-turbo,kokoro-82m \
  psyb0t/talkies:latest

curl -s http://127.0.0.1:8000/healthz
curl -s http://127.0.0.1:8000/v1/audio/transcriptions \
  -F "file=@/path/to/clip.wav" \
  -F "model=whisper-large-v3-turbo"

For CUDA-only models and Qwen3 TTS, use psyb0t/talkies:latest-cuda with --gpus all. The loopback port mapping keeps the service local; see Getting started for first boot and authentication.

What it provides

The HTTP transcription and speech routes use the corresponding OpenAI wire shapes where those contracts overlap. Streaming ASR, files, lifecycle controls, and MCP are Talkies extensions.

Models at a glance

• CPU: two Whisper models, Canary-180M-Flash, Nemotron ASR via parakeet.cpp, and two Kokoro TTS backends.
• CUDA: the CPU set plus Parakeet-TDT, Canary 1B/Qwen ASR, and five Qwen3 TTS variants.
• Live ASR: bundled Nemotron is native; bundled Whisper is a bounded rolling decoder. Sherpa-ONNX and Vosk are native through a custom registry.
• Streaming TTS: Qwen3 returns incremental raw PCM for response_format="pcm"; other TTS formats and Kokoro are buffered.

Exact slugs, executors, and registry format: Models and registries.

Documentation

Security in one minute

TALKIES_AUTH_TOKEN enables a shared bearer token for every HTTP and WebSocket route except /healthz. It is unset by default. Keep the port loopback-only or put Talkies behind TLS, authentication, and rate limiting. If untrusted callers can supply remote file_path URLs, set TALKIES_BLOCK_PRIVATE_DOWNLOADS=true. See Operations and security for the complete posture.

Development

make check                 # lint + unit tests in the dev image
make test-streaming        # real CPU native WebSocket ASR test
make test-streaming-custom # real Sherpa-ONNX and Vosk WebSocket tests
make build-all             # CPU and CUDA production images

Talkies is released under the WTFPL. Model weights are downloaded at runtime and have their own terms; image component notices are in THIRD_PARTY.md. Release notes are in CHANGELOG.md.