使用 CLI 工具

DevTools CLI 用于开发和联调阶段。你可以用它为客户端生成调试用连接 token；CLI 同时会输出二维码，方便示例客户端扫码填入连接信息。没有真实设备端时，也可以在本机启动一个设备端，让客户端连上后接收固定 MP4 的音视频。

生产环境的连接 token 应由你的业务服务端签发。CLI 生成的 token 只用于开发和调试。

前置步骤

开始前先准备这些信息：

准备项	用在哪里	从哪里获取
Node.js / npm	安装和运行 CLI	本机开发环境
AccessKeyId、SecretKeyId、AppId	生成客户端连接 token	你的团队在控制台或服务端配置中提供
device_id、device_secret_key、endpoint	启动本机设备端	你的团队在控制台或服务端配置中提供
openapi endpoint	自定义接入环境下生成 token	你的团队提供；默认环境通常不需要显式传入
MP4 文件	本机设备端发送的音视频内容	使用自己的 MP4，或下载本文提供的建议资源

安装或更新 CLI：

npm install -g tirtc-devtools-cli@latest

确认 CLI 可用：

tirtc-devtools-cli --help

生成连接 token

当客户端要连接某个设备端时，用 token issue 生成临时连接 token。

先准备签发 token 需要的应用凭证：

export TIRTC_ACCESS_KEY_ID="your_access_key_id"
export TIRTC_SECRET_KEY_ID="your_secret_key_id"
export TIRTC_APP_ID="your_app_id"

为目标设备端生成 token：

tirtc-devtools-cli token issue your_remote_id

这里的 your_remote_id 是客户端要连接的 remote_id。常见设备连接场景里，它就是目标设备端的 device_id。

如果要连接本页后面启动的本机设备端，先完成“准备设备端身份”，再用该设备端的 device_id 生成 token。

如果使用自定义接入环境，token issue 和设备端启动必须使用同一个 endpoint：

tirtc-devtools-cli token issue your_remote_id \
  --endpoint "your_endpoint" \
  --openapi-endpoint "your_openapi_endpoint"

执行成功后，CLI 会输出连接 token，并同时给出二维码：

• 连接 token
• 控制台二维码，用于扫码填入本次连接信息
• 本地二维码 PNG 路径，方便在其他设备上打开或分享给测试机扫码

二维码只是连接信息的载体，核心凭证仍然是这次签发的 token。连接 token 带有防重放语义；每次重新扫码、重新连接或连接失败后重试前，都重新执行 token issue 生成新的 token，并使用新的二维码。

目标设备端已在线时，可以用示例客户端扫码验证连接。

启动本机设备端

如果手边没有真实设备端，可以用 device start 在本机启动一个设备端。客户端连上它之后，可以收到一段固定 MP4 的音视频。

本文里的“本机设备端”指 CLI 通过 device start 启动的设备端。它使用的 device_id、device_secret_key、remote_id、stream_id 等名词含义与名词解释一致。

准备设备端身份

本机设备端启动前，需要准备设备身份和接入环境。这些值通常由你的团队在控制台或服务端配置中提供：

export TIRTC_DEVICE_ID="your_device_id"
export TIRTC_DEVICE_SECRET_KEY="your_device_secret_key"
export TIRTC_ENDPOINT="your_endpoint"

客户端连接这个本机设备端时，remote_id 应填写同一个 TIRTC_DEVICE_ID。

生成客户端连接 token 还需要应用凭证。如果前面没有配置过，先配置：

export TIRTC_ACCESS_KEY_ID="your_access_key_id"
export TIRTC_SECRET_KEY_ID="your_secret_key_id"
export TIRTC_APP_ID="your_app_id"

如果还没有为这个本机设备端生成客户端连接 token，可以在这里生成：

tirtc-devtools-cli token issue "$TIRTC_DEVICE_ID"

使用自定义接入环境时，token 生成命令也要传入同一个 TIRTC_ENDPOINT：

tirtc-devtools-cli token issue "$TIRTC_DEVICE_ID" \
  --endpoint "$TIRTC_ENDPOINT" \
  --openapi-endpoint "your_openapi_endpoint"

准备 MP4

本机设备端不会从当前电脑的摄像头或麦克风采集数据，而是循环发送你准备好的 MP4。启动前，需要先用 assets prepare 把这个 MP4 转换成 device start 使用的 manifest.json。

如果你还没有自己的 MP4，可以先下载下面的建议资源：

mkdir -p .build/tirtc-source
curl -L "https://download.tangeopen.com/TIRTC_OPEN_DOC/assets/sea.mp4" \
  -o .build/tirtc-source/sea.mp4

生成 device start 使用的 manifest.json：

