本文档将帮助您使用 AtomicXCore SDK 的核心组件 AtomicLiveView,配合 AtomicPusher(主播推流)和 AtomicPlayer(观众拉流),快速构建一个包含主播开播和观众观看功能的基础直播 App。
核心功能
AtomicLiveView 是一个专为直播场景设计的轻量级
View 组件,是您构建直播画面的"画布"。主播端通过 AtomicPusher 完成本地音视频采集与推流,观众端通过 AtomicPlayer 完成拉流播放,两端都通过 setView 将画面渲染到同一个 AtomicLiveView 上。您只需专注于上层 UI 与交互的开发。通过下方的视图层级示意图,您可以直观了解 AtomicLiveView 在直播界面中的位置和作用:

准备工作
步骤1:开通服务
步骤2:在当前项目中导入 AtomicXCore
安装组件:请在您的 build.gradle 文件中添加
implementation 'com.tencent.atomicx:atomicxcore:latest' 依赖,然后执行 Gradle Sync。implementation("io.trtc.uikit:atomicx-core:latest.release")api("com.tencent.imsdk:imsdk-plus:8.9.7511")
implementation 'io.trtc.uikit:atomicx-core:latest.release'api "com.tencent.imsdk:imsdk-plus:8.9.7511"
步骤3:实现登录逻辑
在您的项目中调用
LoginStore.shared.login 完成登录,这是使用 AtomicXCore 所有功能的关键前提。重要:
推荐在您 App 自身的用户账户登录成功后,再调用 LoginStore.shared.login,以确保登录业务逻辑的清晰和一致。
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。 |
搭建基础直播间
步骤1:实现主播视频开播
主播开播流程如下,您只需执行以下几步操作,即可快速搭建主播视频直播。

