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

准备工作
步骤1:开通服务
步骤2:在当前项目中导入 AtomicXCore
1. 安装组件:请在您的
pubspec.yaml 文件中添加 atomic_x_core 依赖,然后执行 flutter pub get。dependencies:atomic_x_core: ^4.0.1
2. 配置工程权限:Android 和 iOS 工程都需要配置权限。
请在
android/app/src/main/AndroidManifest.xml 文件中添加相机和麦克风的使用权限说明。<uses-permission android:name="android.permission.CAMERA" /><uses-permission android:name="android.permission.RECORD_AUDIO" />
请在应用
iOS 目录的 Podfile 和 ios/Runner 目录的 Info.plist 文件中添加相机和麦克风的使用权限说明。Podfile
post_install do |installer|installer.pods_project.targets.each do |target|flutter_additional_ios_build_settings(target)target.build_configurations.each do |config|config.build_settings['GCC_PREPROCESSOR_DEFINITIONS'] ||= ['$(inherited)','PERMISSION_MICROPHONE=1','PERMISSION_CAMERA=1',]endendend
Info.plist
<key>NSCameraUsageDescription</key><string>TUILiveKit需要访问您的相机权限,开启后录制的视频才会有画面</string><key>NSMicrophoneUsageDescription</key><string>TUILiveKit需要访问您的麦克风权限,开启后录制的视频才会有声音</string>

步骤3:实现登录逻辑
在您的项目中调用
LoginStore.shared.login 完成登录,这是使用 AtomicXCore 所有功能的关键前提。重要:
推荐在您 App 自身的用户账户登录成功后,再调用 LoginStore.shared.login,以确保登录业务逻辑的清晰和一致。
import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';void main() async {WidgetsFlutterBinding.ensureInitialized();final result = await LoginStore.shared.login(sdkAppID: 1400000001, // 替换为您的 sdkAppIDuserID: "test_001", // 替换为您的 userIDuserSig: "xxxxxxxxxxx", // 替换为您的 userSig);if (result.isSuccess) {debugPrint("login success");} else {debugPrint("login failed code: ${result.errorCode}, message: ${result.errorMessage}");}runApp(const MyApp());}
登录接口参数说明:
参数 | 类型 | 说明 |
sdkAppID | int | |
userID | String | 当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用 1、123等简单 ID。 |
userSig | String | 用于腾讯云鉴权的票据。请注意: 开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 UserSig 辅助工具 生成临时的 UserSig。生产环境:为了防止密钥泄露,请务必采用服务端生成 UserSig 的方式。详细信息请参考 服务端生成 UserSig。 |
搭建基础直播间
步骤1:实现主播开播
主播开播只需三步:创建推流视图、打开摄像头和麦克风、调用 startPush 开播。AtomicLiveWidget 会持续渲染本地预览与推流画面,您无需在“预览”和“直播”之间切换视图。

