JoyInside 接入手册

主题

第 5 章 设备端适配 ​

跑通第 3 章后，你手里有了一台能对话的设备。本章解决两件事：① 我的硬件能不能接、要配什么声学算法、选哪种交互模式；② 设备端音频怎么处理——采集、前处理、切包、上行。

读完你能：选定交互模式与声学算法、确定芯片型号、把麦克风收到的声音处理成符合协议要求、能被云端 ASR 正确识别的上行音频流。

5.1 硬件能力准入基线 ​

设备要与 JoyInside 云端稳定连接并实时上传语音，需具备以下底层能力：

能力要求
网络接入支持 Wi-Fi 或 4G
全双工长连接基于 WebSocket 协议（暂不支持 webrtc/mqtt）
安全加密HTTPS + HTTP 安全证书，设备端实现证书上传与验证
音频采集麦克风 + 扬声器，16k 采样率 / 16 位深 / 单声道
音频播放能解码 PCM/Opus/mp3 并播放

⚠ 暂不支持 webrtc/mqtt，语音对话必须走 WebSocket 长连接。这是 JoyInside 接入的唯一入口。

5.2 三种交互模式选型（声学要求对照） ​

根据产品形态选择交互模式，不同模式对设备端声学算法的要求不同。三种模式与设备端声学算法的对应关系如下图：

模式一：全双工免唤醒（推荐，体验最佳） ​

交互方式：设备在"播放云端语音"的同时持续"收听用户指令"，支持用户随时打断（Barge-in）。一次唤醒或触发后，无需反复呼叫唤醒词，Agent 可结合上下文多轮深度对话。

设备端必须具备的声学能力：

算法要求作用
AEC（声学回声消除）必选，硬件级或算法级精准过滤设备自身扬声器播放的声音，防止云端听到回音
ANS（背景降噪）必选抑制平稳噪声与非平稳突发噪声
AGC（自动增益）必选自动调节拾音音量，确保远场/近场信噪比达标
打断处理必选处理云端下发的 CALL_AGENT_INTERRUPTED 事件，停止当前播放，无缝衔接下一轮

适合：需要自然拟人交互的场景（陪伴玩具、音箱）。技术门槛最高，但体验最佳。

模式二：按键对讲机 ​

交互方式：类似"对讲机"的强控交互。用户按住实体或虚拟按键时设备开始收音，松开按键则结束收录，随后等待云端处理并播放回复。

设备端必须具备的声学能力：

算法要求作用
ANS（背景降噪）必选抑制背景环境噪音
AGC（自动增益）必选自动调节收音音量，确保声音清晰平稳
按键状态联动必选按键"按下/松开"状态精准转化为音频流上传的"开始/截断"信号，与云端时序同步

适合：强隐私场景，或环境噪声复杂的工业/商业设备。技术门槛最低。

模式三：半双工 VAD ​

交互方式：经典的"一问一答"轮流交谈。设备播放云端语音时麦克风关闭或忽略；播放完全结束，或通过特定唤醒词激活后，才开启短暂收音窗口听取用户指令。不支持播报中途打断。

设备端必须具备的声学能力：

算法要求作用
ANS（背景降噪）必选抑制背景环境噪音
AGC（自动增益）必选自动调节收音音量
VAD（语音活动检测） 或 唤醒模型必选灵敏的静音检测算法判断用户何时开始说话；或唤醒模型唤醒后再收音

适合：信息查询、家电控制等指令明确、无需频繁探讨的场景。无需手动按键，技术门槛适中，降低了对复杂声学算法的依赖。

三模式速查对照 ​

维度全双工免唤醒按键对讲机半双工 VAD
AEC必选不要求不要求
ANS必选必选必选
AGC必选必选必选
VAD/唤醒云端 VAD不要求端侧 VAD 或唤醒模型
打断（Barge-in）✅ 支持✅（松键即断）❌ 不支持
隐私一般最强一般
技术门槛高低中
典型场景陪伴玩具/音箱强隐私/工业设备家电控制/信息查询

算法定义详见 附录 C 术语表（VAD/AEC/AGC/ANS/OTA）。打断事件 CALL_AGENT_INTERRUPTED 的处理见 4.4 WebSocket语音通道。

5.3 设备端音频处理链路 ​

选好交互模式（5.2）后，本节讲设备端音频从采集到上行的完整处理链路。5.2 讲「要哪些算法」，本节讲「这些算法在链路里怎么协同，音频怎么切包上传」。

5.3.1 音频处理链路总览 ​

5.3.2 采集与前处理（AEC/ANS/AGC 协同） ​

