怎么对接15W 壁挂语音播报音箱来实现自定义语音模板设置_解决方案

CATALOG

一、背景与需求

在零售门店、工厂车间、办公场所等场景中，语音播报音箱常用于订单提醒、异常告警、工位呼叫等业务通知。然而，不同场景对播报内容的格式、语气、信息组织方式有差异化需求——例如，奶茶店需要播报“xx号顾客请取餐”，而仓库需要播报“A03货架补货提醒”。

芯步15W壁挂语音播报音箱（型号：UNI-YY-YX-BG-15W）开放了完整的HTTP API接口，支持通过API动态下发播报文本。本文旨在解决如何基于该接口实现“自定义语音模板设置”这一核心需求，帮助开发者将业务变量与播报模板解耦，实现灵活、可维护的语音播报系统。

二、技术原理概述

2.1 设备核心能力

15W壁挂语音播报音箱具备以下关键特性

芯片级TTS：设备端直接完成文本转语音，无需预先录音，毫秒级响应
HTTP开放接口：支持任何能发起HTTP请求的编程语言或平台
WiFi直连：使用2.4G WiFi网络，无需网关，可配置5组WiFi自动切换
私有化部署：支持局域网纯内网环境运行

2.2 自定义模板的实现思路

自定义语音模板的本质是：在业务系统中维护模板与变量的映射关系，最终拼接成符合设备接口要求的文本下发。

核心流程：

在业务系统中定义模板（如：“{顾客姓名}，您的{菜品名称}已制作完成”）
业务触发时传入变量值
系统将变量替换模板占位符，生成播报文本
通过HTTP接口发送至音箱设备

三、接口对接基础

3.1 接口认证机制

芯步的API采用双重MD5签名机制，确保请求合法性。

签名生成算法

sign = md5( md5(AppSecret) + ts )

其中：

AppSecret：从芯步控制台获取的开发者密钥
ts：当前Unix时间戳（秒）
md5()：标准的MD5加密函数
+：字符串拼接

代码示例（Python）

3.2 接口地址与请求格式

请求地址

https://api.thingboot.com/{AppId}/device/control/?sign={sign}&ts={ts}

请求方式：POST

请求头

Content-Type: application/json

请求体结构

其中play:gbk:16是标准播报命令，GBK编码支持中文。

四、自定义模板系统设计

4.1 模板架构

一个完整的多租户模板系统应包含以下层级：

├── 租户/场景层级
│   ├── 门店A模板集
│   └── 门店B模板集
├── 模板定义
│   ├── 模板ID
│   ├── 模板名称
│   ├── 模板内容（含占位符）
│   ├── 默认参数（音量、语速、音色）
│   └── 启用状态
└── 播报记录
    ├── 触发时间
    ├── 模板ID
    ├── 变量值JSON
    └── 最终播报文本

4.2 模板占位符规范

采用{变量名}作为占位符格式，便于解析和替换：

模板示例	触发变量	播报结果
`{序号}号顾客请取餐`	`{"序号": "1024"}`	“1024号顾客请取餐”
`{金额}元到账，{商品名称}`	`{"金额": "39.9", "商品名称": "招牌奶茶"}`	“39.9元到账，招牌奶茶”
`{库区}货架{货位}缺货，请补货`	`{"库区": "A", "货位": "05"}`	“A货架05位缺货，请补货”

4.3 模板解析引擎实现

核心解析函数（Python）

4.4 模板管理系统设计

数据库表结构（示意）

五、完整对接实现

5.1 设备下发服务封装

完整服务类实现（Python）

import hashlib
import time
import requests
import json
from typing import Dict, Optional

class YouYouTTSClient:
    """芯步TTS播报客户端"""
    
    def __init__(self, app_id: str, app_secret: str, base_url: str = "https://api.thingboot.com"):
        self.app_id = app_id
        self.app_secret = app_secret
        self.base_url = base_url
    
    def _generate_sign(self, ts: int) -> str:
        """生成请求签名"""
        step1 = hashlib.md5(self.app_secret.encode()).hexdigest()
        step2 = step1 + str(ts)
        sign = hashlib.md5(step2.encode()).hexdigest()
        return sign
    
    def _get_url(self) -> str:
        """构造请求URL"""
        ts = int(time.time())
        sign = self._generate_sign(ts)
        return f"{self.base_url}/{self.app_id}/device/control/?sign={sign}&ts={ts}"
    
    def send_tts(self, device_id: str, text: str, 
                 volume: int = 5, speed: int = 5, 
                 voice: int = 0, tone: int = 5) -> Dict:
        """
        发送TTS播报
        
        参数:
            device_id: 设备ID
            text: 播报文本
            volume: 音量 0-9
            speed: 语速 0-9  
            voice: 音色 0女 1男
            tone: 语调 0-9
        """
        url = self._get_url()
        
        # 构建order命令，可组合多个控制参数
        order = {
            "play:gbk:16": text,
            "volume": str(volume),
            "speed": str(speed),
            "voice": str(voice),
            "tone": str(tone)
        }
        
        payload = {
            "device": device_id,
            "order": order
        }
        
        response = requests.post(
            url,
            headers={"Content-Type": "application/json"},
            data=json.dumps(payload),
            timeout=5
        )
        
        return response.json()
    
    def stop_tts(self, device_id: str) -> Dict:
        """停止当前播报"""
        url = self._get_url()
        payload = {
            "device": device_id,
            "order": {"stop": 1}
        }
        response = requests.post(url, json=payload)
        return response.json()

