Android API 参考
本页描述 Android SDK products/sdk/android/av 当前公开的客户端侧 API，适用于用 Android 原生应用接入 TiRTC 的开发者。
如果你还没有完成 AAR 接入、工程配置或连接主线准备，先看 集成到客户端。页面里提到的 AppId、remote_id、token、stream_id 等术语，以 名词解释 为准。
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtcInitOptions | 组织 runtime 初始化参数 | 调用方自行持有 |
TiRtc | 初始化和关闭全局 runtime，准备日志，读取 SDK 版本 | TiRtc.shutdown() |
TiRtcConn | 建连、断连、收发命令、收发流内消息、手动订阅媒体、请求关键帧 | release() |
TiRtcAudioOutputOptions | 组织音频播放参数 | 调用方自行持有 |
TiRtcAudioOutput | 播放一条远端音频流 | release() |
TiRtcVideoOutput | 播放一条远端视频流，并把渲染宿主绑定到 Android 容器 | release() |
TiRtcLogging | 写 SDK 日志、上传日志 | 无 |
通用约束
- 先调用
TiRtc.initialize(context, ...)，再创建TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 - 当前公开主线里，所有 listener 都通过 Android 主线程回调分发。
connect(...)返回0只表示建连请求已提交，不表示已经连上；真正连接结果以后续onStateChanged为准。attach()/detach()只控制本地播放绑定；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。disconnect()只断开连接，detach()/detachView()只解除当前播放绑定；对象本身仍可复用。release()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。- 调用
TiRtc.shutdown()前，先release()所有仍存活的连接和输出对象；如果还有 live object，shutdown()会返回错误码，而不是强制回收。 - 当前公开互通范围里，
streamId按stream_id的约定使用0..15。 TiRtcVideoOutput.attachView(...)和detachView()必须在主线程调用；如果当前 output 还绑定着容器，release()也必须在主线程调用。
TiRtcInitOptions
TiRtc.initialize(...) 的参数对象。
| 字段 | 说明 |
|---|---|
appId | 你的 AppId。默认值为空字符串。 |
endpoint | 自定义服务入口。留空时由 native runtime 使用内置默认入口。 |
consoleLogEnabled | 是否把 SDK 日志镜像到控制台。默认值为 false。 |
TiRtc
TiRtc 管理进程级共享 runtime。典型调用顺序是：可选 prepareLogging() -> initialize() -> 创建连接和播放对象 -> 业务结束后 release() 这些对象 -> shutdown()。
| API | 说明 |
|---|---|
versionName: String | 当前 SDK 版本名。native bridge 不可用时返回空字符串。 |
prepareLogging(context: Context): Int | 只准备 SDK 日志目录和日志系统，不初始化 runtime。适合需要在 initialize() 之前收集 SDK-native 日志的宿主。 |
initialize(context: Context, config: TiRtcInitOptions): Int | 初始化 Android runtime。context 内部会收成 applicationContext；返回统一的 TiRTCError 错误码。若 runtime 已初始化，会返回 RUNTIME_ALREADY_INITIALIZED。 |
shutdown(): Int | 关闭共享 runtime。重复调用在 runtime 已关闭后返回成功 no-op。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
TiRtcConnState.IDLE | 连接对象已存在，但没有活动中的传输尝试 |
TiRtcConnState.CONNECTING | 建连请求已提交，正在等待连接结果 |
TiRtcConnState.CONNECTED | 连接已经建立，可开始收发命令、流内消息、绑定播放对象、手动订阅和请求关键帧 |
TiRtcConnState.DISCONNECTED | 连接已经不可用；对象仍需要 release() |
创建
TiRtcConn() 会立即创建一个断开状态的 native connection handle。
如果 native bridge 不可用，或 native handle 创建失败，构造函数会抛 IllegalStateException。
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcConnState | 当前连接状态 |
onStateChanged | 连接状态变化回调，签名为 TiRtcConnStateListener { state, errorCode -> ... } |
onCommand | 收到命令通道消息时回调，签名为 TiRtcConnCommandListener { command, data -> ... } |
onStreamMessage | 收到流内消息时回调，签名为 TiRtcConnStreamMessageListener { streamId, timestampMs, data -> ... } |
onStateChanged 在赋值后会通过主线程立即回放当前状态，这样 UI 不需要先主动轮询当前 state。对于 retained server API 创建的已连上连接，晚一点设置 listener 也会补回当前状态。
方法
| API | 说明 |
|---|---|
connect(remoteId: String, token: String): Int | 发起到目标 remote_id 的连接。返回 0 只表示请求提交成功。 |
disconnect(): Int | 断开当前连接，但不释放对象。当前已经是 IDLE 或 DISCONNECTED 时返回成功 no-op。 |
sendCommand(command: Long, data: ByteArray = byteArrayOf()): Int | 在命令通道上发送业务自定义命令。Android 当前公开参数名是 command；如果链路里包含设备端 C SDK，这个值与设备侧看到的原始 cmdw 是同一份标识。 |
sendStreamMessage(streamId: Int, timestampMs: Long, data: ByteArray): Int | 发送流内消息。发送前两端应先约定好 streamId 和消息语义。 |
requestKeyFrame(streamId: Int): Int | 向指定远端视频流请求关键帧。 |
subscribeVideo(streamId: Int): Int | 可选的手动视频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeVideo(streamId: Int): Int | 取消手动视频订阅。它不等于 TiRtcVideoOutput.detach()。 |
subscribeAudio(streamId: Int): Int | 可选的手动音频订阅控制。它只负责请求远端开始发送，不会自动创建本地播放。 |
unsubscribeAudio(streamId: Int): Int | 取消手动音频订阅。它不等于 TiRtcAudioOutput.detach()。 |
release(): Int | 最终释放连接对象。重复调用返回成功 no-op。 |
TiRtcAudioOutputOptions
TiRtcAudioOutput.updateOptions(...) 使用的参数对象。
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比，默认值为 100；小于 0 的值会被拒绝 |
gainLevel | 额外增益等级，默认值为 0 |
noiseReductionLevel | 降噪等级，默认值为 0 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcAudioOutputState.IDLE | 当前没有绑定远端音频流 |
TiRtcAudioOutputState.BUFFERING | 已绑定远端音频流，但还没有进入稳定播放 |
TiRtcAudioOutputState.PLAYING | 正在播放远端音频 |
TiRtcAudioOutputState.FAILED | 播放路径发生错误 |
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcAudioOutputState | 当前播放状态 |
onStateChanged | 播放状态变化回调，签名为 TiRtcAudioOutputStateListener { state -> ... } |
onError | 播放错误回调，签名为 TiRtcAudioOutputErrorListener { code -> ... } |
给 onStateChanged 赋值后，SDK 会立即通过主线程回调当前状态。
方法
| API | 说明 |
|---|---|
TiRtcAudioOutput() | 创建音频输出对象。native bridge 不可用或 native handle 创建失败时抛 IllegalStateException。 |
updateOptions(options: TiRtcAudioOutputOptions): Int | 更新播放参数。当前公开表面上的方法名就是 updateOptions(...)。 |
attach(connection: TiRtcConn, streamId: Int): Int | 绑定指定连接上的一条远端音频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeAudio() / unsubscribeAudio()。 |
detach(): Int | 解除当前音频绑定，但对象仍可复用。 |
release(): Int | 最终释放音频输出对象。内部会先尝试 detach()；重复调用返回成功 no-op。 |
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
TiRtcVideoOutputState.IDLE | 当前没有可用的视频本地渲染路径 |
TiRtcVideoOutputState.BUFFERING | 已绑定远端视频流，但还没有开始稳定渲染 |
TiRtcVideoOutputState.RENDERING | 已经开始渲染远端视频 |
TiRtcVideoOutputState.FAILED | 视频播放路径发生错误 |
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcVideoOutputState | 当前播放状态 |
renderSize: Size? | 最近一次由渲染器上报的远端画面尺寸；它反映的是远端帧尺寸，不是 Android 容器尺寸 |
onStateChanged | 播放状态变化回调，签名为 TiRtcVideoOutputStateListener { state -> ... } |
onRenderSizeChanged | 渲染尺寸变化回调，签名为 TiRtcVideoOutputRenderSizeListener { size -> ... } |
onError | 播放错误回调，签名为 TiRtcVideoOutputErrorListener { code -> ... } |
给 onStateChanged 赋值后，SDK 会立即通过主线程回调当前状态。
方法
| API | 说明 |
|---|---|
TiRtcVideoOutput() | 创建视频输出对象。native bridge 不可用或 native handle 创建失败时抛 IllegalStateException。 |
attach(connection: TiRtcConn, streamId: Int): Int | 绑定指定连接上的一条远端视频流。它只决定本地播放哪一条流；如需控制远端开始或停止发送，还要配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach(): Int | 解除当前远端视频流绑定，但对象仍可复用。 |
attachView(container: ViewGroup): Int | 把 output 绑定到一个 Android 容器。必须在主线程调用。SDK 会在容器内创建并管理自己的 TextureView。同一个 output 同时只支持一个已绑定容器；未先 detachView() 就改绑到其他容器会返回失败。 |
detachView(): Int | 解除当前容器绑定，但不解除远端视频流绑定。必须在主线程调用。调用后本地渲染宿主会被移除，renderSize 会清空。 |
release(): Int | 最终释放视频输出对象。内部会同时清理远端绑定和渲染宿主；如果当前还绑定着容器，必须在主线程调用。重复调用返回成功 no-op。 |
TiRtcLogging
| API | 说明 |
|---|---|
d(tag: String, message: String): Int | 写一条 debug 日志 |
i(tag: String, message: String): Int | 写一条 info 日志 |
w(tag: String, message: String): Int | 写一条 warning 日志 |
e(tag: String, message: String): Int | 写一条 error 日志 |
upload(callback: TiRtcLogUploadCallback): Int | 异步上传当前 SDK 日志。调用成功只表示后台 worker 已经启动；真正结果通过 callback.onCompleted(code, logId) 回来，回调也会通过主线程分发。 |
常见误用
- 没有先
TiRtc.initialize(...)就创建TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 - 把
connect(...)返回0误解成已经连上；真正连接结果要以后续onStateChanged为准。 - 按旧文档去找
TiRtc.Config、environment、onDisconnected、onError这类当前 Android client 主线里已经不存在的 surface。 - 把
sendCommand(...)的参数名写成其他技术栈里的commandId；Android 当前公开参数名是command。 - 把
disconnect()、detach()、detachView()当成最终清理；真正的最终清理是release()。 - 把视频状态写成
PLAYING；当前 Android 公开状态名是TiRtcVideoOutputState.RENDERING。 - 在非主线程调用
attachView(...)、detachView()，或在仍绑定容器时从非主线程调用release()。 - 设备端按订阅再发时，只做
attach(...)没有配合subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 还有 live object 没有
release()时就调用TiRtc.shutdown()。