TiRTC Android API Reference

• Integration Guide

Object Overview

TiRtc

• Initializes the full SDK runtime
• Configures base behavior
• Uninitializes the SDK when the process no longer uses it

TiRtcDebugging

• Uploads logs asynchronously
• Returns a shareable logId

TiRtcConn

• Connects to a remote peer actively
• Sends and receives commands
• Sends and receives stream messages
• Acts as the binding target for audio and video outputs

TiRtcAudioOutput / TiRtcVideoOutput

• Play remote audio
• Render remote video

TiRtcAudioBinding / TiRtcVideoBinding

• Bind an output to a connection and its corresponding streamId
• Audio and video each use their own streamId
• Mainly intended for direct Java calls

RtcConnCommand / RtcConnCommandResponse / RtcStreamMessage

• Carry command, command-response, and in-stream message payloads
• Used in callbacks and request-response results

TiRtc

Constants

TiRtc.ENV_TEST = 0
TiRtc.ENV_PRE = 1
TiRtc.ENV_PROD = 2

TiRtc.Config.Builder

val config =
  TiRtc.Config.Builder(context)
    .setEnableConsoleLog(BuildConfig.DEBUG)
    .build()

Common fields:

• context: required. Pass an application-level Context
• setEnvironment(value): optional. Accepts only 0 / 1 / 2
• setEnableConsoleLog(value): optional. Recommended to use BuildConfig.DEBUG
• setEndpoint(value): optional. Use only when your environment explicitly requires a custom entry endpoint

initialize(config: Config): Int

Initializes the SDK.

• 0: success
• non-zero: failure

setTransportDebugEnabled(enabled: Boolean): Int

Enables or disables transport debug logging.

uninitialize()

Uninitializes the SDK.

TiRtcDebugging

uploadLogs(callback: UploadLogsCallback): Int

val submitCode =
  TiRtcDebugging.uploadLogs(
    object : TiRtcDebugging.UploadLogsCallback {
      override fun onSuccess(logId: String) {
        println("logId=$logId")
      }

      override fun onFailure(code: Int, message: String) {
        println("upload failed code=$code message=$message")
      }
    },
  )

The return value only indicates whether the upload task was accepted. The actual result is reported through the callback.

TiRtcConn

Lifecycle

1. Create the object
2. setObserver(...)
3. connect(...)
4. Bind audio and video outputs
5. Send and receive commands and messages
6. disconnect()
7. destroy()

TiRtcConn()

Creates a connection object.

The SDK must already be initialized before construction. If native object creation fails, the constructor throws an exception.

setObserver(observer: Observer?): Int

Set the observer before connect(...).

connect(peerId: String, token: String): Int

• peerId: remote target identifier
• token: connection authorization token

disconnect(): Int

Disconnects the connection.

destroy(): Int

Releases the connection object resources.

• disconnect() is not the same as destroy()
• You still need to call destroy() explicitly when the object itself is no longer used

sendCommand(commandId: Int, data: ByteArray): Int

Sends a one-way command.

• commandId must be agreed with the remote protocol
• The valid range is 0x1000..0x7FFF
• Values below 0x1000 are reserved for internal runtime commands

requestCommand(commandId: Int, data: ByteArray, timeoutMs: Long, callback: CommandCallback): Int

Sends a request-response command.

• commandId must be agreed with the remote protocol
• The valid range is 0x1000..0x7FFF
• Values below 0x1000 are reserved for internal runtime commands
• Requests and responses usually reuse the same commandId

replyRemoteCommand(remoteRequestId: Long, commandId: Int, data: ByteArray): Int

• remoteRequestId: the unique identifier of the remote request being replied to
• Use it to associate this reply with the original request

sendStreamMessage(streamId: Int, timestampMs: Long, data: ByteArray): Int

Sends an in-stream message.

• The message is bound to the specified streamId
• That streamId must not conflict with any bound audio or video streamId
• The remote side receives it through onStreamMessageReceived(streamId, message)

Common Kotlin Extension Methods

conn.attachAudioOutput(audioStreamId, audioOutput)
conn.detachAudioOutput(audioStreamId)
conn.attachVideoOutput(videoStreamId, videoOutput)
conn.detachVideoOutput(videoStreamId)
conn.requestKeyframe(videoStreamId)

