AUIKaraoke Kotlin API

本文介绍 AUIKaraoke 组件的 API。你可以在 GitHub 上查看源码文件。

KaraokeUIKit

提供 AUIKitKaraoke 的核心类，可用于实现组件初始化、创建、销毁房间等基础功能。

setup

Kotlin

fun setup(
    config: AUICommonConfig,
    apiConfig: AUIAPIConfig
)

初始化 AUIKaraoke。

在调用 KaraokeUIKit 类下的其他 API 前，你需要先调用该方法进行初始化。

参数

• config：初始化设置，详见 AUICommonConfig。
• apiConfig：声网 API 实例结构体，包括 RtcEngineEx、RtmClient和 K 歌房场景化 API 实例。如需使用其中任一一个实例，请通过该结构体进行传入，如果未传入，系统内部会自动创建。详见 AUIAPIConfig。

getRoomList

Kotlin

fun getRoomList(
  startTime: Long?,
  pageSize: Int,
  success: (List<AUIRoomInfo>) -> Unit,
  failure: (AUIException) -> Unit
)

获取 K 歌房间列表。

你可以调用该方法获取当前的已创建的 K 歌房间列表。

参数

• startTime：房间创建的时间，用于筛选在该时间之后创建的房间。
• pageSize：每一页房间列表所展示的房间数量。
• success：回调函数，当成功获取到 K 歌房间列表时调用，会返回一个房间信息列表，详见 AUIRoomInfo。
• failure：回调函数，当房间创建失败时调用，接受一个 AUIException 参数表示房间创建失败的异常，无返回值。

createRoom

Kotlin

fun createRoom(
    roomInfo: AUIRoomInfo,
    roomConfig: AUIRoomConfig,
    karaokeView: KaraokeRoomView,
    completion: (AUIException?, AUIRoomInfo?) -> Unit
)

创建并启动 K 歌房间。

如果用户角色为房主，可以调用该方法来创建并进入 K 歌房间。如果用户角色为听众，调用 enterRoom 进入房间。

参数

• roomInfo：所创建的房间信息，详见 AUIRoomInfo。
• roomConfig：K 歌房间配置，如房间名、Token 等，详见AUIRoomConfig。
• karaokeView：KaraokeRoomView 实例，用于显示 K 歌房间的界面。
• completion：回调函数，当房间创建失败时接受一个 AUIException 参数，表示房间创建失败的异常；当房间创建成功时 AUIException 为空并会返回 AUIRoomInfo，包含房间信息。

enterRoom

Kotlin

fun enterRoom(
    roomInfo: AUIRoomInfo,
    roomConfig: AUIRoomConfig,
    karaokeView: KaraokeRoomView,
    completion: (AUIException?, AUIRoomInfo?) -> Unit
)

进入 K 歌房间。

如果用户角色为听众，可以调用此方法进入 K 歌房间。

参数

• roomInfo：房间信息，详见 AUIRoomInfo。
• roomConfig：K 歌房间配置，如房间名、Token 等，详见AUIRoomConfig。
• karaokeView： KaraokeRoomView 实例，用于显示 K 歌房间的界面。
• completion：回调函数，当进入房间失败时接受一个 AUIException 参数，表示进入房间失败的异常；当进入房间成功时 AUIException 为空并会返回 AUIRoomInfo，包含房间信息。

leaveRoom

Kotlin

fun leaveRoom(roomId: String?)

离开 K 歌房间。

如果用户角色为房主，调用该方法后会离开并销毁房间。房主成功销毁房间后会触发 onRoomDestroy 回调报告房间被销毁。

参数

• roomId：房间的 ID。

release

Kotlin

fun release()

释放 AUIKaraoke 的所有资源。

renewToken

Kotlin

fun renewToken(roomId: String, roomConfig: AUIRoomConfig)

当 Token 过期时，更新房间内 Token 配置。

参数