tirtc-devtools-cli --json assets prepare \
  --source .build/tirtc-source/sea.mp4 \
  --output-root .build/tirtc-assets

如果使用自己的 MP4，把 --source 改成你的本地文件路径即可。

转换完成后，device start 使用输出目录里的 manifest.json。下面的示例使用固定路径 .build/tirtc-assets/manifest.json。

看到 .build/tirtc-assets/manifest.json 已生成，或 --json 输出里的 manifest_path 指向该文件，就可以继续启动设备端。

设备端会循环发送这段 MP4。音频或视频任一轨道到达文件末尾后，两条轨道会一起从头开始，时间戳继续递增。

启动设备端

启动设备端时必须传入 --source：

tirtc-devtools-cli --json device start \
  --source .build/tirtc-assets/manifest.json \
  --video-codec h264 \
  --artifact-root .build/tirtc-device

--artifact-root 是本次运行的输出目录。CLI 会把日志和运行记录写到这里；联调失败时，保留这个目录和终端输出一起排查。

--video-codec 选择设备端发送的视频编码：

值	说明
h264	默认值，适合常规客户端联调
h265	用于验证客户端 H.265 解码
mjpeg	用于验证客户端 MJPEG 解码

设备端启动成功后，先看这条日志：

[device] listener ready; waiting for client connections

这表示本机设备端已经在等待客户端连接。没有客户端连接不算启动失败；默认情况下，device start 会持续运行，直到你结束进程。只有脚本化测试才建议传入 --duration-ms <ms>。

使用 --json 时，运行日志输出到 stderr，stdout 保留给最终 JSON 结果；如果在脚本里重定向输出，需要同时保留 stderr。

用客户端验证

设备端就绪后，准备 Flutter 客户端示例。可以直接安装预编译 APK：

• Flutter Android 客户端

也可以从源码运行：

git clone https://github.com/tangeai/tirtc-example-flutter.git
cd tirtc-example-flutter
flutter pub get
flutter run -d your_android_device_id

客户端启动后：

1. 点击右上角「扫一扫」，允许相机权限。
2. 扫描前面 token issue 输出的二维码；如果重新扫码或重新连接，先重新生成 token 并使用新的二维码。
3. 回到配置页后，确认 app_id、remote_id、token 已填充。
4. 确认音频使用 stream_id = 10、视频使用 stream_id = 11，然后进入播放页。

客户端连接并收到首包后，设备端通常还会看到：

[device] client connected session=1
[device] first audio packet sent session=1
[device] first video packet sent session=1 codec=h264

本机设备端行为

本机设备端固定使用下面的 stream_id：

媒体	stream_id
音频	10
视频	11

客户端连接成功后，CLI 会直接按上面的 stream_id 发送音视频。它不会等待客户端订阅后才开始发送，也不会根据客户端请求切换到其他 stream_id。

因此，客户端需要把音频输出绑定或订阅到 stream_id = 10，把视频输出绑定或订阅到 stream_id = 11。如果客户端使用其他 stream_id，常见表现是连接成功，但没有声音或黑屏。

本机设备端还会自动回显命令消息：收到任意 command 后，会用同一个命令 ID 和同一份数据内容回复。这个行为默认开启，不需要额外 CLI 参数，可用于验证客户端的命令请求和响应流程。

常见失败

Token 生成失败

优先检查：

• TIRTC_ACCESS_KEY_ID、TIRTC_SECRET_KEY_ID、TIRTC_APP_ID 是否已配置。
• remote_id 是否正确。连接本机设备端时，它应该等于 TIRTC_DEVICE_ID。
• 自定义接入环境下，--endpoint 和 --openapi-endpoint 是否同时传入。

设备端启动失败

优先检查：

• TIRTC_DEVICE_ID、TIRTC_DEVICE_SECRET_KEY、TIRTC_ENDPOINT 是否已配置。
• --source 指向的转换结果或 manifest.json 是否存在。
• --endpoint / TIRTC_ENDPOINT 是否和客户端 token 使用的是同一个接入环境。
• --artifact-root 指向的目录是否可写。

客户端连接后没有声音或画面

优先检查：

• 客户端音频是否绑定或订阅 stream_id = 10，视频是否绑定或订阅 stream_id = 11。
• 客户端版本是否支持当前 --video-codec。H.265 和 MJPEG 需要支持对应解码能力的客户端版本。
• 客户端页面是否已经显示视频视图，并且没有被遮挡或隐藏。

仍然失败时，在本地保留完整命令、CLI 输出、--artifact-root 目录、二维码 PNG 路径和客户端日志。对外发送前，先删除或打码连接 token、二维码、SecretKeyId、device_secret_key 等敏感信息。