Use DevTools CLI

DevTools CLI is for development and integration. Use it to issue temporary client connection token values. The CLI also prints a QR code so the example client can scan and fill the connection information. When no real device is available, you can also start a local device so clients can connect and receive audio/video from a fixed MP4.

Production connection tokens should be issued by your backend service. The CLI is for development and debugging.

Prerequisite

Prepare these items before you start:

Item	Used for	Where to get it
Node.js / npm	Install and run the CLI	Your local development environment
AccessKeyId, SecretKeyId, AppId	Issue client connection token values	Provided by your team through the console or backend configuration
device_id, device_secret_key, endpoint	Start a local device	Provided by your team through the console or backend configuration
OpenAPI endpoint	Issue a token in a non-default environment	Provided by your team; usually not needed for the default environment
MP4 file	Audio/video content sent by the local device	Use your own MP4 or download the suggested file in this page

Install or update:

npm install -g tirtc-devtools-cli@latest

Check the installation:

tirtc-devtools-cli --help

Issue a Connection Token

Use token issue when a client needs to connect to a device. The command issues a temporary connection token.

Before issuing a token, prepare:

• AccessKeyId
• SecretKeyId
• AppId
• the target remote_id

Set them as environment variables:

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"

Issue a token:

tirtc-devtools-cli token issue your_remote_id

To connect to the local device started later in this page, prepare the device identity first, then issue a token with that device's device_id as the remote_id.

For a non-default environment, pass both endpoints:

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

On success, the CLI prints the connection token and a QR code:

• connection token
• terminal QR code, used to scan this connection information into the example client
• local QR PNG path, useful when the test device needs to open or scan the QR image

The QR code is only a carrier for the connection information; the actual credential is still the issued token. Connection tokens have anti-replay semantics. Before each new scan, reconnect attempt, or retry after a failed connection, run token issue again to generate a fresh token and use the fresh QR code.

When the target device is online, use the example client to scan the QR code and verify the connection.

Start a Local Device

Use device start when you do not have a real device available. After a client connects to this local device, it receives audio and video from a fixed MP4.

Starting a local device requires:

• device_id
• device_secret_key
• service endpoint
• a local MP4 file

Prepare the Device Identity

Prepare the local device identity and endpoint before startup. These values are usually provided by your team through the console or backend configuration:

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

When the client connects to this local device, its remote_id should be the same TIRTC_DEVICE_ID.

Issuing the client connection token also needs application credentials. If you have not configured them earlier, configure them here:

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"

If you have not issued a client connection token for this local device yet, issue it here:

tirtc-devtools-cli token issue "$TIRTC_DEVICE_ID"

For a non-default environment, pass the same TIRTC_ENDPOINT when issuing the token:

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

Prepare the MP4

The local device does not capture from your computer's camera or microphone. It sends audio/video from the MP4 you prepare, so run assets prepare first to generate the manifest.json used by device start.

If you do not have your own MP4 yet, download this suggested file first:

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

Generate the manifest.json used by device start:

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

If you use your own MP4, replace --source with your local file path.

After conversion, device start uses the generated manifest.json. The examples below use the fixed path .build/tirtc-assets/manifest.json.

Continue when .build/tirtc-assets/manifest.json exists, or when the manifest_path field in the --json output points to that file.

The local device sends this MP4 in a loop. When either the audio or video track reaches the end, both tracks restart from offset 0 while timestamps keep increasing.

Start the Device

Pass --source when starting the device:

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

--artifact-root is the output directory for this run. The CLI writes logs and run records there. Keep this directory together with terminal output when troubleshooting.

--video-codec selects the video codec sent by the device:

Value	Description
h264	Default. Use it for the most common client integration path.
h265	Use it to verify H.265 video decoding.
mjpeg	Use it to verify MJPEG video decoding.

The local device uses fixed media stream IDs:

Media	stream_id
Audio	10
Video	11

After a client connects, the CLI immediately sends audio and video on those stream IDs. This device is not subscription-driven: it does not wait for the client to subscribe before sending media, and it does not switch to a different stream_id based on a client request.

When using any client for integration, bind or subscribe the audio output to stream_id = 10 and the video output to stream_id = 11. If the client is hard-coded to other stream IDs, the connection may succeed but audio/video output will stay silent or blank.

The local device also echoes command messages automatically: for every command it receives, it replies with the same command ID and the same data payload. This behavior is enabled by default and does not require any extra CLI option. Use it to verify the client's command request/response flow.

When startup succeeds, lifecycle logs are written to stderr. First, check for this log:

[device] listener ready; waiting for client connections

A missing client is not a device startup failure. By default, device start keeps running until you stop it. Use --duration-ms <ms> only for bounded automation.

With --json, runtime logs are written to stderr, while stdout is reserved for the final JSON result. If a script redirects output, keep stderr as well.

Verify with a Client

After the device is ready, prepare a client example. The fastest path is the Flutter Android prebuilt APK:

• Flutter Android client

Or run a client from source.

Flutter Android client:

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

HarmonyOS native client:

git clone https://github.com/fengjundev/tirtc-example-ohos.git
cd tirtc-example-ohos
ohpm install

The HarmonyOS example currently takes app_id, remote_id, and token manually on its configuration page. Leave stream IDs empty to use the defaults 10 / 11.

After the client starts:

1. Tap the scan button in the upper-right corner and allow camera access.
2. Scan the QR code printed by token issue; if you scan again or reconnect, issue a fresh token first and use the fresh QR code.
3. After returning to the configuration page, check that app_id, remote_id, and token are filled.
4. Make sure audio uses stream_id = 10 and video uses stream_id = 11, then enter the playback page.

After the client connects and receives the first packets, the device usually shows:

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

Common Failures

Token Issue Fails

Check:

• whether TIRTC_ACCESS_KEY_ID, TIRTC_SECRET_KEY_ID, and TIRTC_APP_ID are configured;
• whether remote_id is correct. For a local device, it should equal TIRTC_DEVICE_ID;
• whether both --endpoint and --openapi-endpoint are passed for a non-default environment.

Device Startup Fails

Check:

• whether TIRTC_DEVICE_ID, TIRTC_DEVICE_SECRET_KEY, and TIRTC_ENDPOINT are configured;
• whether --source points to the converted output directory or manifest.json;
• whether --endpoint / TIRTC_ENDPOINT matches the endpoint used by the client token.
• whether the --artifact-root directory is writable.

Client Connects but Has No Audio or Video

Check:

• whether audio is bound or subscribed to stream_id = 10, and video is bound or subscribed to stream_id = 11;
• whether the client version supports the selected --video-codec; H.265 and MJPEG need a client version with the corresponding decoder support;
• whether the video output widget is mounted in a visible view tree.

If the problem remains, keep the full command, CLI output, --artifact-root directory, QR PNG path, and client logs locally. Before sharing them externally, remove or mask connection tokens, QR codes, SecretKeyId, device_secret_key, and other sensitive values.