Integrate the Python SDK

The TiRTC Python SDK is for headless macOS and Linux applications. It can connect to a device, receive decoded or encoded audio and video frames, save received media as MP4, take JPEG snapshots, and exchange command and stream messages. It does not publish captured audio or video.

Requirements

• CPython 3.11 or a later stable release.
• macOS 11.5+ on arm64, or Linux x86_64 with glibc 2.35+.
• A writable absolute cache directory.

The binary wheel contains the TiRTC Runtime libraries and third-party notices. You do not need to install the C SDK or configure a library search path.

Install

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --only-binary=:all: tirtc==2.5.0a4

Authenticate and connect

Use External Token mode when the application receives a short-lived device-bound token from your service. Use Access Key mode only in a trusted process that can protect long-lived credentials.

import os
from pathlib import Path

import tirtc

options = tirtc.ClientOptions(
    app_id=os.environ["TIRTC_APP_ID"],
    cache_dir=Path(".tirtc-cache").resolve(),
    endpoint=os.environ.get("TIRTC_ENDPOINT") or None,
)

with tirtc.Client(
    options,
    access_key_id=os.environ["TIRTC_ACCESS_KEY_ID"],
    access_key_secret=os.environ["TIRTC_SECRET_KEY_ID"],
) as client:
    with client.create_connection() as connection:
        connection.connect(os.environ["TIRTC_DEVICE_ID"], timeout=120)

For External Token mode, omit both Access Key arguments and pass token=os.environ["TIRTC_TOKEN"] to connect(). Only one RTC Client may be active in a process.

Run the public RTC sample

The sample receives decoded and encoded media, records MP4 while receiving, takes a JPEG snapshot, and checks command and stream-message sending and reception. The device must publish audio stream 10 and video stream 11, echo the sample command, and send at least one stream message. DevTools CLI device start provides this behavior.

git clone https://github.com/tangeai/tirtc-api-samples.git
cd tirtc-api-samples/python/rtc-client
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --only-binary=:all: -r ../requirements.txt

export TIRTC_APP_ID=<app-id>
export TIRTC_ACCESS_KEY_ID=<access-key-id>
export TIRTC_SECRET_KEY_ID=<access-key-secret>
export TIRTC_DEVICE_ID=<device-id>

python main.py \
  --auth-mode access-key \
  --device-id "$TIRTC_DEVICE_ID" \
  --cache-dir "$(pwd)/.cache" \
  --output-dir "$(pwd)/output" \
  --audio-stream-id 10 \
  --video-stream-id 11 \
  --timeout 120

A successful run leaves output/rtc-recording-stream-11.mp4 and output/rtc-snapshot-stream-11.jpg. Use ffprobe to inspect the MP4 tracks, codecs, and duration.

See the Python API reference, release notes, and public sample.