Python API reference

The RTC API is exported from the root tirtc package. Client owns the local resource tree and creates Connection objects. Applications create and own media Output objects independently.

See Integrate the Python SDK and the public RTC sample for complete flows.

Client and authentication

ClientOptions contains app_id, an absolute cache_dir, an optional endpoint, and console_log_enabled. It does not store credentials.

Create Client(options) for External Token mode. Create Client(options, access_key_id=..., access_key_secret=...) for Access Key mode. Supplying only one credential is invalid. Only one RTC Client may be active in a process, and authentication modes cannot coexist.

Client.create_connection() accepts on_state_changed, on_command, and on_stream_message callbacks. Client.upload_logs() returns a log ID. Client.close() is idempotent and closes its Connection tree after detaching bound Outputs.

Connection

Connection.connect(device_id, *, token=None, timeout=30) is synchronous and bounded. When it returns successfully, state is ConnectionState.CONNECTED. External Token clients must pass token; Access Key clients must omit it. The maximum timeout is 120 seconds.

The public operations are:

• disconnect() and close()
• subscribe_audio(stream_id) / unsubscribe_audio(stream_id)
• subscribe_video(stream_id) / unsubscribe_video(stream_id)
• request_video_keyframe(stream_id)
• send_command(command_id, data)
• send_stream_message(stream_id, timestamp, data)
• start_recording(video_stream_id=..., audio_stream_id=...)

Stream IDs range from 0 through 15. Customer command IDs range from 0x2001 through 0xffffffff. A stream-message timestamp is a timedelta with an exact whole-millisecond value from 0 through 0xffffffff milliseconds.

Outputs and frames

AudioOutput, VideoOutput, EncodedAudioOutput, and EncodedVideoOutput provide attach(connection, stream_id), detach(), state, idempotent close(), and context-manager support. VideoOutput also provides take_snapshot().

The first on_frame constructor argument is required. Frames are immutable, and media data is exposed as a read-only memoryview. Copy it with bytes(frame.data) if it must outlive the callback or be modified.

Closing a Connection or Client detaches Outputs but does not close them. The application remains responsible for closing each Output.

Recording and snapshots

Connection.start_recording() returns a RecordingTask; stop() returns a RecordingFile. VideoOutput.take_snapshot() returns a SnapshotFile. Both file types expose a path in the SDK cache. Copy files that must be retained into an application-owned directory, then call the idempotent delete() method or use the file as a context manager.

Errors and process lifecycle

Invalid Python types and values raise TypeError and ValueError. Native failures raise TiRTCError or one of its stable subclasses. Caller-side timeouts raise OperationTimeoutError(code=None).

Release resources in this order: finish recording tasks; unsubscribe, detach, and close Outputs; disconnect and close Connections; then close the Client. Importing tirtc has no Runtime side effects. Do not fork after a Client becomes active; create the Client inside a spawned worker process instead.