名词解释

客户端

客户端是用户或业务应用使用的一端，用来连接目标设备、查看音视频、发起对讲、发送控制命令或承接业务交互。

在常见接入里，手机 App、桌面 App、Web 管理台或基于 Flutter / React Native / Android / HarmonyOS / iOS SDK 开发的应用都属于客户端。客户端拿到 remote_id 和 token 后连接目标设备。

设备端

设备端是运行在嵌入式设备上的一端，用来让这台设备接入 TiRTC，并把设备上的音视频、对讲或控制能力开放给客户端。

摄像头、门铃、对讲设备、智能音箱、Linux 嵌入式设备或设备网关都可以作为设备端。设备端用 device_id 和 device_secret_key 启动 SDK；客户端连接它以后，可以查看音视频、进行对讲、收发命令或使用其他设备侧能力。

TGMP

TGMP 是 TGTRP Media Transport 的缩写，也是 TGTRP 实时音视频传输协议的简称。该协议由 TiRTC 自研，针对弱网络环境进行了深度优化。

4G 定向卡

4G 定向卡是“4G 定向物联网卡”的简称，指运营商或物联网卡服务商为指定业务用途提供的 SIM 卡及网络服务。这类卡通常只能访问事先配置的业务地址，不能像普通 4G 卡一样访问任意互联网地址。

域名或 IP 地址白名单是常见的限制方式：白名单中的地址可以访问，其他互联网地址不能访问。

4G 白名单网络

4G 白名单网络是设备使用上述白名单访问规则时所处的网络环境。设备可以直接使用 4G 定向卡联网，也可以通过 Wi-Fi 接入装有这类卡的路由器。在这两种情况下，设备都只能访问白名单内的地址。

受限网络

本文将只能访问白名单内地址的网络统称为“受限网络”。

设备处于受限网络时，需要在启动 TiRTC C SDK 前设置对应的网络信息，具体方法见为 4G 设备补充网络初始化配置。

AppId

AppId 是客户端应用的唯一标识。

AppId 标识接入 TiRTC 的业务 App。同一个业务 App 可以有 Android、HarmonyOS、iOS、Flutter、React Native 等多个客户端技术栈，它们可以使用同一个 AppId。

AppId 不表示某个用户、某台设备或某一次连接。

AccessKeyId

AccessKeyId 是应用级凭证标识。

它用来标识这次签发或接入属于哪个 TiRTC 应用。服务端签发连接 token 时会用到它，TiRTC 也会用它识别对应的应用级凭证。

AccessKeyId 本身不是密钥，和 SecretKeyId 配套使用。

SecretKeyId

SecretKeyId 是应用级密钥。

它用于服务端签名和鉴权，属于敏感信息。你的业务服务端可以使用它签发连接 token，但不要把它下发到客户端，也不要写进客户端代码、日志、截图或工单。

device_id

device_id 是 TiRTC 平台为设备生成的稳定标识。它是一段随机加密、可自校验的字符串，自校验由 TiRTC 平台完成，应用层代码不需要解析或重新实现。

device_id 标识具体设备，常用于设备管理、授权判断、远端目标识别和排查定位。

平台当前生成的 device_id 格式如下：

• 长度为 12 到 32 个字符。
• 由数字 0-9 和大写字母 A-Z 组成。

如果应用层代码需要校验 device_id，建议使用较宽松的规则：

• 字节长度为 12 到 32，包含上下限。
• 每个字节都是 0x21 到 0x7E 范围内的可见 ASCII 字符，不包含空格或控制字符。
• 不按当前字符集写死校验规则，以便兼容后续格式扩展。

把平台下发的 device_id 当成不透明字符串，原样保存和传递；不要自行生成、解析、删除首尾字符或转换大小写。

常见设备连接场景里，客户端要连接某台设备时，remote_id 就是这台设备的 device_id。

device_secret_key

device_secret_key 是与 device_id 成对使用的设备级密钥。

设备端使用它证明自己持有对应 device_id 的密钥，TiRTC 据此校验设备身份。

平台当前生成的 device_secret_key 格式如下：

• 长度为 32 到 64 个字符。
• 由数字、大小写字母和 + - / _ = 组成。

如果应用层代码需要校验 device_secret_key，建议使用较宽松的规则：

• 字节长度为 32 到 64，包含上下限。
• 每个字节都是 0x21 到 0x7E 范围内的可见 ASCII 字符，不包含空格或控制字符。
• 不按当前字符集写死校验规则。

