ARTICLE · 1395205
信电助录音盒通话实时语音流上传对接文档
1 前言
1.1 文档概要
1.2 编写目的
为了用户能更方便地使用信电助实现通话时实时语音流推送,并在自己的服务器端正常接收语音流,特编写本对接说明书。
1.3 版本要求
本说明书对应的信电助手软件版本至少为 26.11.20,低于该版本不支持实时语音流上传功能。
2 安装信创电话助手
使用对接开发前,先从官网下载并安装信创电话助手,并接入 USB 信创录音盒设备。
注意:信创电话助手软件分为 Windows 版本和国产信创麒麟统信版本,两个版本的软件功能一致。
信创电话助手安装启动后的主界面如下图所示:

USB 信创录音盒设备如下图所示:

信电助手软件采用标准 WebSocket 协议的 ws 或 wss 请求,将记录发送到用户服务器,文本数据采用 JSON 格式,不加密。
3 WebSocket 服务器 URL 地址设置
在信创电话助手中配置语音流上传的服务器地址,操作步骤如下:
点击【文件】菜单,如下图所示: 
在弹出的菜单里选择【数据上传配置】: 
图 3-2 选择【数据上传配置】
在弹出的配置界面里,找到「通话语音流实时上传参数」区域,将【启用上传】打勾,然后在【服务器URL】中输入已开发好的 WebSocket 服务器 URL 地址。请确保该 URL 地址与当前软件处于同一局域网内,或为有效的公网地址,能够被运行信创助手软件的电脑正常连接访问。 
ws://192.168.0.9:8080/xdz
wss://192.168.0.9:8080/xdz
或者输入有效的域名,例如:
ws://ws.agicall.com:8080/xdz
wss://ws.agicall.com:8080/xdz
4 服务端参考示例代码下载
官方提供了 WebSocket 接收实时音频流的服务端 Java / Python 参考示例代码,下载步骤如下:
使用浏览器打开官网:https://www.agicall.com 点击右上角的【下载】; 
在打开的页面中找到【开发资源(Windows)】项目; 找到【通话实时语音流 websocket 服务端 java/python 例子】,点击下载。 
5 实时语音流 WebSocket 上传协议说明
5.1 协议概述
设备通过 WebSocket 建立长连接,先用文本帧(JSON)握手,再用二进制帧实时上传 20ms 一包的小体积 PCM 语音流,服务端按声道分文件落盘为 .pcm。
本协议定义「设备端 → 远端服务器」实时上传语音流的全过程,属于「小脑直推」方案:音频不经额外转码,按固定大小的帧切片,通过 WebSocket 通道持续推送。整体分三层。
核心约定:控制走文本帧、音频走二进制帧,二者在同一连接上并行收发。
5.2 系统角色
客户端 :嵌入设备/对话流程,负责连接服务器、发起握手、把采集到的 PCM 切片持续上传、结束时发送停止信令。 服务端 (提供 Python 或 Java 示例代码):基于 websockets 库,监听端口,接收握手并回确认,接收二进制帧解析出声道与 PCM,按时间戳分声道保存为 .pcm 文件。
5.3 连接建立
目标地址来自后台配置字段 config/agi_wsstream.json 的 ws_url(示例:ws://127.0.0.1:8080/ws)。 可选扩展 HTTP 头 http_header(如阿里系鉴权需要 token,一般场景不需要),随握手一起发送。 客户端调用连接 WebSocket 的服务器地址。 连接成功后进入「已连接」状态,并立即主动发送开始包(见 5.6 节)。
5.4 两类消息帧
(1)文本帧(控制信令):UTF-8 编码的 JSON 字符串,用于 stream_start、stream_stop 及对应应答。
(2)二进制帧(音频数据):固定结构,8 字节协议头 + 320 字节 PCM,单帧共 328 字节。
5.5 二进制帧协议头详解(8 字节)
音频参数:采样率 8kHz、位深 16bit、单声道。20ms 时长 = 8000 × 0.02 = 160 个采样 = 160 × 2 字节 = 320 字节。
服务端解析规则:channel = frame[1],payload = frame[8:]。通道号非 0/1 时按左声道兜底,帧长 ≤ 8 字节则丢弃。
备注:只有设备为双轨型号 UB-B-XC 或 UB-B-AGI 时才会有通道 id=1 的语音流;一般单轨设备只有通道 = 0 的语音流。
5.6 控制信令(JSON 文本帧)格式
5.6.1 开始推流 stream_start(客户端 → 服务端)
连接建立后客户端主动发送,由配置模板 stream_start 加上实时字段拼装:
{
"cmd": "wsstream_start",
"其它固定字段": "来自配置 stream_start",
"dev_info": { "设备型号": "...", "设备SN": "..." },
"dialog_id": "本次会话/对话ID"
}
dev_info:客户端运行期当前设备的基础信息,比如序列号等。 dialog_id:本次呼叫记录的唯一标识 id。
5.6.2 开始应答(服务端 → 客户端)
服务端必须回一个文本帧,且携带与请求相同的 cmd 以及 err_id=0:
{ "cmd": "wsstream_start", "err_id": 0, "msg": "ok" }
客户端据此判定:cmd 与本地 stream_start.cmd 匹配且 err_id == 0 → 进入 established(可推流);否则视为开始失败,不推流。
5.6.3 结束推流 stream_stop(客户端 → 服务端)
由配置模板 stream_stop 生成:
{ "cmd": "wsstream_stop", "其它字段": "来自配置 stream_stop" }
5.6.4 结束应答(服务端 → 客户端)
{ "cmd": "wsstream_stop", "err_id": 0, "msg": "ok" }
客户端收到停止应答(无论成败)即进入 end 状态。
客户端识别回包归属:比较应答 JSON 的 cmd 与本地配置的 stream_start.cmd / stream_stop.cmd,因此服务端回包必须原样回显请求的 cmd。
5.7 完整通讯流程(时序)
图 5-1 完整通讯流程时序图

分步要点:
连接 :客户端读取配置后向 ws_url 发起带可选 HTTP 头的 WebSocket 连接。 发开始包 :收到 OPEN 回调后,立即把 stream_start + dev_info + dialog_id 作为文本帧发出。 确认 :服务端回相同 cmd 且 err_id=0,客户端进入 established,此后才允许推流(未 established 时调用上传接口会被忽略)。 推流 :每积累满 20ms(320 字节)PCM 即拼上 8 字节头作为一帧二进制发送;左右声道各自独立成帧、各自攒包。 结束 :对话到达结束步骤时发送 stream_stop 文本帧。 停止应答 :服务端回包后客户端进入 end。 收尾 :服务端关闭文件句柄,统计字节数与约估时长(bytes / 2 / 8000 秒)。
5.8 客户端状态机

5.9 服务端落盘规则
每条连接 = 一个会话(Session),会话级时间戳在收到 start / 首帧时生成,格式 YYYYmmdd_HHMMSS。 每个声道单独一个文件:recordings/stream_<时间戳>_ch<声道>.pcm。 文件以追加方式持续写入对应声道的 PCM 载荷。 会话结束时关闭句柄并输出每声道字节数与估算时长(秒)。 文件为裸 PCM(无 WAV 头),如需播放可按 8kHz / 16bit / 单声道导入音频工具。
5.10 客户端配置文件结构(JSON)
{
"ws_url": "ws://127.0.0.1:8080/ws",
"http_header": { },
"stream_start": { "cmd": "wsstream_start", ... },
"stream_stop": { "cmd": "wsstream_stop", ... },
"in": "in_connected",
"out": "out_invite"
}
in / out 用于把推流时机绑定到对话流程的特定步骤:当对话推进到配置的步骤名时自动 start,到达「对话结束」步骤时自动 stop。
5.11 关键约束与注意事项
先确认后推流 :未收到 err_id=0 的 start 应答前,二进制帧一律不发。 回包必须回显 cmd :服务端应答中的 cmd 必须与请求一致,否则客户端无法匹配、无法进入推流态。 帧长固定 :二进制帧严格为 8 + 320 = 328 字节;服务端对 ≤8 字节的短帧直接丢弃。 声道隔离 :左右声道各自独立攒包、独立成帧、独立落盘,互不混包。 PCM 格式 :8kHz、16bit、单声道、小端,落盘无文件头。 服务端兼容性 :示例服务端把「带 dialog_id/dev_info 或尚未 start」的文本帧视为 start,其余文本帧视为 stop/控制,回包统一 err_id=0。 触发时机由对话流程驱动 :设备侧比对当前通话步骤名,命中 in/out 配置即启动推流,对话结束步骤自动停止。默认 in_connected 表示来电接听后开始,out_invite 表示去电拨号结束后开始。















































































