主题
C. 术语表
本手册涉及的术语速查。按声学算法 / 协议与链路 / 平台与业务 / 编码格式四组。
A.1 声学算法
VAD(Voice Activity Detection,语音活动检测)
在音频流中自动检测语音段与非语音段（静音/噪声），确定说话起止时间，用于端点检测与流式分段。
在 JoyInside 中的应用:
- 自由对话模式下,云端 VAD 用于检测用户说话结束,触发响应;
- 半双工模式(见 5.2)依赖端侧或云端 VAD 判断说话起止;
- 与 AEC 协同,VAD 提供语音活动信息辅助 AEC 双讲决策。
AEC(Acoustic Echo Cancellation,声学回声消除)
消除扬声器播放声经麦克风回采产生的回声（含混响与反馈），避免设备"自言自语"。
在 JoyInside 中的应用:
AGC(Automatic Gain Control,自动增益控制)
自动调整麦克风输入信号增益(音量)的技术,使远近距离说话、大小声说话都能保持合适的录音电平。
在 JoyInside 中的应用:
- 全双工模式与按键模式建议启用(见 5.2);
- 防止用户说话过小导致 ASR 拒识,或过大导致削波失真。
ANS(Acoustic Noise Suppression,噪声抑制)
抑制背景噪声(风噪、空调声、环境嘈杂)的技术,提升语音信噪比。
在 JoyInside 中的应用:
- 全双工模式建议启用(见 5.2);
- 远场场景或嘈杂环境下,ANS 显著提升 ASR 识别率。
唤醒词检测(Wake Word Detection / KWS)
在待机状态下持续监听麦克风,检测预设唤醒词(如"你好东东")的技术。检测到唤醒词后触发设备进入对话状态。
在 JoyInside 中的应用:
- 全双工免唤醒模式无需唤醒词,直接说话即可(见 5.2);
- 半双工 VAD 模式可结合唤醒词检测实现低功耗待机。
A.2 协议与链路
roundId(轮次标识)
一轮语音对话从 ASR 到 TTS 的全链路唯一标识。服务端通过 roundId 在 ASR → Flow → TTS 全链路串联这一轮的所有事件。
在 JoyInside 中的应用:
- 端到端排查主键(见 4.5 roundId 与 12.3);
- 下行事件
content.roundId字段携带; - 排查粒度:
roundId>requestId>botId; - 联系京东技术支持必须提供
roundId。
requestId(请求标识)
一次 WebSocket 建连的全周期唯一标识。一次 WS 连接内可能包含多个 roundId(多轮对话)。
排查用途:定位单次连接内的问题,如建连阶段失败、连接内多轮异常。
sessionId(会话标识)
WebSocket 建联参数,标识一次会话。建议每次 WS 建连新生成 UUID 传入,用于实现多轮对话(见 4.3)。
barge-in(打断)
用户在系统播放 TTS 期间开口说话,打断当前 TTS 播放并开始新一轮对话的机制。
在 JoyInside 中的应用:
- 自由对话模式下,服务端下发
CALL_AGENT_INTERRUPTED事件,端侧收到后清空播放队列(见 10.3); - 手动模式下,端侧主动发送
CLIENT_INTERRUPT事件打断; - 打断不生效多因端侧单线程处理下行事件,改并发监听可解决 80% 问题(见 10.3.3)。
dispose(打断原理)
服务端在用户打断时,通过 dispose 机制中断正在进行的 LLM/TTS 流,避免继续生成已无意义的回复。详见 4.5 TTS 打断原理。
双连接互踢(REPEAT_CLIENT_SESSION)
同一个 botId 在服务端同时存在两个 WS 连接时,新连接踢掉旧连接的机制。一个 botId 代表一台设备,不应同时有两个活跃对话通道(否则上下文、打断、TTS 播放都会混乱),见 4.2 双连接互踢。排查见 10.1.4。
拒识四层防护
JoyInside 服务端对无效输入的四层过滤机制,最终输出 EMPTY_CONTENT 事件。详见 4.5 拒识四层防护。排查见 10.2.1。
A2A(Agent-to-Agent,智能体间通信)
JoyInside 自定义技能的流式协议,智能体通过 Message → Instruction → Done 的顺序输出,id 从 0 计数。详见 6.6.5 A2A 流式响应协议。
extInfo(自定义变量)
JoyInside 提供的短期记忆变量机制,通过 CLIENT_UPDATE_CHAT_CONTEXT 上行事件写入,effectiveTimeMinutes 控制有效期(1~1440 分钟)。需申请权限。详见 7.4。
A.3 平台与业务
appId / botId / vendorId / deviceId / SN(设备身份三层映射)
JoyInside 设备身份的三层映射关系:
vendorId(企业) → appId(应用) → botId(设备) → deviceId/SN(物理设备)| 标识 | 层级 | 获取位置 | 章节 |
|---|---|---|---|
| vendorId | 企业 ID | 个人信息 > 企业信息 | 3.2 |
| appId | 应用 ID | 应用管理卡片下方 | 3.2 |
| botId | 设备 ID(WS 建联必需) | 设备管理 ID 列 | 3.2 |
| deviceId / SN | 物理设备唯一标识 | 制造商分配,建议作为 deviceId | 4.2 |
详见 4.2 设备注册与绑定。
APP_ROBOT / PHYSICAL_ROBOT(设备类型)
| type | 含义 | 用途 |
|---|---|---|
APP_ROBOT | 测试设备 | 研发调试、预览 |
PHYSICAL_ROBOT | 生产设备 | 量产出货、正式商用 |
切换见 11.1。
双 Token 机制
| Token | 有效期 | 用途 |
|---|---|---|
| accessToken | 2 小时 | API 鉴权与 WS 建联 |
| refreshToken | 7 天 | 有效期内刷新 accessToken |
详见 4.1 双 Token 与 12.1。
任务规划器
IOT 指令下发的调度机制,开启时并行下发多个指令,关闭时按 instructions[] 串行下发。详见 6.1.4。
垫句
IOT 指令下发前播放的过渡语句(如"好的,正在执行"),避免用户等待感。清空垫句 + 关闭执行反馈 = 静默执行。详见 6.1.5。
有声书 V1 / V2
| 版本 | feature 参数 | 交互模式 |
|---|---|---|
| V1 | AUDIO_BOOK + clientType=AUDIO_BOOK | 按键交互 |
| V2 | AUDIO_BOOK_V2 | 连续对话 |
详见 6.2。
魔法打印三态机
魔法打印设备的三种状态:打印态 / 唤醒态 / 关机态。详见 6.3.2。
OTA(Over-The-Air,空中下载)
通过无线网络远程对设备进行软件更新、配置下发或数据同步的技术，支持固件/应用/配置推送、漏洞修复、灰度发布与回滚。
在 JoyInside 中的应用:见 12.5 OTA 与远程配置。
A.4 编码与音频格式
PCM(脉冲编码调制, Pulse-Code Modulation)
未经压缩的原始数字音频格式,所有数字音频处理都始于 PCM 数据流。采样 + 量化 + 编码三位一体。详见 附录 D。
在 JoyInside 中的应用:上行默认格式(16k/16bit/单声道,单包 ≤300ms),下行 TTS 支持格式。详见 4.4。
Opus
IETF 制定的开源、免版税音频编码格式,结合 SILK(语音)与 CELT(音乐)两种模式,自适应选择。低延迟、高压缩比。详见 附录 D。
在 JoyInside 中的应用:上行推荐格式(体积约 PCM 的 1/8,单包 ≤480 字节),下行 TTS 支持格式。详见 4.4。
MP3
首个成功实现高压缩比且保持"可接受"音质的有损音频编码标准,基于心理声学模型。详见 附录 D。
在 JoyInside 中的应用:仅支持下行 TTS,不支持流式切分,不支持上行。详见 4.4。
采样率 / 位深 / 声道数 / 码率
| 参数 | 决定因素 | 典型值 | 影响 |
|---|---|---|---|
| 采样率 | 最高可记录频率 | 16kHz(JoyInside 默认)/ 44.1kHz(CD)/ 48kHz(影视) | 高频响应、时间精度 |
| 位深 | 动态范围与噪声 | 16 bit(CD/JoyInside)/ 24 bit(专业) | 信噪比、细节层次 |
| 声道数 | 空间维度 | 1(单声道,JoyInside)/ 2(立体声) | 沉浸感、混音复杂度 |
| 码率 | 质量与文件大小 | 码率 = 采样率 × 位深 × 声道数 / 1000 | 存储、传输带宽 |
详见 附录 D。
frameSizeMs(帧长)
TTS 音频下发的单帧时长。PCM 帧 60-120ms,Opus 帧 10/20/40/60ms。详见 4.4。
CBR / VBR
| 码率模式 | 全称 | 特点 |
|---|---|---|
| CBR | 恒定码率 | 每帧固定字节数,JoyInside Opus 支持 enableOpusCbr=true |
| VBR | 可变码率 | JoyInside 默认模式 |
二进制传输
通过 audio.binary=true 开启,上行用 ws.send(bytes) 替代 AUDIO 事件,下行用 binary frame 替代 TTS 事件。二进制通道仅用于音频,其他事件仍用 text 消息。详见 4.4。
下一步
C. 术语表
本手册涉及的术语速查。按声学算法 / 协议与链路 / 平台与业务 / 编码格式四组。
A.1 声学算法
VAD(Voice Activity Detection,语音活动检测)
在音频流中自动检测语音段与非语音段（静音/噪声），确定说话起止时间，用于端点检测与流式分段。
在 JoyInside 中的应用:
- 自由对话模式下,云端 VAD 用于检测用户说话结束,触发响应;
- 半双工模式(见 5.2)依赖端侧或云端 VAD 判断说话起止;
- 与 AEC 协同,VAD 提供语音活动信息辅助 AEC 双讲决策。
AEC(Acoustic Echo Cancellation,声学回声消除)
消除扬声器播放声经麦克风回采产生的回声（含混响与反馈），避免设备"自言自语"。
在 JoyInside 中的应用:
AGC(Automatic Gain Control,自动增益控制)
自动调整麦克风输入信号增益(音量)的技术,使远近距离说话、大小声说话都能保持合适的录音电平。
在 JoyInside 中的应用:
- 全双工模式与按键模式建议启用(见 5.2);
- 防止用户说话过小导致 ASR 拒识,或过大导致削波失真。
ANS(Acoustic Noise Suppression,噪声抑制)
抑制背景噪声(风噪、空调声、环境嘈杂)的技术,提升语音信噪比。
在 JoyInside 中的应用:
- 全双工模式建议启用(见 5.2);
- 远场场景或嘈杂环境下,ANS 显著提升 ASR 识别率。
唤醒词检测(Wake Word Detection / KWS)
在待机状态下持续监听麦克风,检测预设唤醒词(如"你好东东")的技术。检测到唤醒词后触发设备进入对话状态。
在 JoyInside 中的应用:
- 全双工免唤醒模式无需唤醒词,直接说话即可(见 5.2);
- 半双工 VAD 模式可结合唤醒词检测实现低功耗待机。
A.2 协议与链路
roundId(轮次标识)
一轮语音对话从 ASR 到 TTS 的全链路唯一标识。服务端通过 roundId 在 ASR → Flow → TTS 全链路串联这一轮的所有事件。
在 JoyInside 中的应用:
- 端到端排查主键(见 4.5 roundId 与 12.3);
- 下行事件
content.roundId字段携带; - 排查粒度:
roundId>requestId>botId; - 联系京东技术支持必须提供
roundId。
requestId(请求标识)
一次 WebSocket 建连的全周期唯一标识。一次 WS 连接内可能包含多个 roundId(多轮对话)。
排查用途:定位单次连接内的问题,如建连阶段失败、连接内多轮异常。
sessionId(会话标识)
WebSocket 建联参数,标识一次会话。建议每次 WS 建连新生成 UUID 传入,用于实现多轮对话(见 4.3)。
barge-in(打断)
用户在系统播放 TTS 期间开口说话,打断当前 TTS 播放并开始新一轮对话的机制。
在 JoyInside 中的应用:
- 自由对话模式下,服务端下发
CALL_AGENT_INTERRUPTED事件,端侧收到后清空播放队列(见 10.3); - 手动模式下,端侧主动发送
CLIENT_INTERRUPT事件打断; - 打断不生效多因端侧单线程处理下行事件,改并发监听可解决 80% 问题(见 10.3.3)。
dispose(打断原理)
服务端在用户打断时,通过 dispose 机制中断正在进行的 LLM/TTS 流,避免继续生成已无意义的回复。详见 4.5 TTS 打断原理。
双连接互踢(REPEAT_CLIENT_SESSION)
同一个 botId 在服务端同时存在两个 WS 连接时,新连接踢掉旧连接的机制。一个 botId 代表一台设备,不应同时有两个活跃对话通道(否则上下文、打断、TTS 播放都会混乱),见 4.2 双连接互踢。排查见 10.1.4。
拒识四层防护
JoyInside 服务端对无效输入的四层过滤机制,最终输出 EMPTY_CONTENT 事件。详见 4.5 拒识四层防护。排查见 10.2.1。
A2A(Agent-to-Agent,智能体间通信)
JoyInside 自定义技能的流式协议,智能体通过 Message → Instruction → Done 的顺序输出,id 从 0 计数。详见 6.6.5 A2A 流式响应协议。
extInfo(自定义变量)
JoyInside 提供的短期记忆变量机制,通过 CLIENT_UPDATE_CHAT_CONTEXT 上行事件写入,effectiveTimeMinutes 控制有效期(1~1440 分钟)。需申请权限。详见 7.4。
A.3 平台与业务
appId / botId / vendorId / deviceId / SN(设备身份三层映射)
JoyInside 设备身份的三层映射关系:
vendorId(企业) → appId(应用) → botId(设备) → deviceId/SN(物理设备)| 标识 | 层级 | 获取位置 | 章节 |
|---|---|---|---|
| vendorId | 企业 ID | 个人信息 > 企业信息 | 3.2 |
| appId | 应用 ID | 应用管理卡片下方 | 3.2 |
| botId | 设备 ID(WS 建联必需) | 设备管理 ID 列 | 3.2 |
| deviceId / SN | 物理设备唯一标识 | 制造商分配,建议作为 deviceId | 4.2 |
详见 4.2 设备注册与绑定。
APP_ROBOT / PHYSICAL_ROBOT(设备类型)
| type | 含义 | 用途 |
|---|---|---|
APP_ROBOT | 测试设备 | 研发调试、预览 |
PHYSICAL_ROBOT | 生产设备 | 量产出货、正式商用 |
切换见 11.1。
双 Token 机制
| Token | 有效期 | 用途 |
|---|---|---|
| accessToken | 2 小时 | API 鉴权与 WS 建联 |
| refreshToken | 7 天 | 有效期内刷新 accessToken |
详见 4.1 双 Token 与 12.1。
任务规划器
IOT 指令下发的调度机制,开启时并行下发多个指令,关闭时按 instructions[] 串行下发。详见 6.1.4。
垫句
IOT 指令下发前播放的过渡语句(如"好的,正在执行"),避免用户等待感。清空垫句 + 关闭执行反馈 = 静默执行。详见 6.1.5。
有声书 V1 / V2
| 版本 | feature 参数 | 交互模式 |
|---|---|---|
| V1 | AUDIO_BOOK + clientType=AUDIO_BOOK | 按键交互 |
| V2 | AUDIO_BOOK_V2 | 连续对话 |
详见 6.2。
魔法打印三态机
魔法打印设备的三种状态:打印态 / 唤醒态 / 关机态。详见 6.3.2。
OTA(Over-The-Air,空中下载)
通过无线网络远程对设备进行软件更新、配置下发或数据同步的技术，支持固件/应用/配置推送、漏洞修复、灰度发布与回滚。
在 JoyInside 中的应用:见 12.5 OTA 与远程配置。
A.4 编码与音频格式
PCM(脉冲编码调制, Pulse-Code Modulation)
未经压缩的原始数字音频格式,所有数字音频处理都始于 PCM 数据流。采样 + 量化 + 编码三位一体。详见 附录 D。
在 JoyInside 中的应用:上行默认格式(16k/16bit/单声道,单包 ≤300ms),下行 TTS 支持格式。详见 4.4。
Opus
IETF 制定的开源、免版税音频编码格式,结合 SILK(语音)与 CELT(音乐)两种模式,自适应选择。低延迟、高压缩比。详见 附录 D。
在 JoyInside 中的应用:上行推荐格式(体积约 PCM 的 1/8,单包 ≤480 字节),下行 TTS 支持格式。详见 4.4。
MP3
首个成功实现高压缩比且保持"可接受"音质的有损音频编码标准,基于心理声学模型。详见 附录 D。
在 JoyInside 中的应用:仅支持下行 TTS,不支持流式切分,不支持上行。详见 4.4。
采样率 / 位深 / 声道数 / 码率
| 参数 | 决定因素 | 典型值 | 影响 |
|---|---|---|---|
| 采样率 | 最高可记录频率 | 16kHz(JoyInside 默认)/ 44.1kHz(CD)/ 48kHz(影视) | 高频响应、时间精度 |
| 位深 | 动态范围与噪声 | 16 bit(CD/JoyInside)/ 24 bit(专业) | 信噪比、细节层次 |
| 声道数 | 空间维度 | 1(单声道,JoyInside)/ 2(立体声) | 沉浸感、混音复杂度 |
| 码率 | 质量与文件大小 | 码率 = 采样率 × 位深 × 声道数 / 1000 | 存储、传输带宽 |
详见 附录 D。
frameSizeMs(帧长)
TTS 音频下发的单帧时长。PCM 帧 60-120ms,Opus 帧 10/20/40/60ms。详见 4.4。
CBR / VBR
| 码率模式 | 全称 | 特点 |
|---|---|---|
| CBR | 恒定码率 | 每帧固定字节数,JoyInside Opus 支持 enableOpusCbr=true |
| VBR | 可变码率 | JoyInside 默认模式 |
二进制传输
通过 audio.binary=true 开启,上行用 ws.send(bytes) 替代 AUDIO 事件,下行用 binary frame 替代 TTS 事件。二进制通道仅用于音频,其他事件仍用 text 消息。详见 4.4。