tencent cloud

实时音视频

动态与公告
产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
产品简介
产品概述
基本概念
产品功能
产品优势
应用场景
性能数据
购买指南
计费概述
免费时长说明
月订阅
现收现付
TRTC 逾期与暂停政策
常见问题解答
退款说明
新手指引
Demo 体验
视频通话 SDK
组件介绍
开通服务
跑通 Demo
快速接入
离线唤醒
会话聊天
云端录制
AI 降噪
界面定制
Chat 集成通话能力
更多特性
无 UI 集成
服务端 API
客户端 API
解决方案
错误码表
发布日志
常见问题
视频会议 SDK
组件介绍(TUIRoomKit)
开通服务(TUIRoomKit)
跑通 Demo(TUIRoomKit)
快速接入(TUIRoomKit)
屏幕共享(TUIRoomKit)
预定会议(TUIRoomKit)
会中呼叫(TUIRoomKit)
界面定制(TUIRoomKit)
虚拟背景(TUIRoomKit)
会议控制(TUIRoomKit)
云端录制(TUIRoomKit)
AI 降噪(TUIRoomKit)
会中聊天(TUIRoomKit)
机器人推流(TUIRoomKit)
更多特性(TUIRoomKit)
客户端 API(TUIRoomKit)
服务端 API(TUIRoomKit)
常见问题(TUIRoomKit)
错误码 (TUIRoomKit)
SDK更新日志(TUIRoomKit)
直播与语聊 SDK
Live 视频直播计费说明
组件介绍
开通服务(TUILiveKit)
跑通 Demo
无 UI 集成
UI 自定义
直播监播
视频直播
语聊房
高级功能
客户端 API
服务端 API
错误码
发布日志
常见问题
RTC Engine
开通服务
SDK 下载
API-Example
接入指引
API-参考手册
高级功能
AI 集成
概述
MCP 配置
Skills 配置
集成指南
常见问题
RTC RESTFUL API
History
Introduction
API Category
Room Management APIs
Stream mixing and relay APIs
On-cloud recording APIs
Data Monitoring APIs
Pull stream Relay Related interface
Web Record APIs
AI Service APIs
Cloud Slicing APIs
Cloud Moderation APIs
Making API Requests
Call Quality Monitoring APIs
Usage Statistics APIs
Data Types
Appendix
Error Codes
控制台指南
应用管理
套餐包管理
用量统计
监控仪表盘
开发辅助
解决方案
实时合唱
常见问题
迁移指南
计费相关
功能相关
UserSig 相关
应对防火墙限制相关
缩减安装包体积相关
Andriod 与 iOS 相关
Web 端相关
Flutter 相关
Electron 相关
TRTCCalling Web 相关
音视频质量相关
其他问题
旧版文档
RTC RoomEngine SDK(旧)
集成 TUIRoom (Web)
集成 TUIRoom (Android)
集成 TUIRoom (iOS)
集成 TUIRoom (Flutter)
集成 TUIRoom (Electron)
TUIRoom API 查询
实现云端录制与回放(旧)
监控仪表盘计费(旧)
协议与策略
安全合规认证
安全白皮书
信息安全说明
服务等级协议
苹果隐私策略:PrivacyInfo.xcprivacy
TRTC 政策
隐私协议
数据处理和安全协议
词汇表

观众列表(iOS)

PDF
聚焦模式
字号
最后更新时间: 2025-12-04 15:02:47
LiveAudienceStoreAtomicXCore 中专门负责管理直播间观众信息的模块。通过 LiveAudienceStore,可以在直播应用快速构建一套完整的观众列表及管理系统。


核心功能

实时观众列表:获取并展示当前在直播间内的所有观众信息。
观众人数统计:实时获取当前直播间的准确观众总数。
观众动态监听:通过事件订阅,实时感知观众的加入和离开。
管理员权限:主播可以将普通观众设为管理员,或撤销其管理员身份。
房间管理:主播或管理员可以将任意普通观众请出(踢出)直播间。

核心概念