• roomId：房间的 ID。
• roomConfig：K 歌房间配置，如房间名、Token 等，详见AUIRoomConfig。

registerRoomRespObserver

Kotlin

fun registerRoomRespObserver(roomId: String, observer: AUIKaraokeRoomServiceRespObserver)

注册房间事件观测器。

你可以调用该方法注册一个 AUIKaraokeRoomServiceRespObserver 对象，以便监听房间相关的事件回调，例如房间被销毁、用户被踢出、房间的信息更新等。

参数

• roomId：房间的 ID。
• observer：AUIKaraokeRoomServiceRespObserver 对象，用于处理与房间操作相关的各种事件。你可以根据你的业务需求来实现该接口类中的方法。

unRegisterRoomRespObserver

Kotlin

fun unRegisterRoomRespObserver(roomId: String, observer: AUIKaraokeRoomServiceRespObserver)

取消注册房间事件观测器。

当你退出或销毁房间时，可以调用该方法取消注册房间事件观测器。取消后，你不会再收到任何与房间相关的事件通知。

参数

• roomId：房间的 ID。
• observer：AUIKaraokeRoomServiceRespObserver 对象，用于处理与房间操作相关的各种事件。你可以根据你的业务需求来实现该接口类中的方法。

AUIKaraokeRoomServiceRespObserver

该接口类提供房间相关的响应回调。

onTokenPrivilegeWillExpire

Kotlin

fun onTokenPrivilegeWillExpire(roomId: String)

Token 即将过期时回调。

在收到该回调后，声网建议你重新生成 Token，然后调用 renewToken 来传入更新后的 Token。

参数

• roomId：房间 ID。

onRoomDestroy

Kotlin

fun onRoomDestroy(roomId: String)

房间被销毁回调。

当房主调用 leaveRoom 离开并销毁房间后，会触发该回调。

参数

• roomId：被销毁的房间 ID。

onRoomInfoChange

Kotlin

fun onRoomInfoChange(roomId: String, roomInfo: AUIRoomInfo)

房间相关信息变更回调。

当房间的房主、房间内人数等信息发生变化时，可通过该回调获取变化后的信息。

参数

• roomId：房间 ID。
• roomInfo：房间信息，详见 AUIRoomInfo。

数据模型

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。
• appId：你的声网项目的 App ID。
• appCert：你的声网项目的 App 证书。
• basicAuth：预留参数，传空。
• imAppKey：环信 IM App Key。
• imClientId：环信 IM Client ID。
• imClientSecret：环信 IM Client Secret。

信息

上述信息可参考开通服务获取。

AUIAPIConfig

Kotlin

data class AUIAPIConfig(
    val ktvApi: KTVApi? = null,
    val rtcEngineEx: RtcEngineEx? = null,
    val rtmClient: RtmClient? = null
)

声网 API 实例结构体。

参数

• ktvApi：K 歌房场景化 API 实例，如果未传入，AUIKaraoke 内部会自行创建场景化 API 实例。
• rtcEngineEx：RtcEngineEx 实例。如果未传入，AUIKaraoke 内部会自行创建 RtcEngineEx 实例。
• rtmClient：RtmClient 实例。如果未传入，AUIKaraoke 内部会自行创建 RtmClient 实例。

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。
• onlineUsers：房间内的人数。
• createTime：房间创建的时间，单位为毫秒。

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

Kotlin

public AUIException(int code, String message)

错误码及信息。

参数

• code：错误码。
• message：错误信息。

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 服务器。

  注意

  请确保你使用的 RTM Token 是 AccessToken2。

• rtcToken：加入主频道时使用的 RTC Token。

  注意

  请确保你使用的 RTC Token 是 AccessToken2。详见使用 Token 鉴权。

• rtcChorusChannelName：合唱频道名。独唱场景下，该参数可为空。

• rtcChorusRtcToken：根据合唱频道名和用户 ID 生成的 RTC Token，用于加入合唱频道时进行鉴权。独唱场景下，该参数可为空。