TiRTC Android API Reference

接入指南

对象总览

`TiRtc`

初始化和反初始化整个 SDK 运行时
配置环境、接入地址和控制台日志
开启或关闭传输调试日志

`TiRtcConn`

创建一条主动连接
收发命令和流消息
绑定音频输出、视频输出、音频输入、视频输入

`TiRtcConnService`

在设备侧启动监听服务
接收入站连接
控制自动发流策略和最大连接数

`TiRtcAudioInput` / `TiRtcAudioOutput`

采集本地音频并绑定到连接
播放远端音频

`TiRtcVideoInput` / `TiRtcVideoOutput`

采集本地视频并绑定到连接
绑定本地预览容器
渲染远端视频

`TiRtcAudioBinding` / `TiRtcVideoBinding`

把 input 或 output 绑定到某条连接和指定 streamId
主要给 Java 直接调用

`TiRtcDebugging` / `TiRtcLogging`

上传日志
TiRtcLogging 已废弃，优先使用 TiRtcDebugging

`TiRtcCredential`

按参数申请连接 token
返回 RtcResult<String>

常用数据类型

RtcConnCommand / RtcConnCommandResponse / RtcStreamMessage
RtcLocalAudioOptions / RtcAudioOutputOptions
RtcCredentialIssueTokenOptions
RtcCameraFacing
RtcResult<T>
TiRtcException

`TiRtc`

常量

kotlin

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

`TiRtc.Config.Builder`

kotlin

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

字段和方法：

context：必填，内部会转成应用级 Context
setEndpoint(value)：可选，自定义接入地址
setEnvironment(value)：可选，只允许 ENV_TEST / ENV_PRE / ENV_PROD
setEnableConsoleLog(value)：可选，是否输出控制台日志

`initialize(config: Config): Int`

初始化 SDK 运行时
返回 0 表示成功，非 0 表示失败
应在创建连接、服务、音频对象、视频对象之前调用

`setTransportDebugEnabled(enabled: Boolean): Int`

开启或关闭传输调试日志
需要先完成初始化

`uninitialize()`

反初始化 SDK
进入 uninitialize() 前，先销毁不再使用的连接、服务、音频对象和视频对象

`TiRtcDebugging`

`uploadLogs(callback: UploadLogsCallback): Int`

kotlin

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")
      }
    },
  )

返回值只表示任务是否成功受理
真正的上传结果通过 callback 返回

`UploadLogsCallback`

kotlin

