Android SDK

基于 LiveKit 的 TgoRTC Android (Kotlin) SDK，用于实时音视频通讯。

安装

在 build.gradle.kts (Project) 中添加 JitPack 仓库：

allprojects {
    repositories {
        maven { url = uri("https://jitpack.io") }
    }
}

在 build.gradle.kts (Module) 中添加依赖：

dependencies {
    implementation("com.github.TgoRTC:TgoRTCSDK:1.0.0")
}

最新版本：

依赖说明

SDK 自动包含以下核心依赖：

• io.livekit:livekit-android:2.23.1

快速开始

1. 初始化 SDK

import com.tgo.rtc.TgoRTC
import com.tgo.rtc.entity.TgoOptions

val options = TgoOptions().apply {
    debug = true
    mirror = false
}

TgoRTC.instance.init(applicationContext, options)

2. 创建房间信息并加入

import com.tgo.rtc.entity.TgoRoomInfo
import com.tgo.rtc.entity.TgoRTCType
import kotlinx.coroutines.MainScope
import kotlinx.coroutines.launch

val scope = MainScope()

val roomInfo = TgoRoomInfo(
    roomName = "room-name",
    token = "your-token",
    url = "http://your-server",
    loginUID = "local-user-id",
    creatorUID = "creator-user-id"
)

roomInfo.maxParticipants = 4
roomInfo.rtcType = TgoRTCType.VIDEO
roomInfo.timeout = 30

scope.launch {
    TgoRTC.instance.roomManager.joinRoom(
        roomInfo,
        micEnabled = true,
        cameraEnabled = true
    )
}

3. 监听连接状态

import com.tgo.rtc.entity.TgoConnectStatus

val connectListener = { roomName: String, status: TgoConnectStatus, reason: String ->
    println("Room $roomName: $status - $reason")

    when (status) {
        TgoConnectStatus.CONNECTING -> println("正在连接...")
        TgoConnectStatus.CONNECTED -> println("已连接到房间")
        TgoConnectStatus.DISCONNECTED -> println("已断开连接")
    }
}

TgoRTC.instance.roomManager.addConnectListener(connectListener)
TgoRTC.instance.roomManager.removeConnectListener(connectListener)

说明： 当前 Android SDK 中没有单独的 RECONNECTING / RECONNECTED 枚举值。 RoomEvent.Reconnecting 在 TgoRoomManager 中会回调为 TgoConnectStatus.CONNECTING。

4. 获取参与者

val local = TgoRTC.instance.participantManager.getLocalParticipant()
val localOrNull = TgoRTC.instance.participantManager.getLocalParticipantOrNull()

val remotes = TgoRTC.instance.participantManager.getRemoteParticipants()
val joinedRemotes = TgoRTC.instance.participantManager.getJoinedRemoteParticipants()

val all = TgoRTC.instance.participantManager.getAllParticipants()
val joined = TgoRTC.instance.participantManager.getJoinedParticipants()
val joinedCount = TgoRTC.instance.participantManager.getJoinedParticipantCount()

TgoRTC.instance.participantManager.addNewParticipantListener { participant ->
    println("新参与者加入: ${participant.uid}")
}

5. 媒体控制与事件

媒体控制仅对本地参与者有效。

import com.tgo.rtc.entity.TgoConnectionQuality
import com.tgo.rtc.entity.TgoVideoInfo

val participant = TgoRTC.instance.participantManager.getLocalParticipant()

scope.launch {
    participant.setMicrophoneEnabled(true)
}

scope.launch {
    participant.setCameraEnabled(true)
}

scope.launch {
    participant.setScreenShareEnabled(true)
}

participant.switchCamera()

val micEnabled = participant.getMicrophoneEnabled()
val cameraEnabled = participant.getCameraEnabled()
val screenShareEnabled = participant.getScreenShareEnabled()
val cameraPosition = participant.getCameraPosition()
val isSpeaking = participant.getIsSpeaking()
val audioLevel = participant.getAudioLevel()
val createdAt = participant.getCreatedAt()
val isJoined = participant.isJoined()

val onMicChange: (Boolean) -> Unit = { enabled ->
    println("麦克风: ${if (enabled) "开启" else "关闭"}")
}

val onCameraChange: (Boolean) -> Unit = { enabled ->
    println("摄像头: ${if (enabled) "开启" else "关闭"}")
}

val onScreenShareChange: (Boolean) -> Unit = { enabled ->
    println("屏幕共享: ${if (enabled) "开启" else "关闭"}")
}

val onSpeakingChange: (Boolean, Float) -> Unit = { speaking, level ->
    println("正在说话: $speaking, 音量: $level")
}

val onConnQualityChange: (TgoConnectionQuality) -> Unit = { quality ->
    println("连接质量: $quality")
}

val onJoined: () -> Unit = {
    println("参与者已加入")
}

val onLeave: () -> Unit = {
    println("参与者已离开")
}

val onTrackPublished: () -> Unit = {
    println("轨道已发布")
}

