Android API Reference

• Integration Guide

Primary Path Overview

Android v1 documents a single client-role primary path:

• TiRtc: initialize and shut down the global runtime
• TiRtcConn: create one outbound connection, send and receive commands or stream messages, request key frames
• TiRtcAudioOutput: consume remote audio
• TiRtcVideoOutput: consume remote video and bind rendering through attachView(container)
• TiRtcLogging: write SDK logs and upload log bundles

Typical flow:

1. TiRtc.initialize(context, TiRtcInitOptions(appId = "..."))
2. TiRtcConn()
3. Assign listener properties
4. connect(remoteId, token)
5. TiRtcAudioOutput.attach(connection, streamId)
6. TiRtcVideoOutput.attach(connection, streamId)
7. TiRtcVideoOutput.attachView(container)
8. Call release() on owned objects, then TiRtc.shutdown()

Minimal Example

val initCode = TiRtc.initialize(
  context = applicationContext,
  config = TiRtcInitOptions(appId = appId),
)
check(initCode == 0)

val conn = TiRtcConn()
val audioOutput = TiRtcAudioOutput()
val videoOutput = TiRtcVideoOutput()

conn.onStateChanged = TiRtcConnStateListener { state, errorCode ->
  println("conn state=$state errorCode=$errorCode")
}
conn.onCommand = TiRtcConnCommandListener { command, data ->
  println("command=$command bytes=${data.size}")
}
conn.onStreamMessage = TiRtcConnStreamMessageListener { streamId, timestampMs, data ->
  println("streamId=$streamId ts=$timestampMs bytes=${data.size}")
}

conn.connect(remoteId, token)
check(audioOutput.attach(conn, audioStreamId) == 0)
check(videoOutput.attach(conn, videoStreamId) == 0)
check(videoOutput.attachView(videoContainer) == 0)

Callback And Lifecycle Rules

• Client-facing listeners are always delivered on the Android main looper
• disconnect(), detach(), and release() are cleanup-friendly; repeated calls in the already-clean state succeed as no-ops
• Connection close and connection failure are reported through onStateChanged(state, errorCode)
• TiRtc.shutdown() succeeds only after every object that still owns a native handle has been cleaned up; any unreleased TiRtcConn, TiRtcAudioOutput, or TiRtcVideoOutput keeps shutdown in INVALID_STATE

TiRtc

initialize(context: Context, config: TiRtcInitOptions): Int

val code = TiRtc.initialize(
  context = applicationContext,
  config = TiRtcInitOptions(
    appId = appId,
    endpoint = "",
    consoleLogEnabled = BuildConfig.DEBUG,
  ),
)

• context: required; the SDK stores applicationContext
• config.appId: your TiRTC application id
• config.endpoint: optional; leave empty to use the runtime default endpoint
• config.consoleLogEnabled: optional console log mirroring switch, default false

shutdown(): Int

• Shuts the global runtime down
• If the runtime is already uninitialized, shutdown() succeeds as a no-op
• Call it only after every connection and output object has been cleaned up
• The SDK does not force-destroy live objects; shutdown returns INVALID_STATE while any live object remains

TiRtcConn

States

• IDLE
• CONNECTING
• CONNECTED
• DISCONNECTED

Listener Properties

var onStateChanged: TiRtcConnStateListener?
var onCommand: TiRtcConnCommandListener?
var onStreamMessage: TiRtcConnStreamMessageListener?

• Observer and setObserver(...) are no longer part of the client primary path
• Listeners can be assigned or cleared independently after construction
• Accepted connections follow the same listener contract; the SDK replays early events so a late listener assignment does not lose the initial CONNECTED, the following disconnect, the first command, or the first stream message

TiRtcConn()

• Public no-arg constructor
• Requires a successful TiRtc.initialize(...)
• Throws IllegalStateException if the runtime is unavailable, the native bridge is not ready, or the native handle cannot be created

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

• remoteId: remote peer identifier
• token: externally issued connection token
• Blank strings return INVALID_ARGUMENT

disconnect(): Int

• Disconnects transport only
• Does not release the object itself
• Returns success when already IDLE or DISCONNECTED

release(): Int

• Releases connection resources
• Repeated calls succeed as no-ops
• A disconnected TiRtcConn still blocks TiRtc.shutdown() until release() has been called

sendCommand(command: Long, data: ByteArray = byteArrayOf()): Int

• Sends a one-way raw command
• command is exposed as an opaque uint32_t command word; Android does not interpret bit semantics
• Valid range: 0..0xFFFF_FFFFL

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

