使用 CLI 工具

DevTools CLI 是开源的开发者工具，适合在开发、联调和问题复现阶段使用。完整源代码可以在 tangeai/tirtc-developer-tools 获取。

主要能力有：

启动一个 token 签发 HTTP 服务，按 TiRTC token 规则签发连接 token
启动一个模拟设备端：把给定的 MP4 文件作为设备端音视频数据源，供客户端连接、拉流调试

运行环境

支持 macOS arm64 以及 Linux x86_64。

前置步骤

准备项	用在哪里
Node.js / npm	安装和运行 CLI
`AccessKeyId`、`SecretKeyId`	启动开发用 token 服务
`AppId`	客户端初始化
`device_id`、`device_secret_key`	启动模拟设备端、签发连接 token
MP4 文件	模拟设备端发送的音视频内容

安装或更新 CLI：

bash

npm install -g tirtc-devtools-cli@latest

确认 CLI 可用：

bash

tirtc-devtools-cli --help

启动一个 token 签发 HTTP 服务

token serve 会启动一个 HTTP 服务，用来模拟业务服务端签发 token 这一步。它可以跑在你的电脑、云服务器或 Docker 容器里；客户端只需要配置服务地址，例如 http://192.168.1.10:8966，连接前会请求固定的 /v1/tokens 接口获取连接 token。

这个服务只适合开发和受控联调。它不会替你判断：
请求 token 的用户是谁，是否是合法用户。
这个用户是否有权限访问 remote_id 对应的设备。
生产环境应由你的业务服务端先完成登录鉴权和设备权限判断，再签发连接 token。

1. 配置凭证

bash

export TIRTC_ACCESS_KEY_ID="your_access_key_id"
export TIRTC_SECRET_KEY_ID="your_secret_key_id"
export TIRTC_DEVICE_SECRET_KEY="your_device_secret_key"

如果只调试一台设备，可以继续使用 TIRTC_DEVICE_SECRET_KEY。如果要同时服务多台设备，准备一个 JSON 映射文件：

json

{
  "device-001": "device_001_secret_key",
  "device-002": "device_002_secret_key"
}

然后改用映射文件：

bash

export TIRTC_DEVICE_SECRET_MAP="./device-secrets.json"

2. 启动服务

bash

tirtc-devtools-cli token serve \
  --port 8966

使用映射文件时，也可以不设置 TIRTC_DEVICE_SECRET_MAP，直接在命令里传：

bash

tirtc-devtools-cli token serve \
  --port 8966 \
  --device-secret-map ./device-secrets.json

启动成功后，CLI 会输出：

开发用 token 服务监听地址
Token 签发服务地址，例如 http://192.168.1.10:8966
HTTP 请求示例，例如 POST /v1/tokens
可直接复制运行的 cURL 示例

保持这个进程运行。客户端配置页里的“Token 签发服务地址”填写客户端能访问到的服务地址，例如 http://your_computer_lan_ip:8966。

如果不知道当前电脑的局域网 IP，可以在运行 CLI 的机器上查看：

bash

# macOS
ipconfig getifaddr en0

# Linux
hostname -I

3. HTTP 请求协议

token serve 提供的是一个普通 HTTP JSON 接口。你可以让自己的客户端、脚本或调试页面直接请求它。

请求：

http

POST /v1/tokens
Content-Type: application/json

请求 body：

json

{
  "remote_id": "device-001",
  "subject": "dev-user-001",
  "ttl_seconds": 300
}

字段说明：

字段	必填	类型	说明
`remote_id`	是	string	客户端要连接的目标标识。常见设备连接场景里就是目标设备的 `device_id`；也可以写成 `device://device-001`。
`subject`	否	string	这次 token 对应的主体标识，写入 token payload 的 `sub`。不传时使用服务启动时的默认 subject。
`ttl_seconds`	否	number	token 有效期，单位秒。不传时默认 `300`；当前最大值为 `86400`。

成功响应：

json