前处理是音频质量的第一道关卡，直接决定云端 ASR 能不能听清。三个算法在链路中的顺序见 5.3.1 总览图（AEC → ANS → AGC）。

算法协同要点
AEC消除设备自身扬声器的回声。全双工模式下扬声器的声音会被麦克风重新收到，必须用 AEC 抵消，否则云端听到"回音"。硬件级 AEC 效果优于算法级
ANS抑制稳态噪声（风扇、空调）与突发噪声（关门、敲击）。ANS 过度会损伤语音，需调参平衡
AGC自动调节增益。远场说话音量小就放大，近场大就压低，保证信噪比稳定

协同要点：前处理在端侧完成，上行的是已处理的干净音频。云端不再做回声消除/降噪（云端只做 ASR 识别），所以端侧前处理质量直接决定识别率。

5.3.3 PCM 上行切包（硬约束） ​

PCM 是原始音频，切包规则简单但必须遵守时长上限。PCM 切包只受单包帧时长这一条硬约束。

规则要求
单包帧时长≤300ms（硬上限）
单包字节数时长 × 采样率 × 2bytes（16bit） × 1声道（如 16k/16bit 下 120ms = 16000×2×0.12 = 3840 字节）
发送节奏间隔 = 音频时长，均匀发送（实时流式，不批量发）

⚠ 单包超 300ms 的后果：云端 ASR 是流式处理的，单包太长会导致首字延迟增大、打断响应变慢。300ms 是硬上限，建议实际取 120ms 左右平衡延迟与开销。不均匀发送（攒一批一次发）会导致回复延时异常。

5.3.4 Opus 上行：单包与拼包（⭐单包推荐） ​

Opus 是压缩格式（体积约 PCM 的 1/8，省流量），支持 CBR/VBR。上行有两种模式：单包（1 个 opus 音频包 = 1 个数据包，推荐）与拼包（多个 opus 音频包裸拼接成 1 个数据包，不推荐）。三层概念（数据包 / opus 音频包 / opus 帧）与数据包构成图见 4.5 音频格式与分片。

单包与拼包怎么选 ​

模式何时用opus 音频包格式frameSize
单包（推荐）默认场景0 号包或 3 号包均可（opus 标准都支持）不传
拼包（不推荐）仅 CPU 不足、需减少上传次数时3 号包 + CBR传（=单个 opus 音频包字节数）

0/1/2/3 号包、CBR/VBR 的原理见 附录D · Opus 包结构与拼包原理；本节只讲怎么选、不讲为什么。

标准场景字节参考 ​

标准场景参考：16k 采样率、8:1 压缩比、60ms 帧长 → 单个 opus 音频包约 240 字节（供拼包场景估算 frameSize 用；单包字节数随码率可变，无需关注）。

易踩坑点 ​

  • audio.input.frameSize = 单个 opus 音频包字节数,仅拼包时传(单包不传);原理详见 附录D
  • 设了 frameSize 且小于实际 opus 音频包字节数 → 服务端按 frameSize 切错 → 解码失败
  • 单个 opus 音频包字节超 480(默认上限)时,需显式设 frameSize
  • 数据包总时长建议 ≤300ms(软建议,与 PCM 单包对齐);opus 音频包时长 ≤120ms 是 opus 标准硬上限

5.3.5 上行时序与抖动控制 ​

要点说明
间隔 = 音频时长实时流式发送，间隔等于单包音频时长。120ms 的包每 120ms 发一个
不批量发送不能攒一批一次发，不均匀会导致回复延时异常
抖动容忍网络抖动会影响 ASR 首字延迟，弱网下抖动大时首字会更慢
二进制传输audio.binary=true 启用后，上行用 ws.send(bytes)（替代 base64），省带宽

端侧 VAD 的开启与建联时 audio.vad 配置开关是两件事：本节讲端侧实现（怎么采集、怎么切包、怎么发），建联时是否在协议层开启端侧 VAD 由 audio.vad 字段控制（true 开启 / false 关闭，默认 false），字段定义见 4.5 语音基础协议参考手册 · CLIENT_VOICE_CHAT_UPDATE。协议层格式（PCM/Opus/mp3 参数、二进制配置）见 4.5 音频格式与分片：§4.5 是格式字典，§5.3 是设备端落地。

5.4 芯片支持与 Demo 下载 ​

芯片 SDK 支持矩阵（ESP32S3 / BK7258 / Linux / 杰里）、ESP32S3 快速接入教程、多语言 Demo（Java / Python / C++ / Android）下载地址统一见 附录 G. 下载 Demo。

下一步 ​

读完本章，你已经知道硬件要配什么声学算法、音频怎么处理切包、用什么芯片。接下来：