帮你快速理解、总结文档立即下载

开播与观看(Flutter)

最近更新时间:2026-11-09 19:22:21
本文档已由 AI 辅助审校
我的收藏
本文档将帮助您使用 AtomicXCore SDK 的核心组件 AtomicLiveWidget,配合 AtomicPusher(主播推流)和 AtomicPlayer(观众拉流),快速构建一个包含主播开播和观众观看功能的基础直播 App。

核心功能

AtomicLiveWidget 是一个专为直播场景设计的轻量级 Widget 组件,是您构建直播画面的"画布"。主播端通过 AtomicPusher 完成本地音视频采集与推流,观众端通过 AtomicPlayer 完成拉流播放,两端都通过 setView 将画面渲染到同一个 AtomicLiveWidget 上。您只需专注于上层 UI 与交互的开发。
通过下方的视图层级示意图,您可以直观了解 AtomicLiveWidget 在直播界面中的位置和作用:


准备工作

步骤1:开通服务

请参见 开通服务,获取体验版或付费版 SDK。

步骤2:在当前项目中导入 AtomicXCore

1. 安装组件:请在您的 pubspec.yaml 文件中添加 atomic_x_core 依赖,然后执行 flutter pub get。
dependencies:
atomic_x_core: ^4.0.1
2. 配置工程权限:Android 和 iOS 工程都需要配置权限。
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',
]
end
end
end
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, // 替换为您的 sdkAppID
userID: "test_001", // 替换为您的 userID
userSig: "xxxxxxxxxxx", // 替换为您的 userSig
);

if (result.isSuccess) {
debugPrint("login success");
} else {
debugPrint("login failed code: ${result.errorCode}, message: ${result.errorMessage}");
}

runApp(const MyApp());
}
登录接口参数说明:
参数
类型
说明
sdkAppID
int
从 控制台 获取,通常是以 140 或 160 开头的 10 位整数。
userID
String
当前用户的唯一 ID,仅包含英文字母、数字、连字符和下划线。为避免多端登录冲突,请勿使用1、123等简单 ID。
userSig
String
用于腾讯云鉴权的票据。请注意:
开发环境:您可以采用本地 GenerateTestUserSig.genTestSig 函数生成 userSig 或者通过 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;

@override
void 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 组合主视图
@override
Widget build(BuildContext context) {
return Scaffold(
body: Stack(
children: [
// 视图层:预览与直播共用同一个 AtomicLiveWidget
Positioned.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});

@override
State<YourAnchorPage> createState() => _YourAnchorPageState();
}

class _YourAnchorPageState extends State<YourAnchorPage> {
late final AtomicLiveController _controller;
late final AtomicLiveWidget _videoView;
final AtomicPusher _pusher = AtomicPusher.shared;
bool _isLiveStarted = false; // 直播状态标记

@override
void 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();
}

@override
Widget build(BuildContext context) {
return Scaffold(
body: Stack(
children: [
// 视图层:预览与直播共用同一个 AtomicLiveWidget
Positioned.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:实现观众进房观看

观众观看流程如下,通过简单几步操作,即可实现观众观看直播。

提示:
观众进房拉流的业务代码,您也可以参考 TUILiveKit 开源项目中的 audience_widget.dart 文件来了解完整的实现逻辑。
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;

@override
void 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}");
}
}

@override
Widget 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});

@override
State<YourAudiencePage> createState() => _YourAudiencePageState();
}

class _YourAudiencePageState extends State<YourAudiencePage> {
late final AtomicLiveController _controller;
late final AtomicLiveWidget _videoView;
final AtomicPlayer _player = AtomicPlayer();

@override
void 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: 与主播开播同样的 liveId
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}");
// 进房失败,也需要退出页面
// if (mounted) Navigator.of(context).pop();
}
}

@override
Widget 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});

@override
State<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});

@override
State<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;

@override
void 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");
}

@override
void dispose() {
// 5. 移除事件监听
_player.removeListener(_playerListener);
super.dispose();
}

@override
Widget build(BuildContext context) {
return Scaffold(
body: Stack(
children: [
_videoView,
],
),
);
}
}

运行效果

集成 AtomicLiveWidget 后,您将得到一个纯净的视频渲染视图,主播端由 AtomicPusher 推流、观众端由 AtomicPlayer 拉流,画面都会渲染到该视图上,但它本身不包含任何交互 UI。您可以参考下一章节 丰富直播场景 来完善直播场景。
布局类型
动态宫格布局
浮动小窗布局
固定宫格布局
固定小窗布局
模板 ID
600
601
800
801
描述
默认布局,可根据连麦人数动态调整宫格大小。
连麦嘉宾以浮动小窗形式显示。
连麦人数固定,每个嘉宾占据一个固定宫格。
连麦人数固定,嘉宾以固定小窗形式显示。
运行效果













丰富直播场景

当您完成了基础的直播功能后,您可以参考以下功能指南来为直播添加丰富的互动玩法。
直播功能
功能介绍
功能 Stores
实现指南
实现观众音视频连线
观众申请上麦,与主播进行实时视频互动。
实现主播跨房连线 PK
两个不同房间的主播进行连线,实现互动或 PK。
添加弹幕聊天功能
观众可以在直播间发送和接收实时文字消息。
构建礼物赠送系统
观众可以向主播赠送虚拟礼物,增加互动和趣味性。
GiftStore

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 方法中清理资源,例如移除事件监听器:
@override
void dispose() {
_player.removeListener(_playerListener);
super.dispose();
}