TiRTC 开发文档

中文

English

中文

English

Python SDK 接入 ​

更新记录API 说明示例源码

TiRTC Python SDK 面向 macOS 或 Linux 上的无界面应用。它可以连接设备、接收解码或编码音视频帧、保存正在接收的内容、截取视频画面，并收发命令消息和流消息。音视频采集和发布不在 Python SDK 的支持范围内。

完成本页后，你可以运行公开 RTC Example，取得一段 MP4 和一张 JPEG，确认 Python SDK、凭据、设备送流和本机媒体处理都可用。

接入要求 ​

  • CPython 3.11 或后续稳定版本。
  • macOS 11.5 及以上 arm64，或 glibc 2.35 及以上 Linux x86_64。
  • 安装 binary wheel。wheel 已包含 TiRTC Runtime 动态库和第三方许可证，不需要单独下载 C SDK，也不需要设置动态库搜索路径。
  • cache_dir 使用可写的绝对路径。

macOS x86_64、Windows、Linux arm64、free-threaded CPython 和 subinterpreter 不在支持范围内。

安装 SDK ​

以下步骤使用公开的预发布包 2.6.0-alpha.18（Python 包版本为 2.6.0a18）。将同版安装脚本和依赖文件下载到同一目录，在虚拟环境中安装：

bash
curl -fLO https://github.com/tangeai/tirtc-sdk-python/releases/download/v2.6.0-alpha.18/install.py
curl -fLO https://github.com/tangeai/tirtc-sdk-python/releases/download/v2.6.0-alpha.18/requirements.txt
python3 -m venv .venv
source .venv/bin/activate
python install.py
python -c 'import tirtc; print(tirtc.__file__)'

脚本先检查 Python、系统和架构，再按哈希安装对应 wheel。导入命令应输出虚拟环境中的 tirtc 路径。需要合并到业务依赖流程时，先执行 python install.py --check 检查环境，再使用同版 requirements.txt 和 python -m pip install --require-hashes --only-binary=:all: -r requirements.txt；应用的其他依赖也需提供固定版本和哈希。

正式版与预发布版 ​

SDK 版本引用方式
正式版 2.5.0PyPI：python -m pip install --only-binary=:all: tirtc==2.5.0。
预发布版 2.6.0-alpha.18GitHub 同版 install.py 和 requirements.txt。

切换到上述预发布包时，将业务依赖中的 PyPI 版本声明替换为对应 wheel 来源，并更新锁文件。pip install -U tirtc 不会取得 GitHub 上的新版本；Python 包名和 import tirtc 不变。发布到 PyPI 的上层 library 不能在依赖元数据中声明直接 wheel URL，需要由最终应用配置 wheel 来源。

选择鉴权模式 ​

Python SDK 支持两种互斥的鉴权模式：

  • External Token： 应用从业务服务端取得绑定目标设备的短期 Token。适合不能安全保存长期密钥的应用。
  • Access Key： 可信进程直接持有 Access Key ID 和 Secret Key ID。不要把长期密钥放入桌面安装包、脚本仓库、命令行或日志。

两种模式都先创建 ClientOptions。cache_dir 必须是绝对路径：

python
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,
)

External Token 模式不向 Client 传凭据，连接时传短期 Token：

python
with tirtc.Client(options) as client:
    with client.create_connection() as connection:
        connection.connect(
            os.environ["TIRTC_DEVICE_ID"],
            token=os.environ["TIRTC_TOKEN"],
            timeout=120,
        )

Access Key 模式在创建 Client 时传入一对凭据，连接时不再传 Token：

python
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)

同一进程同时只能创建一个 RTC Client。一个 Client 关闭后，才可以改用另一种鉴权模式。

拉取音视频 ​

先创建 Output 并绑定 Stream ID，再连接和订阅。Output 的首个位置参数是帧回调；帧数据是只读 memoryview，持有 Frame 即可在回调后继续访问；需要独立字节副本时使用 bytes(frame.data)。

python
from threading import Event

video_received = Event()

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:
        with tirtc.VideoOutput(lambda frame: video_received.set()) as video:
            video.attach(connection, 11)
            connection.connect(os.environ["TIRTC_DEVICE_ID"], timeout=120)
            connection.subscribe_video(11)
            connection.request_video_keyframe(11)

            if not video_received.wait(30):
                raise TimeoutError("30 秒内没有收到视频帧")

            connection.unsubscribe_video(11)
            video.detach()
            connection.disconnect()

connect() 成功返回时，连接已经进入 CONNECTED。Stream ID 标识同一条连接、一个发送方向中的一路流，取值范围是 0..15。同一方向、同一路流的设备端发送编号，必须与 Python Output 绑定、订阅和请求关键帧时使用的编号一致；同一发送方向内，不同音视频流使用不同编号，音频和视频不能共用编号。相反方向使用独立的编号空间，可以复用相同数值。

本页公开 Example、配套 API Samples 和 DevTools CLI 使用 10 表示设备端音频、11 表示设备端视频。这些只是便于直接联调的示例值，不是 SDK 保留或固定的编号；实际项目可以使用其他有效值，但要同步修改设备端和 Python 端。

用公开 Example 验证 MP4 保存 ​

公开 Example 会同时接收解码和编码音视频帧，并在拉流期间保存 MP4、截取 JPEG、验证命令消息和流消息的发送与接收。开始前确认目标设备正在发送音频流 10 和视频流 11，能够回显 Example 发出的命令，并会向 Example 发送至少一条流消息。DevTools CLI 的 device start 满足这些条件。

bash
git clone --branch sdk-v2.6.0-alpha.18-python https://github.com/tangeai/tirtc-api-samples.git
cd tirtc-api-samples/python/rtc-client

python3 -m venv .venv
source .venv/bin/activate
curl -fLO https://github.com/tangeai/tirtc-sdk-python/releases/download/v2.6.0-alpha.18/install.py
curl -fLO https://github.com/tangeai/tirtc-sdk-python/releases/download/v2.6.0-alpha.18/requirements.txt
python install.py

export TIRTC_APP_ID="your-app-id"
export TIRTC_ACCESS_KEY_ID="your-access-key-id"
export TIRTC_SECRET_KEY_ID="your-secret-key-id"
export TIRTC_DEVICE_ID="your-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

使用自定义服务地址时，另外设置 TIRTC_ENDPOINT，并在命令中加入 --endpoint "$TIRTC_ENDPOINT"。运行成功后，检查两个应用输出文件：

text
output/rtc-recording-stream-11.mp4
output/rtc-snapshot-stream-11.jpg

可用 ffprobe output/rtc-recording-stream-11.mp4 检查音视频轨、编码格式和时长。Example 会把 SDK cache 中的临时文件复制到 output，因此程序结束后这两个应用文件仍然保留。

接入客户端诊断能力（推荐） ​

创建 Client 后，建议在开发阶段为应用预留日志上传入口。这样在需要平台协助诊断时，可以直接上传同一次复现的日志；入口设计和上传结果处理见接入客户端诊断能力。

释放资源 ​

常规释放顺序是：停止 RecordingTask，取消订阅并 Detach/关闭 Output，断开并关闭 Connection，最后关闭 Client。使用 with 管理这些对象可以在异常路径执行同样的收口。

import tirtc 不会创建线程、目录或网络连接。进程内已经有活动 Client 时不要调用 fork()；需要多进程时，在通过 spawn 创建的 worker 内初始化 SDK。

下一步 ​

TiRTC 开发文档

Copyright © 2025