iOS SDK (Swift)

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

安装

Swift Package Manager

1. 在 Xcode 中选择 File → Add Packages...
2. 输入仓库地址：

https://github.com/TgoRTC/TgoRTCiOS

3. 选择 Branch: main 或指定版本
4. 勾选 TgoRTCSDK

依赖说明

SDK 自动包含 LiveKit 依赖。

快速开始

1. 初始化 SDK

import TgoRTCSDK

let options = Options()
options.isDebug = true
options.mirror = false

TgoRTC.shared.configure(options: options)

2. 创建房间信息并加入

import TgoRTCSDK

let roomInfo = RoomInfo(
    roomName: "room-name",
    token: "your-token",
    url: "wss://your-server",
    maxParticipants: 4,
    rtcType: .video,
    isP2P: true,
    uidList: ["local-user-id", "remote-user-id"],
    timeout: 30,
    creatorUid: "creator-user-id",
    loginUID: "local-user-id"
)

TgoRTC.shared.roomManager.join(
    roomInfo: roomInfo,
    micEnabled: true,
    cameraEnabled: true,
    screenShareEnabled: false
)

说明： 当前 Swift SDK 的 join(...) 是非阻塞方法。 调用后会立即返回，连接状态请通过 addConnectionStatusListener(...) 监听。

3. 监听连接状态

let connectionToken = TgoRTC.shared.roomManager.addConnectionStatusListener { roomName, status in
    print("房间 \(roomName) 状态变化: \(status)")

    switch status {
    case .connecting:
        print("正在连接...")
    case .connected:
        print("已连接到房间")
    case .disconnected:
        print("已断开连接")
    }
}

// 停止监听
connectionToken.cancel()

说明： 当前 iOS SDK 的 ConnectStatus 只有 connecting / connected / disconnected 三个状态。

4. 获取参与者

let local = TgoRTC.shared.participantManager.getLocalParticipant()
let remotes = TgoRTC.shared.participantManager.getRemoteParticipants()
let all = TgoRTC.shared.participantManager.getAllParticipants()

let newParticipantToken = TgoRTC.shared.participantManager.addNewParticipantListener { participant in
    print("新参与者加入: \(participant.uid)")
}

5. 媒体控制与事件

TgoParticipant 使用 Combine 的 @Published 属性和 PassthroughSubject 事件。

import Combine
import TgoRTCSDK

var cancellables = Set<AnyCancellable>()

let participant = TgoRTC.shared.participantManager.getLocalParticipant()

Task {
    await participant?.setMicrophoneEnabled(true)
    await participant?.setCameraEnabled(true)
    await participant?.setScreenShareEnabled(true)
    await participant?.setSpeakerphoneOn(true)
}

participant?.switchCamera()

participant?.$isMicrophoneOn
    .sink { isOn in
        print("麦克风状态: \(isOn)")
    }
    .store(in: &cancellables)

participant?.$isCameraOn
    .sink { isOn in
        print("摄像头状态: \(isOn)")
    }
    .store(in: &cancellables)

participant?.$isSpeaking
    .sink { speaking in
        print("正在说话: \(speaking)")
    }
    .store(in: &cancellables)

participant?.$audioLevel
    .sink { level in
        print("音量: \(level)")
    }
    .store(in: &cancellables)

participant?.$connectionQuality
    .sink { quality in
        print("连接质量: \(quality)")
    }
    .store(in: &cancellables)

participant?.$cameraPosition
    .sink { position in
        print("摄像头位置: \(position)")
    }
    .store(in: &cancellables)

participant?.$videoInfo
    .sink { info in
        print("视频信息: \(info.resolutionString), \(info.bitrateString)")
    }
    .store(in: &cancellables)

participant?.onJoined
    .sink {
        print("参与者已加入")
    }
    .store(in: &cancellables)

participant?.onLeave
    .sink { reason in
        print("参与者离开，原因: \(reason)")
    }
    .store(in: &cancellables)

participant?.onTrackPublished
    .sink {
        print("轨道已发布")
    }
    .store(in: &cancellables)

participant?.onTrackUnpublished
    .sink {
        print("轨道已取消发布")
    }
    .store(in: &cancellables)

6. 渲染视频轨道

SDK 提供了 TgoTrackRenderer（SwiftUI View）用于显示视频。

import SwiftUI
import TgoRTCSDK

struct VideoView: View {
    @ObservedObject var participant: TgoParticipant

    var body: some View {
        TgoTrackRenderer(
            participant: participant,
            source: .camera,
            fit: .fill
        )
        .frame(width: 200, height: 300)
    }
}

7. 音频管理

Task {
    await TgoRTC.shared.audioManager.toggleSpeakerphone()
    await TgoRTC.shared.audioManager.setSpeakerphoneOn(true)
}

Task {
    let devices = await TgoRTC.shared.audioManager.getAudioOutputDevices()
    print(devices.map { "\($0.name)-\($0.type.rawValue)" })

    if let speaker = devices.first(where: { $0.type == .speaker }) {
        let success = await TgoRTC.shared.audioManager.selectAudioOutputDevice(speaker)
        print("切换扬声器结果: \(success)")
    }
}

let deviceToken = TgoRTC.shared.audioManager.addDeviceChangeListener { devices in
    print("音频设备变化: \(devices)")
}

