FlashTTS

将自托管 FlashTTS 服务作为 LiveKit 流式 TTS

支持能力

FlashTTS 插件适合已经部署 HuiResearch/FlashTTS 服务、希望在 LiveKit 中使用开源 TTS 模型的团队。它不是托管 API，因此服务容量、模型文件、音色和鉴权均由部署方负责。

TTS：通过自托管 FlashTTS HTTP 服务进行流式语音合成。
支持服务端音色、语速、音高和采样参数；实际能力取决于服务端模型。
插件不提供 STT、LLM 或 RealtimeModel。

部署与安装

先按 FlashTTS 项目说明启动 API 服务，再安装 LiveKit 插件：

配置

也可以显式传参：

代码示例

FLASHTTS_BASE_URL=http://127.0.0.1:8000
FLASHTTS_API_KEY=optional-bearer-token

from livekit.plugins import flashtts

tts = flashtts.TTS(
    voice="female",
    sample_rate=16000,
)

tts = flashtts.TTS(
    base_url="https://tts.internal.example",
    api_key="your-token",
    voice="female",
    pitch="moderate",
    speed="moderate",
    temperature=0.9,
)

主要参数

参数	类型 / 可选值	默认值	说明
`base_url`	URL	`FLASHTTS_BASE_URL` 或 `http://localhost:8000`	FlashTTS 服务地址。插件会向该地址的 `/speak` 路径发起请求。
`api_key`	字符串或 `None`	`FLASHTTS_API_KEY`	Bearer Token。服务端启用鉴权时必须配置。
`sample_rate`	整数	`16000`	输出采样率，单位为 Hz。应与服务端返回音频的实际采样率一致。
`voice`	服务端音色名	`female`	音色名称。可用值由服务端加载的模型决定。
`pitch`	`very_low` / `low` / `moderate` / `high` / `very_high`	`None`	音高档位。`None` 表示使用服务端默认值。
`speed`	同上	`None`	语速档位。`None` 表示使用服务端默认值。
`temperature`	浮点数	`0.9`	控制合成采样随机性，值越高通常越有变化。
`top_k`	整数	`50`	从概率最高的候选 token 中选取前 `k` 个参与采样。
`top_p`	浮点数	`0.95`	累积概率采样阈值，用于限制候选 token 范围。
`repetition_penalty`	浮点数	`1.0`	重复惩罚系数。调高可减少重复词句，过高可能影响自然度。
`max_tokens`	整数	`32768`	单次合成允许生成的最大 token 数。
`extra_headers`	`dict[str, str]`	`{}`	发送给 FlashTTS 服务的额外 HTTP Header。

voice 的实际可选值由服务端加载的模型与配置决定，插件本身不维护统一音色列表。

排查

连接被拒绝：先从 Agent 主机访问 FLASHTTS_BASE_URL，确认容器端口已暴露。
401：确认服务是否真的启用了 Bearer Token，以及 FLASHTTS_API_KEY 是否一致。
播放速度或音高无变化：当前模型可能不支持对应控制字段。
音频速度异常：确保插件 sample_rate 与服务端返回音频的真实采样率一致。

建议修改