val onTrackUnpublished: () -> Unit = {
    println("轨道已取消发布")
}

val onVideoInfoChange: (TgoVideoInfo) -> Unit = { info ->
    println("视频信息: ${info.resolutionString}, ${info.bitrateString}")
}

participant.addMicrophoneStatusListener(onMicChange)
participant.addCameraStatusListener(onCameraChange)
participant.addScreenShareStatusListener(onScreenShareChange)
participant.addSpeakingListener(onSpeakingChange)
participant.addConnQualityListener(onConnQualityChange)
participant.addJoinedListener(onJoined)
participant.addLeaveListener(onLeave)
participant.addTrackPublishedListener(onTrackPublished)
participant.addTrackUnpublishedListener(onTrackUnpublished)
participant.addVideoInfoListener(onVideoInfoChange)

participant.removeMicrophoneStatusListener(onMicChange)
participant.removeCameraStatusListener(onCameraChange)
participant.removeScreenShareStatusListener(onScreenShareChange)
participant.removeSpeakingListener(onSpeakingChange)
participant.removeConnQualityListener(onConnQualityChange)
participant.removeJoinedListener(onJoined)
participant.removeLeaveListener(onLeave)
participant.removeTrackPublishedListener(onTrackPublished)
participant.removeTrackUnpublishedListener(onTrackUnpublished)
participant.removeVideoInfoListener(onVideoInfoChange)

6. 渲染视频轨道

在布局 XML 中添加 TgoVideoRenderer：

<com.tgo.rtc.track.TgoVideoRenderer
    android:id="@+id/videoRenderer"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

在 Activity 或 Fragment 中初始化：

import com.tgo.rtc.track.TgoRendererType
import com.tgo.rtc.track.TgoVideoRenderer
import com.tgo.rtc.track.TgoVideoScaleType
import io.livekit.android.room.track.Track

val renderer = findViewById<TgoVideoRenderer>(R.id.videoRenderer)

renderer.init()
renderer.setParticipant(participant)
renderer.setMirror(true)
renderer.setRendererType(TgoRendererType.TEXTURE_VIEW)
renderer.setScaleType(TgoVideoScaleType.FILL)
renderer.setTrackSource(Track.Source.CAMERA)

7. 音频管理

import com.tgo.rtc.entity.TgoAudioDevice
import com.tgo.rtc.entity.TgoAudioDeviceType

val devices = TgoRTC.instance.audioManager.getAudioOutputDevices()
val selected = TgoRTC.instance.audioManager.getSelectedDevice()

val deviceListener: (List<TgoAudioDevice>, TgoAudioDevice?) -> Unit = { available, current ->
    println("可用设备: $available")
    println("当前设备: $current")
}

TgoRTC.instance.audioManager.addDeviceChangeListener(deviceListener)

selected?.let { TgoRTC.instance.audioManager.selectDevice(it) }
TgoRTC.instance.audioManager.selectDeviceByType(TgoAudioDeviceType.SPEAKER)

TgoRTC.instance.audioManager.toggleSpeakerphone()
TgoRTC.instance.audioManager.setSpeakerphoneOn(true)

val isSpeakerOn = TgoRTC.instance.audioManager.isSpeakerOn()
val hasBluetooth = TgoRTC.instance.audioManager.isBluetoothConnected()
val hasWiredHeadset = TgoRTC.instance.audioManager.isWiredHeadsetConnected()
val canSwitchSpeaker = TgoRTC.instance.audioManager.canSwitchSpeakerphone()

TgoRTC.instance.audioManager.removeDeviceChangeListener(deviceListener)

8. 离开房间

TgoRTC.instance.roomManager.leaveRoom()

API 参考

TgoRTC

属性	类型	描述
instance	TgoRTC	单例实例
options	TgoOptions	SDK 配置选项
roomManager	TgoRoomManager	房间管理
participantManager	TgoParticipantManager	参与者管理
audioManager	TgoAudioManager	音频管理

TgoRoomManager

方法	描述
joinRoom(roomInfo, micEnabled, cameraEnabled)	加入房间 (suspend)
leaveRoom()	离开当前房间
addConnectListener(listener)	添加连接状态监听器
removeConnectListener(listener)	移除连接状态监听器
addVideoInfoListener(listener)	添加视频信息监听器
removeVideoInfoListener(listener)	移除视频信息监听器
isCalling()	是否正在通话中

TgoParticipantManager

方法	描述
getLocalParticipantOrNull()	获取本地参与者，为空时返回 null
getLocalParticipant()	获取本地参与者
getRemoteParticipants(includePending)	获取远程参与者列表
getAllParticipants(includePending)	获取所有参与者列表
getJoinedParticipants()	获取已加入的参与者列表
getJoinedRemoteParticipants()	获取已加入的远程参与者列表
getJoinedParticipantCount()	获取已加入参与者数量
inviteParticipant(roomName, uids)	邀请指定 UID 的参与者
removePendingParticipants(roomName?, uids)	移除尚未加入的待加入参与者
addNewParticipantListener(listener)	监听新参与者加入
removeNewParticipantListener(listener)	移除新参与者监听

