AtomicXCore 的核心功能的集成指南,开发者使用 Atomicx 快速实现大型网络研讨会、企业全员大会或在线教育大班课的基础能力。开发者可完全自定义 UI 界面,专注于业务逻辑和用户体验的实现。主持人 | 嘉宾 | 观众 |
支持主持人发起高清音视频推流与屏幕共享,支持对成员进行管理。 | 支持嘉宾开启麦克风进行实时语音讨论和分享。 | 支持观众无上限并发进房,以超低延迟观看实况并参与高频消息互动。支持观众通过“举手”功能向主持人申请变更为嘉宾。 |
![]() | ![]() | ![]() |
AtomicXCore,您可以快速获得构建专业研讨会场景所需的完整能力:AtomicXCore 核心模块包含以下两个:RoomStore:房间管理功能入口,包含功能:创建房间、加入房间等。RoomParticipantStore:房间内成员功能入口, 包含功能:管理员设置、嘉宾观众管理、成员移出房间、嘉宾设备控制等。Android 5.0 (SDK API level 21)及以上。Gradle 8.0 及以上。Android 5.0 以上的设备。JDK 17、18 或 19 版本。dependencies {implementation 'io.trtc.uikit:atomicx-core:4.0.6.181'api "com.tencent.imsdk:imsdk-plus:8.7.7201"}
LoginStore.shared.login 完成登录,这是使用 AtomicXCore 所有功能的关键前提。import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.login.LoginStoreimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport android.util.Logclass MainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)LoginStore.shared.login(this, // context1400000001, // 替换为项目的 sdkAppID"test_001", // 替换为项目的 userID"xxxxxxxxxxx", // 替换为项目的 userSigobject : CompletionHandler {override fun onSuccess() {// 登录成功处理Log.d("Login", "login success");}override fun onFailure(code: Int, desc: String) {// 登录失败处理Log.e("Login", "login failed, code: $code, error: $desc");}})}}
参数 | 类型 | 说明 |
sdkAppID | Int | |
userID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123 等简单 ID。 |
userSig | String | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 UserSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参见 服务端生成 UserSig。 |

CreateRoomOptions 设置房间名称,房间配置。RoomStore 的 createAndJoinRoom 接口执行核心操作。import android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.CreateRoomOptionsimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomType// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {private val roomID = "webinar_123456"override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)//自动创建并加入房间逻辑createAndJoinRoom()}// 调用此方法完成创建并加入房间的复合操作private fun createAndJoinRoom() {// 1. 配置房间初始化参数// CreateRoomOptions 用于定义房间的基础属性及初始权限控制val options = CreateRoomOptions()options.roomName = "我的研讨会" // 设置房间对外展示的名称options.password = "" // 研讨会房间暂时不支持密码,这里可以填空// 2. 房间权限预设:在创建之初即可控制全场权限(通常用于正式会议场景)options.isAllCameraDisabled = false // 全员开启/禁用摄像头的初始状态options.isAllMessageDisabled = false // 全员开启/禁言的初始状态options.isAllMicrophoneDisabled = false // 全员开启/静音的初始状态options.isAllScreenShareDisabled = false // 全员禁止/允许屏幕分享的初始状态// 3. 创建并加入房间// 该方法是一个复合操作:若房间不存在则先创建,随后自动执行加入流程RoomStore.shared().createAndJoinRoom(roomID, RoomType.WEBINAR, options, object : CompletionHandler {override fun onSuccess() {// 创建并加入成功:此时可以开始订阅房间状态、打开本地摄像头或麦克风Log.d("Room", "创建并加入研讨会房间成功")}override fun onFailure(code: Int, desc: String) {// 创建并加入失败:可能由于权限不足、网络异常或参数非法Log.e("Room", "创建并加入研讨会房间失败 [错误码: $code]: $desc")}})}}
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型: STANDARD:标准房间。WEBINAR:大型研讨会房间。研讨会场景这里填写 WEBINAR 房间类型。 |
options | CreateRoomOptions | 是 | 创建房间配置对象。 详细用法请参考:CreateRoomOptions 结构体详细说明。 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回创建和加入房间的结果。若创建失败则会返回错误码和错误信息。 |
参数名 | 类型 | 必填 | 说明 |
roomName | String | 否 | 房间名称,可以不设置,默认为空字符串。 限制长度为 0-60 字节。 【推荐用法】支持中英文、数字、特殊字符。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
isAllMicrophoneDisabled | Boolean | 否 | 是否全员禁止打开麦克风。开启后,除房主/管理员外,嘉宾默认禁止打开麦克风: true:禁止 false:取消禁止 (默认值) |
isAllCameraDisabled | Boolean | 否 | 是否全员禁止打开摄像头。开启后,除房主/管理员外,嘉宾默认禁止打开摄像头: true:禁止 false:取消禁止(默认值) |
isAllScreenShareDisabled | Boolean | 否 | 是否全员禁止发起屏幕共享。开启后,仅房主/管理员可进行屏幕共享: true:禁止 false:取消禁止(默认值) |
isAllMessageDisabled | Boolean | 否 | 是否全员禁止发送聊天消息(禁言)。开启后,成员无法在房间内发送文字消息: true:禁止 false:取消禁止(默认值) |
DeviceStore 单例对象的 openLocalCamera、openLocalMicrophone 接口打开本地音视频设备采集,startScreenShare 可以开启屏幕分享(屏幕分享时需要关闭摄像头)。import android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.device.DeviceStore// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)openDevices()}private fun openDevices() {// 1. 打开前置摄像头DeviceStore.shared().openLocalCamera(true, completion = null)// 2. 打开麦克风DeviceStore.shared().openLocalMicrophone(completion = null)// 3. 开始屏幕分享 (屏幕分享开启的时候需要关闭摄像头)// DeviceStore.shared().closeLocalCamera() //关闭摄像头// DeviceStore.shared().startScreenShare() //开始屏幕分享}}
参数名 | 类型 | 必填 | 说明 |
isFront | Boolean | 是 | 是否开启前置摄像头: true :开启前置摄像头。 false :开启后置摄像头。 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回开启摄像头的结果。若开启失败则会返回错误码和错误信息。 |
RoomStore 的 endRoom 接口即可结束当前房间。结束房间后,房间内的所有成员都会收到房间结束事件。import android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)endRoom()}// 调用此方法结束房间private fun endRoom() {// endRoom 接口用于永久结束当前房间。// 注意:通常该操作仅限房主(Owner)执行,执行后所有成员将被移出房间且音视频采集会强制停止。RoomStore.shared().endRoom(object : CompletionHandler {override fun onSuccess() {// 结束房间成功Log.d("Room", "结束房间成功")}override fun onFailure(code: Int, desc: String) {// 结束房间失败Log.e("Room", "结束房间失败 [错误码: $code]: $desc")}})}}
RoomStore 的 joinRoom 接口,即可加入房间。import android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStoreimport io.trtc.tuikit.atomicxcore.api.room.RoomType// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {private val roomID = "webinar_123456"override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)joinRoom()}// 调用此方法加入一个已存在的房间private fun joinRoom() {// 1. 准备加入参数// joinRoom 适用于加入一个已知且正在进行的房间val targetRoomID = this.roomID // 目标房间 ID// 2. 调用 RoomStore 加入房间接口RoomStore.shared().joinRoom(targetRoomID, RoomType.WEBINAR, completion = object : CompletionHandler {override fun onSuccess() {// 3. 加入成功处理Log.d("Room", "加入房间成功")}override fun onFailure(code: Int, desc: String) {// 4. 加入失败处理Log.e("Room", "加入房间失败 [错误码: $code]: $desc")}})}}
参数名 | 类型 | 必填 | 说明 |
roomID | String | 是 | 字符串类型的房间唯一标识符。 限制长度为 0-48 字节。 建议仅包含数字、英文字母(区分大小写)、下划线(_)和连字符(-)。避免使用空格和中文字符。 |
roomType | RoomType | 是 | 房间类型: STANDARD:标准房间。WEBINAR:大型研讨会房间。研讨会场景这里填写 WEBINAR 房间类型。 |
password | String | 否 | 房间密码,空字符串 "" 通常表示该房间不设密码。 限制长度为 0-32 字节。 推荐使用 4-8 位纯数字,方便移动端输入。设置后,其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 研讨会场景暂时不支持密码功能,这里可以填空。 |
completion | CompletionHandler | 否 | 操作完成回调,用于返回加入房间的结果。若加入房间失败则会返回错误码和错误信息。 |
RoomStore 的 leaveRoom 接口即可离开房间。import android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)leaveRoom()}// 调用此方法主动退出当前房间private fun leaveRoom() {// 1. 业务逻辑说明// leaveRoom 接口用于普通成员或房主主动退出房间。// 与 endRoom 不同,房主调用 leaveRoom 只会让自己离开,房间依然存在。// 2. 调用 RoomStore 离开房间接口// 该操作会停止音视频流传输,并通知服务器将当前用户移出房间RoomStore.shared().leaveRoom(object : CompletionHandler {override fun onSuccess() {// 3. 退出成功处理Log.d("Room", "退出房间成功")}override fun onFailure(code: Int, desc: String) {// 4. 退出失败处理Log.e("Room", "退出房间失败 [错误码: $code]: $desc")}})}}
RoomView 组件已封装了研讨会的流媒体处理逻辑。开发者只需在页面中渲染 RoomView 组件,即可自动完成研讨会房间的音视频能力建设。视频渲染需要配合 TUIRoomKit 的组件来完成。RoomView 内置能力:<com.trtc.uikit.roomkit.view.main.RoomViewandroid:id="@+id/room_view"android:layout_width="match_parent"android:layout_height="match_parent"app:layout_constraintStart_toStartOf="parent"app:layout_constraintTop_toTopOf="parent" />
RoomParticipantStore 的 promoteAudienceToParticipant 接口可以将房间内的观众提升成为嘉宾。demoteParticipantToAudience 接口可以将房间内的嘉宾降级成为观众。import android.util.Logimport io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.room.RoomParticipantStorefun promoteAudienceToParticipant(userID: String) {// 前提:需要先完成进房操作。// 1. 业务逻辑说明// 通过进房的 roomID 创建 RoomParticipantStore 实例val participantStore = RoomParticipantStore.create(roomID = "webinar_123456")// 2. 调用 RoomParticipantStore 提升观众为嘉宾接口// 注意:只有房主或管理员才有权限执行此操作。participantStore.promoteAudienceToParticipant(userID = userID, completion = object : CompletionHandler {override fun onSuccess() {Log.d("Test", "提升为嘉宾成功")}override fun onFailure(code: Int, desc: String) {Log.e("Test", "提升为嘉宾失败 [错误码: $code]: $desc")}})}fun demoteParticipantToAudience(userID: String) {// 前提:需要先完成进房操作。// 1. 业务逻辑说明// 通过进房的 roomID 创建 RoomParticipantStore 实例val participantStore = RoomParticipantStore.create(roomID = "webinar_123456")// 2. 调用 RoomParticipantStore 降级嘉宾为观众接口// 注意:只有房主或管理员才有权限执行此操作。participantStore.demoteParticipantToAudience(userID = userID, completion = object : CompletionHandler {override fun onSuccess() {Log.d("Test", "降级为观众成功")}override fun onFailure(code: Int, desc: String) {Log.e("Test", "降级为观众失败 [错误码: $code]: $desc")}})}
RoomStore 的 addRoomListener 可以订阅到 RoomListener 中与房间相关的被动事件。import android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.room.RoomInfoimport io.trtc.tuikit.atomicxcore.api.room.RoomListenerimport io.trtc.tuikit.atomicxcore.api.room.RoomStore// RoomMainActivity 代表房间主视图 Activityclass RoomMainActivity : AppCompatActivity() {// 1. 访问 RoomStore 的 RoomListener// 该 RoomListener 会推送房间全生命周期的事件,如呼叫、解散、预约提醒等private val roomListener = object : RoomListener() {// 2. 根据事件类型执行相应的业务逻辑override fun onRoomEnded(roomInfo: RoomInfo) {Log.d("Room", "当前所在房间已结束")}// ... 处理其他 RoomListener 事件 ...}override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)// 核心流程:在初始化时开启事件监听subscribeRoomEvents()}// 调用此方法订阅房间被动事件private fun subscribeRoomEvents() {RoomStore.shared().addRoomListener(roomListener)}override fun onDestroy() {super.onDestroy()// 移除监听器,防止内存泄漏RoomStore.shared().removeRoomListener(roomListener)}}

AndroidManifest.xml 中都配置了 allowBackup 属性,造成冲突。AndroidManifest.xml 文件中删除 allowBackup 属性或将该属性改为 false,表示关闭备份和恢复功能;并在 AndroidManifest.xml 文件的 application 节点中添加 tools:replace="android:allowBackup" 表示覆盖其他模块的设置,使用您自己的设置。修复示例如图所示:
<uses-permission android:name="android.permission.CAMERA" /><uses-permission android:name="android.permission.RECORD_AUDIO" />
import android.Manifestimport android.content.pm.PackageManagerimport android.os.Bundleimport android.util.Logimport androidx.appcompat.app.AppCompatActivityimport androidx.core.app.ActivityCompatimport androidx.core.content.ContextCompatimport io.trtc.tuikit.atomicxcore.api.device.DeviceStoreclass RoomMainActivity : AppCompatActivity() {private val PERMISSION_REQUEST_CODE = 1001override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)checkAndRequestPermissions()}private fun checkAndRequestPermissions() {val permissions = arrayOf(Manifest.permission.CAMERA,Manifest.permission.RECORD_AUDIO)val permissionsToRequest = permissions.filter {ContextCompat.checkSelfPermission(this, it) != PackageManager.PERMISSION_GRANTED}if (permissionsToRequest.isNotEmpty()) {ActivityCompat.requestPermissions(this,permissionsToRequest.toTypedArray(),PERMISSION_REQUEST_CODE)} else {// 权限已授予,可以打开设备openDevices()}}override fun onRequestPermissionsResult(requestCode: Int,permissions: Array<out String>,grantResults: IntArray) {super.onRequestPermissionsResult(requestCode, permissions, grantResults)if (requestCode == PERMISSION_REQUEST_CODE) {if (grantResults.all { it == PackageManager.PERMISSION_GRANTED }) {// 所有权限已授予,调用打开设备如openDevices()openDevices()} else {// 部分权限被拒绝Log.e("Permission", "部分权限被拒绝")}}}private fun openDevices() {// 1. 打开前置摄像头DeviceStore.shared().openLocalCamera(isFront = true, completion = null)// 2. 打开麦克风DeviceStore.shared().openLocalMicrophone(completion = null)}
FOREGROUND_SERVICE 、 FOREGROUND_SERVICE_CAMERA 、 FOREGROUND_SERVICE_MICROPHONE 权限和 service 声明。<uses-permission android:name="android.permission.FOREGROUND_SERVICE" /><uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" /><uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" /><serviceandroid:name=".MediaCaptureService"android:foregroundServiceType="camera|microphone" />
import android.app.NotificationChannelimport android.app.NotificationManagerimport android.app.Serviceimport android.content.Intentimport android.content.pm.ServiceInfoimport android.os.Bundleimport android.os.IBinderimport androidx.appcompat.app.AppCompatActivityimport androidx.core.app.NotificationCompatclass MainActivity : AppCompatActivity() {override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)startForegroundService(Intent(this, MediaCaptureService::class.java))}}class MediaCaptureService : Service() {override fun onCreate() {super.onCreate()// 1. 创建通知渠道val channel = NotificationChannel("media", "媒体采集", NotificationManager.IMPORTANCE_LOW)getSystemService(NotificationManager::class.java).createNotificationChannel(channel)// 2. 构建通知val notification = NotificationCompat.Builder(this, "media").setContentTitle("音视频通话中").setSmallIcon(android.R.drawable.ic_menu_call).build()// 3. 启动前台服务,指定 camera 和 microphone 类型(Android 14+ 必须)startForeground(1, notification,ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE)}override fun onBind(intent: Intent?): IBinder? = null}
文档反馈