# AUIKaraoke Kotlin API (/zh-CN/api-reference/online-ktv/android/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/Android)。 ## KaraokeUIKit [#karaokeuikit] 提供 `AUIKitKaraoke` 的核心类,可用于实现组件初始化、创建、销毁房间等基础功能。 ### setup [#setup] ```kotlin fun setup( config: AUICommonConfig, apiConfig: AUIAPIConfig ) ``` 初始化 AUIKaraoke。 在调用 `KaraokeUIKit` 类下的其他 API 前,你需要先调用该方法进行初始化。 **参数** - `config`:初始化设置,详见 [`AUICommonConfig`](#AUICommonConfig)。 - `apiConfig`:声网 API 实例结构体,包括 [`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex)、[`RtmClient`](/zh-CN/api-reference/rtm/android/configuration#create)和 [K 歌房场景化 API](/zh-CN/api-reference/online-ktv/android/ktv-scenario/api/ktv-api) 实例。如需使用其中任意一个实例,请通过该结构体传入;如果未传入,系统内部会自动创建。详见 [`AUIAPIConfig`](#AUIAPIConfig)。 ### getRoomList [#getroomlist] ```kotlin fun getRoomList( startTime: Long?, pageSize: Int, success: (List) -> Unit, failure: (AUIException) -> Unit ) ``` 获取 K 歌房间列表。 你可以调用该方法获取当前已创建的 K 歌房间列表。 **参数** - `startTime`:房间创建的时间,用于筛选在该时间之后创建的房间。 - `pageSize`:每一页房间列表所展示的房间数量。 - `success`:回调函数,当成功获取到 K 歌房间列表时调用,会返回一个房间信息列表,详见 [`AUIRoomInfo`](#AUIRoomInfo)。 - `failure`:回调函数,当房间创建失败时调用,接受一个 `AUIException` 参数表示房间创建失败的异常,无返回值。 ### createRoom [#createroom] ```kotlin fun createRoom( roomInfo: AUIRoomInfo, roomConfig: AUIRoomConfig, karaokeView: KaraokeRoomView, completion: (AUIException?, AUIRoomInfo?) -> Unit ) ``` 创建并启动 K 歌房间。 如果用户角色为房主,可以调用该方法来创建并进入 K 歌房间。如果用户角色为听众,调用 [`enterRoom`](#enterroom) 进入房间。 **参数** - `roomInfo`:所创建的房间信息,详见 [`AUIRoomInfo`](#AUIRoomInfo)。 - `roomConfig`:K 歌房间配置,如房间名、Token 等,详见[`AUIRoomConfig`](#AUIRoomConfig)。 - `karaokeView`:`KaraokeRoomView` 实例,用于显示 K 歌房间的界面。 - `completion`:回调函数,当房间创建失败时接受一个 `AUIException` 参数,表示房间创建失败的异常;当房间创建成功时 `AUIException` 为空并会返回 [`AUIRoomInfo`](#AUIRoomInfo),包含房间信息。 ### enterRoom [#enterroom] ```kotlin fun enterRoom( roomInfo: AUIRoomInfo, roomConfig: AUIRoomConfig, karaokeView: KaraokeRoomView, completion: (AUIException?, AUIRoomInfo?) -> Unit ) ``` 进入 K 歌房间。 如果用户角色为听众,可以调用此方法进入 K 歌房间。 **参数** - `roomInfo`:房间信息,详见 [`AUIRoomInfo`](#AUIRoomInfo)。 - `roomConfig`:K 歌房间配置,如房间名、Token 等,详见[`AUIRoomConfig`](#AUIRoomConfig)。 - `karaokeView`: `KaraokeRoomView` 实例,用于显示 K 歌房间的界面。 - `completion`:回调函数,当进入房间失败时接受一个 `AUIException` 参数,表示进入房间失败的异常;当进入房间成功时 `AUIException` 为空并会返回 [`AUIRoomInfo`](#AUIRoomInfo),包含房间信息。 ### leaveRoom [#leaveroom] ```kotlin fun leaveRoom(roomId: String?) ``` 离开 K 歌房间。 如果用户角色为房主,调用该方法后会离开并销毁房间。房主成功销毁房间后会触发 [`onRoomDestroy`](#onroomdestroy) 回调报告房间被销毁。 **参数** - `roomId`:房间的 ID。 ### release [#release] ```kotlin fun release() ``` 释放 AUIKaraoke 的所有资源。 ### renewToken [#renewtoken] ```kotlin fun renewToken(roomId: String, roomConfig: AUIRoomConfig) ``` 当 Token 过期时,更新房间内 Token 配置。 **参数** - `roomId`:房间的 ID。 - `roomConfig`:K 歌房间配置,如房间名、Token 等,详见[`AUIRoomConfig`](#AUIRoomConfig)。 ### registerRoomRespObserver [#registerroomrespobserver] ```kotlin fun registerRoomRespObserver(roomId: String, observer: AUIKaraokeRoomServiceRespObserver) ``` 注册房间事件观测器。 你可以调用该方法注册一个 `AUIKaraokeRoomServiceRespObserver` 对象,以便监听房间相关的事件回调,例如房间被销毁、房间信息更新等。 **参数** - `roomId`:房间的 ID。 - `observer`:[`AUIKaraokeRoomServiceRespObserver`](#AUIKaraokeRoomServiceRespObserver) 对象,用于处理与房间操作相关的各种事件。你可以根据你的业务需求来实现该接口类中的方法。 ### unRegisterRoomRespObserver [#unregisterroomrespobserver] ```kotlin fun unRegisterRoomRespObserver(roomId: String, observer: AUIKaraokeRoomServiceRespObserver) ``` 取消注册房间事件观测器。 当你退出或销毁房间时,可以调用该方法取消注册房间事件观测器。取消后,你不会再收到任何与房间相关的事件通知。 **参数** - `roomId`:房间的 ID。 - `observer`:[`AUIKaraokeRoomServiceRespObserver`](#AUIKaraokeRoomServiceRespObserver) 对象,用于处理与房间操作相关的各种事件。你可以根据你的业务需求来实现该接口类中的方法。 ## AUIKaraokeRoomServiceRespObserver [#auikaraokeroomservicerespobserver] 该接口类提供房间相关的响应回调。 ### onTokenPrivilegeWillExpire [#ontokenprivilegewillexpire] ```kotlin fun onTokenPrivilegeWillExpire(roomId: String) ``` Token 即将过期时回调。 在收到该回调后,声网建议你重新生成 Token,然后调用 [`renewToken`](#renewtoken) 来传入更新后的 Token。 **参数** - `roomId`:房间 ID。 ### onRoomDestroy [#onroomdestroy] ```kotlin fun onRoomDestroy(roomId: String) ``` 房间被销毁回调。 当房主调用 [`leaveRoom`](#leaveroom) 离开并销毁房间后,会触发该回调。 **参数** - `roomId`:被销毁的房间 ID。 ### onRoomInfoChange [#onroominfochange] ```kotlin fun onRoomInfoChange(roomId: String, roomInfo: AUIRoomInfo) ``` 房间相关信息变更回调。 当房间的房主、房间内人数等信息发生变化时,可通过该回调获取变化后的信息。 **参数** - `roomId`:房间 ID。 - `roomInfo`:房间信息,详见 [`AUIRoomInfo`](#AUIRoomInfo)。 ## 数据模型 [#数据模型] ### AUICommonConfig [#auicommonconfig] ```kotlin public class AUICommonConfig { public @NonNull Context context; public @NonNull String host = ""; public @NonNull AUIUserThumbnailInfo owner = ""; public @NonNull String appId = ""; public @NonNull String appCert = ""; public @NonNull String basicAuth = ""; public @NonNull String imAppKey = ""; public @NonNull String imClientId = ""; public @NonNull String imClientSecret = ""; } ``` 通用设置。 **参数** - `context`:安卓 Context 上下文。 - `host`:你的业务服务器域名。 - `owner`:用户信息,详见 [`AUIUserThumbnailInfo`](#AUIUserThumbnailInfo)。 - `appId`:你的声网项目的 App ID。 - `appCert`:你的声网项目的 App 证书。 - `basicAuth`:预留参数,传空。 - `imAppKey`:环信 IM App Key。 - `imClientId`:环信 IM Client ID。 - `imClientSecret`:环信 IM Client Secret。 :::info[信息] 上述信息可参考[开通服务](/zh-CN/solutions/online-ktv/auikaraoke/build/setup-and-access/enable-service)获取。 ::: ### AUIAPIConfig [#auiapiconfig] ```kotlin data class AUIAPIConfig( val ktvApi: KTVApi? = null, val rtcEngineEx: RtcEngineEx? = null, val rtmClient: RtmClient? = null ) ``` 声网 API 实例结构体。 **参数** - `ktvApi`:[K 歌房场景化 API](/zh-CN/api-reference/online-ktv/android/ktv-scenario/api/ktv-api) 实例,如果未传入,AUIKaraoke 内部会自行创建场景化 API 实例。 - `rtcEngineEx`:[`RtcEngineEx`](/zh-CN/api-reference/rtc/android/rtc-interface-class#class_irtcengineex) 实例。如果未传入,AUIKaraoke 内部会自行创建 `RtcEngineEx` 实例。 - `rtmClient`:[`RtmClient`](/zh-CN/api-reference/rtm/android/configuration#create) 实例。如果未传入,AUIKaraoke 内部会自行创建 `RtmClient` 实例。 ### AUIRoomInfo [#auiroominfo] ```kotlin public class AUIRoomInfo extends AUICreateRoomInfo implements Serializable { public @NonNull String roomId = ""; public @Nullable AUIUserThumbnailInfo roomOwner; public int onlineUsers = 0; public long createTime = 0; } ``` 已创建的 K 歌房间的相关信息。 **参数** - `roomId`:房间 ID。 - `roomOwner`:房主信息,详见 [`AUIUserThumbnailInfo`](#AUIUserThumbnailInfo)。 - `onlineUsers`:房间内的人数。 - `createTime`:房间创建的时间,单位为毫秒。 ### AUIUserThumbnailInfo [#auiuserthumbnailinfo] ```kotlin public class AUIUserThumbnailInfo implements Serializable { public @NonNull String userId = ""; public @NonNull String userName = ""; public @NonNull String userAvatar = ""; } ``` K 歌中房主的相关信息。 **参数** - `userId`:房主的 ID。 - `userName`:房主的用户名。 - `userAvatar`:房主的头像。 ### AUIException [#auiexception] ```kotlin public AUIException(int code, String message) ``` 错误码及信息。 **参数** - `code`:错误码。 - `message`:错误信息。 ### AUIRoomConfig [#auiroomconfig] ```kotlin public class AUIRoomConfig { @NonNull public String channelName = ""; @NonNull public String rtmToken = ""; @NonNull public String rtcToken = ""; @NonNull public String rtcChorusChannelName = ""; @NonNull public String rtcChorusRtcToken = ""; } ``` 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,用于加入合唱频道时进行鉴权。独唱场景下,该参数可为空。