TgoParticipant

媒体控制方法 (仅本地有效)

方法	描述
setMicrophoneEnabled(enabled)	开启/关闭麦克风 (suspend)
setCameraEnabled(enabled)	开启/关闭摄像头 (suspend)
setScreenShareEnabled(enabled)	开启/关闭屏幕共享 (suspend)
switchCamera()	切换前后摄像头

状态获取方法

方法	描述
getMicrophoneEnabled()	获取麦克风状态
getCameraEnabled()	获取摄像头状态
getScreenShareEnabled()	获取屏幕共享状态
getCameraPosition()	获取摄像头位置 (前/后)
getAudioLevel()	获取当前音量 (0.0 - 1.0)
getIsSpeaking()	检查是否正在说话
getVideoTrack(source)	获取视频轨道
getCreatedAt()	获取参与者对象创建时间
isJoined()	是否已加入房间

事件监听方法

方法	描述
addMicrophoneStatusListener(listener)	监听麦克风状态变化
addCameraStatusListener(listener)	监听摄像头状态变化
addSpeakerStatusListener(listener)	监听扬声器状态变化
addScreenShareStatusListener(listener)	监听屏幕共享状态变化
addSpeakingListener(listener)	监听说话状态及音量变化
addCameraPositionListener(listener)	监听摄像头位置变化
addConnQualityListener(listener)	监听连接质量变化
addJoinedListener(listener)	监听参与者加入
addLeaveListener(listener)	监听参与者离开
addTrackPublishedListener(listener)	监听轨道发布
addTrackUnpublishedListener(listener)	监听轨道取消发布
addVideoInfoListener(listener)	监听视频信息变化
remove...Listener(listener)	移除对应的监听器

属性

属性	描述
uid	参与者 UID
isLocal	是否为本地参与者

TgoVideoRenderer (View)

方法	描述
init()	初始化渲染器
init(room)	使用指定 Room 初始化渲染器
setParticipant(participant)	设置要渲染的参与者
setVideoTrack(track)	直接设置视频轨道
setMirror(mirror)	设置镜像
setRendererType(type)	设置渲染器类型 (SurfaceView/TextureView)
setScaleType(type)	设置视频缩放模式 (FILL/FIT)
setTrackSource(source)	设置轨道来源 (CAMERA/SCREEN_SHARE)
release()	释放资源

TgoAudioManager

方法	描述
addDeviceChangeListener(listener)	监听输出设备变化
removeDeviceChangeListener(listener)	移除设备变化监听
getAudioOutputDevices()	获取可用输出设备
getSelectedDevice()	获取当前选中的输出设备
selectDevice(device)	选择指定输出设备
selectDeviceByType(type)	按设备类型选择输出设备
isWiredHeadsetConnected()	是否连接有线耳机
isBluetoothConnected()	是否连接蓝牙音频设备
isSpeakerOn()	当前是否为扬声器输出
setSpeakerphoneOn(on)	设置扬声器开关状态
toggleSpeakerphone()	切换扬声器状态
canSwitchSpeakerphone()	当前是否支持切换扬声器

枚举类型

TgoConnectStatus

enum class TgoConnectStatus {
    CONNECTING,
    CONNECTED,
    DISCONNECTED
}

TgoRTCType

enum class TgoRTCType {
    AUDIO,
    VIDEO
}

TgoConnectionQuality

enum class TgoConnectionQuality {
    UNKNOWN,
    EXCELLENT,
    GOOD,
    POOR,
    LOST
}

TgoCameraPosition

enum class TgoCameraPosition {
    FRONT,
    BACK
}

TgoRoomInfo 类

用于配置房间连接的信息类。

属性	描述
roomName	房间名称
token	LiveKit Token
url	LiveKit 服务器地址
loginUID	当前用户 ID
creatorUID	房间创建者 ID
maxParticipants	最大参与人数 (默认 2)
rtcType	通话类型 (默认 AUDIO)
isP2P	是否为 P2P 模式 (默认 true)
uidList	参与者 UID 列表
timeout	加入超时时间（秒，默认 30）

配置选项

class TgoOptions {
    var mirror: Boolean = false
    var debug: Boolean = true
}

平台配置

权限设置

在 AndroidManifest.xml 中添加以下权限：

<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
<uses-permission android:name="android.permission.BLUETOOTH" />

对于 Android 12 (API 31) 及以上版本，如果使用蓝牙耳机，还需要：

<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />

处理未加入的待加入参与者

当前 Android SDK 没有 participant.addTimeoutListener(...) 这类参与者级超时事件。 SDK 的做法是由 TgoRoomManager 按 roomInfo.timeout 定时检查待加入参与者， 超时后通过 TgoParticipantManager.removePendingParticipants(...) 移除。 如果业务侧已经知道某些用户未接听，也可以主动调用：

TgoRTC.instance.participantManager.removePendingParticipants(
    roomName = roomInfo.roomName,
    uids = listOf("user_b", "user_c")
)