• Sends one in-stream message
• streamId: remote stream identifier
• timestampMs: non-negative millisecond timestamp
• data: application payload

requestKeyFrame(streamId: Int): Int

• Requests a key frame from the selected remote video stream
• Returns a stable error when the connection is not ready, the object has been released, or the arguments are out of range

TiRtcAudioOutput

States

• IDLE
• BUFFERING
• PLAYING
• FAILED

TiRtcAudioOutputOptions

class TiRtcAudioOutputOptions @JvmOverloads constructor(
  val volumePercent: Int = 100,
  val gainLevel: Int = 0,
  val noiseReductionLevel: Int = 0,
)

Listener Properties

var onStateChanged: TiRtcAudioOutputStateListener?
var onError: TiRtcAudioOutputErrorListener?

TiRtcAudioOutput()

• Public no-arg constructor
• Requires TiRtc.initialize(...)
• Throws IllegalStateException on construction failure

attach(connection: TiRtcConn, streamId: Int): Int

• Binds the output to one remote audio stream on the selected connection
• One output consumes only one remote audio route at a time

detach(): Int

• Removes the current remote audio route
• Keeps the output reusable
• Repeated calls succeed as no-ops

updateOptions(options: TiRtcAudioOutputOptions): Int

• Updates playback options
• volumePercent must be greater than or equal to 0

release(): Int

• Releases the output and automatically detaches the current route
• Repeated calls succeed as no-ops

TiRtcVideoOutput

States

• IDLE
• BUFFERING
• RENDERING
• FAILED

Listener Properties

var onStateChanged: TiRtcVideoOutputStateListener?
var onRenderSizeChanged: TiRtcVideoOutputRenderSizeListener?
var onError: TiRtcVideoOutputErrorListener?

renderSize: Size?

• Current render output size
• This is an advanced observability signal; the primary rendering mental model remains “bind a container and render”

TiRtcVideoOutput()

• Public no-arg constructor
• Requires TiRtc.initialize(...)
• Throws IllegalStateException on construction failure

attach(connection: TiRtcConn, streamId: Int): Int

• Binds the output to one remote video stream on the selected connection
• Container binding is separate, so attach(...) may happen before attachView(...)

detach(): Int

• Removes the current remote video route
• Does not release the object and is not equivalent to detachView()
• Repeated calls succeed as no-ops

attachView(container: ViewGroup): Int

• The Android public rendering entry point
• Must run on the main thread
• The argument is a parent ViewGroup, not a TextureView
• The SDK creates and manages the internal TextureView and render host inside that container
• One TiRtcVideoOutput supports only one currently bound container; rebinding to a different container fails instead of performing implicit re-parenting

detachView(): Int

• Unbinds the internal render host from the container
• Does not affect the remote stream route
• Does not release the TiRtcVideoOutput object itself

release(): Int

• Releases the output
• Also cleans up the remote route, the internal render host, and the native resources
• Repeated calls succeed as no-ops

TiRtcLogging

d(tag, message) / i(tag, message) / w(tag, message) / e(tag, message)

• Write messages into the SDK logging system
• TiRtcDebugging is no longer the client primary logging surface; the public entry point is now TiRtcLogging

upload(callback: TiRtcLogUploadCallback): Int

val submitCode =
  TiRtcLogging.upload { code, logId ->
    if (code == 0) {
      println("logId=$logId")
    } else {
      println("upload failed code=$code")
    }
  }

• The return value only reports whether the upload task was accepted
• The completion callback shape is fixed to (code, logId)
• When code == 0, logId may be non-null
• When code != 0, logId must be null
• The callback is also dispatched on the main looper

Public Error Codes

Code	Name	Meaning
0	OK	Operation succeeded
-1	INVALID_ARGUMENT	Invalid or out-of-range argument
-2	INVALID_STATE	The current runtime or object state does not allow the call
-3	NATIVE_UNAVAILABLE	Native bridge or dynamic library is unavailable
-4	NOT_READY	The underlying object is not ready yet
-5	OPERATION_FAILED	Generic failure
-9	TRANSPORT_INVALID_LICENSE	Invalid service-side license
-10	TRANSPORT_TIMEOUT	Transport timeout
-11	TRANSPORT_BUSY	Transport is busy
-12	TRANSPORT_CONNECTION_TIMEOUT_CLOSED	Connection closed due to timeout
-13	TRANSPORT_REMOTE_CLOSED	Connection closed by the remote side
-14	TRANSPORT_CONNECTION_OTHER_ERROR	Connection closed for another transport error
-15	TRANSPORT_TOKEN_EXPIRED	Token expired