概念与术语
本文汇总 GT-Streaming 集成中常见的概念与术语，帮助你在阅读 API 文档和示例代码时快速对齐含义。
系统与模块
| 术语 | 说明 |
|---|
| GT-Streaming | 道路运输车辆卫星定位系统的流媒体中间件，向企业应用提供媒体 API，屏蔽 JT/T 1076 终端协议细节 |
| 企业应用 / 客户端 | 调用媒体服务 API、创建播放器的业务系统或浏览器页面 |
| 终端网关 | 维持与车载终端长连接（JT/T 808 等），转发媒体指令并上报终端应答的企业侧模块 |
| 终端 / 车载视频终端 | 符合 JT/T 1076 的车载视频设备，向媒体服务推送 1078 码流 |
| 消息队列（MQ） | 媒体服务与网关/企业后端之间的异步通道，当前支持 RabbitMQ |
标识与请求
| 术语 | 说明 |
|---|
| 终端识别号（simNo） | 终端在平台中的唯一标识，即协议中的「终端手机号」 |
| 通道号（channel） | 逻辑音视频通道，常见为 1–4；打开实时/回放时需指定 |
| reqId | 一次媒体请求的唯一 ID，用于保活、控制、关闭及接收状态通知 |
| token | 会话令牌，登录后获得；除登录外每次 API 调用需在请求头携带（X-Auth-Token） |
| playUrl | 客户端播放器加载的媒体地址，协议由打开请求中的 proto 决定 |
| instanceId | 媒体服务分配的流媒体实例 ID |
实时打开参数
| 术语 | 取值 | 说明 |
|---|
| dataType | 0 | 音视频 |
| 1 | 仅视频 |
| 2 | 双向对讲 |
| 3 | 监听（只听终端音频） |
| codeStream | 0 / 1 | 主码流 / 子码流 |
| proto | 0 / 1 / 4 | FLV / HLS / RTSP |
| async | true / false | 异步 / 同步打开模式 |
详见 打开实时音视频。
请求生命周期
| 术语 | 说明 |
|---|
| 同步打开 | 接口在终端推流就绪（或失败）后才返回；返回时 ready 通常为 true |
| 异步打开 | 接口先返回 reqId，终端推流就绪后通过 WebSocket 通知；需订阅通知 |
| 保活（keep_alive） | 客户端每约 15 秒调用一次，防止媒体服务因超时关闭请求 |
| 共享打开 | 同一实时通道允许多个 reqId 同时观看；仅一个请求拥有控制权 |
| 控制权（ctrl） | 拥有控制权的请求可切换码流、暂停/恢复；无控制权时操作返回 -25 |
| 通道关闭 | 某 reqId 关闭 ≠ 终端停推；同通道无活动请求时，服务端才关闭终端连接 |
状态说明见 音视频请求的生命周期。
流媒体状态（StrmNotif）
客户端订阅通知后，主要关心以下 act 值：
| act | 含义 |
|---|
sent | 已向终端下发指令 |
failed | 终端应答失败 |
id | 检测到终端开始推流 |
ready | 客户端可开始播放 |
closed | 请求已关闭 |
客户端协议
| 术语 | 说明 |
|---|
| HTTP-FLV / WS-FLV | FLV over HTTP 或 WebSocket；低延时，现代浏览器友好（iPhone Safari 除外） |
| HLS | HTTP Live Streaming；兼容性好，延时较高 |
| fMP4 / mpegts | HLS 分段格式；默认 fMP4，支持 H.265 |
| RTSP | 多用于原生 App 或专用播放器，一般浏览器不支持 |
选型见 客户端播放协议的选择。
API 类型
| 术语 | 说明 |
|---|
| HTTP API | REST 接口 + 独立 STOMP WebSocket 接收通知 |
| WebSocket API（v4） | 单 WebSocket 连接完成 API 调用与通知；推荐新应用使用 |
| strm-js | 官方 TypeScript/JavaScript 客户端库，封装 StrmWsApi / StrmHttpApi |
对比见 HTTP API 与 WebSocket API 选型。
对讲相关
| 术语 | 说明 |
|---|
| taUrl | 对讲时客户端推送本端音频的二进制 WebSocket 地址 |
| wsUrl | 对讲时客户端推送本端音频的 STOMP WebSocket 地址（HTTP API 场景） |
对讲不支持共享打开；同通道有对讲或其他播放占用时，新打开可能返回 -21。详见 对讲集成指南。
主动安全附件
| 术语 | 说明 |
|---|
| ADAS 附件 / 报警附件 | 主动安全报警关联的图片、视频等证据文件 |
| 9208 | 平台下发报警附件上传指令的消息号 |
| fetch-alm-att | 企业应用请求提取附件的 MQ 队列 |
| fetch-alm-att-completed | 媒体服务通知提取任务结束的 MQ 队列 |
详见 主动安全附件集成指南 与 ADAS 报警类型编码。
常见错误码（集成相关）
| 错误码 | 含义 | 常见原因 |
|---|
-5 | 超时 | 终端未及时推流 |
-10 | 无效或过期 token | 需重新登录 |
-21 | 资源已被占用 | 对讲/回放通道已被占用 |
-25 | 无控制权 | 非控制方请求执行切流等操作 |
-27 | 终端不在线 | 网关未连接或终端离线 |
完整列表见 错误码定义；排错见 常见问题与排错。