音视频 API

本地音视频推流（摄像头/麦克风/屏幕共享）和远端流渲染 API。

使用示例

// 本地推流
await classroom.startCamera(document.getElementById('local-video')!);
await classroom.startMicrophone();

// 远端渲染
const binding = classroom.bindRemoteView('teacher_001', dom, StreamType.Camera);

// 停止
await classroom.stopCamera();
binding.unbind();

API 参考

networkLevel

当前网络质量等级（实时读取，0-5，数值越小越好）。

等同于 state.networkQualityLevel$.get() 的同步快捷读取。

0 = 未知 / unknown, 1 = 极佳 / excellent, 2 = 良好 / good, 3 = 一般 / fair, 4 = 较差 / poor, 5 = 极差 / bad

---

bindRemoteView()

绑定远端流到 DOM 元素（远端流渲染的唯一入口）。

绑定一次即可持续渲染，SDK 会自动处理：远端用户开关摄像头/麦克风、网络降级切流等。

参数	类型	说明
userId	string	远端用户 ID
dom	HTMLElement	渲染目标 DOM 元素
streamType?	StreamType = StreamType.Camera	流类型（默认 Camera）

返回值: ViewBinding

示例:

const camBinding  = classroom.bindRemoteView('teacher_001', videoDom, StreamType.Camera);
const screenBinding = classroom.bindRemoteView('teacher_001', screenDom, StreamType.Screen);

// 组件卸载时解绑 / Unbind on component unmount
classroom.unbindRemoteView(camBinding);
classroom.unbindRemoteView(screenBinding);

---

enableVolumeEvaluation()

开启/关闭音频音量评估上报。

进房成功后 SDK 会自动以 500ms 间隔开启一次；调用此方法可调整间隔或关闭。

业务层若要驱动音量动画 UI，可订阅以下事件之一获取数据：

• TEvent.LOCAL_AUDIO_STATS / TEvent.REMOTE_AUDIO_STATS — TRTC 推/拉流音频统计（含 audioLevel）
• TEvent.LIVE_VOLUME_UPDATE — 大班课快直播拉流的音量回调（含 streamId / volume 0-100）
• TEvent.LOCAL_AUDIO_STATS / TEvent.REMOTE_AUDIO_STATS — TRTC publish/subscribe audio stats (with audioLevel)
• TEvent.LIVE_VOLUME_UPDATE — Live (大班课) stream volume callback (streamId / volume 0–100)

参数	类型	说明
interval	number	回调间隔（ms）；传 0 关闭

返回值: void

示例:

// 调高上报频率到 200ms / Increase reporting frequency to 200ms
classroom.enableVolumeEvaluation(200);

// 订阅本地音频统计驱动音量条 / Drive volume bar with local audio stats
classroom.on(TEvent.LOCAL_AUDIO_STATS, (stats) => {
  updateLocalVolumeBar(stats.audioLevel ?? 0); // 0~100
});

// 大班课快直播音量 / Live stream volume in Big-class
classroom.on(TEvent.LIVE_VOLUME_UPDATE, ({ streamId, volume }) => {
  updateRemoteVolumeBar(streamId, volume);
});

// 关闭上报（如离开课堂前）/ Disable (e.g., before leaving class)
classroom.enableVolumeEvaluation(0);

---

muteAllRemoteAudio()

全局静音/取消静音所有远端音频（本地静音，不影响其他人）。

参数	类型	说明
mute	boolean	true=静音 / true=mute, false=取消静音 / false=unmute

返回值: void

---

muteRemoteAudio()

静音/取消静音指定远端用户音频（本地静音，不影响其他人）。

参数	类型	说明
userId	string	目标用户 ID
mute	boolean	true=静音 / mute, false=取消静音 / unmute

返回值: void

---

setAvatar()

设置虚拟形象（webAR 旗舰版能力）。

仅旗舰版套餐支持（isFeatureAvailable('enableAvatar') === true）； 调用后会替换本地视频流的画面为虚拟形象动作捕捉效果。

参数	类型	说明
params	TAvatarParam	虚拟形象参数（模型 URL / 缩放 / 偏移等）

返回值: Promise<TResult<void>>

示例:

if (!classroom.isFeatureAvailable('enableAvatar')) {
  toast.warn('当前套餐不支持虚拟形象');
  return;
}
await classroom.setAvatar({ modelUrl: 'https://cdn/avatar.glb', scale: 1 });

---

setBeautyParam()

设置美颜参数。

需要套餐支持（isFeatureAvailable('enableBeauty') === true）。

