Client 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)
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(applicationContext)
check(initCode == 0)

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

conn.onStateChanged = TiRtcConnStateListener { state ->
  println("conn state=$state")
}
conn.onDisconnected = TiRtcConnDisconnectedListener { code ->
  println("disconnected code=$code")
}
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.onError = TiRtcConnErrorListener { code ->
  println("conn error=$code")
}

check(conn.connect(remoteId, token) == 0)
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
• When a connection closes, TiRtcConn always delivers onDisconnected(code) before onStateChanged(DISCONNECTED)
• TiRtc.shutdown() succeeds only after every object that still owns a native handle has been cleaned up; any unreleased TiRtcConn, TiRtcAudioOutput, TiRtcVideoOutput, or retained server-side object keeps shutdown in INVALID_STATE

TiRtc

initialize(context, endpoint = "", environment = 0, consoleLoggingEnabled = false): Int

val code = TiRtc.initialize(
  context = applicationContext,
  endpoint = "",
  environment = 0,
  consoleLoggingEnabled = BuildConfig.DEBUG,
)

• context: required; the SDK stores applicationContext
• endpoint: optional; an empty string lets the runtime resolve its default endpoint for the selected environment
• environment: optional Int, default 0; Android no longer exposes public ENV_* constants on the primary path
• consoleLoggingEnabled: optional console log mirroring switch, default false
• Java callers consume the generated @JvmOverloads overloads

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, output, and retained server-side 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 onDisconnected: TiRtcConnDisconnectedListener?
var onCommand: TiRtcConnCommandListener?
var onStreamMessage: TiRtcConnStreamMessageListener?
var onError: TiRtcConnErrorListener?

• 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

Retained APIs That Still Ship In The Artifact

The following APIs still ship in the same com.tange.ai:tirtc-av artifact, but they are not part of the Android v1 client primary path:

• TiRtcConnService
• TiRtcAudioInput
• TiRtcVideoInput
• TiRtcCredential
• TiRtcCredentialResult
• RtcCredentialIssueTokenOptions
• RtcLocalAudioOptions
• RtcCameraFacing

They remain the retained server-side or auxiliary surface:

• TiRtcConnService: device-side listener service that delivers accepted connections through onConnected(connection)
• TiRtcAudioInput and TiRtcVideoInput: local capture and uplink bindings
• TiRtcCredential: issue tokens from input parameters; accessId and secretKey must not be embedded in production clients

These APIs were not removed from the artifact in this redesign, but the primary docs and example-client no longer use them to define the client-role integration model.