1. 初始化主播推流的视图
在您的主播 Activity 中,创建一个
AtomicLiveView 实例,并将 viewType 指定为 AtomicLiveViewType.PUSH_VIEW(推流视图)。import io.trtc.tuikit.atomicxcore.api.view.AtomicLiveViewimport io.trtc.tuikit.atomicxcore.api.view.AtomicLiveViewTypeimport android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport androidx.constraintlayout.widget.ConstraintLayout// YourAnchorActivity 代表您的主播开播Activityclass YourAnchorActivity : AppCompatActivity() {// 1. 将 AtomicLiveView 作为您Activity的一个属性private lateinit var liveView: AtomicLiveViewoverride fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)// 2. 初始化视图liveView = AtomicLiveView(this, viewType = AtomicLiveViewType.PUSH_VIEW)// 布局 UIsetupUI()}private fun setupUI() {setContentView(R.layout.activity_anchor)// 3. 将主播推流页面加载到您的视图上val container = findViewById<ConstraintLayout>(R.id.container)container.addView(liveView)// 设置布局参数val params = ConstraintLayout.LayoutParams(ConstraintLayout.LayoutParams.MATCH_PARENT,ConstraintLayout.LayoutParams.MATCH_PARENT)params.topMargin = 36params.bottomMargin = 96liveView.layoutParams = params}}
2. 打开摄像头和麦克风
通过调用 DeviceStore 的
openLocalCamera、openLocalMicrophone 接口打开摄像头和麦克风,您无需做额外操作,AtomicLiveView 会自动预览当前摄像头的视频流,示例代码如下:import androidx.appcompat.app.AppCompatActivityimport android.os.Bundleimport io.trtc.tuikit.atomicxcore.api.device.DeviceStoreclass YourAnchorActivity : AppCompatActivity() {// ... 其他代码 ...override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)// 布局 UIsetupUI()// 打开设备openDevices()}private fun openDevices() {// 1. 打开前置摄像头DeviceStore.shared().openLocalCamera(true, completion = null)// 2. 打开麦克风DeviceStore.shared().openLocalMicrophone(completion = null)}}
3. 开始直播
通过调用 AtomicPusher 的
setView 绑定渲染视图,再调用 startPush 接口开始视频直播,完整示例代码如下:import android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.live.AtomicPusherimport io.trtc.tuikit.atomicxcore.api.live.PusherInfoclass YourAnchorActivity : AppCompatActivity() {// ... 其他代码 ...// 调用开播接口开始直播private fun startLive() {// 1. 将渲染视图绑定到 AtomicPusher,绑定后即可看到本地预览画面AtomicPusher.shared().setView(liveView)// 2. 配置直播间信息val config = PusherInfo().apply {// 设置直播的房间 idliveID = "test_live_001"// 设置直播的房间名称liveName = "test 直播"}// 3. 调用 AtomicPusher.shared().startPush 开始直播AtomicPusher.shared().startPush(config)Log.d("Live", "startPush")}}
PusherInfo 参数说明参数名 | 类型 | 属性 | 描述 |
liveID | String | 必填 | 直播间的唯一标识符。 |
liveName | String | 选填 | 直播间的标题。 |
notice | String | 选填 | 直播间的公告信息。 |
metaData | Map<String, String> | 选填 | 直播间的自定义元数据。 |
isPublicVisible | Boolean | 选填 | 是否公开可见( true:是,false:否)。 |
coverURL | String | 选填 | 直播间的封面图片地址。 |
backgroundURL | String | 选填 | 直播间的背景图片地址。 |
categoryList | List<Int> | 选填 | 直播间的分类标签列表。 |
4. 结束直播
直播结束后,主播可以调用 AtomicPusher 的
stopPush 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。import android.util.Logimport androidx.appcompat.app.AppCompatActivityimport io.trtc.tuikit.atomicxcore.api.device.DeviceStoreimport io.trtc.tuikit.atomicxcore.api.live.AtomicPusherclass YourAnchorActivity : AppCompatActivity() {// ... 其他代码 ...// 结束直播private fun stopLive() {AtomicPusher.shared().stopPush()Log.d("Live", "stopPush")}// 确保在 Activity 销毁时也调用结束直播override fun onDestroy() {super.onDestroy()stopLive()// 关闭本地设备DeviceStore.shared().closeLocalCamera()DeviceStore.shared().closeLocalMicrophone()Log.d("Live", "YourAnchorActivity onDestroy")}}
步骤2:实现观众进房观看
观众观看流程如下,通过简单几步操作,即可实现观众观看直播。

1. 添加观众拉流页面
在您的观众 Activity 中,创建
AtomicLiveView 实例,并将 viewType 指定为 AtomicLiveViewType.PLAY_VIEW(拉流视图)。import io.trtc.tuikit.atomicxcore.api.view.AtomicLiveViewimport io.trtc.tuikit.atomicxcore.api.view.AtomicLiveViewTypeimport android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport androidx.constraintlayout.widget.ConstraintLayout// YourAudienceActivity 代表您的观众观看Activityclass YourAudienceActivity : AppCompatActivity() {// 1. 初始化观众拉流页面private lateinit var liveView: AtomicLiveViewoverride fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)// 2. 初始化视图liveView = AtomicLiveView(this, viewType = AtomicLiveViewType.PLAY_VIEW)// UI 布局setupUI()}private fun setupUI() {setContentView(R.layout.activity_audience)// 3. 将观众拉流页面加载到您的视图上val container = findViewById<ConstraintLayout>(R.id.container)container.addView(liveView)// 设置布局参数val params = ConstraintLayout.LayoutParams(ConstraintLayout.LayoutParams.MATCH_PARENT,ConstraintLayout.LayoutParams.MATCH_PARENT)params.topMargin = 36params.bottomMargin = 96liveView.layoutParams = params}}
2. 进入直播间观看
通过调用 AtomicPlayer 的
setView 绑定渲染视图,再调用 joinChannel 接口加入直播,加入成功后调用 startPlay 播放当前房间的视频流,完整示例代码如下:import io.trtc.tuikit.atomicxcore.api.CompletionHandlerimport io.trtc.tuikit.atomicxcore.api.live.AtomicPlayerimport android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport android.util.Log// YourAudienceActivity 代表您的观众观看Activityclass YourAudienceActivity : AppCompatActivity() {// ... 其他代码 ...private val player = AtomicPlayer()override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setupUI()// 1. 将渲染视图绑定到 AtomicPlayerplayer.setView(liveView)// 2. 进入直播间joinLive()}private fun joinLive() {// 调用 joinChannel 进入直播间,成功后调用 startPlay 开始拉流// - liveID: 与主播开播同样的 liveIDval liveID = "test_live_001"player.joinChannel(liveID, object : CompletionHandler {override fun onSuccess() {// 拉流地址由 liveID 按 livekit://liveid=<liveID> 规则生成player.startPlay("livekit://liveid=$liveID")Log.d("Live", "joinChannel success")}override fun onFailure(code: Int, desc: String) {Log.e("Live", "joinChannel error: $desc")}})}}
3. 退出直播
观众退出直播间时,需要调用 AtomicPlayer 的
stopPlay 和 leaveChannel 接口退出直播。SDK 会自动停止拉流并退出房间。import androidx.appcompat.app.AppCompatActivityimport android.util.Log// YourAudienceActivity 代表您的观众观看Activityclass YourAudienceActivity : AppCompatActivity() {// ... 其他代码 ...// 退出直播private fun leaveLive() {player.stopPlay()player.leaveChannel()Log.d("Live", "leaveLive success")}// 确保在 Activity 销毁时也调用退出直播override fun onDestroy() {super.onDestroy()leaveLive()Log.d("Live", "YourAudienceActivity onDestroy")}}
步骤3:监听直播事件
在观众加入直播间后,您还需要处理一些房间内的“被动”事件。例如主播主动结束了直播,或者观众因为违规等原因被踢出房间。如果不监听这些事件,观众端 UI 可能会停留在黑屏页面,影响用户体验。
您可以通过实现
PlayerListener 监听器,并将其注册到 AtomicPlayer 来实现事件监听。import io.trtc.tuikit.atomicxcore.api.live.PlayerListenerimport android.os.Bundleimport androidx.appcompat.app.AppCompatActivityimport android.util.Log// YourAudienceActivity 代表您的观众观看Activityclass YourAudienceActivity : AppCompatActivity() {// ... (liveView, player, liveID, setupUI, joinLive, leaveLive 等代码) ...// 2. 定义一个 PlayerListener 实例private val playerListener = object : PlayerListener() {override fun liveEnded(reason: PlayerListener.EndedReason) {// 监听到直播结束Log.d("Live", "Live ended. reason: $reason")// 在此处处理退出直播间的逻辑,例如关闭当前 Activity// finish()}override fun kickedOut(reason: PlayerListener.KickedOutReason, message: String) {// 监听到被踢出直播Log.d("Live", "Kicked out of live. reason: $reason, message: $message")// 在此处处理退出直播间的逻辑// finish()}}override fun onCreate(savedInstanceState: Bundle?) {super.onCreate(savedInstanceState)setupUI()// 3. 注册监听器player.addListener(playerListener)// 4. 进入直播间joinLive()}// ... joinLive() 和 leaveLive() 方法 ...override fun onDestroy() {super.onDestroy()// 5. 确保在 Activity 销毁时移除监听器,防止内存泄漏player.removeListener(playerListener)leaveLive()Log.d("Live", "YourAudienceActivity onDestroy")}}
运行效果
集成 AtomicLiveView 后,您将得到一个纯净的视频渲染视图,主播端由 AtomicPusher 推流、观众端由 AtomicPlayer 拉流,画面都会渲染到该视图上,但它本身不包含任何交互 UI。您可以参考下一章节 丰富直播场景 来完善直播场景。
布局类型 | 动态宫格布局 | 浮动小窗布局 | 固定宫格布局 | 固定小窗布局 |
模板 ID | 600 | 601 | 800 | 801 |
描述 | 默认布局,可根据连麦人数动态调整宫格大小。 | 连麦嘉宾以浮动小窗形式显示。 | 连麦人数固定,每个嘉宾占据一个固定宫格。 | 连麦人数固定,嘉宾以固定小窗形式显示。 |
运行效果 | ![]() | ![]() | ![]() | ![]() |
丰富直播场景
当您完成了基础的直播功能后,您可以参考以下功能指南来为直播添加丰富的互动玩法。
直播功能 | 功能介绍 | 功能 Stores | 实现指南 |
实现观众音视频连线 | 观众申请上麦,与主播进行实时视频互动。 | ||
实现主播跨房连线 PK | 两个不同房间的主播进行连线,实现互动或 PK。 | ||
添加弹幕聊天功能 | 观众可以在直播间发送和接收实时文字消息。 | ||
构建礼物赠送系统 | 观众可以向主播赠送虚拟礼物,增加互动和趣味性。 |
API 文档
Store/Component | 功能描述 | API 文档 |
AtomicPusher | 主播推流:本地音视频采集与预览、开始 / 停止推流、直播间信息配置更新、推流状态与统计、事件回调。 | |
AtomicPlayer | 观众拉流:渲染视图绑定、加入 / 离开频道、开始 / 停止播放、播放状态与统计、事件回调。 | |
LiveListStore | 直播间全生命周期管理:创建 / 加入 / 离开 / 销毁房间,查询房间列表,修改直播信息(名称、公告等),监听直播状态(例如被踢出、结束)。 | |
DeviceStore | 音视频设备控制:麦克风(开关 / 音量)、摄像头(开关 / 切换 / 画质)、屏幕共享,设备状态实时监听。 | |
CoGuestStore | 观众连麦管理:连麦申请 / 邀请 / 同意 / 拒绝,连麦成员权限控制(麦克风 / 摄像头),状态同步。 | |
CoHostStore | 主播跨房连线:支持多布局模板(动态网格等),发起 / 接受 / 拒绝连线,连麦主播互动管理。 | |
BattleStore | 主播 PK 对战:发起 PK(配置时长 / 对手),管理 PK 状态(开始 / 结束),同步分数,监听对战结果。 | |
GiftStore | 礼物互动:获取礼物列表,发送 / 接收礼物,监听礼物事件(含发送者、礼物详情)。 | |
BarrageStore | 弹幕功能:发送文本 / 自定义弹幕,维护弹幕列表,实时监听弹幕状态。 | |
LikeStore | 点赞互动:发送点赞,监听点赞事件,同步总点赞数。 | |
LiveAudienceStore | 观众管理:获取实时观众列表(ID / 名称 / 头像),统计观众数量,监听观众进出事件。 | |
AudioEffectStore | 音频特效:变声(童声 / 男声)、混响(KTV 等)、耳返调节,实时切换特效。 | |
BaseBeautyStore | 基础美颜:调节磨皮 / 美白 / 红润(0-100 级),重置美颜状态,同步效果参数。 |
常见问题
主播调用 startPush 或 观众调用 joinChannel 后为什么画面是黑的,没有视频画面?
检查 setView:请确保在调用开播或观看接口前,已经调用 setView 将 AtomicLiveView 绑定到 AtomicPusher 或 AtomicPlayer。
检查设备权限:请确保 App 已获得摄像头和麦克风的系统使用权限。
检查主播端:主播端是否正常调用
DeviceStore.shared().openLocalCamera(true) 打开了摄像头。检查网络:请检查设备网络连接是否正常。
主播端打开摄像头后,开播后可以看到本地视频预览画面,开播前视频预览是黑屏?
检查主播端:请检查主播推流视图
AtomicLiveView 的 viewType 是否配置为 AtomicLiveViewType.PUSH_VIEW。检查观众端:请检查观众拉流视图
AtomicLiveView 的 viewType 是否配置为 AtomicLiveViewType.PLAY_VIEW。