保存和使用 device_secret_key 时：

• 设备端应将它保存在设备平台提供的安全存储中，例如安全芯片（SE）、TEE 安全存储、加密的 KV 存储或访问受限的 Flash 分区。
• 设备应用只在启动 SDK 等需要鉴权的场景读取它，并原样传给设备端 C SDK；不要自行生成、解析、删除首尾字符或转换大小写。

不要把 device_secret_key 写进源码、公共固件包或未加密的配置文件；不要打印到日志；不要通过聊天、邮件、截图或工单发送。

client_id

client_id 是设备端启动时上报的硬件或生产标识，由你自己生成和维护。

设备端启动前必须设置 client_id；未设置会导致启动失败。client_id 长度必须为 1 到 64 个可打印 ASCII 字符。

client_id 应当稳定、可追溯，能在你的生产或售后系统里定位到一台实物设备。常见取值包括生产序列号、MAC、ICCID、IMEI、芯片标识，或由产品线、批次、序列号等稳定字段组合生成。

同一个 device_id 首次启动后会绑定当次上报的 client_id；后续启动同一个 device_id 时，必须继续使用同一个 client_id。

remote_id

remote_id 是客户端发起连接时填写的目标标识。

remote_id 回答的是“这次要连谁”。客户端拿到 token 后，会配合 remote_id 发起连接。

常见设备连接场景里，remote_id 就是目标设备的 device_id。例如目标设备的 device_id 是 PRODFENGXXXX，客户端连接时 remote_id 就传 PRODFENGXXXX。服务端签发 token 时绑定的目标，也应当和客户端传入的 remote_id 保持一致。

token

token 是客户端发起一次连接时使用的短时凭证。

它由你的业务服务端签发。服务端在签发前应先完成自己的业务授权判断，例如验证当前用户对目标设备的访问权限。

签发 token 不受目标设备在线状态影响。客户端真正发起连接时，目标设备才需要启动并在线。

客户端只需要把 token 当成一段不透明字符串使用，不应在客户端拼装、解析或改写它。

stream

stream 表示同一条连接、一个发送方向里的“一路一路”数据，例如设备端发给客户端的主视频、子视频和主音频，以及客户端发给设备端的对讲音频。每一路流都是单向的；需要双向传输时，两个方向分别建立和标识各自的流。

TiRTC 用 stream_id 标识同一条连接、同一发送方向里的每一路数据，并用媒体类型区分帧是音频、视频还是流消息。相反方向使用各自独立的编号空间，因此可以复用相同数值。

stream 包括这些类型：

类型	说明	示例
音频流	持续传输音频帧的 stream	主音频、对讲音频
视频流	持续传输视频帧的 stream	主视频、子视频
流消息	带 stream_id 的业务自定义消息帧	字幕片段、叠字文本、和某路音视频同步的状态提示

流消息

流消息是在一条已建立的 TiRTC 连接上，沿指定 stream_id 传输的业务自定义字节数据。

它适合表达“这段轻量数据属于某一路流”，例如字幕片段、叠字文本或和某路音视频同步的状态提示。流消息不是命令通道；如果你要表达请求、控制指令或处理结果，优先使用命令消息。

stream_id

stream_id 是同一条连接、一个发送方向里某一条 stream 的编号。每一路流都是单向的；同一条连接的两个发送方向分别使用各自的编号空间。

客户端用它声明要播放、订阅、退订或请求关键帧的是哪一路远端音频或视频；设备端也用它标识正在发送、订阅或停止的是哪一路流。同一方向、同一路流在发送、Output / Input 绑定、订阅和接收配置中必须使用相同编号。

stream_id 的取值范围是 0 到 15。在同一条连接的同一发送方向内，不同音视频流必须使用不同编号，音频和视频不能共用同一个 stream_id；相反方向可以复用相同数值。例如，设备端发给客户端的音频和客户端发给设备端的对讲音频可以都使用 10，但两端仍要分别按方向配置一致。

流消息也带 stream_id，但它不要求独占一个新的 stream_id。消息可以放到某一路已有音视频 stream_id 上，也可以单独约定一个 stream_id 专门承载消息；关键是两端按同一套约定解析。

stream_id 不等于 Ti 云存的 channel_id。前者用于 TiRTC 实时连接，范围是 0..15，同一连接、同一发送方向中的音频和视频不能共用编号；后者用于标识云录像中的媒体通道，范围是 0..255，音频和视频可以使用相同编号。两套编号属于不同业务域，不要求数值一致。