xiaomusic 小爱音箱 TTS 语音播报ttsCommand 型号兼容表与源码实现原理【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic本文围绕 xiaomusic 项目维护的「已知 ttsCommand」兼容性清单展开系统梳理小爱音箱各型号的硬件代号hardware与 TTS 命令取值并结合仓库源码xiaomusic/const.py、xiaomusic/device_player.py讲解 ttsCommand 在语音播报链路中的实际调用方式、回退逻辑与新机型的接入方法。读完本文你将能判断自己的小爱音箱是否需要 ttsCommand、它如何被使用以及遇到「不能语音转文字播放」问题时该怎样排查与反馈。一、为什么小爱音箱需要 ttsCommandxiaomusic 通过小爱音箱播放音乐同时也依赖小爱音箱的「语音播报TTS」能力与用户交互例如回复「本地不存在歌曲xxx」「已经设置为单曲循环」等提示语。不同硬件批次的小爱音箱其内部语音合成接口的命令格式并不一致一部分设备可以直接调用小米云的 Mina 服务完成文字转语音另一部分设备则必须通过 miIO 底层命令、以「命令前缀 文本」的形式触发播报。这里的ttsCommand就是后者所需的命令前缀。它通常形如5-1、7-3、3-1、5-3由「数字-数字」组成。从源码调用方式可以推断该前缀被拼接成完整的 miIO 指令字符串发给设备详见下文第三节因此型号选错或缺失该值时音箱将无法正确执行语音播报。二、已知 ttsCommand 型号兼容表以下清单整理自 docs/issues/365.md「已知 ttsCommand」一节包含型号名称、硬件代号与对应 ttsCommand音箱型号硬件代号hardwarettsCommand小爱音箱 ProLX065-1小爱音箱 miniLX015-1小爱音箱 Play2019 款LX055-1小爱音箱 万能遥控版LX5A5-1小米 AI 音箱S125-1小米 AI 音箱第二代L15A7-3小爱智能家庭屏 10X10A7-3Xiaomi Sound ProL17A7-3小爱音箱L06A5-1小爱音箱 PlayL05B5-3小米小爱音箱 Play 增强版L05C5-3Xiaomi 智能家庭屏 6X6A7-3Redmi 小爱触屏音箱 Pro 8 英寸X08E7-3小爱音箱 ArtL09A3-1小爱触屏音箱LX045-12.1 源码内置的完整映射表原 Issue 的评论hanxi说明「可以不用手动配置了写到代码里了」。经核对仓库源码 xiaomusic/const.pyTTS_COMMAND字典确实已将这些型号并补充了 Issue 清单之外的型号内置到项目中# 有 tts command 的设备型号 TTS_COMMAND { OH2: 5-3, OH2P: 7-3, LX06: 5-1, S12: 5-1, L15A: 7-3, LX5A: 5-1, LX01: 5-1, LX05: 5-1, X10A: 7-3, L17A: 7-3, ASX4B: 5-3, L06A: 5-1, L05B: 5-3, L05C: 5-3, X6A: 7-3, X08E: 7-3, L09A: 3-1, LX04: 5-1, }对比可见源码表比 Issue 文档多收录了OH2、OH2P、ASX4B三个硬件代号说明该表仍在持续补充。因此实际运行时以 const.py 中TTS_COMMAND为准文档表格可作为历史兼容性参考。2.2 如何查看自己音箱的 hardware 代号hardware硬件代号是判断是否命中TTS_COMMAND的关键字段。从源码看它来自设备档案信息在 xiaomusic/auth.py 中程序遍历设备档案数据读取其中的hardware字段并写入Device对象Device模型在 xiaomusic/config.py 中定义包含did、device_id、hardware、name、play_type等字段。因此你可以通过以下方式获取自己音箱的硬件代号查看 xiaomusic 启动时的设备发现日志通常会打印各设备的did、device_id、hardware、name对照上表与源码TTS_COMMAND的键key若你的硬件代号不在其中则说明该型号尚未收录。三、ttsCommand 在源码中的调用链路3.1 入口do_tts 一路到 text_to_speechTTS 播报的入口是 xiaomusic/xiaomusic.py 的do_tts它会将请求转发到对应设备的播放器async def do_tts(self, did, value): return await self.device_manager.devices[did].do_tts(value)最终核心实现在 xiaomusic/device_player.py 的text_to_speech方法中。该方法的完整分支逻辑如下async def text_to_speech(self, value): 文字转语音 try: # 检查设置中是否启用了语音TTS。如果是关闭直接退出避免后续走到小米TTS导致token失效 if self.config.edge_tts_voice disable: return # 检查是否配置了 edge-tts 语音角色 elif self.config.edge_tts_voice: await self._text_to_speech_edge_tts(value) else: # 使用原有的 TTS 逻辑 # 有 tts command 优先使用 tts command 说话 if self.hardware in TTS_COMMAND: tts_cmd TTS_COMMAND[self.hardware] self.log.info(Call MiIOService tts.) value value.replace( , ,) # 不能有空格 await miio_command( self.auth_manager.miio_service, self.did, f{tts_cmd} {value}, ) else: self.log.debug(Call MiNAService tts.) await self.auth_manager.mina_service.text_to_speech( self.device_id, value ) except Exception as e: self.log.exception(fExecption {e})3.2 ttsCommand 的实际执行细节优先级最高的开关当配置项edge_tts_voice为disable时直接返回不使用小米 TTS避免 token 失效。edge-tts 优先只要配置了edge_tts_voice默认值为zh-CN-XiaoyiNeural见 xiaomusic/config.py就会走_text_to_speech_edge_tts的本地合成路径此时不会用到 ttsCommand。命中 TTS_COMMAND 时走 miIO 通道若设备硬件代号在TTS_COMMAND中则通过miio_command来自miservice库见 xiaomusic/device_player.py发送f{tts_cmd} {value}指令。空格处理发送前会将文本中的空格替换为逗号value value.replace( , ,)源码注释明确「不能有空格」——这是 miIO 命令格式的硬性约束也是排查播报异常时值得留意的点。未收录型号的回退硬件代号不在TTS_COMMAND中的设备会回退到mina_service.text_to_speech(device_id, value)的 Mina 云服务通道。3.3 对外 HTTP 接口语音播报能力同时暴露为 HTTP 接口位于 xiaomusic/api/routers/device.pyrouter.get(/playtts) async def playtts(did: str, text: str): 播放 TTS if not xiaomusic.did_exist(did): return {ret: Did not exist} log.info(ftts {did} {text}) await xiaomusic.do_tts(diddid, valuetext) return {ret: OK}调用GET /api/playtts?did设备didtext播报文本即可触发一次 TTS 播报方便集成方或网页前端直接验证 ttsCommand 是否生效。四、新机型接入如何贡献你的 ttsCommand原 Issue 末尾注明「如果你是其他型号的小爱音箱且不能语音转文字播放欢迎分享你的型号的 ttsCommand。」也就是说TTS_COMMAND表是一个开放共建的兼容清单接入流程如下确认自己的音箱硬件代号hardware不在TTS_COMMAND中且未配置edge_tts_voice时无法正常播报通过抓取 miIO 请求或其他调试手段找出该机型可用的命令前缀如5-1按硬件代号: ttsCommand的格式补充到TTS_COMMAND映射并同步更新本文对应的兼容清单文档提交给项目维护者合入。由于代码中已通过「空格替换为逗号」规避了文本空格的坑新增机型时只需关注命令前缀本身是否准确无需修改其他逻辑。五、与 edge-tts 的关系及适用前提需要注意ttsCommand 只是 xiaomusic 三条 TTS 路径中的一条且只在「未配置edge_tts_voice」时生效edge_tts_voice disable完全禁用语音播报edge_tts_voice配置为具体角色默认zh-CN-XiaoyiNeural走 edge-tts 本地合成播放不依赖型号edge_tts_voice为空走小米原生 TTS此时TTS_COMMAND表决定设备走 miIO 通道还是 Mina 回退通道。因此如果你的设备不在兼容表中又不想折腾 ttsCommand配置XIAOMUSIC_EDGE_TTS_VOICE启用 edge-tts 是绕过该问题的最直接方式而兼容表的存在则为希望使用小米原生语音能力的用户提供了开箱即用的覆盖范围。六、小结ttsCommand是 xiaomusic 为小爱音箱提供的 miIO 语音播报命令前缀常见取值为5-1、7-3、5-3、3-1与设备硬件代号一一对应。兼容清单已内置到 xiaomusic/const.py 的TTS_COMMAND字典涵盖 18 个硬件代号无需手动配置。源码在 xiaomusic/device_player.py 中按「edge-tts 开关 → edge-tts 角色 → TTS_COMMAND 命中 → Mina 回退」的顺序决策发送前会做空格转逗号处理。未收录型号可参照 docs/issues/365.md 的约定分享自己的 ttsCommand 以扩充兼容表。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考