1. 核心逻辑与状态定义。
首先,在您的 State 类中定义渲染视图、控制器与 AtomicPusher,并增加一个 _isLiveStarted 标记,用于控制开播按钮的显示。
class _YourAnchorPageState extends State<YourAnchorPage> {// 核心组件late final AtomicLiveController _controller;late final AtomicLiveWidget _videoView;final AtomicPusher _pusher = AtomicPusher.shared;// 状态标记:false = 预览中; true = 直播中bool _isLiveStarted = false;@overridevoid initState() {super.initState();_controller = AtomicLiveController.create(AtomicLiveViewType.pushView);_videoView = AtomicLiveWidget(controller: _controller);_controller.setLiveID(widget.liveId);// 绑定渲染视图,绑定后即可看到本地预览画面_pusher.setView(_videoView);// 初始化时直接打开设备(详见下一步)_openDevices();}}
2. 打开摄像头和麦克风。
通过调用 DeviceStore 的
openLocalCamera、openLocalMicrophone 接口打开摄像头和麦克风,您无需做额外操作,AtomicLiveWidget 会自动预览当前摄像头的视频流,示例代码如下:注意:
此步骤对于预览至关重要。只有打开设备,AtomicLiveWidget 才有画面可渲染。
void _openDevices() {// 1. 打开前置摄像头 (true 表示前置)DeviceStore.shared.openLocalCamera(true);// 2. 打开麦克风DeviceStore.shared.openLocalMicrophone();}
3. 构建预览视图。
将
AtomicLiveWidget 放入页面即可,预览与直播共用同一个视图,无需切换组件:渲染视图:使用
AtomicLiveWidget(预览与直播共用,绑定后自动渲染画面)。// 3.1 封装渲染视图组件Widget _buildVideoView() {return Container(color: Colors.black,child: _videoView,);}// 3.2 组合主视图@overrideWidget build(BuildContext context) {return Scaffold(body: Stack(children: [// 视图层:预览与直播共用同一个 AtomicLiveWidgetPositioned.fill(child: _buildVideoView(),),// UI 层:开播按钮(仅在预览时显示)if (!_isLiveStarted)Positioned(bottom: 50, left: 0, right: 0,child: Center(child: ElevatedButton(onPressed: _startLive, // 下一步实现此方法child: const Text('开始直播'),),),),],),);}
4. 实现开播与关播逻辑。
通过调用 AtomicPusher 的
startPush 接口开始视频直播,示例代码如下:Future<void> _startLive() async {// 1. 配置直播间参数final config = PusherInfo(liveID: widget.liveId, // 房间唯一标识liveName: "Atomic Live Demo", // 房间标题);// 2. 发起开播请求_pusher.startPush(config);debugPrint("开播成功");// 3. 关键步骤:更新状态// 将 _isLiveStarted 置为 true,触发 build 方法重新构建,// 从而隐藏开播按钮。setState(() {_isLiveStarted = true;});}
PusherInfo 参数说明:
参数名 | 类型 | 属性 | 描述 |
liveID | String | 必填 | 直播间的唯一标识符。 |
liveName | String | 选填 | 直播间的标题。 |
notice | String | 选填 | 直播间的公告信息。 |
metaData | Map<String, String> | 选填 | 直播间的自定义元数据。 |
isPublicVisible | Boolean | 选填 | 是否公开可见( true:是,false:否)。 |
coverURL | String | 选填 | 直播间的封面图片地址。 |
backgroundURL | String | 选填 | 直播间的背景图片地址。 |
categoryList | List<Int> | 选填 | 直播间的分类标签列表。 |
5. 结束直播。
直播结束后,主播可以调用 AtomicPusher 的
stopPush 接口结束直播。SDK 会处理停止推流和销毁房间的逻辑。Future<void> _stopLive() async {// 1. 调用接口结束直播// SDK 内部会自动停止推流、销毁房间并清理媒体资源_pusher.stopPush();debugPrint("关播成功");// 2. 退出当前页面if (mounted) {Navigator.of(context).pop();}}
6. 完整代码参考。
为了方便您快速集成,我们将上述步骤整合为完整的
YourAnchorPage 文件。您可以直接复制以下代码:import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';class YourAnchorPage extends StatefulWidget {final String liveId;const YourAnchorPage({super.key, required this.liveId});@overrideState<YourAnchorPage> createState() => _YourAnchorPageState();}class _YourAnchorPageState extends State<YourAnchorPage> {late final AtomicLiveController _controller;late final AtomicLiveWidget _videoView;final AtomicPusher _pusher = AtomicPusher.shared;bool _isLiveStarted = false; // 直播状态标记@overridevoid initState() {super.initState();_controller = AtomicLiveController.create(AtomicLiveViewType.pushView);_videoView = AtomicLiveWidget(controller: _controller);_controller.setLiveID(widget.liveId);_pusher.setView(_videoView); // 步骤1:绑定渲染视图_openDevices(); // 步骤2:打开设备}void _openDevices() {DeviceStore.shared.openLocalCamera(true);DeviceStore.shared.openLocalMicrophone();}@overrideWidget build(BuildContext context) {return Scaffold(body: Stack(children: [// 视图层:预览与直播共用同一个 AtomicLiveWidgetPositioned.fill(child: Container(color: Colors.black,child: _videoView,),),// 开播按钮if (!_isLiveStarted)Positioned(bottom: 50, left: 0, right: 0,child: Center(child: ElevatedButton(onPressed: _startLive, child: const Text('开始直播')),),),],),);}// 步骤3:开播逻辑void _startLive() {final config = PusherInfo(liveID: widget.liveId,liveName: "Test Live",);_pusher.startPush(config);setState(() {_isLiveStarted = true; // 切换 UI 状态});}}
步骤2:实现观众进房观看
观众观看流程如下,通过简单几步操作,即可实现观众观看直播。

提示:
1. 实现观众拉流页面。
在您的观众页面中,创建
AtomicLiveWidget 实例,并通过 AtomicLiveController 与 AtomicPlayer 控制直播行为。注意:
必须确保在调用 joinChannel() 之前已经调用 setView 将 AtomicLiveWidget 绑定到 AtomicPlayer。
原理分析:
AtomicPlayer 通过 setView 与渲染视图建立绑定,该绑定与视图挂载时序解耦:即使在 Widget 尚未挂载时调用 setView 也是安全的,绑定会在视图就绪后自动完成。另外,joinChannel 成功后还需要调用 startPlay 才会开始拉流,否则画面黑屏。import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';/// YourAudiencePage 代表您的观众观看页面class _YourAudiencePageState extends State<YourAudiencePage> {late final AtomicLiveController _controller;late final AtomicLiveWidget _videoView;final AtomicPlayer _player = AtomicPlayer();bool _isJoining = true;@overridevoid initState() {super.initState();_controller = AtomicLiveController.create(AtomicLiveViewType.playView);_videoView = AtomicLiveWidget(controller: _controller);_controller.setLiveID(widget.liveId);// 1. 绑定渲染视图_player.setView(_videoView);// 修正:在第一帧渲染完成后再进房,确保 AtomicLiveWidget 已完成初始化WidgetsBinding.instance.addPostFrameCallback((_) {_joinLive();});}Future<void> _joinLive() async {final result = await _player.joinChannel(widget.liveId);if (result.isSuccess) {debugPrint("joinChannel success");// 拉流地址由 liveId 按 livekit://liveid=<liveId> 规则生成_player.startPlay("livekit://liveid=${widget.liveId}");if (mounted) setState(() => _isJoining = false);} else {debugPrint("joinChannel error: ${result.errorMessage}");}}@overrideWidget build(BuildContext context) {return Scaffold(body: Stack(children: [// 必须始终渲染,不可根据 _isJoining 状态移除,否则会导致画面中断_videoView,if (_isJoining)const Center(child: CircularProgressIndicator(color: Colors.white)),],),);}}
2. 进入直播间观看。
通过调用 AtomicPlayer 的
setView 绑定渲染视图,再调用 joinChannel 接口加入直播,加入成功后调用 startPlay 播放当前房间的视频流,完整示例代码如下:import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';/// YourAudiencePage 代表您的观众观看页面class YourAudiencePage extends StatefulWidget {final String liveId;const YourAudiencePage({super.key, required this.liveId});@overrideState<YourAudiencePage> createState() => _YourAudiencePageState();}class _YourAudiencePageState extends State<YourAudiencePage> {late final AtomicLiveController _controller;late final AtomicLiveWidget _videoView;final AtomicPlayer _player = AtomicPlayer();@overridevoid initState() {super.initState();_controller = AtomicLiveController.create(AtomicLiveViewType.playView);_videoView = AtomicLiveWidget(controller: _controller);_controller.setLiveID(widget.liveId);// 1. 绑定渲染视图_player.setView(_videoView);// 2. 进入直播间_joinLive();}Future<void> _joinLive() async {// 调用 joinChannel 进入直播间,成功后调用 startPlay 开始拉流// - liveId: 与主播开播同样的 liveIdfinal result = await _player.joinChannel(widget.liveId);if (result.isSuccess) {debugPrint("joinChannel success");_player.startPlay("livekit://liveid=${widget.liveId}");} else {debugPrint("joinChannel error: ${result.errorMessage}");// 进房失败,也需要退出页面// if (mounted) Navigator.of(context).pop();}}@overrideWidget build(BuildContext context) {return Scaffold(body: Stack(children: [_videoView,],),);}}
3. 退出直播。
观众退出直播间时,需要调用 AtomicPlayer 的
stopPlay 和 leaveChannel 接口退出直播。SDK 会自动停止拉流并退出房间。import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';/// YourAudiencePage 代表您的观众观看页面class YourAudiencePage extends StatefulWidget {final String liveId;const YourAudiencePage({super.key, required this.liveId});@overrideState<YourAudiencePage> createState() => _YourAudiencePageState();}class _YourAudiencePageState extends State<YourAudiencePage> {// ... 其他代码 ...// 退出直播Future<void> _leaveLive() async {_player.stopPlay();_player.leaveChannel();debugPrint("leaveLive success");}// ... 其他代码 ...}
步骤3:监听直播事件
在观众加入直播间后,您还需要处理一些房间内的"被动"事件。例如,主播主动结束了直播,或者观众因为违规等原因被踢出房间。如果不监听这些事件,观众端 UI 可能会停留在黑屏页面,影响用户体验。
您可以通过
PlayerListener 来实现事件监听。import 'package:flutter/material.dart';import 'package:atomic_x_core/atomicxcore.dart';/// YourAudiencePage 代表您的观众观看页面class YourAudiencePage extends StatefulWidget {final String liveId;const YourAudiencePage({super.key, required this.liveId});@overrideState<YourAudiencePage> createState() => _YourAudiencePageState();}class _YourAudiencePageState extends State<YourAudiencePage> {late final AtomicLiveController _controller;late final AtomicLiveWidget _videoView;final AtomicPlayer _player = AtomicPlayer();// 1. 定义 PlayerListener 来管理事件监听late final PlayerListener _playerListener;@overridevoid initState() {super.initState();_controller = AtomicLiveController.create(AtomicLiveViewType.playView);_videoView = AtomicLiveWidget(controller: _controller);_controller.setLiveID(widget.liveId);_player.setView(_videoView);// 2. 监听直播事件_setupLiveEventListener();// 3. 进入直播间_joinLive();}// 4. 新增一个方法来设置事件监听void _setupLiveEventListener() {_playerListener = PlayerListener(liveEnded: (reason) {// 监听到直播结束debugPrint("Live ended. reason: ${reason.name}");// 在此处处理退出直播间的逻辑,例如关闭当前页面// if (mounted) Navigator.of(context).pop();},kickedOut: (reason, message) {// 监听到被踢出直播debugPrint("Kicked out of live. reason: ${reason.name}, message: $message");// 在此处处理退出直播间的逻辑// if (mounted) Navigator.of(context).pop();},);_player.addListener(_playerListener);}Future<void> _joinLive() async {final result = await _player.joinChannel(widget.liveId);if (result.isSuccess) {debugPrint("joinChannel success");_player.startPlay("livekit://liveid=${widget.liveId}");} else {debugPrint("joinChannel error: ${result.errorMessage}");}}Future<void> _leaveLive() async {_player.stopPlay();_player.leaveChannel();debugPrint("leaveLive success");}@overridevoid dispose() {// 5. 移除事件监听_player.removeListener(_playerListener);super.dispose();}@overrideWidget build(BuildContext context) {return Scaffold(body: Stack(children: [_videoView,],),);}}
运行效果
集成 AtomicLiveWidget 后,您将得到一个纯净的视频渲染视图,主播端由 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 将 AtomicLiveWidget 绑定到 AtomicPusher 或 AtomicPlayer。
检查设备权限:请确保 App 已获得摄像头和麦克风的系统使用权限。
检查主播端:主播端是否正常调用
DeviceStore.shared.openLocalCamera(true) 打开了摄像头。检查网络:请检查设备网络连接是否正常。
观众端调用了 joinChannel 且返回 Success,但依然没有视频画面?
拉流时机:是否在
joinChannel 成功后调用了 startPlay?请参考上文在进房成功后调用 startPlay 开始拉流。Controller 类型:创建时是否正确传入了
AtomicLiveViewType.playView?Widget 持久性:在进房过程中,
AtomicLiveWidget 是否因为 setState 被意外销毁或重新创建?请确保其在 Widget 树中的稳定性。Flutter 项目如何请求权限?
您可以使用
permission_handler 插件来请求摄像头和麦克风权限:import 'package:permission_handler/permission_handler.dart';Future<void> requestPermissions() async {await [Permission.camera,Permission.microphone,].request();}
如何在 Flutter 中处理页面生命周期?
建议在
dispose 方法中清理资源,例如移除事件监听器:@overridevoid dispose() {_player.removeListener(_playerListener);super.dispose();}



