Feedback

观众观看

TUILiveKit 的观众观看页为用户提供了丰富且便捷的直播观看与互动功能,能快速集成到您的应用中,满足观众多样化的需求。

功能概览

直播预览:未进房前即可先预览主播实时画面,点击进入直播间后再参与互动。
直播观看:清晰、流畅观看主播实时直播画面,可查看直播间标题、主播信息及在线观众。
直播互动:送礼物(有动画特效,主播接收提示)、点赞(有动画及实时统计)、发弹幕互动,并可申请与主播音视频连麦互动。
直播预览
直播观看
直播互动






组件说明

PlayerView 是一个 StatefulWidget,用于观看单个直播间,统一从 package:tencent_live_uikit/tencent_live_uikit.dart 导入;它通过 PlayerViewController 暴露播放控制,若不传入 controller,组件会自行创建并销毁一个控制器。组件内已包含拉流、进房、连麦、弹幕、礼物、点赞等完整交互 UI。

快速接入

步骤 1:开通服务

参考 开通服务 文档领取 TUILiveKit 体验版或开通专业版套餐。

步骤 2:代码集成

参考 准备工作 接入 TUILiveKit。

步骤 3:使用 PlayerView 观看单个直播间

在您的观众观看页中创建 PlayerView 并持有 PlayerViewController。

import 'dart:async';

import 'package:atomic_x_core/atomicxcore.dart';
import 'package:flutter/material.dart';
import 'package:tencent_live_uikit/tencent_live_uikit.dart';

class AudiencePlayerPage extends StatefulWidget {
const AudiencePlayerPage({super.key, required this.liveID});

final String liveID;

@override
State<AudiencePlayerPage> createState() => _AudiencePlayerPageState();
}

class _AudiencePlayerPageState extends State<AudiencePlayerPage> {
final PlayerViewController controller = PlayerViewController();

@override
void initState() {
super.initState();
// 1. (可选) 监听播放状态变化
controller.status.addListener(onStatusChanged);

// 2. PlayerView 在挂载时会调用 controller.setLiveInfo,
// 因此 startPlay / joinChannel 需等首帧之后再调用
WidgetsBinding.instance.addPostFrameCallback((_) {
// 3. 开始拉流播放
controller.startPlay();

// 4. 加入直播间,进房成功后观众才能发弹幕、点赞、送礼、连麦
controller.joinChannel(completion: (LiveInfo? liveInfo, Object? error) {
if (error != null) {
debugPrint('joinChannel failed: $error');
return;
}
debugPrint('joinChannel success: ${liveInfo?.liveID}');
});
});
}

void onStatusChanged() {
debugPrint('player status: ${controller.status.value}');
}

@override
void dispose() {
// 5. 页面销毁时停止播放、退出直播间并释放控制器
controller.status.removeListener(onStatusChanged);
controller.stopPlay();
unawaited(controller.leaveChannel());
controller.dispose();
super.dispose();
}

@override
Widget build(BuildContext context) {
return Scaffold(
backgroundColor: Colors.black,
body: PlayerView(
// 6. 传入直播间信息,组件内部会自动调用 setLiveInfo
liveInfo: LiveInfo(liveID: widget.liveID),
controller: controller,
onCloseClicked: () => Navigator.of(context).maybePop(),
onJoinLiveClicked: () => debugPrint('join live: ${widget.liveID}'),
),
);
}
}

步骤 4:跳转到观众观看页面

在您需要跳转到观众观看页时,可参考如下代码示例:
import 'package:flutter/material.dart';

import 'audience_player_page.dart';

void enterPlayerPage(BuildContext context, String liveID) {
Navigator.of(context).push(
MaterialPageRoute<void>(
builder: (_) => AudiencePlayerPage(liveID: liveID),
fullscreenDialog: true,
),
);
}

组件 API 说明

PlayerView

PlayerView 是一个 StatefulWidget,用于观看单个直播间。
属性
说明
liveInfo(必填)
要观看的直播间信息 LiveInfo。组件挂载时自动调用 controller.setLiveInfo。
controller
PlayerViewController,播放控制入口。不传时组件自行创建并在销毁时释放。
onCloseClicked
观众点击关闭按钮时回调(组件会先退出直播间再回调)。
onJoinLiveClicked
观众通过进入直播间入口进房成功时回调。

PlayerViewController

方法 / 属性
说明
PlayerViewController()
工厂构造,创建播放控制器。
setLiveInfo(LiveInfo liveInfo)
设置直播间信息。必须在 startPlay、joinChannel 之前调用;切换直播间时组件会先停止播放并退出原直播间。
startPlay()
开始拉流播放(仅播放画面,尚未进房)。liveID 为空时直接返回。
stopPlay()
停止拉流播放。
joinChannel({PlayerJoinCompletion? completion})
加入直播间,返回 Future<bool>;completion 回调参数为 (LiveInfo? liveInfo, Object? error)。进房成功后观众才能发弹幕、点赞、送礼、申请连麦。
leaveChannel({PlayerLeaveCompletion? completion})
退出直播间,返回 Future<bool>。
setVolume(int volume)
设置播放音量,取值范围 0 ~ 100;常量 previewVolume = 0、roomVolume = 100。
setJoinLiveEntranceEnabled(bool enabled)
是否展示进入直播间入口。
setContentSafeAreaInsets(EdgeInsets insets)
组件内容区的安全边距,用于适配刘海屏与自定义容器。
status
ValueListenable<PlayerStatus>,用于观察当前播放状态。
joinInProgress
ValueListenable<bool>,是否正在进房。
liveID
当前观看的直播间 ID。
dispose()
释放控制器资源,页面销毁时需调用。

PlayerStatus

PlayerViewController.status 的播放状态,取值如下:
状态
说明
idle
空闲,未播放也未进房。
playing
正在拉流播放,观众尚未进房(展示进入直播间入口)。
inRoom
已进房,观众可参与弹幕、点赞、送礼、连麦等互动。
coGuest
连麦中(申请中或已上麦)。
end
直播已结束或被踢出,组件展示直播结束页。

下一步

恭喜您,现在您已经成功集成了观众观看。接下来,您可以实现主播开播、直播列表等功能,可参考下表:
功能
描述
集成指引
主播开播
主播开播全流程功能,包括开播前的准备和开播后的各种互动。
直播列表
展示直播列表界面和功能,包含直播列表、房间信息展示功能。

常见问题

观众选择视频连麦后,视频画面显示黑屏?

请前往手机设置 > App > 相机,检查摄像头权限是否开启,可参考下图:
iOS
Android






观众发送弹幕时,直播间内其他观众看不到弹幕内容?

原因 1: 先检查网络连接,确保观众设备网络正常。
原因 2: 该观众被主播禁言,无法发送弹幕。
原因 3:观众的弹幕内容涉及了关键词屏蔽,请确认观众发送的弹幕内容是否符合直播间规则。

App 退到后台无法进入应用外浮窗(画中画)模式?

参考 进入应用外浮窗模式,进入直播间后,已开启了画中画开关。
如果是 Android 平台,在您打开画中画开关后,还会自动检测 App 系统画中画模式开关状态,如果没有打开,App 会自动跳转到设置页面,请您允许进入画中画模式: