怎么二次开发30W 云 TTS 语音音柱来实现云平台语音推送_解决方案

CATALOG

芯步30W云TTS语音音柱的核心优势在于“文本即播”——你只需向开放HTTP接口推送文本，设备端即可完成语音合成，无需预录音或复杂配置。以下方案涵盖接口规范、签名算法、多语言代码示例及混合设计，帮助你在业务系统中快速集成云语音推送能力。

1. 总览：二次开发的核心逻辑

芯步的智能硬件（包括30W音柱）本质上是一个接收HTTP指令的终端。二次开发的逻辑非常简单：你的业务系统 -> 触发事件 -> 调用API -> 音柱播放。

不需要复杂的驱动或协议栈，只要你的开发环境能够支持标准的 HTTP POST 请求和 MD5 加密即可。

重要参数准备：在芯步控制台，你需要获取以下三个关键信息：

AppID：应用标识。
AppSecret：应用密钥（用于加密，绝不暴露在前端）。
Device ID：30W语音音柱的设备编号。

2. 鉴权与接口详解

为了防止接口被恶意调用，采用了动态签名验证方式。

2.1 签名算法 (Sign)

请求URL中必须携带 sign 和 ts 参数。算法规则为：sign = md5( md5(AppSecret) + ts )

通俗解释：

把你拿到的 AppSecret 进行一次MD5加密。
把当前的时间戳（秒级，如 1715328000）拼接到第一步的结果后面。
把拼接后的整个字符串再做一次MD5加密。

2.2 请求地址

POSThttp(s)://api.thingboot.com/{AppID}/device/control/?sign={sign}&ts={ts}

2.3 必填Header

Content-Type: application/json

2.4 关键命令结构

核心指令在 order 字段中

功能	Order JSON	说明
语音播报	`{"play:gbk:16":"你要说的话"}`	这是核心功能。`gbk`表示编码，`16`是默认参数，直接填写即可。
调节音量	`{"volume":"5"}`	范围 0~9，数值越大声音越大。
切换音色	`{"voice":"0"}`	`0`=女声，`1`=男声。
调节语速	`{"speed":"5"}`	范围 0~9。

3. 代码实战：如何“喂”给音柱文本

以下演示如何在三种最常见的后端环境下，通过代码向30W音柱推送语音。

3.1 Python 3 (Flask/Django/脚本)

适合数据分析、自动化脚本、Web后端集成。

import requests
import hashlib
import time

# 配置信息 (从控制台获取)
APP_ID = "Your_App_ID"
APP_SECRET = "Your_App_Secret"
DEVICE_ID = "Your_Device_30W_ID" # 30W音柱的设备号
API_URL = f"https://api.thingboot.com/{APP_ID}/device/control/"

def send_voice_to_column(text_content):
    # 1. 生成签名
    ts = str(int(time.time()))
    md5_app_secret = hashlib.md5(APP_SECRET.encode()).hexdigest()
    sign_str = md5_app_secret + ts
    sign = hashlib.md5(sign_str.encode()).hexdigest()
    
    # 2. 构建请求参数
    params = {
        "sign": sign,
        "ts": ts
    }
    
    # 3. 构建指令 (核心:让音柱说话)
    payload = {
        "device": DEVICE_ID,
        "order": {
            "play:gbk:16": text_content  # 这里就是你要播报的文本
        }
    }
    
    # 4. 发起请求
    headers = {"Content-Type": "application/json"}
    try:
        response = requests.post(API_URL, params=params, json=payload, headers=headers, timeout=5)
        if response.status_code == 200:
            print(f"推送成功: {text_content}")
        else:
            print(f"推送失败: {response.text}")
    except Exception as e:
        print(f"网络错误: {e}")

# 实际调用示例
if __name__ == "__main__":
    send_voice_to_column("工单号5648，请尽快处理异常。")

3.2 Node.js (Express/Serverless)

适合高并发、事件驱动的JavaScript/TypeScript环境。

const crypto = require('crypto');
const axios = require('axios'); // 确保安装了axios

const APP_ID = "Your_App_ID";
const APP_SECRET = "Your_App_Secret";
const DEVICE_ID = "Your_Device_30W_ID";

async function sendVoice(text) {
    // 1. 签名计算
    const ts = Math.floor(Date.now() / 1000).toString();
    const md5Secret = crypto.createHash('md5').update(APP_SECRET).digest('hex');
    const signRaw = md5Secret + ts;
    const sign = crypto.createHash('md5').update(signRaw).digest('hex');

// 2. 请求配置
    const url = `https://api.thingboot.com/${APP_ID}/device/control/`;
    
    const payload = {
        device: DEVICE_ID,
        order: {
            "play:gbk:16": text
        }
    };

try {
        const response = await axios.post(url, payload, {
            params: { sign, ts },
            headers: { 'Content-Type': 'application/json' }
        });
        console.log(`[TTS] 推送成功: ${text}`);
    } catch (error) {
        console.error('[TTS] 推送失败:', error.response?.data || error.message);
    }
}

// 调用示例
sendVoice("仓库三号门即将开启，请注意安全。");

3.3 Java (Spring Boot)

适合企业级后端系统。

import org.springframework.http.*;
import org.springframework.web.client.RestTemplate;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class TtsService {
    private static final String APP_ID = "Your_App_ID";
    private static final String APP_SECRET = "Your_App_Secret";
    private static final String DEVICE_ID = "Your_Device_30W_ID";

public void playVoice(String text) throws NoSuchAlgorithmException {
        // 1. 生成签名
        long tsLong = System.currentTimeMillis() / 1000;
        String ts = String.valueOf(tsLong);
        
        String md5Secret = md5(APP_SECRET);
        String signRaw = md5Secret + ts;
        String sign = md5(signRaw);
        
        // 2. 构建URL和Body
        String url = "https://api.thingboot.com/" + APP_ID + "/device/control/?sign=" + sign + "&ts=" + ts;
        
        RestTemplate restTemplate = new RestTemplate();
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        // 构建JSON: {"device":"xxx", "order":{"play:gbk:16":"文本"}}
        String jsonBody = String.format(
            "{\"device\":\"%s\", \"order\":{\"play:gbk:16\":\"%s\"}}", 
            DEVICE_ID, text
        );
        
        HttpEntity<String> entity = new HttpEntity<>(jsonBody, headers);
        ResponseEntity<String> response = restTemplate.exchange(url, HttpMethod.POST, entity, String.class);
        
        System.out.println("推送结果: " + response.getBody());
    }
    
    private String md5(String input) throws NoSuchAlgorithmException {
        MessageDigest md = MessageDigest.getInstance("MD5");
        byte[] digest = md.digest(input.getBytes());
        StringBuilder sb = new StringBuilder();
        for (byte b : digest) sb.append(String.format("x", b));
        return sb.toString();
    }
}

4. 高级应用与场景优化

30W音柱通常用于工业/商业环境（如车间、停车场），采用以下架构以提升健壮性。

4.1 结合“云语音合成”提升声音质量

设备自带TTS是芯片级合成（速度快），但如果你需要更拟人的情感或特定明星声音，可以将“云TTS”和“推送”结合：

调用百度/阿里/腾讯的云端TTS接口，将文本合成为高质量的 MP3 文件，上传到你的OSS获取URL。
*注：标准音柱主要支持文本流。如果需要播放MP3文件，需确认你的30W型号是否支持 play 远程文件指令（具体可查看具体的产品手册）。

4.2 处理长文本：分段机制

接口通常有文本长度限制（如200字）。如果推送一大段文章：

策略：在代码中利用 substring 或正则切分文本（按句号分割）。
注意：虽然可以连续调用10次API，但每次调用中间 sleep(0.5秒)，避免音柱“反应不过来”导致丢字。

4.3 失败重试机制

网络是不可靠的。在你的二次开发代码中，请一定要加入 “重试”逻辑。

5. 常见问题排查

返回签名错误：检查时间戳 ts 是否是秒级（10位数），而不是毫秒级（13位数）。检查AppSecret在MD5前后是否有空格。
设备不在线：30W音柱支持WiFi，需确保设备通电且连接了2.4G WiFi。可以通过控制台查看设备状态。
播报乱码：确保代码文件的编码格式为 UTF-8，且 play:gbk:16 中的 gbk 参数可以尝试改为 utf8（视具体固件版本而定，一般默认支持中文）。

通过以上方案，你应该能快速完成30W云TTS音柱的二次开发，将其无缝对接到你的ERP、CRM或自定义工单系统中。