怎样对接10W壁挂语音播报音箱以实现语音播放进度控制_解决方案

CATALOG

针对芯步10W壁挂音箱的对接，核心其实就是调用它那个开放的HTTP接口。你只需要按照签名规则拼好URL，然后往指定设备ID发送播报或停止指令，就能实现播放进度控制（比如“停止当前播放”）。下面是一套比较落地的对接方案，我尽量写得口语化一点，方便你直接拿去给开发团队参考。

一、我们到底要解决什么问题？

简单来说，就是你手里有一批（或者即将有一批）芯步的10W壁挂音箱，型号一般是 UNI-YY-YX-BG-10W。

你的系统（比如你写的某个后端服务、小程序，甚至是脚本）需要在特定的时机，让这些音箱执行“开口说话”、“闭嘴停止”、“调大音量”等操作，也就是所谓控制播放进度。

这个方案的妙处在于：音箱不需要一直连着手机APP，它直接连WiFi，你的服务器通过HTTP接口就能远程指挥它。

二、先看看这个音箱有什么“超能力”

在写代码之前，你得知道你能控制它干啥。根据官方手册，这个10W音箱支持以下“命令”：

播报文字：直接发中文过去，它就用TTS（语音合成）读出来，支持GBK编码的中文。
停止播放：这是实现“进度控制”的核心，可以让他立即闭嘴，或者清空队列。
调节音量：0-9级可调。
调节语速：0-9级可调。
调节音调：0-9级可调。
切换音色：男声/女声。
播放内置铃声：有5种提示音。

重点来了：所谓的“进度控制”，在这个场景下其实并不是“拖动进度条到第5秒”，而是“开始播放某段内容”和“在播放中途强制停止/跳过”。

三、对接前的准备工作

你需要先拿到三把“钥匙”：

AppID：你的应用ID。
AppSecret：你的应用密钥（这个要保密，千万别写在网页前端里）。
Device ID：音箱的ID。每个音箱都有唯一编号，通常在设备底部标签上，或者在芯步控制台里能看到。

这三个东西准备好了，你就能调用接口了。

四、核心接口怎么调

所有控制操作都通过一个接口地址搞定，只是参数不一样。

接口地址https://api.thingboot.com/{你的AppID}/device/control/
请求方式：POST （推荐用JSON格式）。

1. 鉴权怎么搞？

芯步的接口采用双重MD5签名机制，虽然是老派的做法，但胜在简单。它的计算规则是 md5( md5(AppSecret) + ts )。

也就是把开发者密码做一次MD5，然后拼接上时间戳，再对整个拼接后的字符串做一次MD5。

开发的时候，你只需要封装一个函数，每次请求前动态生成这个签名就行。

2. 实操：让它“说话”与“闭嘴”

假设你的设备ID是 123456789，你想让它说“你好，欢迎光临”。

这时候音箱会马上合成语音并播放出来。

关键的“进度控制”——停止播放：如果它正在巴拉巴拉说个不停，你想让它立刻闭嘴（比如来了新的紧急通知，或者用户按了取消键），可以下发停止指令：

stop参数说明：传0是停止当前正在播放的这一条；传1是清空整个播放队列。

3. 让声音更好听的一些设置

你可以在播放前先把状态调好。例如，将音量设置为7（最大9），语速设置为5（适中），并切换为男声。

小技巧：如果你想一次性既调音量又说话，把参数都塞在 order 里就行，音箱会一起执行。

五、针对10W壁挂音箱的“进度控制”实战逻辑

既然你是针对“进度控制”，那你需要的可能不仅仅是“停止”。我们结合场景来设计一下代码逻辑：

第一种场景：打断播报（高优先级插播）假设早上8点，系统正在播报“今日日程安排...”，此时来了一个火警警报。方案：系统先下发 {"stop":"1"} 清空队列，然后立即下发 {"play:gbk:16":"[alert_1]请注意，火警演练开始"}。这样能保证紧急消息0延时播出。

第二种场景：分句播报（实现类似“字幕”或“逐句跟读”）你不需要一次性把整篇课文发过去，而是把长文本拆成句子。流程：播放第一句 -> （等待服务器逻辑判断，如时间间隔或收到特定信号） -> 下发 {"stop":"0"} 掐断第一句（如果还没说完） -> 立即下发下一句。这样就实现了基于指令的“切歌”或“下一句”效果。

第三种场景：音量渐变（模拟“淡入淡出”）如果要优雅地结束一段背景音乐播报，不要直接停止。你可以分两次下发指令：第一步：下发 {"volume":"2"}（音量调低）。第二步：延时1秒后，下发 {"stop":"0"}。

六、代码示例

下面给你一段伪代码逻辑，展示在关键业务中如何调用：

import requests
import hashlib
import time

class YoyoSpeaker:
    def __init__(self, app_id, app_secret, device_id):
        self.app_id = app_id
        self.app_secret = app_secret
        self.device_id = device_id
        self.base_url = f"https://api.thingboot.com/{app_id}/device/control/"

def _gen_sign(self):
        # 生成签名
        ts = str(int(time.time()))
        md5_first = hashlib.md5(self.app_secret.encode()).hexdigest()
        sign_str = md5_first + ts
        sign = hashlib.md5(sign_str.encode()).hexdigest()
        return sign, ts

def send_command(self, order_dict):
        sign, ts = self._gen_sign()
        url = f"{self.base_url}?sign={sign}&ts={ts}"
        payload = {
            "device": self.device_id,
            "order": order_dict
        }
        # 发送POST请求
        resp = requests.post(url, json=payload)
        return resp.json()

# 1. 开始播放一段长文本（进度:开始）
    def play_text(self, text):
        return self.send_command({"play:gbk:16": text})

# 2. 停止播放（进度:跳转/停止）
    def stop(self, mode=0):
        # mode=0停止当前，mode=1全部停止
        return self.send_command({"stop": str(mode)})

# 3. 调整音量和语速（播放中调节）
    def set_volume(self, level):
        return self.send_command({"volume": str(level)})

# 实际使用场景
speaker = YoyoSpeaker("your_app_id", "your_app_secret", "123456789")

# 场景:开始播放
speaker.play_text("欢迎来到某某展厅，这里是我们的核心产品区...")

# 假设过了2秒，用户走过去了，或者按了下一首，立即停止当前的
time.sleep(2)
speaker.stop(mode=0)  # 闭嘴，准备播下一句

# 开始播新的一句
speaker.play_text("现在为您介绍下一款产品...")

七、避坑指南

关于返回码：接口返回{"code":200}只代表指令发出去了，不代表音箱播完了。如果音箱离线，命令就丢失了。如果需要精确知道音箱是否播报完成，需要开启平台的异步消息推送功能，音箱会在播放结束后回调你的服务器。
频率限制：单个设备访问限制最高1次/秒。不要狂发“暂停、播放、暂停、播放”，设备会反应不过来或者拒绝服务。
网络环境：这音箱只支持2.4G WiFi，配网时记得确认一下环境有没有5G WiFi隔离的问题。
中文字符：如果你用的是 play:gbk:16 指令，注意中文编码要转成GBK，或者确保你的库支持。如果不确定，直接用纯文本，大多数SDK会自动处理好。

这套方案用好 stop 指令和对 order 的灵活组合，你就能玩转这10W音箱的播放节奏了。