Self-hosted Docker speech API for OpenAI-compatible transcription and text-to-speech, streaming A...
10K+
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.
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 the CUDA-only models (Parakeet-TDT, the larger Canary models, Qwen3 TTS
and Chatterbox Turbo), use psyb0t/talkies:latest-cuda with --gpus all. The
loopback port mapping keeps the service local; see
Getting started
for first boot and authentication.
| Surface | Purpose | Reference |
|---|---|---|
POST /v1/audio/transcriptions | File transcription and subtitles | HTTP API |
WS /v1/audio/transcriptions/stream | Live 16 kHz PCM ASR | Streaming |
POST /v1/audio/speech | Speech synthesis in six formats | HTTP API |
GET /v1/models | Enabled slugs and their modality | HTTP API |
GET /v1/audio/voices | Per-model voice catalog with origin tags | Models |
GET/PUT/DELETE /v1/files/* | Server-side file staging | HTTP API |
/api/ps, /unload | Model inspection and eviction | Operations |
/v1/mcp | Streamable HTTP MCP with ASR/file tools | HTTP API |
GET /healthz | Liveness probe; the only unauthenticated route | Operations |
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.
wav2vec2-xlsr-53-espeak and zipa-ipa return the IPA
phones that were spoken, not words, with no language model correcting them
toward the nearest dictionary entry. Same transcription endpoint and
timestamp options as the other ASR models; see
Phoneme recognition.response_format="pcm"; other TTS formats and Kokoro are buffered.[sigh], [whispering] and [laugh] directly in the input text. Its output
carries a neural watermark by default; set TALKIES_CHATTERBOX_WATERMARK to
false to emit unmarked audio..wav into /data/custom-voices and it appears on
GET /v1/audio/voices. Qwen3 pairs it with an optional sibling .txt
transcript; Chatterbox needs only the clip, longer than five seconds.Exact slugs, executors, tag list, and registry format: Models and registries.
wav2vec2-xlsr-53-espeak and zipa-ipa use the same transcription call as
every other ASR slug; only the model changes. text comes back as a
space-separated IPA phone stream rather than words, and no language model
corrects a mispronunciation toward a real word.
curl -s http://127.0.0.1:8000/v1/audio/transcriptions \
-F "file=@/path/to/clip.wav" \
-F "model=zipa-ipa"
# {"text": "a ɪ m k ə n f j u z ...", ...}
Add -F "response_format=verbose_json" to get each phone as a words entry
with start and end in seconds.
Tags go inline in input, in square brackets, lowercase. They are real tokens
in the model's tokenizer, so only these 19 do anything; any other bracketed
word is spoken as literal text:
[angry] [fear] [surprised] [whispering] [advertisement] [dramatic] [narration]
[crying] [happy] [sarcastic] [clear throat] [sigh] [shush] [cough] [groan]
[sniff] [gasp] [chuckle] [laugh]
curl -s http://127.0.0.1:8000/v1/audio/speech \
-H 'Content-Type: application/json' \
-d '{
"model": "chatterbox-turbo",
"voice": "builtin",
"input": "Oh, that is hilarious. [chuckle] Anyway [sigh] back to work.",
"response_format": "mp3"
}' --output out.mp3
Swap "voice" for the name of any .wav you dropped in /data/custom-voices
(extension stripped) to speak the same line in a cloned voice.
The full documentation is at psyb0t.github.io/docker-talkies.
| Guide | Contents |
|---|---|
| Getting started | Run CPU/CUDA, persist data, authenticate, verify |
| Models and registries | Bundled slugs, image availability, registry fields, custom registries |
| HTTP API | Requests, responses, errors, files, lifecycle, MCP |
| Streaming | Live ASR protocol, streaming backends, PCM TTS |
| Configuration | Supported environment variables and limits |
| Operations and security | Exposure, model memory, data retention, logs |
| Agent integrations | Skill, Claude Code, Codex and OpenClaw plugins, MCP bridge |
| Architecture | Request flow, backend selection, on-disk layout |
| Development | Make targets, test suites, image builds, docs site |
The Talkies skill
teaches agents to use the HTTP, WebSocket, and MCP routes. It installs as a
Claude Code or Codex plugin from the shared psyb0t marketplace, and OpenClaw
installs the skill and a stdio MCP bridge from ClawHub. For Claude Code:
claude plugin marketplace add psyb0t/agents
claude plugin install talkies@psyb0t
The Codex and OpenClaw commands and the bridge settings are in Agent integrations.
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.
make check # lint + unit tests in the dev image
make lint # flake8 + mypy only
make test-unit # fast offline unit tests
make run # run the CPU image locally
make test-streaming # real CPU native WebSocket ASR test
make test-streaming-custom # real CPU Sherpa/Vosk WebSocket + HTTP tests
make test-streaming-custom-cuda # real CUDA Sherpa WebSocket + HTTP test
make compile-heavy # regenerate the hash-locked ML requirements
make build-all # CPU and CUDA production images
make docs # build the documentation site into .testing/docs-site
make help lists every target, and
Development describes each one.
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.
Content type
Image
Digest
sha256:1c9272ff9…
Size
1.1 GB
Last updated
9 days ago
docker pull psyb0t/talkies