核心概念
类型
核心职责与描述
LiveUserInfo
struct
代表一个观众(用户)的基础信息模型。它包含了用户的唯一标识 (userID)、昵称 (userName) 和头像地址 (avatarURL)。
LiveAudienceState
struct
代表观众模块的当前状态。其核心属性 audienceList 是一个 [LiveUserInfo] 数组,存储了观众列表的快照;audienceCount 则代表当前观众总数。
LiveAudienceEvent
enum
代表观众动态的实时事件。分为 .onAudienceJoined(观众加入) 和 .onAudienceLeft(观众离开)两种,用于实现对观众列表的增量更新。
LiveAudienceStore
class
这是与观众列表功能交互的核心管理类。通过它,您可以获取观众列表快照、执行管理操作,并通过订阅其 liveAudienceEventPublisher 来接收实时动态。

实现步骤

步骤1:组件集成

视频直播:请参考 快速接入 集成 AtomicXCore,完成接入。
语聊房:请参考 快速接入 集成 AtomicXCore,完成接入。

步骤2:初始化并获取观众列表

获取一个与当前直播间 liveId 绑定的 LiveAudienceStore 实例,并主动拉取一次当前的观众列表,用于首次展示。
import Foundation
import AtomicXCore
import Combine

class AudienceManager {
private let liveId: String
private let audienceStore: LiveAudienceStore
private var cancellables = Set<AnyCancellable>()
// 对外暴露【全量】观众列表的发布者,方便UI层订阅
let audienceListPublisher = CurrentValueSubject<[LiveUserInfo], Never>([])
// 对外暴露观众总数的发布者
let audienceCountPublisher = PassthroughSubject<UInt, Never>()

init(liveId: String) {
self.liveId = liveId
// 1. 通过 liveId 获取 LiveAudienceStore 的实例
self.audienceStore = LiveAudienceStore.create(liveID: liveId)
// 2. 订阅状态和事件
subscribeToAudienceState()
subscribeToAudienceEvents()
// 3. 主动拉取首屏数据
fetchInitialAudienceList()
}

/// 主动获取一次观众列表快照
func fetchInitialAudienceList() {
audienceStore.fetchAudienceList { [weak self] result in
switch result {
case .success:
print("首次拉取观众列表成功")
// 成功后,数据会通过下面的 state 订阅通道自动更新
case .failure(let error):
print("首次拉取观众列表失败: \\(error.localizedDescription)")
}
}
}
// ... 后续代码
}

步骤3:监听观众列表状态与实时动态

订阅 audienceStorestateevent,以接收全量列表快照和实时的观众进出事件,从而驱动 UI 更新。
extension AudienceManager {
/// 订阅 state,用于获取观众总数和列表快照
private func subscribeToAudienceState() {
audienceStore.state
.subscribe()
.receive(on: DispatchQueue.main)
.sink { [weak self] state in
// state.audienceList 是一个全量快照
self?.audienceListPublisher.send(state.audienceList)
// state.audienceCount 是实时总数
self?.audienceCountPublisher.send(state.audienceCount)
}
.store(in: &cancellables)
}

/// 订阅 event,用于处理观众的实时进出
private func subscribeToAudienceEvents() {
audienceStore.liveAudienceEventPublisher
.receive(on: DispatchQueue.main)
.sink { [weak self] event in
guard let self = self else { return }
var currentList = self.audienceListPublisher.value
switch event {
case .onAudienceJoined(let newAudience):
print("观众 \\(newAudience.userName) 加入了直播间")
// 增量更新:在当前列表末尾添加新观众
if !currentList.contains(where: { $0.userID == newAudience.userID }) {
currentList.append(newAudience)
self.audienceListPublisher.send(currentList)
}
case .onAudienceLeft(let departedAudience):
print("观众 \\(departedAudience.userName) 离开了直播间")
// 增量更新:从当前列表中移除离开的观众
currentList.removeAll { $0.userID == departedAudience.userID }
self.audienceListPublisher.send(currentList)
}
}
.store(in: &cancellables)
}
}

步骤4:管理观众(踢人与设置管理员)

作为主播或管理员,对直播间内的观众进行管理操作。

4.1 将观众踢出直播间

调用 kickUserOutOfRoom 接口可以将指定用户请出直播间。
extension AudienceManager {
func kick(userId: String) {
audienceStore.kickUserOutOfRoom(userID: userId) { result in
switch result {
case .success:
print("成功将用户 \\(userId) 踢出房间")
// 踢出成功后,您会收到 onAudienceLeft 事件
case .failure(let error):
print("踢出用户 \\(userId) 失败: \\(error.localizedDescription)")
}
}
}
}

4.2 设置/撤销管理员

