Talkies

talkies

一个 Docker 镜像中集成的可自托管语音服务：兼容 OpenAI 的文件转录和文本转语音、通过 WebSocket 提供的 Talkies 实时 ASR、文件暂存、模型生命周期控制，以及用于 ASR 工作流的 MCP 端点。

目录

• 从这里开始
• 功能简介
• 模型一览
  • 阅读音素
  • 为 Chatterbox 添加情感提示词
• 文档
• Agent 集成
• 一分钟了解安全性
• 开发

从这里开始

首次启动时，请仅启用所需的模型；否则，入口点会下载内置注册表中的所有模型。

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"

对于仅支持 CUDA 的模型——Parakeet-TDT、较大的 Canary 模型、Qwen3 TTS 和 Chatterbox Turbo——请使用 psyb0t/talkies:latest-cuda 并添加 --gpus all。回环端口映射可确保服务仅在本地运行；首次启动和身份验证请参阅入门指南。

功能简介

接口	用途	参考
POST /v1/audio/transcriptions	文件转录和字幕	HTTP API
WS /v1/audio/transcriptions/stream	实时 16 kHz PCM ASR	流式处理
POST /v1/audio/speech	支持六种格式的语音合成	HTTP API
GET /v1/models	已启用的模型标识及其模态	HTTP API
GET /v1/audio/voices	带有来源标签的各模型语音目录	模型
GET/PUT/DELETE /v1/files/*	服务端文件暂存	HTTP API
/api/ps、/unload	模型检查和卸载	运维
/v1/mcp	提供 ASR/文件工具的流式 HTTP MCP	HTTP API
GET /healthz	存活探针；唯一无需身份验证的路由	运维

HTTP 转录和语音路由在契约兼容的范围内采用相应的 OpenAI 数据格式。流式 ASR、文件、生命周期控制和 MCP 则是 Talkies 扩展功能。

模型一览

• CPU：两个 Whisper 模型、Canary-180M-Flash、通过 parakeet.cpp 运行的 Nemotron ASR、四种英文 Sherpa-ONNX Zipformer 选项、Vosk 英文小型模型、两个音素识别器，以及两个 Kokoro TTS 后端。
• CUDA：CPU 配置中的模型，外加 Parakeet-TDT、Canary 1B/Qwen ASR、五种 Qwen3 TTS 变体，以及 Chatterbox Turbo。
• 实时 ASR：内置的 Nemotron、Sherpa-ONNX 和 Vosk 均为原生实现；内置 Whisper 使用有界滚动解码器。Sherpa 和 Vosk 也可通过 OpenAI 兼容的文件转录端点使用。
• 音素识别：wav2vec2-xlsr-53-espeak 和 zipa-ipa 返回实际发出的 IPA 音素，而非单词；不会使用语言模型将其纠正为最接近的词典词条。使用与其他 ASR 模型相同的转录端点和时间戳选项；请参阅音素识别。
• 每个模型的并发限制适用于 WebSocket、HTTP、MCP、ASR 和 TTS；内置的 Nemotron CPU 和 CUDA 配置各允许两个请求。
• 流式 TTS：Qwen3 在 response_format="pcm" 时会增量返回原始 PCM；其他 TTS 格式和 Kokoro 则会缓冲。
• 富有表现力的 TTS：Chatterbox Turbo（英语）可直接在输入文本中识别 19 种内联标签，例如 [sigh]、[whispering] 和 [laugh]。其输出默认带有神经水印；将 TALKIES_CHATTERBOX_WATERMARK 设为 false 可生成无水印音频。
• 声音克隆：将 .wav 文件放入 /data/custom-voices，即可通过 GET /v1/audio/voices 获取。Qwen3 可选配同名 .txt 转录文件；Chatterbox 只需音频片段，且时长须超过五秒。

确切的 slug、执行器、标签列表和注册表格式： 模型和注册表。

解读音素

wav2vec2-xlsr-53-espeak 和 zipa-ipa 使用与其他所有 ASR slug 相同的转录调用；只有模型不同。返回的 text 是以空格分隔的 IPA 音素流，而非单词；语言模型不会将误读纠正为真实单词。

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 ...", ...}

添加 -F "response_format=verbose_json"（或 timestamp_granularities[]=word），即可在 words 条目中获取每个音素及其以秒为单位的 start 和 end 时间。

通过情绪提示 Chatterbox

标签以小写形式置于 input 中，并用方括号括起。它们是模型分词器中的真实令牌，因此只有这 19 个标签有效——其他任何带方括号的词都会作为字面文本朗读：

[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

将 "voice" 替换为你放入 /data/custom-voices 的任意 .wav 文件名（不含扩展名），即可用克隆的声音朗读同一句话。

文档

指南	内容
快速入门	运行 CPU/CUDA、持久化数据、进行身份验证、验证
模型和注册表	内置 slug、镜像可用性、自定义注册表
架构	请求流程、后端选择、磁盘布局
HTTP API	请求、响应、文件、生命周期、MCP
流式处理	实时 ASR 协议、流式后端、PCM TTS
配置	支持的环境变量和限制
运维与安全	暴露、模型内存、数据保留、日志
开发	Make 目标、测试套件、镜像构建

Agent 集成

Talkies 技能指导 Agent 使用 HTTP、WebSocket 和 MCP 接口。可通过共享的 psyb0t marketplace 安装，也可让 Codex 直接从此代码检出目录发现它。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install talkies@psyb0t

Claude Code 会提示输入 Talkies URL；如果已启用，还会提示输入 bearer token。敏感令牌会通过客户端的受保护配置存储。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add talkies@psyb0t

通过 marketplace 安装后，可将技能作为 $talkies:talkies 调用。Codex 也会直接发现此仓库中的 .agents/skills/talkies，无需安装即可通过 $talkies 调用。

OpenClaw

该技能和 MCP 桥接器通过 ClawHub 发布：

openclaw skills install @psyb0t/talkies
openclaw plugins install clawhub:@psyb0t/talkies

该桥接器将本地 stdio MCP 客户端连接到运行中的 Talkies /v1/mcp 端点。设置 TALKIES_URL，并在启用身份验证时设置 TALKIES_AUTH_TOKEN。

一分钟了解安全性

TALKIES_AUTH_TOKEN 会为除 /healthz 之外的所有 HTTP 和 WebSocket 路由启用共享承载令牌。默认未设置。请将端口限制为仅允许回环访问，或 在 Talkies 前部署 TLS、身份验证和速率限制。如果不受信任的调用方 可以提供远程 file_path URL，请设置 TALKIES_BLOCK_PRIVATE_DOWNLOADS=true。 完整的安全措施请参阅运维与安全。

开发

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 help 会列出所有目标。

Talkies 基于 WTFPL 发布。模型权重会在运行时下载，并适用各自的条款；图像组件声明请见 THIRD_PARTY.md。发行说明请见 CHANGELOG.md。