产品动态
产品近期公告
关于 TRTC Live 正式上线的公告
关于TRTC Conference 正式版上线的公告
Conference 商业化版本即将推出
关于多人音视频 Conference 开启内测公告
关于音视频通话 Call 正式版上线的公告
关于腾讯云音视频终端 SDK 播放升级及新增授权校验的公告
关于 TRTC 应用订阅套餐服务上线的相关说明
观众连线（Web）
AtomicXCore 提供了 CoGuestState 模块，专门用于管理观众连麦的完整业务流程。您无需关心复杂的状态同步和信令交互，只需调用几个简单的方法，即可为您的直播添加强大的观众与主播音视频互动功能。
核心场景
CoGuestState 支持以下两种最主流的连麦场景：观众申请上麦：观众主动发起连麦请求，主播在收到请求后进行同意或拒绝。
主播邀请上麦：主播可以主动向直播间内的任意一位观众发起连麦邀请。
示例项目
实现步骤
步骤1：组件集成
注意：
步骤2：实现观众申请上麦
观众端实现
作为观众，您的核心任务是发起申请、接收结果和主动下麦。
1. 发起连麦申请
当用户点击界面上的"申请连麦"按钮时，调用
applyForSeat 方法。import { useCoGuestState } from "tuikit-atomicx-vue3";const { applyForSeat } = useCoGuestState();// 用户点击“申请连麦”const handleRequestToConnect = async () => {try {await applyForSeat({seatIndex: -1, // 申请的麦位，-1 表示随机分配timeout: 30, // 请求超时时间（秒），注意：TS定义单位若为毫秒请传入 30000});console.log('申请已发送');} catch (error) {console.error('申请失败', error);}}
2. 监听主播的响应
通过
subscribeEvent 订阅CoGuestEvent.onGuestApplicationResponded事件，您可以接收到主播的处理结果。import { onMounted, onUnmounted } from 'vue';import { useCoGuestState, useDeviceState, CoGuestEvent } from "tuikit-atomicx-vue3";const { subscribeEvent, unsubscribeEvent } = useCoGuestState();const { openLocalMicrophone, openLocalCamera } = useDeviceState();const handleGuestApplicationResponded = (eventInfo: any) => {if (eventInfo.isAccept) {console.log('上麦申请被同意');// 1. 打开麦克风和摄像头openLocalMicrophone();openLocalCamera();// 2. 在此更新 UI，例如变更申请按钮状态，显示为连麦中} else {console.log('上麦申请被拒绝');// 弹窗提示用户申请被拒绝}};// 在组件挂载时订阅事件onMounted(() => {subscribeEvent(CoGuestEvent.onGuestApplicationResponded, handleGuestApplicationResponded);});// 在组件卸载时取消订阅onUnmounted(() => {unsubscribeEvent(CoGuestEvent.onGuestApplicationResponded, handleGuestApplicationResponded);});
3. 主动下麦
当连麦观众想结束互动时，调用
disConnect 方法即可返回普通观众状态。import { useCoGuestState } from "tuikit-atomicx-vue3";const { disConnect } = useCoGuestState();// 用户点击“下麦”按钮const leaveSeat = async () => {try {await disConnect();console.log('下麦成功');} catch (error) {console.log('下麦失败', error);}}
4.(可选) 取消申请
如果观众在主播处理前想撤回申请，可以调用
cancelApplication。import { useCoGuestState } from "tuikit-atomicx-vue3";const { cancelApplication } = useCoGuestState();// 用户在等待时，点击“取消申请”const handleCancelRequest = async () => {await cancelApplication();console.log('取消申请成功');}
主播端实现
作为主播，您的核心任务是接收申请、展示申请列表和处理申请。
1. 监听新的连麦申请
通过
subscribeEvent 订阅 CoHostEvent.onGuestApplicationReceived 事件后，您可以在有新观众申请时立即收到通知。import { onMounted, onUnmounted } from 'vue';import { useCoGuestState, CoHostEvent } from "tuikit-atomicx-vue3";const { subscribeEvent, unsubscribeEvent } = useCoGuestState();const handleGuestApplicationReceived = (eventInfo: any) => {console.log('收到观众的连麦申请:', eventInfo.guestUser);// 在此更新 UI，例如在"申请列表"按钮上显示红点};onMounted(() => {subscribeEvent(CoHostEvent.onGuestApplicationReceived, handleGuestApplicationReceived);});onUnmounted(() => {unsubscribeEvent(CoHostEvent.onGuestApplicationReceived, handleGuestApplicationReceived);});
2.展示申请列表
CoGuestState 会实时维护当前的申请者列表 applicants，这是一个 Vue 的 ComputedRef，包含当前所有申请连麦的观众信息。每个申请者对象包含 userId（用户ID）和 userName（用户名）等字段。您可以直接在模板中使用：<template><div v-for="audience in applicants" :key="audience.userId" class="applicant-item"><span>{{ audience.userName }}</span><button @click="handleAccept(audience.userId)">同意</button><button @click="handleReject(audience.userId)">拒绝</button></div></template><script setup lang="ts">import { useCoGuestState } from "tuikit-atomicx-vue3";const { applicants, acceptApplication, rejectApplication } = useCoGuestState();const handleAccept = async (userId: string) => {await acceptApplication({ userId });};const handleReject = async (userId: string) => {await rejectApplication({ userId });};</script>
步骤3：实现主播邀请上麦
主播端实现
1. 向观众发起邀请
当主播在观众列表中选择某人并点击"邀请连麦"时，调用
inviteToSeat 方法。import { useCoGuestState } from "tuikit-atomicx-vue3";const { inviteToSeat } = useCoGuestState();// 主播选择观众并发起邀请const handleInviteToSeat = async (userId: string) => {try {await inviteToSeat({userId,seatIndex: -1, // 随机分配麦位timeout: 30,});console.log(`已向观众 ${userId} 发送上麦邀请`);} catch (error) {console.error('邀请失败', error);}}
2.监听观众的回应
通过
subscribeEvent 订阅 CoHostEvent.onHostInvitationResponded 事件。import { onMounted } from 'vue';import { useCoGuestState, CoHostEvent } from "tuikit-atomicx-vue3";const { subscribeEvent } = useCoGuestState();onMounted(() => {subscribeEvent(CoHostEvent.onHostInvitationResponded, (eventInfo) => {if(eventInfo.isAccept){console.log(`观众 ${eventInfo.guestUser.userName} 接受了您的邀请`);} else {console.log(`观众 ${eventInfo.guestUser.userName} 拒绝了您的邀请`);}});});
观众端实现
1.接收主播的邀请
通过
subscribeEvent 订阅 CoGuestEvent.onHostInvitationReceived 事件。import { onMounted } from 'vue';import { useCoGuestState, CoGuestEvent } from "tuikit-atomicx-vue3";const { subscribeEvent } = useCoGuestState();onMounted(() => {subscribeEvent(CoGuestEvent.onHostInvitationReceived, (eventInfo) => {// 在此弹出一个 Modal 对话框，让用户选择“接受”或“拒绝”// 保存 eventInfo.hostUser.userId 作为 inviterIdshowInviteDialog(eventInfo.hostUser.userId);});});
2.响应邀请
当用户在弹出的对话框中做出选择后，调用相应的方法。
import { useCoGuestState, useDeviceState } from "tuikit-atomicx-vue3";const { acceptInvitation, rejectInvitation } = useCoGuestState();const { openLocalMicrophone, openLocalCamera } = useDeviceState();// 用户点击“接受”const handleAccept = async (inviterId: string) => {try {await acceptInvitation({ inviterId });// 接受后通常需要自动打开设备openLocalMicrophone();openLocalCamera();} catch (error) {console.error('接受邀请失败', error);}}// 用户点击“拒绝”const handleReject = async (inviterId: string) => {await rejectInvitation({ inviterId });}
运行效果
当您集成以上功能后，请分别使用两个观众与主播进行连麦操作，观众 A 同时打开摄像头和麦克风，观众 B 只打开麦克风，运行效果如下。
API 文档
常见问题
连麦功能无响应（申请/邀请/接受/拒绝均失败）
问题描述：调用
applyForSeat, acceptApplication, inviteToSeat 等方法后，没有任何效果。原因分析：
CoGuestState 依赖于底层的房间引擎状态。通常是因为并未成功加入房间，或者 useCoGuestState 调用时上下文的环境尚未初始化完成。解决方案：请确保在调用这些方法之前，用户已经成功加入了直播间。
无法接收到连麦相关的事件通知
问题描述：观众端收不到主播的邀请，或者主播端收不到观众的申请。
原因分析：
没有正确调用
subscribeEvent。使用了错误的 Event 枚举值（例如
CoHostEvent 和 CoGuestEvent 混用）。解决方案：
主播端：订阅
CoHostEvent.onGuestApplicationReceived, CoHostEvent.onHostInvitationResponded。观众端：订阅
CoGuestEvent.onGuestApplicationResponded, CoGuestEvent.onHostInvitationReceived。连麦成功后，对方看不到我的画面或听不到我的声音
问题描述：上麦成功后，麦位列表已更新，但没有画面或声音。
原因分析：
CoGuestState 仅负责信令层面的“上麦”操作（分配麦位）。推流（打开麦克风/摄像头）需要显式调用 DeviceState 的方法。解决方案：在收到“接受申请”或“接受邀请”的回调中，务必调用
openLocalMicrophone 和 openLocalCamera。并且要注意浏览器的自动播放策略，确保用户与页面有过交互。文档反馈