通过 setAdministratorrevokeAdministrator 接口可以管理用户的管理员身份。
extension AudienceManager {
/// 将用户设为管理员
func promoteToAdmin(userId: String) {
audienceStore.setAdministrator(userID: userId) { result in
if case .success = result {
print("成功将用户 \\(userId) 设为管理员")
}
}
}

/// 撤销用户的管理员身份
func revokeAdmin(userId: String) {
audienceStore.revokeAdministrator(userID: userId) { result in
if case .success = result {
print("成功撤销用户 \\(userId) 的管理员身份")
}
}
}
}

功能进阶

在弹幕区展示观众入场欢迎语

当有新观众进入直播间时,弹幕/聊天区域会在本地自动显示一条欢迎消息,例如:“欢迎 [用户昵称] 进入直播间”。

实现方式

我们通过订阅 LiveAudienceStore 的观众加入事件(LiveAudienceEvent.onAudienceJoined)来获取新观众加入的实时通知。一旦事件触发,我们便提取出新观众的昵称信息,然后立即调用 BarrageStore 的本地插入接口 appendLocalTip
import Foundation
import AtomicXCore
import Combine

class LiveRoomManager {
private let liveId: String
private let audienceManager: AudienceManager
private let barrageManager: BarrageManager // 假设您已实现了弹幕文档中的BarrageManager
private var cancellables = Set<AnyCancellable>()

init(liveId: String) {
self.liveId = liveId
// 初始化两个核心管理器
self.audienceManager = AudienceManager(liveId: liveId)
self.barrageManager = BarrageManager(liveId: liveId)

// 设置联动
setupWelcomeMessageFlow()
}

private func setupWelcomeMessageFlow() {
// 1. 获取 LiveAudienceStore 的实例
let audienceStore = LiveAudienceStore.create(liveID: self.liveId)

// 2. 获取 BarrageStore 的实例 (得益于内部机制,这会是同一个实例)
let barrageStore = BarrageStore.create(liveID: self.liveId)

// 3. 订阅观众事件
audienceStore.liveAudienceEventPublisher
.receive(on: DispatchQueue.main)
.sink { event in
// 4. 只处理观众加入事件
guard case .onAudienceJoined(let newAudience) = event else {
return
}

// 5. 创建一条本地提示消息
var welcomeTip = Barrage()
welcomeTip.messageType = .text
welcomeTip.textContent = "欢迎 \\(newAudience.userName) 进入直播间!"

// 6. 调用 BarrageStore 的接口将其插入弹幕列表
barrageStore.appendLocalTip(message: welcomeTip)
}
.store(in: &cancellables)
}
}

API 文档

关于 LiveAudienceStore 及其相关类的所有公开接口、属性和方法的详细信息,请参阅随 AtomicXCore 框架的官方 API 文档。本文档使用到的相关 Store 如下:
Store/Component
功能描述
API 文档
LiveCoreView
直播视频流展示与交互的核心视图组件:负责视频流渲染和视图挂件处理,支持主播直播、观众连麦、主播连线等场景。
LiveAudienceStore
观众管理:获取实时观众列表(ID / 名称 / 头像),统计观众数量,监听观众进出事件。
BarrageStore
弹幕功能:发送文本 / 自定义弹幕,维护弹幕列表,实时监听弹幕状态。

常见问题

LiveAudienceState 中的在线人数(audienceCount)是如何更新的?时机和频率是怎样的?

audienceCount 的更新并非总是实时的,其机制如下:
主动进出房间:当用户主动加入或正常退出直播间时,在线人数的变更通知会即时触发。您会很快在 LiveAudienceState 中观察到 audienceCount 的变化。
异常掉线:当用户因网络问题、应用崩溃等原因异常掉线时,系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后,系统才会判定其为离线,并触发人数变更通知。
更新机制与频率控制:
无论是即时触发还是延迟触发,所有的人数变更通知都是以消息的形式在房间内广播的。
房间内每秒的消息总量有上限,单房间消息频控是每秒 40 条消息
关键点:在“弹幕风暴”或礼物刷屏等消息流量极高的场景下,如果房间内的消息速率超过了 40条/秒 的阈值,为了保证核心消息(例如弹幕)的送达,人数变更的消息可能会被频控策略丢弃
这对开发者意味着什么?
audienceCount 是一个非常接近实时的高精度估算值,但在极端高并发场景下,它可能存在短暂的延迟或数据丢失。因此,我们建议您将其用于 UI 展示,而不应作为计费、统计等需要绝对精准场景的唯一依据。


帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