interface UploadLogsCallback {
  fun onSuccess(logId: String)

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

`TiRtcLogging`

kotlin

@Deprecated("Use TiRtcDebugging.uploadLogs(callback)")
object TiRtcLogging

`upload(): RtcResult<String>`

已废弃
同步返回 RtcResult<String>
成功时 getValue() 是 logId

`TiRtcConn`

生命周期

创建对象
设置 observer
connect(...)
绑定输入或输出
收发命令 / 流消息
disconnect()
destroy()

`TiRtcConn(observer: Observer? = null)`

创建一条连接对象
需要先完成 TiRtc.initialize(...)
native 创建失败会抛 TiRtcException 或 IllegalStateException
如果构造时传了 observer，会立即收到当前状态回调

`setObserver(observer: Observer?): Int`

设置、替换或清空连接 observer
成功后会立即回放当前状态
如果连接已经处于 DISCONNECTED，还会额外回放一次 onDisconnected(...)

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

peerId：远端目标标识
token：连接鉴权令牌
空字符串会直接返回参数错误

`disconnect(): Int`

断开连接
不等于销毁对象

`destroy(): Int`

释放连接对象资源
连接本身不再使用时仍要显式调用
销毁后对象不可复用

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

发送单向命令
commandId 由业务和远端协议约定
业务命令 ID 应使用 0x1000..0x7FFF
0x1000 以下保留给 SDK 内部使用

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

发送请求-响应命令
commandId 由业务和远端协议约定
业务命令 ID 应使用 0x1000..0x7FFF
timeoutMs 应按 32 位无符号毫秒值使用
返回 0 只表示请求已成功发出；真正结果通过 callback 返回

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

回复一次远端请求
remoteRequestId 来自 onRemoteCommandRequest(...)
commandId 通常与请求里的 command.commandId 相同
一个 remoteRequestId 正常只回复一次

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

发送流内消息
streamId 应按 0..15 使用
streamId 与音频、视频绑定共用同一命名空间，不能重号
timestampMs 应按 32 位无符号毫秒值使用；业务不用时可直接传 0

Kotlin 常用扩展方法

kotlin

conn.attachAudioInput(audioStreamId, audioInput)
conn.detachAudioInput(audioStreamId)
conn.attachAudioOutput(audioStreamId, audioOutput)
conn.detachAudioOutput(audioStreamId)

conn.attachVideoInput(videoStreamId, videoInput)
conn.detachVideoInput(videoStreamId)
conn.attachVideoOutput(videoStreamId, videoOutput)
conn.detachVideoOutput(videoStreamId)

conn.requestKeyframe(videoStreamId)

Java 直接调用时，使用 TiRtcAudioBinding 和 TiRtcVideoBinding。

`Observer`

kotlin

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`

kotlin

interface CommandCallback {
  fun onSuccess(response: RtcConnCommandResponse)

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

`State`

IDLE
CONNECTING
CONNECTED
DISCONNECTED

`TiRtcConnService`

常量

kotlin

TiRtcConnService.MEDIA_SEND_POLICY_ON_REQUEST = 0
TiRtcConnService.MEDIA_SEND_POLICY_AUTO_ON_CONNECTED = 1

`Config`

kotlin

val config = TiRtcConnService.Config(
  license = license,
  maxConnections = 5,
  mediaSendPolicy = TiRtcConnService.MEDIA_SEND_POLICY_ON_REQUEST,
)

字段：

license：必填
maxConnections：默认 5，必须大于 0
mediaSendPolicy：ON_REQUEST 或 AUTO_ON_CONNECTED

`TiRtcConnService(config: Config, observer: Observer)`

创建设备侧服务对象
构造本身不启动服务

`start(): Int`

启动监听服务
需要先完成 TiRtc.initialize(...)

`stop(): Int`

停止服务
不会自动销毁已经交付给 onConnected(...) 的连接对象

`Observer`

kotlin

interface Observer {
  fun onStarted()

  fun onStopped()

  fun onConnected(connection: TiRtcConn)

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

`TiRtcCredential`

`issueToken(options: RtcCredentialIssueTokenOptions): RtcResult<String>`

根据参数申请 token
成功时 RtcResult.getValue() 返回 token
失败时通过 getErrorCode() / getErrorMessage() 读取错误
需要先完成 TiRtc.initialize(...)
accessId / secretKey 属于敏感信息，不应内嵌在正式客户端中

`RtcCredentialIssueTokenOptions`

openapiEntry: String
accessId: String
secretKey: String
localId: String
peerId: String
userTtlSeconds: Int
channelTtlSeconds: Int

`RtcResult<T>`

常用方法

isOk(): Boolean
getValue(): T?
getErrorCode(): Int
getErrorMessage(): String?

工厂方法

RtcResult.ok(value)
RtcResult.error(code, message)

`TiRtcAudioInput`

生命周期

创建对象
setOptions(...)
setObserver(...) 可选
attachAudioInput(...)
start()
stop()
detachAudioInput(...)
destroy()

`setOptions(options: RtcLocalAudioOptions): Int`

sampleRate 只允许 8000 或 16000
aecMode 只允许 0..1
agcLevel 只允许 0..3
ansLevel 只允许 0..3

`setObserver(observer: Observer?): Int`

设置 observer 后会立即回放当前状态

`start(): Int`

启动采集

`stop(): Int`

停止采集

`destroy(): Int`

释放对象资源

`Observer`

kotlin

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

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

`State`

IDLE
RUNNING
PAUSED
STOPPED
FAILED

`RtcLocalAudioOptions`

sampleRate: Int = 16000
aecMode: Int = 0
agcLevel: Int = 0
ansLevel: Int = 0

`TiRtcAudioOutput`

生命周期

创建对象
setOptions(...) 可选
setObserver(...) 可选
attachAudioOutput(...)
播放远端音频
detachAudioOutput(...)
destroy()

`setOptions(options: RtcAudioOutputOptions): Int`

volumePercent 必须大于等于 0

`setObserver(observer: Observer?): Int`

设置 observer 后会立即回放一次 IDLE

`destroy(): Int`

释放对象资源

`Observer`

kotlin

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

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

`State`

IDLE
PLAYING
BUFFERING
PAUSED
COMPLETED
FAILED

`RtcAudioOutputOptions`

volumePercent: Int = 100
gainLevel: Int = 0
noiseReductionLevel: Int = 0

`TiRtcVideoInput`

生命周期

创建对象
setOptions(...)
setObserver(...) 可选
attachPreview(container) 可选
attachVideoInput(...)
start()
stop()
detachVideoInput(...)
detachPreview()
destroy()

`Options`

width: Int = 640
height: Int = 380
fps: Int = 15
bitrateKbps: Int = 0
cameraFacing: RtcCameraFacing = FRONT

`setOptions(options: Options): Int`

width、height、fps 必须大于 0
bitrateKbps 必须大于等于 0

`attachPreview(container: ViewGroup): Int`

必须在 UI 线程调用
这里传的是父容器，不是 TextureView
SDK 会管理内部预览输出

`detachPreview(): Int`

必须在 UI 线程调用

`start(): Int`

启动本地视频采集
成功后 observer 会收到实际输出尺寸

`stop(): Int`

停止视频采集

`destroy(): Int`

释放对象资源
如果当前仍绑定预览容器，必须在 UI 线程调用

`Observer`

kotlin

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

  fun onOutputSizeChanged(width: Int, height: Int)

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

`State`

IDLE
RUNNING
PAUSED
STOPPED
FAILED

`TiRtcVideoOutput`

生命周期

创建对象
attach(container)
setObserver(...) 可选
attachVideoOutput(...)
渲染远端视频
detachVideoOutput(...)
detach()
destroy()

`attach(container: ViewGroup): Int`

必须在 UI 线程调用
传入的是父容器，不是 TextureView
SDK 会在容器里创建并管理内部 TextureView
已经绑定到另一个容器时，直接返回状态错误

`detach(): Int`

必须在 UI 线程调用
只会移除 SDK 自己创建的内部渲染 view

`setObserver(observer: Observer?): Int`

设置 observer 后会立即回放当前状态

`destroy(): Int`

释放对象资源
如果当前仍绑定容器，必须在 UI 线程调用

`Observer`

kotlin

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

  fun onOutputSizeChanged(width: Int, height: Int)

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

`State`

IDLE
RENDERING
BUFFERING
PAUSED
COMPLETED
FAILED

`TiRtcAudioBinding`

方法

kotlin

TiRtcAudioBinding.attachInput(connection, streamId, input)
TiRtcAudioBinding.detachInput(connection, streamId)
TiRtcAudioBinding.attachOutput(connection, streamId, output)
TiRtcAudioBinding.detachOutput(connection, streamId)

主要给 Java 使用
streamId 当前公开约定应按 0..15 使用

`TiRtcVideoBinding`

方法

kotlin

TiRtcVideoBinding.attachInput(connection, streamId, input)
TiRtcVideoBinding.detachInput(connection, streamId)
TiRtcVideoBinding.attachOutput(connection, streamId, output)
TiRtcVideoBinding.detachOutput(connection, streamId)
TiRtcVideoBinding.requestKeyframe(connection, streamId)

主要给 Java 使用
streamId 当前公开约定应按 0..15 使用

`RtcCameraFacing`

FRONT
BACK

`RtcConnCommand`

commandId: Int
data: ByteArray

`RtcConnCommandResponse`

commandId: Int
data: ByteArray

`RtcStreamMessage`

timestampMs: Long
data: ByteArray

`TiRtcException`

kotlin

class TiRtcException(
  val code: Int,
  override val message: String,
) : RuntimeException(...)

部分对象在构造阶段 native 创建失败时会抛出它

通用约束

`streamId`

Android 层方法签名使用 Int
当前公开约定应按 0..15 使用
音频、视频、流消息共用同一组 streamId 命名空间
同一条连接上，音频和视频不能复用同一个 streamId

`commandId`

业务命令 ID 应使用 0x1000..0x7FFF
0x1000 以下保留给 SDK 内部使用

`timestampMs`

RtcStreamMessage.timestampMs / sendStreamMessage(..., timestampMs, ...) 按 32 位无符号毫秒值使用
业务不用这个字段时，直接传 0

错误码

绝大多数同步接口返回 Int：

0：成功
非 0：失败

TiRtcConn.Observer.onError(...) 与 onDisconnected(...) 也使用同一套统一错误码：

0：本地主动断开，不表示失败
其他负数：对应 runtime/core/foundation/include/public/tirtc/error.h 中 TirtcError 的 Android 映射值
常见值包括：-10 超时、-13 远端关闭、-15 token 过期

线程语义

SDK 不保证回调一定在主线程
SDK 也不保证所有回调都在同一后台线程
下面这些必须在 UI 线程调用：
- TiRtcVideoInput.attachPreview(container)
- TiRtcVideoInput.detachPreview()
- 绑定预览时的 TiRtcVideoInput.destroy()
- TiRtcVideoOutput.attach(container)
- TiRtcVideoOutput.detach()
- 绑定渲染容器时的 TiRtcVideoOutput.destroy()

生命周期配对

initialize ↔ uninitialize
start ↔ stop
connect ↔ disconnect
attachInput ↔ detachInput
attachOutput ↔ detachOutput
attachPreview ↔ detachPreview
attach(container) ↔ detach()
对象创建 ↔ destroy()

构造阶段异常

下面这些对象在 native 创建失败时可能抛异常：

TiRtcConn
TiRtcAudioInput
TiRtcAudioOutput
TiRtcVideoInput
TiRtcVideoOutput

常见误用

把 `disconnect()` 当成 `destroy()`

连接对象本身资源不会被释放。

把 `detach()` / `detachPreview()` 当成 `destroy()`

对象本身资源不会被释放。

自己创建 `TextureView` 再传给 SDK

当前 contract 传的是父容器，不是渲染 view。

把消息 `streamId` 和音频 / 视频 `streamId` 复用

它们共用同一组 streamId 命名空间。

使用 `0x1000` 以下或 `0x7FFF` 以上的业务命令 ID

这不符合当前公开约定。

假设回调一定在主线程

SDK 不做这种承诺。

未初始化就创建连接、服务或媒体对象

初始化前创建对象，构造阶段就可能直接失败。

TiRTC Android API Reference ​

对象总览 ​

TiRtc ​

TiRtcConn ​

TiRtcConnService ​

TiRtcAudioInput / TiRtcAudioOutput ​

TiRtcVideoInput / TiRtcVideoOutput ​

TiRtcAudioBinding / TiRtcVideoBinding ​

TiRtcDebugging / TiRtcLogging ​

TiRtcCredential ​

常用数据类型 ​

TiRtc ​

常量 ​

TiRtc.Config.Builder ​

initialize(config: Config): Int ​

setTransportDebugEnabled(enabled: Boolean): Int ​

uninitialize() ​

TiRtcDebugging ​

uploadLogs(callback: UploadLogsCallback): Int ​

UploadLogsCallback ​

TiRtcLogging ​

upload(): RtcResult<String> ​

TiRtcConn ​

生命周期 ​

TiRtcConn(observer: Observer? = null) ​

setObserver(observer: Observer?): Int ​

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

disconnect(): Int ​

destroy(): Int ​

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

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

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

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

Kotlin 常用扩展方法 ​

Observer ​

CommandCallback ​

State ​

TiRtcConnService ​

常量 ​

Config ​

TiRtcConnService(config: Config, observer: Observer) ​

start(): Int ​

stop(): Int ​

Observer ​

TiRtcCredential ​

issueToken(options: RtcCredentialIssueTokenOptions): RtcResult<String> ​

RtcCredentialIssueTokenOptions ​

RtcResult<T> ​

常用方法 ​

工厂方法 ​

TiRtcAudioInput ​

生命周期 ​

setOptions(options: RtcLocalAudioOptions): Int ​

setObserver(observer: Observer?): Int ​

start(): Int ​

stop(): Int ​

destroy(): Int ​

Observer ​

State ​

RtcLocalAudioOptions ​

TiRtcAudioOutput ​

生命周期 ​

setOptions(options: RtcAudioOutputOptions): Int ​

setObserver(observer: Observer?): Int ​

destroy(): Int ​

Observer ​

State ​

RtcAudioOutputOptions ​

TiRtcVideoInput ​

生命周期 ​

Options ​

setOptions(options: Options): Int ​

attachPreview(container: ViewGroup): Int ​

detachPreview(): Int ​

start(): Int ​

stop(): Int ​

destroy(): Int ​

Observer ​

State ​

TiRtcVideoOutput ​

TiRTC Android API Reference

对象总览

`TiRtc`

`TiRtcConn`

`TiRtcConnService`

`TiRtcAudioInput` / `TiRtcAudioOutput`

`TiRtcVideoInput` / `TiRtcVideoOutput`

`TiRtcAudioBinding` / `TiRtcVideoBinding`

`TiRtcDebugging` / `TiRtcLogging`

`TiRtcCredential`

常用数据类型

`TiRtc`

常量

`TiRtc.Config.Builder`

`initialize(config: Config): Int`

`setTransportDebugEnabled(enabled: Boolean): Int`

`uninitialize()`

`TiRtcDebugging`

`uploadLogs(callback: UploadLogsCallback): Int`

`UploadLogsCallback`

`TiRtcLogging`

`upload(): RtcResult<String>`

`TiRtcConn`

生命周期

`TiRtcConn(observer: Observer? = null)`

`setObserver(observer: Observer?): Int`

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

`disconnect(): Int`

`destroy(): Int`

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

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

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

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

Kotlin 常用扩展方法

`Observer`

`CommandCallback`

`State`

`TiRtcConnService`

常量

`Config`

`TiRtcConnService(config: Config, observer: Observer)`

`start(): Int`

`stop(): Int`

`Observer`

`TiRtcCredential`

`issueToken(options: RtcCredentialIssueTokenOptions): RtcResult<String>`

`RtcCredentialIssueTokenOptions`

`RtcResult<T>`

常用方法

工厂方法

`TiRtcAudioInput`

生命周期

`setOptions(options: RtcLocalAudioOptions): Int`

`setObserver(observer: Observer?): Int`

`start(): Int`

`stop(): Int`

`destroy(): Int`

`Observer`

`State`

`RtcLocalAudioOptions`

`TiRtcAudioOutput`

生命周期

`setOptions(options: RtcAudioOutputOptions): Int`

`setObserver(observer: Observer?): Int`

`destroy(): Int`

`Observer`

`State`

`RtcAudioOutputOptions`

`TiRtcVideoInput`

生命周期

`Options`

`setOptions(options: Options): Int`

`attachPreview(container: ViewGroup): Int`

`detachPreview(): Int`

`start(): Int`

`stop(): Int`

`destroy(): Int`

`Observer`

`State`

`TiRtcVideoOutput`