活动现场语音提示：怎样将20W 远程控制 TTS 语音壁挂音箱集成到软件项目中_解决方案

CATALOG

针对20W远程控制TTS语音壁挂音箱（型号：UNI-YY-YX-BG-PRO-20W）的集成，解决方案围绕芯步的核心优势——芯片级TTS（设备端合成）与全开放HTTP接口展开。

以下是详细集成指南：

1. 核心集成架构

将设备集成到软件项目中的本质，是通过HTTP协议调用云端API。整个过程无需音频文件上传，软件项目只需向芯步平台发送待播报的文本字符串，平台会将指令推送给设备，设备端芯片即时完成“文字->语音”的合成并播放。

支持环境：任何能发起HTTP请求的环境（公网/局域网均可）。
支持语言：全栈兼容（Java, Python, PHP, JS, C#, Shell等）。

2. 详细对接步骤

第一步：设备上电与配网

设备通电后，会发出等待配网的热点信号。使用“芯步”App配置WiFi（仅支持2.4GHz）。

第二步：获取关键凭证

在控制台获取以下信息

AppID：应用唯一标识。
AppSecret：用于计算签名（严禁放到前端代码中）。
设备ID：控制台分配的或设备自身的唯一标识。

第三步：计算动态签名（重要）

为了防止接口被恶意调用，接口使用动态签名机制，算法如下

MD5_Secret = md5(AppSecret) // 将AppSecret进行一次MD5加密
SignString = MD5_Secret + ts // 拼接上当前Unix时间戳（秒）
Sign = md5(SignString) // 对拼接后的字符串再次进行MD5加密
最终URL携带参数：?sign={Sign}&ts={ts}

第四步：发起播报请求

使用标准HTTP POST请求调用接口。

请求地址https://api.thingboot.com/{AppId}/device/control/
HeaderContent-Type: application/x-www-form-urlencoded
Body参数
- device：你的设备ID
- order：JSON字符串，如 {"play:gbk:16":"你好，欢迎光临"}

3. 核心代码示例

以下是以Python和Java为例的后端服务代码，演示如何将文本推送给音箱。

第一种场景：Python后端集成 (Flask示例)

假设你的后端收到了一个“订单支付成功”的事件。

第二种场景：Java后端集成 (Spring Boot)

import com.konghq.unirest.HttpResponse;
import com.konghq.unirest.Unirest;
import org.apache.commons.codec.digest.DigestUtils;

public class VoiceService {
    public void sendVoiceAlert(String text) {
        String AppID = "YOUR_APP_ID";
        String AppSecret = "YOUR_APP_SECRET";
        String deviceId = "YOUR_DEVICE_ID";
        
        // 1. 生成签名
        String ts = String.valueOf(System.currentTimeMillis() / 1000L);
        String md5Secret = DigestUtils.md5Hex(AppSecret);
        String sign = DigestUtils.md5Hex(md5Secret + ts);
        
        // 2. 构造指令
        String url = "https://api.thingboot.com/" + AppID + "/device/control/?sign=" + sign + "&ts=" + ts;
        String orderJson = "{\"play:gbk:16\":\"" + text + "\"}"; // 注意转义
        
        // 3. 发起请求 (使用Unirest或HttpClient)
        HttpResponse<String> response = Unirest.post(url)
            .field("device", deviceId)
            .field("order", orderJson)
            .asString();
            
        System.out.println("HTTP Status: " + response.getStatus());
    }
}

4. 进阶功能与命令参考

为了提升活动现场的体验，单纯播报文字是不够的，可以结合以下参数

功能模块	命令示例 (order Json)	适用场景
音量调节	`{"volume":"7"}`	现场嘈杂时临时调高音量，安静时段降低音量 (0-9级)。
音色切换	`{"voice":"1"}`	男声(`1`)宣布颁奖名单显庄重，女声(`0`)做温馨指引显亲切。
预置音效	`{"ring":"3"}`	紧急事项前播放急促铃声(`alert`)，普通通知前播放提示音(`message`)。
精准播报	`{"play:gbk:16":"[n1]13800138000"}`	现场抽奖读取手机号时，使用`[n1]`确保数字按号码读法而非数值。
强制停止	`{"stop":"1"}`	时间紧迫需打断当前长文本播报，立即播放下一流程指令。

5. 活动场景集成架构

在软件项目架构中，将音箱控制逻辑封装为独立的微服务，以便业务系统调用。

触发器：现场工作人员在PAD端点击“开始抽奖”，或传感器检测到人流量增加。
业务后端：业务系统接收到触发信号，调用语音微服务。
语音微服务：该服务负责管理AppSecret和签名逻辑，向芯步API发起指令。
现场效果：20W壁挂音箱接收指令，现场发出“抽奖环节即将开始”的提示音。

6. 故障排查和需要注意的点

网络诊断：设备Web后台支持配置5组WiFi，会自动切换最强信号源，确保现场网络覆盖。
局域网模式：若活动现场无外网，可将软件项目部署在内网服务器，设备支持纯局域网IP推送。
字符集：中文文本需确保UTF-8编码，特殊字符做URL Encode处理。
超时重试：网络波动可能导致请求失败，在代码中加入重试机制（最多3次）。