# AUIKaraoke Swift API (/zh-CN/api-reference/online-ktv/ios/auikaraoke/api/auikaraoke-api) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文介绍 AUIKaraoke 组件的 API。你可以在 GitHub 上查看[源码文件](https://github.com/AgoraIO-Community/AUIKaraoke/tree/main/iOS)。 ## KaraokeUIKit [#karaokeuikit] 提供 `AUIKaraoke` 的核心类,可用于实现组件初始化、创建、销毁房间等基础功能。 ### setup [#setup] ```swift func setup(commonConfig: AUICommonConfig, apiConfig: AUIAPIConfig? = nil) ``` 初始化 AUIKaraoke。 在调用 `KaraokeUIKit` 类下的其他 API 前,你需要先调用该方法进行初始化。 **参数** - `commonConfig`:初始化配置,详见 [`AUICommonConfig`](#AUICommonConfig)。 - `apiConfig`:声网 API 实例结构体,包括 [`RtcEngineEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex)、[`RtmClient`](/zh-CN/realtime-media/rtm)和 [K 歌房场景化 API](/zh-CN/api-reference/online-ktv/ios/ktv-scenario/api/ktv-api) 实例。如需使用其中任一一个实例,请通过该结构体进行传入,如果未传入,系统内部会自动创建。详见 [`AUIAPIConfig`](#AUIAPIConfig)。 ### getRoomInfoList [#getroominfolist] ```swift func getRoomInfoList(lastCreateTime: Int64?, pageSize: Int, callback: @escaping AUIRoomListCallback) ``` 获取 K 歌房间列表。 你可以调用该方法获取当前已创建的 K 歌房间列表。 **参数** - `lastCreateTime`:(可选)房间创建的时间,单位毫秒。例如:1681879844085。 - `pageSize`:每一页房间列表所展示的房间数量。 - `callback`:用于处理获取房间列表结果的回调闭包,在成功获取房间列表结果后会被调用。回调闭包接受一个 `AUIRoomListCallback` 对象作为参数。 ### createRoom [#createroom] ```swift func createRoom(roomInfo: AUIRoomInfo, roomConfig: AUIRoomConfig, karaokeView: AUIKaraokeRoomView, completion: @escaping (NSError?) -> Void) ``` 创建并启动 K 歌房间。 如果用户角色为房主,可以调用该方法来创建并进入 K 歌房间。如果用户角色为听众,调用 [`enterRoom`](#enterroom) 进入房间。 **参数** - `roomInfo`:一个 [`AUIRoomInfo`](#AUIRoomInfo) 对象,包含要创建的房间信息。 - `roomConfig`:K 歌房间配置,如房间名、Token 等,详见[`AUIRoomConfig`](#AUIRoomConfig)。 - `karaokeView`:`AUIKaraokeRoomView` 实例,用于显示 K 歌房间的界面。 - `completion`:回调闭包,其参数是一个可选的 `NSError` 对象。创建房间成功,则这个参数为 `nil`;如果在创建过程中出现了错误,该参数为一个 `NSError` 对象,包含对应的错误信息。 ### enterRoom [#enterroom] ```swift func enterRoom(roomId: String, roomConfig: AUIRoomConfig, karaokeView: AUIKaraokeRoomView, completion: @escaping (AUIRoomInfo?, NSError?) -> Void) ``` 进入 K 歌房间。 如果用户角色为听众,可以调用此方法进入 K 歌房间。 **参数** - `roomId`:房间 ID。 - `roomConfig`:K 歌房间配置,如房间名、Token 等,详见[`AUIRoomConfig`](#AUIRoomConfig)。 - `karaokeView`: `AUIKaraokeRoomView` 对象,用于显示 K 歌房间的界面。 - `completion`:回调闭包,在进入房间操作完成后被调用。如果进入房间成功,`AUIRoomInfo` 会包含所进入的房间的信息;`NSError` 为 `nil`。如果在进入房间的过程中出现错误,`AUIRoomInfo` 为 `nil`,`NSError` 会包含相应的错误信息。 ### leaveRoom [#leaveroom] ```swift func leaveRoom(roomId: String) ``` 离开 K 歌房间。 如果用户角色为房主,调用该方法后会离开并销毁房间。房主成功销毁房间后会触发 [`onRoomDestroy`](#onroomdestroy) 回调报告房间被销毁。 **参数** - `roomId`:房间的 ID。 ### renew [#renew] ```swift func renew(config: AUIRoomConfig) ``` 当 Token 过期时,更新房间内 Token 配置。 **参数** - `config`:K 歌房间配置,如房间名、Token 等,详见 [`AUIRoomConfig`](#AUIRoomConfig)。 ### bindRespDelegate [#bindrespdelegate] ```swift func bindRespDelegate(delegate: AUIKaraokeRoomServiceRespDelegate) ``` 绑定对应房间的响应。 你可以调用该方法将实现了 `AUIKaraokeRoomServiceRespDelegate` 的对象绑定到当前事件,以便在事件完成时,回调或通知这个对象以处理相应的结果或响应,例如房间被销毁、用户被踢出、房间的信息更新等。 请确保你的 `AUIKaraokeRoomServiceRespDelegate` 对象实现了 `AUIKaraokeRoomServiceRespDelegate` 中的方法,以便能够正确处理响应。 **参数** - `delegate`:[AUIKaraokeRoomServiceRespDelegate](#AUIKaraokeRoomServiceRespDelegate) 对象,用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该协议中的方法。 ### unbindRespDelegate [#unbindrespdelegate] ```swift func unbindRespDelegate(delegate: AUIKaraokeRoomServiceRespDelegate) ``` 取消绑定对应房间的响应。 你可以调用该方法取消已绑定到当前操作或事件的 `AUIKaraokeRoomServiceRespDelegate` 对象。解除绑定后,将不再通知 `AUIKaraokeRoomServiceRespDelegate` 对象与房间管理操作相关的结果或响应。 **参数** `delegate`:[AUIKaraokeRoomServiceRespDelegate](#AUIKaraokeRoomServiceRespDelegate) 对象,用于处理与房间操作相关的各种响应事件。你可以根据你的业务需求选择性实现该协议中的方法。 ## AUIKaraokeRoomServiceRespDelegate [#auikaraokeroomservicerespdelegate] 该接口类提供房间相关的响应回调。 ### onTokenPrivilegeWillExpire [#ontokenprivilegewillexpire] ```swift func onTokenPrivilegeWillExpire(roomId: String?) ``` Token 即将过期时回调。 在收到该回调后,声网建议你重新生成 Token,然后调用 [`renewToken`](#renewtoken) 来传入更新后的 Token。 **参数** `roomId`:房间 ID。 ### onRoomDestroy [#onroomdestroy] ```swift func onRoomDestroy(roomId: String) ``` 房间被销毁回调。 当房主调用 [`leaveRoom`](#leaveroom) 离开并销毁房间后,会触发该回调。 **参数** `roomId`:被销毁的房间 ID。 ### onRoomInfoChange [#onroominfochange] ```swift func onRoomInfoChange(roomId: String, roomInfo: AUIRoomInfo) ``` 房间相关信息变更回调。 当房间的房主、房间内人数等信息发生变化时,可通过该回调获取变化后的信息。 **参数** - `roomId`:房间 ID。 - `roomInfo`:房间信息,详见 [AUIRoomInfo](#AUIRoomInfo)。 ## 数据模型 [#数据模型] ### AUICommonConfig [#auicommonconfig] ```swift open class AUICommonConfig: NSObject { public var host: String = "" public var appId: String = "" public var appCert: String = "" public var basicAuth: String = "" public var imAppKey: String = "" public var imClientId: String = "" public var imClientSecret: String = "" public var owner: AUIUserThumbnailInfo? } ``` 通用设置。 **属性** - `host`:你的业务服务器域名。 - `appId`:你的声网项目的 App ID。 - `appCert`:你的声网项目的 App 证书。 - `basicAuth`:预留参数,传空。 - `imAppKey`:环信 IM App Key。 - `imClientId`:环信 IM Client ID。 - `imClientSecret`:环信 IM Client Secret。 - `owner`:用户信息,详见 [`AUIUserThumbnailInfo`](#AUIUserThumbnailInfo)。 :::info[信息] 上述信息可参考[开通服务](/zh-CN/solutions/online-ktv/auikaraoke/build/setup-and-access/enable-service)获取。 ::: ### AUIRoomInfo [#auiroominfo] ```swift open class AUIRoomInfo: AUICreateRoomInfo { public var roomId: String = "" public var owner: AUIUserThumbnailInfo? public var memberCount: UInt = 0 public var createTime: Int64 = 0 } ``` K 歌房间的相关信息。 **属性** - `roomId`:房间 ID。 - `owner`:房主信息,详见 [`AUIUserThumbnailInfo`](#AUIUserThumbnailInfo)。 - `memberCount`:房间内的人数。 - `createTime`:房间创建的时间,单位为毫秒。 ### AUIUserThumbnailInfo [#auiuserthumbnailinfo] ```swift open class AUIUserThumbnailInfo: NSObject,AUIUserCellUserDataProtocol { public var userId: String = "" public var userName: String = "" public var userAvatar: String = "" } ``` K 歌中房主的相关信息。 **属性** AUIAPIConfig - `userId`:房主的 ID。 - `userName`:房主的用户名。 - `userAvatar`:房主的头像。 ### AUIAPIConfig [#auiapiconfig] ```swift public class AUIAPIConfig: NSObject { var rtcEngine: AgoraRtcEngineKit? = nil var ktvApi: KTVApiDelegate? = nil var rtmClient: AgoraRtmClientKit? = nil } ``` 声网 API 实例结构体。 **属性** - `rtcEngineEx`:[`RtcEngineEx`](/zh-CN/api-reference/rtc/ios/rtc-interface-class#class_irtcengineex) 实例。如果未传入,AUIKaraoke 内部会自行创建 `RtcEngineEx` 实例。 - `ktvApi`:[K 歌房场景化 API](/zh-CN/api-reference/online-ktv/ios/ktv-scenario/api/ktv-api) 实例,如果未传入,AUIKaraoke 内部会自行创建场景化 API 实例。 - `rtmClient`:[`AgoraRtmClientKit`](/zh-CN/realtime-media/rtm) 实例。如果未传入,AUIKaraoke 内部会自行创建 `RtmClient` 实例。 ### AUIRoomConfig [#auiroomconfig] ```swift open class AUIRoomConfig: NSObject { public var channelName: String = "" public var rtmToken: String = "" public var rtcToken: String = "" public var rtcChorusChannelName: String = "" public var rtcChorusRtcToken: String = "" } ``` K 歌房间配置,包括登录 RTM 频道使用的 RTM Token、登录 RTC 频道使用的 RTC Token 等。 **属性** - `channelName`:主频道的频道名。在合唱场景下,领唱需要加入两个频道,在主频道发布人声和播放器的混流,在合唱频道发布麦克风采集的音频流。伴唱需要加入合唱频道来同步领唱的人声。 - `rtmToken`:登陆 RTM 系统时用的 RTM Token,详见 [部署 RTM Token 服务器](/zh-CN/realtime-media/rtm/build/authentication-and-connection/token-generation)。 :::warning[注意] 请确保你使用的 RTM Token 是 AccessToken2。 ::: - `rtcToken`: 加入主频道时使用的 RTC Token。 :::warning[注意] 请确保你使用的 RTC Token 是 AccessToken2。详见[使用 Token 鉴权](/zh-CN/realtime-media/rtc/build/setup-and-access/token-authentication)。 ::: - `rtcChorusChannelName`:合唱频道名。独唱场景下,该参数可为空。 - `rtcChorusRtcToken`:根据合唱频道名和用户 ID 生成的 RTC Token,用于加入合唱频道时进行鉴权。独唱场景下,该参数可为空。