怎么对接智能 30W 语音音柱以实现多音数字读法设置_解决方案

CATALOG

多音字和数字读法的精确控制，是语音播报场景中的常见需求。芯步的音柱通过特定的 TTS 标签语法，可以在播报文本中直接嵌入读法指令，无需额外配置。以下是具体的对接方案。

一、对接核心逻辑与准备

芯步的智能语音音柱（包括 30W 型号，其逻辑与 10W/20W 一致）本质上是一个网络音频终端。它通过 WiFi 连接网络，并开放标准的 HTTP API 接口。

要实现自定义数字读法，核心逻辑是：你的业务系统（服务器）通过 HTTP POST 请求，向音柱的设备 ID 发送一个包含特定语法标签的 JSON 命令。

在对接开发前，你需准备以下三个参数（在芯步控制台获取）：

AppID：应用唯一标识。
AppSecret：接口加密密钥（用于生成签名）。
Device ID：目标 30W 语音音柱的设备编号。

二、接口鉴权与连接方案

芯步的接口采用 Sign (签名) 机制进行安全验证，这是对接的第一步，也是确保设备不被非法控制的关键。

请求地址http(s)://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

签名生成算法（以通用逻辑为例）：sign = md5( md5(AppSecret) + ts )

ts：当前 Unix 时间戳（秒）。
计算步骤：先将 AppSecret 进行 MD5 哈希，再将结果字符串与时间戳拼接，最后对整个拼接字符串再次进行 MD5 哈希。

请求体结构

注： order 对象里放你要执行的命令。

三、 “多音数字读法”设置详解（TTS 语法规则）

这是该解决方案的核心。你无需在后台预设词典，而是直接在播报文本中注入控制符。芯步的音柱引擎支持 SSML（语音合成标记语言）风格的嵌入式标签。

针对 30W 音柱，通过 play:gbk:16 命令配合特定文本格式，可以实现以下读法控制：

1. 数字读法设置（数值 vs 序列号）

这是最常见的需求，例如金额和电话号码的读法冲突。

场景 A：数值读法（如金额 123.5）
- 需求：播报“一百二十三点五”。
- 代码写法
  { "device": "YZ30W001", "order": { "play:gbk:16": "您的余额为[+]:123.5元。" } }
- 解析：引擎默认会将数字串按位读出（如一二三），但遇到金额上下文或特定标记，会自动转换为数值读法。
场景 B：序列号/手机号读法（如 13912345678）
- 需求：播报“一三九一二三四五六七八”（逐个读），而不是“一百三十九亿...”。
- 代码写法
  { "device": "YZ30W001", "order": { "play:gbk:16": "来电号码[=]:13912345678。" } }
- 解析：使用 [=]: 前缀或在特定上下文中，强制设备进行单数字分离播报。

2. 多音字/英文读法设置

需求： “这个参数是 1:1 的”，其中“参”字读“can”而非“cen”。
代码写法
{ "order": { "play:gbk:16": "请注意，这个[[cān]]数很重要。" } }
解析：使用双中括号 [[文字]] 包裹多音字，并在其后紧接拼音，可以强制 TTS 引擎选择特定读音。

3. 音量与语速协同调节

为了达到最佳听觉效果，在设置播报内容的同时，调节设备状态，避免数字播报过快导致听不清。

推荐组合命令示例

(注：上述示例同时设置了音量 8（较高）、语速 4（适中），并混合了数值和单数字的读法)。

四、实操对接示例（Java 语言）

以下是一个使用 Java 调用接口，向音柱下发复杂语音指令的示例，核心是多音字和数字读法的控制。

// 核心逻辑:构建包含 TTS 控制符的 JSON 字符串
// 参考来源:芯步开放接口文档及 TTS 语法说明

public class VoiceBroadcastDemo {
    public static void main(String[] args) {
        // 1. 准备参数（替换为实际值）
        String AppID = "YOUR_APP_ID";
        String AppSecret = "YOUR_APP_SECRET";
        String deviceId = "YOUR_DEVICE_ID_30W";
        long ts = System.currentTimeMillis() / 1000;
        
        // 2. 计算签名 sign = md5(md5(AppSecret) + ts)
        String md5Secret = DigestUtils.md5Hex(AppSecret);
        String signRaw = md5Secret + ts;
        String sign = DigestUtils.md5Hex(signRaw);
        
        // 3. 构建 URL
        String url = String.format("https://api.thingboot.com/%s/device/control/?sign=%s&ts=%d", AppID, sign, ts);
        
        // 4. 构建 Order 命令（重点:多音字与数字读法设置）
        // 需求场景:播报"请重新校准参数[多音字]，重量为 12.5kg[数值读法]，SN码是 987654[单数字读法]"
        String text = "请重新校准[[cān]]数，重量为[+]:12.5公斤，序列号[=]:987654。";
        
        // 构造 order JSON 对象
        // 注意:如果是 30W 音柱，命令字通常为 "play:gbk:16"
        String orderJson = String.format("{\"play:gbk:16\":\"%s\", \"volume\":\"7\"}", text);
        
        // 构建完整请求体
        String requestBody = String.format("{\"device\":\"%s\",\"order\":%s}", deviceId, orderJson);
        
        // 5. 发送 HTTP POST 请求 (此处使用 Unirest 示例)
        HttpResponse<String> response = Unirest.post(url)
            .header("Content-Type", "application/json")
            .body(requestBody)
            .asString();
            
        System.out.println("Response: " + response.getBody());
    }
}

五、排查和需要注意的点

编码问题：命令中的 play:gbk:16 中的 gbk 代表文本编码。如果你的播报内容包含生僻字或特殊符号，请确保你的代码文件编码与系统环境支持 UTF-8 转 GBK 的转换，否则可能出现乱码。
数字读法的触发条件
- 默认情况下，纯数字字符串倾向于单字节读法（如“1,2,3”）。
- 使用 +: 前缀可以强制切换数值读法，这在播报金额和重量时尤其重要。
- 使用 =: 前缀可以强制序列号读法。
30W 音柱的硬件差异：虽然 API 逻辑通用，但 30W 音柱通常用于室外或大范围场景，对网络延迟较为敏感。在发送指令后增加一个 100-200ms 的重试机制或确认机制，确保网络波动时指令送达。

通过上述方案，你可以灵活地利用芯步的 API 实现复杂的语音播报逻辑，完全掌控“123”究竟读作“一百二十三”还是“一二三”。