livekit-plugins-lmnt 插件实战在 LiveKit Agents 中接入 LMNT 语音合成【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本文聚焦于 livekit-plugins-lmnt 插件——LiveKit Agents 生态中用于接入 LMNT 语音合成TTS能力的官方插件。它将指导你在实时语音 Agent 中完成插件安装、API Key 配置、TTS 实例化与 AgentSession 集成并结合源码深入剖析模型、语音、语言、采样率、temperature/top_p 等全部可调参数以及底层 HTTP 合成请求的完整调用链。读完本文你将能够在自己的实时语音 Agent 中直接使用 LMNT 的高质量语音输出并在运行期动态调整合成参数。插件是什么LMNT 是一家提供语音合成服务的厂商livekit-plugins-lmnt是 LiveKit Agents 官方为它提供的 TTS 插件实现。插件在 tts.py 中定义了一个继承自livekit.agents.tts.TTS抽象基类的TTS类并通过init.py 导出TTS、ChunkedStream与__version__同时以Plugin.register_plugin(LMNTPlugin())自动完成插件注册。接入后LMNT 的语音能力就能与 LiveKit Agents 的 STT、LLM、房间音频等模块无缝协作直接作为 Agent 的发声器官。安装插件README 中给出的安装方式是一条 pip 命令这也是所有 LiveKit 插件统一的标准安装路径pip install livekit-plugins-lmnt从插件的 pyproject.toml 可以看到更完整的工程信息供排查环境问题时参考Python 版本要求requires-python 3.10.0即 Python 3.10 及以上核心依赖livekit-agents1.8.0使用前请确保 agents 主框架版本不低于 1.8.0许可证Apache-2.0版本管理版本号由 version.py 中的__version__提供当前仓库内为1.8.0。如果你的项目使用 uv 管理依赖也可以直接在pyproject.toml中声明livekit-plugins-lmnt后执行uv sync。前置条件配置 LMNT API Key按照 README 的要求使用本插件前必须先取得 LMNT 的 API Key推荐做法是把它放到环境变量中export LMNT_API_KEYyour_lmnt_api_key_here从源码来看API Key 的解析逻辑位于 tts.py 的TTS.__init__中api_key api_key or os.environ.get(LMNT_API_KEY) if not api_key: raise ValueError( LMNT API key is required, either as argument or set LMNT_API_KEY environment variable )也就是说Key 有两种提供方式构造函数显式传入或通过LMNT_API_KEY环境变量。两者都没有提供时TTS会直接抛出ValueError提示必须配置 API Key。建议始终使用环境变量方式避免把密钥硬编码进代码库。快速开始最小可用示例在拿到 API Key 后创建 LMNT TTS 实例只需一行代码from livekit.plugins.lmnt import TTS tts TTS() # 使用全部默认配置此时插件会采用源码中的默认参数模型blizzard、音色leah、语言自动检测auto、输出格式mp3、采样率24000Hz、temperature1.0、top_p0.8。也可以显式指定语音与模型from livekit.plugins.lmnt import TTS tts TTS( modelblizzard, # 可选 blizzard / aurora voiceleah, # 替换为你想要使用的音色 ID languagezh, # 显式指定中文绕过自动检测 )在 AgentSession 中接入实时语音 Agent将 LMNT TTS 接入完整的实时语音 Agent需要把它作为AgentSession的tts参数传入。参考 basic_agent.py 展示的会话组织方式核心片段如下from livekit.agents import Agent, AgentServer, AgentSession, cli, room_io from livekit.plugins import lmnt class MyAgent(Agent): def __init__(self) - None: super().__init__( instructionsYou are a helpful voice assistant. Keep responses concise., ) server AgentServer() server.rtc_session() async def entrypoint(ctx) - None: session AgentSession( stt..., # 语音识别 llm..., # 大模型 ttslmnt.TTS(voiceleah), # 使用 LMNT 发声 ) await session.start(agentMyAgent(), roomctx.room) if __name__ __main__: cli.run_app(server)这样Agent 回复用户的每一句话都会先交给 LLM 生成文本再交给 LMNT 合成语音最终通过房间推送给客户端播放。你还可以像 basic_agent 那样叠加tts_text_transforms如过滤 emoji、markdown 符号来净化送入 TTS 的文本进一步提高合成质量。核心配置参数详解TTS构造函数tts.py提供了一组完整的合成参数全部为关键字参数现逐一说明参数类型/可选值默认值作用说明modelblizzard/aurora见 models.pyblizzard使用的合成模型voice字符串音色 IDleah合成音色可前往 LMNT 平台挑选更多音色language见下方语言列表或NoneNone两位 ISO 639-1 语言代码为None时自动推断formataac/mp3/mulaw/raw/wavmp3输出音频格式sample_rate8000/16000/24000Hz24000输出采样率api_key字符串None读环境变量鉴权密钥http_sessionaiohttp.ClientSessionNone自动创建复用 HTTP 会话temperature浮点数0.0~1.01.0控制语气的表现力与情绪丰富度top_p浮点数0.0~1.00.8控制合成语音的稳定性语言参数与自动推断language使用两位 ISO 639-1 代码models.py 中枚举了完整集合auto、de德语、en英语、es西班牙语、fr法语、hi印地语、id印尼语、it意大利语、ja日语、ko韩语、nl荷兰语、pl波兰语、pt葡萄牙语、ru俄语、sv瑞典语、th泰语、tr土耳其语、uk乌克兰语、vi越南语、zh中文。值得注意的自动推断逻辑在 tts.pyif not language: language auto if model blizzard else en即当未显式传language时blizzard模型使用auto自动检测语言而aurora模型默认落到en。如果你的输入文本是中文等非英语场景建议显式传入language避免自动检测结果不符合预期。temperature 与 top_p 的调音指导这两个参数是控制合成风格的旋钮源码 docstring 给出了清晰的调优方向temperature默认 1.0影响语音的表现力和情绪变化程度。较低的值如0.3产生更中性、一致的说话风格较高的值如1.0允许更动态的情绪范围和风格变化。top_p默认 0.8控制生成语音的稳定性。较低的值如0.3产生更稳定、可靠的语音较高的值如0.9让词语发音方式更灵活但偶尔可能出现不寻常的语调或发音模式。实际项目中客服机器人等需要稳定口播的场景可下调两者而陪伴式/角色扮演类 Agent 可适当上调 temperature 换取更生动的情绪表达。运行期动态调整 TTS 参数与只读构造参数不同插件还提供了update_options方法tts.py允许在 Agent 运行过程中动态切换模型、音色、语言、格式、采样率、temperature 与 top_ptts.update_options( modelaurora, voiceanother_voice_id, languageja, temperature0.5, top_p0.6, )该方法内部使用NotGivenOr语义——未传入的参数保持不变只更新显式给定的项配合is_given判断实现见 tts.py因此可以放心地只传需要变更的字段。该能力适合多语言场景例如根据用户当前会话语言动态切换language和voice无需重建 TTS 实例。底层实现原理合成请求的完整链路TTS.synthesize(text)返回一个ChunkedStream它继承自livekit.agents.tts.ChunkedStream抽象基类定义见 tts.py。真正发起网络请求的逻辑在ChunkedStream._run中tts.pydata { text: self._input_text, voice: self._opts.voice, language: self._opts.language, sample_rate: self._opts.sample_rate, model: self._opts.model, format: self._opts.format, temperature: self._opts.temperature, top_p: self._opts.top_p, } async with self._tts._ensure_session().post( LMNT_BASE_URL, headers{ Content-Type: application/json, X-API-Key: self._opts.api_key, }, jsondata, timeoutaiohttp.ClientTimeout(total30, sock_connectself._conn_options.timeout), ) as resp: resp.raise_for_status() ...要点提炼如下端点插件常量LMNT_BASE_URL https://api.lmnt.com/v1/ai/speech/bytes即 LMNT 的字节流语音合成接口鉴权API Key 放在X-API-Key请求头中请求体为 JSON请求体text、voice、language、sample_rate、model、format、temperature、top_p 全部随请求发送超时整体超时 30 秒建连超时复用 LiveKit Agents 传入的conn_options.timeout会话复用优先复用用户传入的http_session否则从utils.http_context.http_session()获取见_ensure_session。响应到达后output_emitter.initialize(...)会以合成请求的采样率、单声道NUM_CHANNELS 1和对应 MIME 类型初始化音频流随后resp.content.iter_chunks()分块把音频字节推给下游播放管线最后flush()收尾。音频格式与 MIME 映射format参数直接决定输出编码插件维护了一张格式到 MIME 类型的映射表tts.pyformatMIME 类型aacaudio/aacmp3audio/mpegmulawaudio/basicrawapplication/octet-streamwavaudio/wav需要注意raw为未加头的裸 PCM 数据配合sample_rate/num_channels才能正确解析默认mp3与24000Hz的组合在多数实时场景下兼顾了体积与音质。错误处理与异常语义插件将底层异常统一收口为 LiveKit Agents 标准错误类型tts.py请求超时asyncio.TimeoutError→ 抛出APITimeoutError非 2xx 响应aiohttp.ClientResponseError→ 通过create_api_error_from_http转换为对应 HTTP 错误其他异常 → 包装为APIConnectionError。这意味着上层 Agent 无需感知 aiohttp 细节可以用 LiveKit Agents 统一的错误体系做重试或降级处理例如切换备用 TTS。非流式特性说明TTS.__init__中声明了capabilitiestts.TTSCapabilities(streamingFalse)tts.py即 LMNT 属于整段合成后返回字节流的模式而非边生成边推流。框架会把整段文本交给 LMNT 一次合成再分块推给播放器。在实现上与真正的逐 token 流式 TTS 不同但这不影响在 AgentSession 中的使用方式合成延迟由 LMNT 侧处理速度决定。测试与验证仓库的 test_tts.py 将 LMNT 插件纳入了参数化的网络测试用例pytest.param( lambda: { tts: lmnt.TTS(), proxy-upstream: api.lmnt.com:443, }, idlmnt, ),该用例以默认参数实例化lmnt.TTS()即不传任何参数并通过本地代理将流量导向api.lmnt.com:443来验证插件在真实网络路径下的行为。由此可以确认默认配置下插件即可正常工作无需额外传参同时这也是排查连通性问题时定位到api.lmnt.com443 端口的重要依据。小结livekit-plugins-lmnt以极简的接入成本为 LiveKit Agents 提供了 LMNT 语音合成能力一条pip install完成安装一个环境变量完成鉴权一行lmnt.TTS()即可发声。配合update_options的动态调参能力与统一的异常体系它可以胜任多语言客服、角色扮演、有声播报等各类实时语音场景。深入阅读 tts.py 与 models.py 源码可以进一步理解每个参数对合成结果的实际影响从而为你的 Agent 调出最合适的声音。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 livekit-plugins-lmnt 插件实战：在 LiveKit Agents 中接入 LMNT 语音合成
livekit-plugins-lmnt 插件实战在 LiveKit Agents 中接入 LMNT 语音合成【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents本文聚焦于 livekit-plugins-lmnt 插件——LiveKit Agents 生态中用于接入 LMNT 语音合成TTS能力的官方插件。它将指导你在实时语音 Agent 中完成插件安装、API Key 配置、TTS 实例化与 AgentSession 集成并结合源码深入剖析模型、语音、语言、采样率、temperature/top_p 等全部可调参数以及底层 HTTP 合成请求的完整调用链。读完本文你将能够在自己的实时语音 Agent 中直接使用 LMNT 的高质量语音输出并在运行期动态调整合成参数。插件是什么LMNT 是一家提供语音合成服务的厂商livekit-plugins-lmnt是 LiveKit Agents 官方为它提供的 TTS 插件实现。插件在 tts.py 中定义了一个继承自livekit.agents.tts.TTS抽象基类的TTS类并通过init.py 导出TTS、ChunkedStream与__version__同时以Plugin.register_plugin(LMNTPlugin())自动完成插件注册。接入后LMNT 的语音能力就能与 LiveKit Agents 的 STT、LLM、房间音频等模块无缝协作直接作为 Agent 的发声器官。安装插件README 中给出的安装方式是一条 pip 命令这也是所有 LiveKit 插件统一的标准安装路径pip install livekit-plugins-lmnt从插件的 pyproject.toml 可以看到更完整的工程信息供排查环境问题时参考Python 版本要求requires-python 3.10.0即 Python 3.10 及以上核心依赖livekit-agents1.8.0使用前请确保 agents 主框架版本不低于 1.8.0许可证Apache-2.0版本管理版本号由 version.py 中的__version__提供当前仓库内为1.8.0。如果你的项目使用 uv 管理依赖也可以直接在pyproject.toml中声明livekit-plugins-lmnt后执行uv sync。前置条件配置 LMNT API Key按照 README 的要求使用本插件前必须先取得 LMNT 的 API Key推荐做法是把它放到环境变量中export LMNT_API_KEYyour_lmnt_api_key_here从源码来看API Key 的解析逻辑位于 tts.py 的TTS.__init__中api_key api_key or os.environ.get(LMNT_API_KEY) if not api_key: raise ValueError( LMNT API key is required, either as argument or set LMNT_API_KEY environment variable )也就是说Key 有两种提供方式构造函数显式传入或通过LMNT_API_KEY环境变量。两者都没有提供时TTS会直接抛出ValueError提示必须配置 API Key。建议始终使用环境变量方式避免把密钥硬编码进代码库。快速开始最小可用示例在拿到 API Key 后创建 LMNT TTS 实例只需一行代码from livekit.plugins.lmnt import TTS tts TTS() # 使用全部默认配置此时插件会采用源码中的默认参数模型blizzard、音色leah、语言自动检测auto、输出格式mp3、采样率24000Hz、temperature1.0、top_p0.8。也可以显式指定语音与模型from livekit.plugins.lmnt import TTS tts TTS( modelblizzard, # 可选 blizzard / aurora voiceleah, # 替换为你想要使用的音色 ID languagezh, # 显式指定中文绕过自动检测 )在 AgentSession 中接入实时语音 Agent将 LMNT TTS 接入完整的实时语音 Agent需要把它作为AgentSession的tts参数传入。参考 basic_agent.py 展示的会话组织方式核心片段如下from livekit.agents import Agent, AgentServer, AgentSession, cli, room_io from livekit.plugins import lmnt class MyAgent(Agent): def __init__(self) - None: super().__init__( instructionsYou are a helpful voice assistant. Keep responses concise., ) server AgentServer() server.rtc_session() async def entrypoint(ctx) - None: session AgentSession( stt..., # 语音识别 llm..., # 大模型 ttslmnt.TTS(voiceleah), # 使用 LMNT 发声 ) await session.start(agentMyAgent(), roomctx.room) if __name__ __main__: cli.run_app(server)这样Agent 回复用户的每一句话都会先交给 LLM 生成文本再交给 LMNT 合成语音最终通过房间推送给客户端播放。你还可以像 basic_agent 那样叠加tts_text_transforms如过滤 emoji、markdown 符号来净化送入 TTS 的文本进一步提高合成质量。核心配置参数详解TTS构造函数tts.py提供了一组完整的合成参数全部为关键字参数现逐一说明参数类型/可选值默认值作用说明modelblizzard/aurora见 models.pyblizzard使用的合成模型voice字符串音色 IDleah合成音色可前往 LMNT 平台挑选更多音色language见下方语言列表或NoneNone两位 ISO 639-1 语言代码为None时自动推断formataac/mp3/mulaw/raw/wavmp3输出音频格式sample_rate8000/16000/24000Hz24000输出采样率api_key字符串None读环境变量鉴权密钥http_sessionaiohttp.ClientSessionNone自动创建复用 HTTP 会话temperature浮点数0.0~1.01.0控制语气的表现力与情绪丰富度top_p浮点数0.0~1.00.8控制合成语音的稳定性语言参数与自动推断language使用两位 ISO 639-1 代码models.py 中枚举了完整集合auto、de德语、en英语、es西班牙语、fr法语、hi印地语、id印尼语、it意大利语、ja日语、ko韩语、nl荷兰语、pl波兰语、pt葡萄牙语、ru俄语、sv瑞典语、th泰语、tr土耳其语、uk乌克兰语、vi越南语、zh中文。值得注意的自动推断逻辑在 tts.pyif not language: language auto if model blizzard else en即当未显式传language时blizzard模型使用auto自动检测语言而aurora模型默认落到en。如果你的输入文本是中文等非英语场景建议显式传入language避免自动检测结果不符合预期。temperature 与 top_p 的调音指导这两个参数是控制合成风格的旋钮源码 docstring 给出了清晰的调优方向temperature默认 1.0影响语音的表现力和情绪变化程度。较低的值如0.3产生更中性、一致的说话风格较高的值如1.0允许更动态的情绪范围和风格变化。top_p默认 0.8控制生成语音的稳定性。较低的值如0.3产生更稳定、可靠的语音较高的值如0.9让词语发音方式更灵活但偶尔可能出现不寻常的语调或发音模式。实际项目中客服机器人等需要稳定口播的场景可下调两者而陪伴式/角色扮演类 Agent 可适当上调 temperature 换取更生动的情绪表达。运行期动态调整 TTS 参数与只读构造参数不同插件还提供了update_options方法tts.py允许在 Agent 运行过程中动态切换模型、音色、语言、格式、采样率、temperature 与 top_ptts.update_options( modelaurora, voiceanother_voice_id, languageja, temperature0.5, top_p0.6, )该方法内部使用NotGivenOr语义——未传入的参数保持不变只更新显式给定的项配合is_given判断实现见 tts.py因此可以放心地只传需要变更的字段。该能力适合多语言场景例如根据用户当前会话语言动态切换language和voice无需重建 TTS 实例。底层实现原理合成请求的完整链路TTS.synthesize(text)返回一个ChunkedStream它继承自livekit.agents.tts.ChunkedStream抽象基类定义见 tts.py。真正发起网络请求的逻辑在ChunkedStream._run中tts.pydata { text: self._input_text, voice: self._opts.voice, language: self._opts.language, sample_rate: self._opts.sample_rate, model: self._opts.model, format: self._opts.format, temperature: self._opts.temperature, top_p: self._opts.top_p, } async with self._tts._ensure_session().post( LMNT_BASE_URL, headers{ Content-Type: application/json, X-API-Key: self._opts.api_key, }, jsondata, timeoutaiohttp.ClientTimeout(total30, sock_connectself._conn_options.timeout), ) as resp: resp.raise_for_status() ...要点提炼如下端点插件常量LMNT_BASE_URL https://api.lmnt.com/v1/ai/speech/bytes即 LMNT 的字节流语音合成接口鉴权API Key 放在X-API-Key请求头中请求体为 JSON请求体text、voice、language、sample_rate、model、format、temperature、top_p 全部随请求发送超时整体超时 30 秒建连超时复用 LiveKit Agents 传入的conn_options.timeout会话复用优先复用用户传入的http_session否则从utils.http_context.http_session()获取见_ensure_session。响应到达后output_emitter.initialize(...)会以合成请求的采样率、单声道NUM_CHANNELS 1和对应 MIME 类型初始化音频流随后resp.content.iter_chunks()分块把音频字节推给下游播放管线最后flush()收尾。音频格式与 MIME 映射format参数直接决定输出编码插件维护了一张格式到 MIME 类型的映射表tts.pyformatMIME 类型aacaudio/aacmp3audio/mpegmulawaudio/basicrawapplication/octet-streamwavaudio/wav需要注意raw为未加头的裸 PCM 数据配合sample_rate/num_channels才能正确解析默认mp3与24000Hz的组合在多数实时场景下兼顾了体积与音质。错误处理与异常语义插件将底层异常统一收口为 LiveKit Agents 标准错误类型tts.py请求超时asyncio.TimeoutError→ 抛出APITimeoutError非 2xx 响应aiohttp.ClientResponseError→ 通过create_api_error_from_http转换为对应 HTTP 错误其他异常 → 包装为APIConnectionError。这意味着上层 Agent 无需感知 aiohttp 细节可以用 LiveKit Agents 统一的错误体系做重试或降级处理例如切换备用 TTS。非流式特性说明TTS.__init__中声明了capabilitiestts.TTSCapabilities(streamingFalse)tts.py即 LMNT 属于整段合成后返回字节流的模式而非边生成边推流。框架会把整段文本交给 LMNT 一次合成再分块推给播放器。在实现上与真正的逐 token 流式 TTS 不同但这不影响在 AgentSession 中的使用方式合成延迟由 LMNT 侧处理速度决定。测试与验证仓库的 test_tts.py 将 LMNT 插件纳入了参数化的网络测试用例pytest.param( lambda: { tts: lmnt.TTS(), proxy-upstream: api.lmnt.com:443, }, idlmnt, ),该用例以默认参数实例化lmnt.TTS()即不传任何参数并通过本地代理将流量导向api.lmnt.com:443来验证插件在真实网络路径下的行为。由此可以确认默认配置下插件即可正常工作无需额外传参同时这也是排查连通性问题时定位到api.lmnt.com443 端口的重要依据。小结livekit-plugins-lmnt以极简的接入成本为 LiveKit Agents 提供了 LMNT 语音合成能力一条pip install完成安装一个环境变量完成鉴权一行lmnt.TTS()即可发声。配合update_options的动态调参能力与统一的异常体系它可以胜任多语言客服、角色扮演、有声播报等各类实时语音场景。深入阅读 tts.py 与 models.py 源码可以进一步理解每个参数对合成结果的实际影响从而为你的 Agent 调出最合适的声音。【免费下载链接】agentsA framework for building realtime voice AI agents ️项目地址: https://gitcode.com/GitHub_Trending/agen/agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考