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

建议在虚拟环境中安装发布包：

bash

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

将 VERSION 替换为更新记录中需要接入的版本。

执行以下命令确认 package 可以导入：

bash

python -c 'import tirtc; print(tirtc.__file__)'

选择鉴权模式

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 的首个位置参数是帧回调；帧数据只在 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 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

使用自定义服务地址时，另外设置 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。

下一步

查看连接设备，了解状态变化和断线处理。
查看播放音视频，了解多路接收、MP4 和 JPEG 文件生命周期。
查阅 Python API 说明。

Python SDK 接入 ​

接入要求 ​

安装 SDK ​

选择鉴权模式 ​

拉取音视频 ​

用公开 Example 验证 MP4 保存 ​

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

释放资源 ​

下一步 ​

Python SDK 接入

接入要求

安装 SDK

选择鉴权模式

拉取音视频

用公开 Example 验证 MP4 保存

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

释放资源

下一步