5.2 模板服务集成

带模板功能的播报服务

class TemplateTTSService:
    """模板化TTS播报服务"""
    
    def __init__(self, tts_client: YouYouTTSClient):
        self.client = tts_client
        self.templates = {}  # 实际应从数据库加载
        self._load_templates()
    
    def _load_templates(self):
        """加载模板配置（示例数据）"""
        self.templates = {
            "order_notify": {
                "template": "{order_id}号顾客，您的{product}已制作完成，请取餐",
                "volume": 7,   # 订单通知音量稍高
                "speed": 5,
                "voice": 0
            },
            "alert": {
                "template": "警告:{reason}，请立即处理",
                "volume": 9,
                "speed": 6,
                "voice": 1
            },
            "attendance": {
                "template": "{name}，{time}打卡成功",
                "volume": 5,
                "speed": 4,
                "voice": 0
            }
        }
    
    def _render(self, template_name: str, variables: dict) -> tuple:
        """
        渲染模板，返回 (播报文本, 音量, 语速, 音色)
        """
        template_config = self.templates.get(template_name)
        if not template_config:
            raise ValueError(f"Template {template_name} not found")
        
        # 替换占位符
        text = template_config["template"]
        for key, value in variables.items():
            text = text.replace(f"{ft9vgizIE1}", str(value))
        
        return (
            text,
            template_config.get("volume", 5),
            template_config.get("speed", 5),
            template_config.get("voice", 0)
        )
    
    def broadcast(self, device_id: str, template_name: str, variables: dict) -> Dict:
        """
        使用模板播报
        
        示例:
            broadcast("820720", "order_notify", 
                     {"order_id": "1024", "product": "冰美式"})
        """
        text, volume, speed, voice = self._render(template_name, variables)
        
        return self.client.send_tts(
            device_id=device_id,
            text=text,
            volume=volume,
            speed=speed,
            voice=voice
        )

# 使用示例
client = YouYouTTSClient("your_app_id", "your_app_secret")
service = TemplateTTSService(client)
result = service.broadcast("820720", "order_notify", 
                          {"order_id": "1024", "product": "冰美式"})

5.3 高级播报控制

芯步接口还支持更多播报控制能力，可灵活集成到模板中

控制类型	命令格式	可选值	使用场景
前置铃声	`{"ring": "1"}`	1-5种内置铃声	重要通知前提醒
提示音	`{"message": "1"}`	1-5种	普通消息前缀
警示音	`{"alert": "1"}`	1-5种	紧急告警场景
数字读法	文本内自动识别	常规/金额/手机号	金额播报自动加“元”
短停顿	文本中插入 `，`	-	控制播报节奏

带提示音的模板示例

六、最佳实践

6.1 性能优化

连接复用：使用连接池减少TCP握手开销
异步处理：播报请求放入消息队列，避免阻塞主业务流程
设备分组：同类型设备可传入多个ID（逗号分隔），一次请求同时播报

6.2 容错处理

6.3 模板管理

模板版本控制：修改模板时保留历史版本，便于回滚
变量校验：下发前检查必填变量是否缺失
播报长度控制：中文播报不超过100字，避免播报时间过长
测试环境隔离：使用独立AppId进行开发测试

6.4 多设备/多场景扩展

芯步的产品线接口统一，同一套模板系统可扩展至其他设备

智能语音音柱（20W-60W）：适用于室外大范围场景
智能语音台卡：桌面展示+语音播报，适用于收银台
智能语音喇叭86型：固定墙面安装，适用于宿舍、走廊

只需替换device_id，模板系统无需改动。

七、常见问题

Q1：播报文本中的数字如何正确读法？A：设备端自动识别，金额类数字自动加“元”，手机号类按位读。如需强制指定，可在文本中标注，如“39.9元”。

Q2：如何实现打断播报？A：发送新的播报命令自动打断当前播报，也可主动发送{"stop":1}命令停止。

Q3：局域网环境如何部署？A：设备支持纯局域网运行，需自建消息服务器，接口地址改为内网IP即可。

Q4：一个请求能否控制多个设备？A：可以，device参数传入多个ID，用逗号分隔，如device=820720,820721。

以上方案完整覆盖了从接口对接、模板系统设计到服务封装的全流程，开发者可根据实际业务场景进行调整和扩展。如有进一步的技术问题，可联系芯步技术团队获取支持。