{
  "token": "v1.<payload_b64>.<app_sig>",
  "payload": {
    "sub": "dev-user-001",
    "scope": "connect:device://device-001",
    "iss": "your_access_key_id",
    "iat": 1710000000,
    "exp": 1710000300,
    "nonce": "random_nonce"
  }
}

客户端拿到响应后，只需要把 token 字段传给 TiRTC SDK 的连接接口；payload 主要用于调试和排查。

请求示例：

bash

curl -sS -X POST "http://your_token_service_host:8966/v1/tokens" \
  -H "Content-Type: application/json" \
  --data '{"remote_id":"device-001"}'

错误响应：

json

{
  "error": {
    "code": "invalid_request",
    "message": "missing required input: remote_id",
    "data": {
      "field": "remote_id"
    }
  }
}

常见状态码：

状态码	说明
`200`	签发成功
`400`	请求 JSON 无效、缺少 `remote_id`、`ttl_seconds` 非法或传入未知字段
`404`	请求路径不存在，或使用了非 `POST` 方法
`500`	服务内部错误，例如随机数或签名过程失败

启动一个模拟设备端

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

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

配置信息

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

bash

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。

准备 MP4

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

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

bash

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：

bash

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

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

启动模拟设备端

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

bash

tirtc-devtools-cli --json device start \
  --source .build/tirtc-assets/manifest.json \
  --video-codec h264 \
  --audio-codec g711a \
  --audio-sample-rate 8000 \
  --artifact-root .build/tirtc-device

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

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

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

音频相关参数：

参数	可选值	默认值	说明
`--audio-codec`	`g711a` / `aac`	`g711a`	选择模拟设备端发送的音频编码
`--audio-sample-rate`	`8000` / `16000`	`8000`	选择 8 kHz 或 16 kHz 音频采样率
`--audio-channels`	`1` / `2`	`1`	选择单声道或双声道

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

text

[device] listener ready; waiting for client connections

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

用客户端验证

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

Flutter Android 客户端

也可以从源码运行：

bash

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

客户端启动后：

填写 AppId、endpoint、remote_id 和“Token 签发服务地址”。
remote_id 使用模拟设备端的 TIRTC_DEVICE_ID。
“Token 签发服务地址”填写 token serve 输出的服务地址，例如 http://your_computer_lan_ip:8966。
确认音频使用 stream_id = 10、视频使用 stream_id = 11，然后进入播放页。

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

text

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

模拟设备端的其他行为说明

固定使用音频 stream_id = 10、视频 stream_id = 11。
客户端连接成功后，模拟设备端会直接发送音视频，不等待客户端订阅。
客户端如果使用其他 stream_id，常见表现是连接成功，但没有声音或黑屏。
收到 command 后，模拟设备端会用同一个命令 ID 和同一份数据内容自动回复。

常见失败

token 服务没有启动成功

按 CLI 输出先看是哪一类问题：

提示缺少 TIRTC_ACCESS_KEY_ID 或 TIRTC_SECRET_KEY_ID：在启动服务的同一个终端里重新 export 这两个变量。
提示缺少 TIRTC_DEVICE_SECRET_KEY：单设备调试时需要配置它；多设备调试时改用 TIRTC_DEVICE_SECRET_MAP 或 --device-secret-map。

使用设备密钥映射文件时，先确认文件存在且 JSON 合法：

bash

echo "$TIRTC_DEVICE_SECRET_MAP"
test -f "$TIRTC_DEVICE_SECRET_MAP"
python3 -m json.tool "$TIRTC_DEVICE_SECRET_MAP" >/dev/null

如果服务刚启动就退出，并输出 issuer server failed，先把命令里的 --port 8966 改成另一个端口，再同步修改客户端里的“Token 签发服务地址”。

客户端请求 token 失败

先用客户端配置页里填写的服务地址加上 /v1/tokens 发一次请求：

bash

curl -sS -X POST "http://your_token_service_host:8966/v1/tokens" \
  -H "Content-Type: application/json" \
  --data '{"remote_id":"your_device_id"}'

