客户端 Android API 参考
对象总览
| 对象 | 作用 | 最终清理 |
|---|---|---|
TiRtc | 初始化和关闭全局 runtime | TiRtc.shutdown() |
TiRtcConn | 建连、断连、订阅/退订媒体流、收发命令、收发流消息、请求关键帧 | release() |
TiRtcAudioOutput | 播放一条远端音频流 | release() |
TiRtcVideoOutput | 播放一条远端视频流，并绑定 Android 容器 | release() |
TiRtcAudioOutputOptions | 调整音频播放参数 | 调用方自行持有 |
TiRtcLogging | 写 SDK 日志、上传日志 | 无 |
通用约束
- 先调用
TiRtc.initialize(...)，再创建TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 - 所有 listener 都通过 Android main looper 投递。
- 当前公开互通范围里，
streamId统一按0..15使用，并与设备端的stream_id约定保持一致。 attach()/detach()只绑定或解除本地播放路由；subscribeAudio()/subscribeVideo()/unsubscribe*()才是向远端发起媒体发送控制。disconnect()只断开连接，不释放对象本身。detach()、detachView()只解除当前绑定，不释放对象本身。release()才是TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput的最终清理动作。- 调用
TiRtc.shutdown()前，先release()所有TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。
TiRtc
| API | 说明 |
|---|---|
initialize(context, endpoint = "", environment = 0, consoleLoggingEnabled = false): Int | 初始化全局 runtime。context 内部会收成 applicationContext；endpoint 为空时由 runtime 按 environment 解析默认入口。 |
shutdown(): Int | 关闭全局 runtime。调用前先 release() 所有连接和输出对象。 |
TiRtcConn
状态
| 状态 | 含义 |
|---|---|
IDLE | 连接对象已创建，但还没有开始建连 |
CONNECTING | 建连请求已提交，正在等待后续连接结果 |
CONNECTED | 连接已经建立，可开始命令、流消息、音视频绑定、媒体订阅控制和关键帧请求 |
DISCONNECTED | 连接已经断开；对象仍然需要 release() |
创建
TiRtcConn() 会立即创建 native handle。
如果 runtime 未初始化、native bridge 不可用，或 native handle 创建失败，构造函数会抛 IllegalStateException。
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcConnState | 当前连接状态 |
onStateChanged | 状态变化回调 |
onDisconnected | 连接进入终态断开时回调；文档语义上和 onStateChanged(DISCONNECTED) 一起表达终态断连 |
onCommand | 收到命令通道消息时回调；回调给业务侧的是原始 cmdw |
onStreamMessage | 收到流内消息时回调；参数依次是 streamId、timestampMs、data |
onError | 连接级错误回调 |
方法
| API | 说明 |
|---|---|
connect(remoteId: String, token: String): Int | 发起到目标 remote_id 的连接。任一参数不能为空或只包含空白。返回 0 只表示建连请求已提交，不表示已经连接成功；真正结果以后续状态回调为准。 |
disconnect(): Int | 只断开传输连接。当前已经是 IDLE 或 DISCONNECTED 时仍返回成功。 |
sendCommand(cmdw: Long, data: ByteArray = byteArrayOf()): Int | 在命令通道上发送原始 cmdw。合法范围是 0..0xFFFF_FFFFL；如果链路里包含设备端 C SDK，业务侧自定义 cmdw 应使用 0x2000..0xFFFF_FFFFL。 |
sendStreamMessage(streamId: Int, timestampMs: Long, data: ByteArray): Int | 发送流内消息。当前公开互通范围里，streamId 应使用 0..15；timestampMs 的合法范围是 0..0xFFFF_FFFFL。 |
requestKeyFrame(streamId: Int): Int | 向指定远端视频流请求关键帧。当前公开互通范围里，streamId 应使用 0..15。 |
subscribeVideo(streamId: Int): Int | 请求对端开始发送指定视频流。当前公开互通范围里，streamId 应使用 0..15。它只发起远端发送控制，本地仍要配合 TiRtcVideoOutput.attach(...) 才能真正播放。 |
unsubscribeVideo(streamId: Int): Int | 请求对端停止发送指定视频流。它不等于 TiRtcVideoOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
subscribeAudio(streamId: Int): Int | 请求对端开始发送指定音频流。当前公开互通范围里，streamId 应使用 0..15。它只发起远端发送控制，本地仍要配合 TiRtcAudioOutput.attach(...) 才能真正播放。 |
unsubscribeAudio(streamId: Int): Int | 请求对端停止发送指定音频流。它不等于 TiRtcAudioOutput.detach()；两者分别作用于远端发送控制和本地播放绑定。 |
release(): Int | 释放连接对象。重复调用返回成功 no-op。 |
TiRtcAudioOutput
状态
| 状态 | 含义 |
|---|---|
IDLE | 当前没有绑定远端音频流 |
BUFFERING | 已绑定远端音频流，但还没有进入稳定播放 |
PLAYING | 正在播放远端音频。音频状态名强调的是“正在输出到播放设备”。 |
FAILED | 播放路径发生错误 |
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcAudioOutputState | 当前播放状态 |
onStateChanged | 状态变化回调 |
onError | 播放错误回调 |
TiRtcAudioOutputOptions
| 字段 | 说明 |
|---|---|
volumePercent | 线性音量百分比，不能小于 0 |
gainLevel | 额外增益等级 |
noiseReductionLevel | 降噪等级 |
方法
| API | 说明 |
|---|---|
TiRtcAudioOutput() | 创建音频输出对象。runtime 未初始化或 native handle 创建失败时抛 IllegalStateException。 |
attach(connection: TiRtcConn, streamId: Int): Int | 绑定指定连接上的一条远端音频流。当前公开互通范围里，streamId 应使用双方预先约定的 0..15。一个 output 一次只消费一条远端音频流。这个绑定只决定本地播放哪一条；如需向远端请求开始或停止发送，再配合 TiRtcConn.subscribeAudio() / unsubscribeAudio()。 |
detach(): Int | 解除当前音频绑定，但对象仍可复用。重复调用返回成功 no-op。 |
updateOptions(options: TiRtcAudioOutputOptions): Int | 更新播放参数。 |
release(): Int | 最终释放 output；内部会先兜底 detach()。重复调用返回成功 no-op。 |
TiRtcVideoOutput
状态
| 状态 | 含义 |
|---|---|
IDLE | 当前没有绑定远端视频流 |
BUFFERING | 已绑定远端视频流，但还没有进入稳定播放 |
PLAYING | 正在播放远端视频。视频状态文档当前统一按播放语义描述。 |
FAILED | 视频播放路径发生错误 |
属性和 listener
| 成员 | 说明 |
|---|---|
state: TiRtcVideoOutputState | 当前播放状态 |
renderSize: Size? | 当前渲染出的远端尺寸；它反映的是远端画面尺寸，不是 Android 容器尺寸 |
onStateChanged | 状态变化回调 |
onRenderSizeChanged | 渲染尺寸变化回调 |
onError | 播放错误回调 |
方法
| API | 说明 |
|---|---|
TiRtcVideoOutput() | 创建视频输出对象。runtime 未初始化或 native handle 创建失败时抛 IllegalStateException。 |
attach(connection: TiRtcConn, streamId: Int): Int | 绑定指定连接上的一条远端视频流。当前公开互通范围里，streamId 应使用双方预先约定的 0..15。即使还没有 attachView(...)，也允许先建立远端视频路由。这个绑定只决定本地播放哪一条；如需向远端请求开始或停止发送，再配合 TiRtcConn.subscribeVideo() / unsubscribeVideo()。 |
detach(): Int | 解除当前视频流绑定，但对象仍可复用。重复调用返回成功 no-op。 |
attachView(container: ViewGroup): Int | 把 output 绑定到一个 Android 容器。必须在主线程调用。SDK 会在这个容器里创建并管理内部 TextureView。一个 output 同时只支持一个已绑定容器；若未先 detachView() 就改绑到另一个容器，会返回失败。 |
detachView(): Int | 解除当前容器绑定，但不解除远端视频流绑定。必须在主线程调用。 |
release(): Int | 最终释放 output；内部会清理远端绑定和渲染容器。若当前还绑定着容器，release() 也必须在主线程调用。 |
TiRtcLogging
| API | 说明 |
|---|---|
d(tag, message): Int | 写一条 debug 日志 |
i(tag, message): Int | 写一条 info 日志 |
w(tag, message): Int | 写一条 warning 日志 |
e(tag, message): Int | 写一条 error 日志 |
upload(callback): Int | 异步上传当前 SDK 日志。调用成功只表示后台上传任务已成功启动；真正结果通过 callback.onCompleted(code, logId) 回来。回调也通过主线程投递。 |
常见误用
- 没有先
TiRtc.initialize(...)就创建TiRtcConn、TiRtcAudioOutput、TiRtcVideoOutput。 - 把
connect(...)返回0误解成已经连上；真正连接结果以后续状态回调为准。 - 把
disconnect()、detach()、detachView()当成最终清理；真正的最终清理是release()。 - 同一个
TiRtcVideoOutput还绑定着旧容器时，直接改绑到另一个容器；正确做法是先detachView()。 - 把
15以上的streamId当成公开可互通范围使用，最终和设备端约定冲突。 - 设备端按订阅再发时，只做
attach(...)没有调用subscribeAudio()/subscribeVideo()，结果一直无声或黑屏。 - 还有 live object 没有
release()时就调用TiRtc.shutdown()。