8. 离开房间

Task {
    await TgoRTC.shared.roomManager.leaveRoom()
}

API 参考

TgoRTC

属性	类型	描述
shared	TgoRTC	单例实例
options	Options?	SDK 配置
roomManager	RoomManager	房间管理
participantManager	ParticipantManager	参与者管理
audioManager	AudioManager	音频管理

RoomManager

方法	描述
join(roomInfo, micEnabled, cameraEnabled, screenShareEnabled)	加入房间
leaveRoom()	离开当前房间
addConnectionStatusListener(listener)	添加连接状态监听器
addVideoInfoListener(listener)	添加本地视频信息监听器
restartTimeoutCheckerIfNeeded()	如有需要重启超时检查器

属性	类型	描述
currentRoomInfo	RoomInfo?	当前房间信息
room	Room?	LiveKit 房间实例

ParticipantManager

方法	描述
getLocalParticipant()	获取本地参与者
getRemoteParticipants()	获取远程参与者
getAllParticipants()	获取所有参与者
initializePendingParticipants()	初始化待加入参与者
syncExistingRemoteParticipants()	同步已在房间中的远程参与者
inviteParticipant(roomName, uids)	邀请参与者
removePendingParticipants(roomName, uids)	移除未加入参与者
setParticipantJoin(participant)	标记参与者加入
setParticipantLeave(participant)	标记参与者离开
addNewParticipantListener(listener)	监听新参与者
clear()	清空参与者状态

TgoParticipant

属性

属性	类型	描述
uid	String	参与者 ID
createdAt	Date	创建时间
isLocal	Bool	是否为本地参与者
isDisposed	Bool	是否已销毁

@Published 属性

属性	类型	描述
isMicrophoneOn	Bool	麦克风是否开启
isCameraOn	Bool	摄像头是否开启
isSpeaking	Bool	是否正在说话
audioLevel	Float	音量级别
connectionQuality	TgoConnectionQuality	连接质量
cameraPosition	TgoCameraPosition	摄像头位置
isJoined	Bool	是否已加入
videoInfo	VideoInfo	当前视频信息

事件

属性	类型	描述
onJoined	PassthroughSubject<Void, Never>	加入事件
onLeave	PassthroughSubject<TgoLeaveReason, Never>	离开事件
onTrackPublished	PassthroughSubject<Void, Never>	轨道发布事件
onTrackUnpublished	PassthroughSubject<Void, Never>	轨道取消发布事件

方法

方法	描述
getVideoTrack(source)	获取指定源的视频轨道
setLocalParticipant(participant)	绑定本地参与者
setRemoteParticipant(participant)	绑定远程参与者
notifyLeave(reason)	通知离开
setSpeakerphoneOn(enabled)	设置扬声器
setMicrophoneEnabled(enabled)	开启/关闭麦克风
setCameraEnabled(enabled)	开启/关闭摄像头
setScreenShareEnabled(enabled)	开启/关闭屏幕共享
switchCamera()	切换前后摄像头
dispose()	释放资源

AudioManager

方法 / 属性	描述
isSpeakerOn	当前是否使用扬声器
currentOutputDevice	当前选中的输出设备
addDeviceChangeListener(listener)	监听设备变化
setSpeakerphoneOn(on, forceSpeakerOutput)	设置扬声器
toggleSpeakerphone()	切换扬声器
getAudioInputDevices()	获取音频输入设备
getAudioOutputDevices()	获取音频输出设备
selectAudioOutputDevice(device)	选择输出设备
dispose()	清理资源

TgoTrackRenderer

TgoTrackRenderer(
    participant: participant,
    source: .camera,
    fit: .fill
)

枚举类型

ConnectStatus

public enum ConnectStatus {
    case connecting
    case connected
    case disconnected
}

RTCType

public enum RTCType {
    case audio
    case video
}

TgoCameraPosition

public enum TgoCameraPosition {
    case front
    case back
}

TgoConnectionQuality

public enum TgoConnectionQuality {
    case unknown
    case excellent
    case good
    case poor
    case lost
}

TgoLeaveReason

public enum TgoLeaveReason {
    case normal
    case timeout
}

RoomInfo

public final class RoomInfo {
    var roomName: String
    var token: String
    var url: String
    var maxParticipants: Int
    var rtcType: RTCType
    var isP2P: Bool
    var uidList: [String]
    var timeout: Int
    var creatorUid: String
    var loginUID: String

    func isCreator() -> Bool
    func getP2PToUID() -> String
}

VideoInfo

public struct VideoInfo {
    let width: Int
    let height: Int
    let bitrate: Int
    let frameRate: Double
    let layerId: String?
    let qualityLimitationReason: String?

    var isValid: Bool
    var resolutionString: String
    var bitrateString: String
}

平台配置

权限设置

在 Info.plist 中添加以下权限描述：

<key>NSCameraUsageDescription</key>
<string>需要访问摄像头进行视频通话</string>
<key>NSMicrophoneUsageDescription</key>
<string>需要访问麦克风进行语音通话</string>

如果需要支持后台音频通话，请在 Signing & Capabilities 中开启 Background Modes，并勾选 Audio, AirPlay, and Picture in Picture。