如果请求连不上，说明这个服务地址当前不可访问；先检查主机名/IP、端口。手机作为客户端时，不要填 127.0.0.1，要填运行 CLI 的机器在局域网里的 IP。
如果返回 missing required input: remote_id，检查请求 body 是否传了 remote_id。
如果返回 device secret key not found for remote_id，说明多设备映射文件里没有这个设备；把请求里的 remote_id 改成映射文件里已有的设备 ID，或补上对应密钥。
连接模拟设备端时，请求里的 remote_id 要等于模拟设备端启动时使用的 TIRTC_DEVICE_ID。
请求 body 只传 remote_id、subject、ttl_seconds；不要把 access_key_id、secret_key_id 或 device_secret_key 放进请求 body。

MP4 转换失败

先确认文件路径和媒体轨道，把 <your_mp4_path> 换成你传给 --source 的文件：

bash

ls -lh <your_mp4_path>
ffprobe -hide_banner <your_mp4_path>

如果 ls 提示文件不存在，修正 assets prepare --source 的路径。
如果 ffprobe 输出里看不到 Audio 或 Video，换一个同时包含音频和视频的 MP4。
如果提示找不到 ffprobe，先安装 FFmpeg，再重新执行 assets prepare。macOS 可以用 brew install ffmpeg，Ubuntu / Debian 可以用 sudo apt-get install ffmpeg。

模拟设备端没有启动成功

按报错信息处理：

提示缺少 device id、device secret key 或 endpoint：在同一个终端里配置 TIRTC_DEVICE_ID、TIRTC_DEVICE_SECRET_KEY、TIRTC_ENDPOINT。
提示 asset_missing：先确认 manifest.json 存在，再把 --source 指向这个文件或它所在的目录。
bash
```
ls -lh .build/tirtc-assets/manifest.json
```
提示 codec 或 audio format 不支持：--video-codec 只能是 h264、h265、mjpeg；--audio-codec 只能是 g711a、aac；--audio-sample-rate 只能是 8000 或 16000。

如果写不出日志或 summary，先确认 --artifact-root 目录可写：

bash

mkdir -p .build/tirtc-device
touch .build/tirtc-device/.write-test
rm .build/tirtc-device/.write-test

客户端连不上模拟设备端

重点对齐三项连接信息：

客户端填写的 endpoint 要和模拟设备端的 TIRTC_ENDPOINT 一致。
客户端填写的 AppId 要属于同一个接入环境。
客户端拿到的 token 要由当前 token 服务签发；请求 token 时使用的 remote_id 要等于模拟设备端的 TIRTC_DEVICE_ID。

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

常见原因通常是 stream id 或 codec 不匹配：

客户端音频绑定或订阅 stream_id = 10，视频绑定或订阅 stream_id = 11。
如果模拟设备端使用了 h265、mjpeg 或 aac，确认客户端版本已经支持对应解码能力。

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

使用 CLI 工具 ​

运行环境 ​

前置步骤 ​

启动一个 token 签发 HTTP 服务 ​

1. 配置凭证 ​

2. 启动服务 ​

3. HTTP 请求协议 ​

启动一个模拟设备端 ​

配置信息 ​

准备 MP4 ​

启动模拟设备端 ​

用客户端验证 ​

模拟设备端的其他行为说明 ​

常见失败 ​

token 服务没有启动成功 ​

客户端请求 token 失败 ​

MP4 转换失败 ​

模拟设备端没有启动成功 ​

客户端连不上模拟设备端 ​

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

使用 CLI 工具

运行环境

前置步骤

启动一个 token 签发 HTTP 服务

1. 配置凭证

2. 启动服务

3. HTTP 请求协议

启动一个模拟设备端

配置信息

准备 MP4

启动模拟设备端

用客户端验证

模拟设备端的其他行为说明

常见失败

token 服务没有启动成功

客户端请求 token 失败

MP4 转换失败

模拟设备端没有启动成功

客户端连不上模拟设备端

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