# 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,用于加入合唱频道时进行鉴权。独唱场景下,该参数可为空。