xiaomusic 在 iOS 上配置捷径快捷指令调用 HTTP 接口控制小爱音箱播放与关机【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic在 iOS 上使用捷径快捷指令控制 xiaomusic本质上就是把「网页上可见的每一个操作」翻译成一次 HTTP 请求。只要理解了接口的请求方法与参数格式就能把播放音乐、停止播放关机、调节音量、TTS 播报等能力全部搬到 iOS 捷径里。本文以仓库中的 iOS 捷径配置讨论 为主题结合 xiaomusic 源码中的 API 路由实现给出可直接照做的捷径配置步骤、参数说明与常见问题排查方法。核心思路网页上每个功能都有对应 HTTP 接口正如 docs/issues/96.md 中所指出的只要在 web 页面上能看到的功能都有对应的 http 请求接口都可以用来配置捷径。这意味着捷径配置并不需要额外开发任何插件或服务端支持只需把页面操作换成等价的 HTTP 请求即可。从源码结构看xiaomusic 的 HTTP 服务基于 FastAPI 构建所有路由通过 register_routers 注册到 FastAPI 应用并统一挂载在 xiaomusic/api/app.py 的HttpInit中。路由按职责拆分为多组device.py设备控制、命令执行、音量、播放状态music.py音乐搜索、播放、列表、在线音乐system.py系统设置、版本、更新以及 playlist、file、plugin 等模块。因此在 iOS 上配捷径第一步就是确定你需要的功能对应的接口路径与请求方式。播放音乐捷径issue 中展示的「播放音乐」捷径对应的接口位于 xiaomusic/api/routers/music.pyPOST /playmusic按名称播放音乐请求体JSON包含did设备 ID、musicname音乐名、searchkey搜索关键词。路由实现见 playmusic 接口它先校验设备是否存在再调用xiaomusic.do_play(did, musicname, searchkey)完成播放。POST /cmd以「口令」方式执行命令请求体JSON为didcmd。路由实现见 device.py 的 cmd 接口内部会先cancel_all_tasks()取消已有任务再把命令交给do_check_cmd解析执行。在 iOS「捷径」App 中配置「播放音乐」的步骤如下新建捷径添加「获取 URL 内容」操作URL 填http://你的主机IP:端口/playmusic示例http://192.168.11.1:5678/playmusic端口为 config-example.json 中的 port 配置项方法选择POST请求体选择「JSON」填写{ did: 小爱音箱的设备ID, musicname: 歌名, searchkey: 搜索关键词 }运行捷径即可让对应设备播放音乐。提示musicname与searchkey的关系可在 xiaomusic.py 的 play 方法 中看到search_key是真正用于搜索的关键词name用于展示与匹配两者可相同。语音播放时还会根据歌曲匹配更新当前播放列表见do_play调用链 xiaomusic/xiaomusic.py#L559-L560。关机停止播放捷径issue 中的第二个示例「关机」对应 device.py 的 stop 接口POST /device/stop请求体JSON只需did。路由内部调用xiaomusic.stop(did, notts)停止播放参数notts表示不播报提示音。对应源码 xiaomusic.py 的 stop 方法 最终把停止操作转发到设备播放器。iOS 捷径配置方式与播放捷径完全一致只是 URL 与方法体不同{ did: 小爱音箱的设备ID }已知问题/cmd返回Method Not Allowedissue 评论区记录了一个典型排障案例用户 Yumega 在浏览器中打开http://192.168.11.1:5678/cmd显示{detail:Method Not Allowed}导致 iOS 捷径无效。这正是本文要重点解释的坑/cmd只接受POST方法不支持 GET。源码 device.py 的 cmd 接口 使用router.post(/cmd)声明FastAPI 对未声明的方法会返回405 Method Not Allowed。因此在浏览器地址栏直接访问/cmd必然是405因为浏览器默认发起 GET在 iOS 捷径中必须把方法明确设置为POST并在请求体中带上did与cmd两个字段否则捷径同样无效。排查捷径无效问题的检查清单方法是否正确/playmusic、/cmd、/device/stop均为 POST使用「获取 URL 内容」时务必选择 POSTURL 是否正确协议头http、IP 与端口必须与 config-example.json 的 hostname/port 配置 一致端口默认 8090示例配置使用--port等启动参数覆盖后以实际为准请求体格式必须是合法 JSON且字段名与接口要求完全一致did、musicname、searchkey、cmd设备 ID 是否真实存在接口会先执行did_exist(did)校验设备不存在时返回{ret: Did not exist}见 device.py 的 cmd 接口认证配置若 disable_httpauth 配置 为 false所有接口都会经过 dependencies.py 的 verification 认证捷径需要配置 HTTP Basic 认证的用户名与密码否则返回 401。如何找到设备 IDdid所有设备相关接口都依赖did参数。获取方式访问GET /device_list获取设备列表返回{devices: [...]}实现见 device.py 的 device_list 接口也可以在网页控制台或设置页面中查看已绑定的小米音箱设备GET /getsetting?need_device_listtrue会额外返回device_list见 system.py 的 getsetting 接口。更多可配置的捷径常用接口速查issue 中强调「网页上能看到的功能都有对应接口」下面列出与日常控制最相关、适合做成捷径的接口全部位于 xiaomusic/api/routers/功能方法与路径关键参数JSON / Query源码位置播放音乐POST/playmusicdid、musicname、searchkeymusic.py#L306执行口令POST/cmddid、cmd如「播放 xxx」「停止」device.py#L72停止播放POST/device/stopdiddevice.py#L122播放 URLGET/playurldid、url需 URL 编码device.py#L101TTS 播报GET/playttsdid、textdevice.py#L111设置音量POST/setvolumedid、volumedevice.py#L59获取音量GET/getvolumediddevice.py#L32获取播放状态GET/getplayerstatusdiddevice.py#L42当前播放GET/playingmusicdidmusic.py#L215音乐列表GET/musiclist无music.py#L236搜索音乐GET/searchmusicnamemusic.py#L31设备列表GET/device_list无device.py#L25其中「执行口令」POST /cmd是最灵活的一种cmd字段填写的正是语音指令本身如「播放周杰伦的歌」「停止」由 command_handler.py 的 do_check_cmd 走与语音完全相同的解析匹配流程因此用户自定义口令、exec#命令等见 config-example.json 中的自定义口令示例也能通过捷径触发。参考接口文档与自测FastAPI 框架自带完整的接口文档能力system.py 中提供了 /docs 与 /openapi.json 路由浏览器访问http://IP:端口/docs可打开 Swagger UI查看每个接口的参数定义、请求方法与返回结构访问http://IP:端口/openapi.json可获得完整的 OpenAPI 规范 JSON便于编写捷径前核对字段。配置捷径前先在这些页面验证一次请求能否成功可以大幅减少「捷径无效」类问题。小结iOS 捷径的本质是 HTTP 客户端xiaomusic 的每个 Web 功能背后都有对应的 FastAPI 路由xiaomusic/api/routers/。按「确认接口路径 → 核对请求方法 → 构造 JSON 请求体 → 正确填写 did」四步走即可稳定复现 issue 96 中「播放音乐」与「关机」两个示例并延伸到音量、TTS、口令等全部控制能力。若遇到捷径无效优先检查是否误用 GET 访问 POST 接口如/cmd的 405 错误并对照/docs页面核验参数格式。【免费下载链接】xiaomusic使用小爱音箱播放音乐音乐使用 yt-dlp 下载。项目地址: https://gitcode.com/GitHub_Trending/xia/xiaomusic创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考