所有参数取值范围 0~100，0 表示关闭该项；任意一项 > 0 时 state.beautyEnabled$ 变为 true。

参数	类型	说明
params	Partial<TBeautyParam>	lift 瘦脸、eye 大眼、chin 下巴

返回值: Promise<TResult<void>>

示例:

// 一键开启自然美颜 / Apply natural beauty preset
await classroom.setBeautyParam({ whiten: 30, smooth: 30, lift: 20, eye: 20 });

// 关闭美颜（所有参数置 0）/ Disable beauty (set all to 0)
await classroom.setBeautyParam({ whiten: 0, smooth: 0, ruddy: 0, lift: 0, eye: 0, chin: 0 });

// 套餐校验 / Package check
if (!classroom.isFeatureAvailable('enableBeauty')) {
  toast.warn('当前套餐不支持美颜');
  return;
}

---

setVirtualBackground()

设置虚拟背景。

需要套餐支持（与美颜共享 enableBeauty 开关）。在摄像头开启后调用立即生效； 摄像头未开启时设置的参数会在下次 startCamera() 时自动应用。 after the camera is on; if the camera is off, params are applied on the next startCamera().

参数	类型	说明
params	TVirtualBackgroundParam	- { type: 'image', imageUrl } 替换为指定图片 / replace with image (URL 必须同源或开启 CORS)

返回值: Promise<TResult<void>>

示例:

await classroom.setVirtualBackground({ type: 'blur' });                              // 模糊背景 / blur
await classroom.setVirtualBackground({ type: 'image', imageUrl: 'https://cdn/bg.jpg' }); // 图片替换 / image
await classroom.setVirtualBackground({ type: 'none' });                              // 关闭 / disable

// 套餐校验 / Package check
if (!classroom.isFeatureAvailable('enableBeauty')) {
  toast.warn('当前套餐不支持虚拟背景');
  return;
}

---

startCamera()

开启摄像头，并将本地预览渲染到指定 DOM 元素。

调用后 SDK 自动采集视频并推流到远端，同时在指定容器中显示本地预览画面。

参数	类型	说明
element	HTMLElement	渲染本地预览的 DOM 容器
deviceId?	string	可选：指定摄像头设备 ID（不传则使用系统默认）

返回值: Promise<TResult<void>>

示例:

// 基础用法 / Basic usage
const result = await classroom.startCamera(document.getElementById('local-video')!);
if (!result.ok) toast.error(result.message);

// 使用指定摄像头 / Use a specific camera
const cams = await classroom.getCameraList();
if (cams.ok && cams.data.length > 0) {
  await classroom.startCamera(videoDom, cams.data[0].deviceId);
}

---

startMicrophone()

开启麦克风，开始推送本地音频流。

调用后 SDK 自动采集音频并推流到远端，远端用户可立即听到本地声音。

参数	类型	说明
deviceId?	string	可选：指定麦克风设备 ID（不传则使用系统默认）

返回值: Promise<TResult<void>>

示例:

const result = await classroom.startMicrophone();
if (!result.ok) toast.error(result.message);

// 使用指定麦克风 / Use a specific microphone
const mics = await classroom.getMicrophoneList();
if (mics.ok && mics.data.length > 0) {
  await classroom.startMicrophone(mics.data[0].deviceId);
}

---

startScreenShare()

开启屏幕共享（会触发浏览器原生选屏弹窗）。

同一时刻只能有一路屏幕共享；如果已在共享，需先调用 stopScreenShare()。

若传入 element，SDK 会将共享画面同时渲染到该容器中供本地预览。

参数	类型	说明
element?	HTMLElement	可选：在此 DOM 元素中渲染本地屏幕共享预览

返回值: Promise<TResult<void>>

示例:

// 基础用法 / Basic usage
const result = await classroom.startScreenShare();
if (!result.ok) toast.error(result.message);

// 带本地预览 / With local preview
const previewDom = document.getElementById('screen-preview')!;
await classroom.startScreenShare(previewDom);

---

stopCamera()

关闭摄像头，停止本地视频推流。

返回值: Promise<TResult<void>>

---

stopMicrophone()

关闭麦克风，停止本地音频推流。

返回值: Promise<TResult<void>>

---

stopScreenShare()

停止屏幕共享。

返回值: Promise<TResult<void>>

---

unbindRemoteView()

解绑远端流（停止渲染并释放订阅资源）。

参数	类型	说明
binding	ViewBinding	bindRemoteView() 返回的 ViewBinding 句柄

返回值: void

---