In Kotlin, these extension methods are the preferred API shape. If you use Java, use TiRtcAudioBinding and TiRtcVideoBinding instead.

Observer

interface Observer {
  fun onStateChanged(state: TiRtcConn.State)

  fun onDisconnected(errorCode: Int)

  fun onRemoteCommandRequest(
    remoteRequestId: Long,
    command: RtcConnCommand,
  )

  fun onStreamMessageReceived(
    streamId: Int,
    message: RtcStreamMessage,
  )

  fun onError(code: Int, message: String)
}

CommandCallback

interface CommandCallback {
  fun onSuccess(response: RtcConnCommandResponse)

  fun onFailure(code: Int, message: String)
}

State

• IDLE
• CONNECTING
• CONNECTED
• DISCONNECTED

Callback threads are not fixed. Switch back to the main thread yourself before updating the UI.

RtcConnCommand

• commandId: Int
• data: ByteArray

RtcConnCommandResponse

• commandId: Int
• data: ByteArray

RtcStreamMessage

• timestampMs: Long
• data: ByteArray

TiRtcAudioOutput

Lifecycle

1. Create the object
2. TiRtcAudioBinding.attachOutput(connection, audioStreamId, output)
3. Play remote audio
4. TiRtcAudioBinding.detachOutput(connection, audioStreamId)
5. destroy()

setOptions(options: RtcAudioOutputOptions): Int

Sets playback-related parameters.

setObserver(observer: Observer?): Int

Observes output state and errors.

destroy(): Int

Releases audio output resources.

TiRtcVideoOutput

attach(container: ViewGroup): Int

• Must be called on the UI thread
• The argument is the parent container, not a TextureView
• The SDK creates and manages the actual internal TextureView by itself
• If another container is already bound, call detach() first

detach(): Int

Detaches the parent container binding.

• The SDK removes only the internal render view that it created itself
• It does not delete or reorder other existing child views in the parent container

setObserver(observer: Observer?): Int

Observes rendering state, size changes, and errors.

destroy(): Int

Releases video output resources.

TiRtcAudioBinding

attachOutput(connection, streamId, output): Int

Binds an audio output to a connection and an audio streamId.

detachOutput(connection, streamId): Int

Detaches the output binding for an audio streamId.

TiRtcVideoBinding

attachOutput(connection, streamId, output): Int

Binds a video output to a connection and a video streamId.

detachOutput(connection, streamId): Int

Detaches the output binding for a video streamId.

requestKeyframe(connection, streamId): Int

Explicitly requests a keyframe from the remote side.

Common Constraints

streamId

• The Android-side type is Int
• The valid range must be 0..255
• Audio and video are bound through their own streamId
• Audio streamId and video streamId must be provided separately

Error Codes

Most synchronous APIs return Int:

• 0: success
• non-zero: failure

TiRtcConn.Observer.onError(...) and onDisconnected(...) use the same unified error-code family:

• 0: local disconnect, not a failure
• other negative values: Android-mapped values derived from TirtcError in runtime/core/foundation/include/public/tirtc/error.h
• common values include -10 timeout, -13 remote closed, and -15 token expired

Threading Semantics

Ordinary control-plane APIs do not require you to switch to a dedicated IO thread.

The following APIs must still respect Android UI thread constraints:

• TiRtcVideoOutput.attach(container)
• TiRtcVideoOutput.detach()
• TiRtcVideoOutput.destroy() when a video container is already bound

The SDK does not guarantee that all callbacks run on the main thread, and it does not guarantee that all callbacks run on the same background thread.

Lifecycle Pairing

• initialize ↔ uninitialize
• connect ↔ disconnect
• attachOutput ↔ detachOutput
• attach(container) ↔ detach()
• object creation ↔ destroy()

Constructor-Time Exceptions

The following objects throw an exception if native creation fails:

• TiRtcConn
• TiRtcAudioOutput
• TiRtcVideoOutput

Common Misuse

Treating detach() as destroy()

The object resources themselves are not released.

Creating your own TextureView and passing it to the SDK

The current contract accepts a parent container, not the render view itself.

Assuming callbacks always run on the main thread

The SDK makes no such guarantee.

Calling connect(...) before setting the observer

That makes it easier to miss the first state transitions or error clues.

Creating connection or output objects before initialization

If you create objects before initialization, construction may fail immediately.

Related Docs

• Integration Guide