环境要求

• Firefox 版本 22+
• Chrome 版本 23+
• Safari 版本 11+
• iOS Safari 版本 11+
• Edge 版本 15+
• Opera 版本 18+
• Android Browser 版本 81+
• Chrome for Android 版本 84+
• Firefox for Android 版本 68+
• IE 不支持

github

音视频互动

本节介绍实现音视频互动的主体流程及必用的 API，SDK 提供的其他能力可参考“通信能力、房间能力、音频/视频能力”的相关功能点描述

在线演示

开发环境 / 测试环境

说明

• 以下为快速接入并体验基本功能，如需要更详细的控制和使用请查阅 完整 api 章节。
• 希望你在使用前先了解以下 SDK 中常见的 ts 类型的定义 以方便后续更简单的接入使用。

媒体类型枚举

type T_mediaType = {
  readonly mc_audio: '麦克风-默认轨道'
  readonly mc_video: '摄像头-默认轨道'
  readonly ss_video: '屏幕共享-视频轨道'
  readonly ss_audio: '屏幕共享-音频轨道'
}
type K_mediaType = keyof T_mediaType

用户轨道

interface UserTrack {
  /**
   * 协商媒体位置
   */

  location: string

  /**
   * 协商媒体ID
   */

  mid: string | null

  /**
   * 远程协商媒体ID
   */

  msid?: string | null

  /**
   * 轨道名称
   */
  trackName: string

  /**
   * 发送者ID
   */
  userId?: string

  /**
   * 轨道类型 0 1 2 3
   */
  type: number

  /**
   * 媒体类型
   */
  mediaType?: K_mediaType

  /**
   * 相对媒体音量
   */
  volume?: number

  /**
   * 表示当前通话的行为
   */
  enabled?: boolean

  /**
   * 当前轨道的具体设置参数
   */
  settings?: MediaTrackSettings
}

房间用户

interface RoomUser {
  id: string
  /**
   * 通话状态
   */
  callAction: number
  callActionMap: {
    [key in K_mediaType]: boolean
  }

  /**
   * 通话行为
   */
  callState: number

  /**
   * 加入时间
   */
  joinTime: number

  /**
   * 是否为自己
   */
  isSelf: boolean

  /**
   * 网络情况
   */
  network: {
    /**
     * 上行网络质量  quality 的值 0 - 5
     * 0为未知 值越大网络越好
     */
    egress: number

    /**
     * 下行网络质量  quality 的值 0 - 5
     * 0为未知 值越大网络越好
     */
    ingress: number
  }

  /**
   * 用户轨道
   */
  tracks: UserTrack[]

  /**
   * 是否更新了流
   */
  updateStreams: {
    [key in K_mediaType]: boolean
  }

  /**
   * 数据更新时间
   */
  updateAt: number
}

加入房间时所需参数

interface RoomOptions {
  /**
   * 房间授权凭证 仅当前房间内操作有效
   */
  sdkToken: string

  /**
   * 房间Id
   */
  roomId: string

  /**
   * 访问者ID 进入房间的人
   */

  userId: string

  /**
   * 会话类型
   * @enum 0 普通通话类型（默认有推拉流权限）
   * @enum 1 会议通话类型（默认有推拉流权限）
   * @enum 2 直播通话类型（间创建者默认拥有推拉流权限，其他加入者默认拥有订阅权限）
   */
  callType: number
}

开始

安装

npm i quickvo-sdk-js

第一步：初始化引擎

// quickvo.ts
import { QuickVO } from 'quickvo-sdk-js'

// 创建 QuickVO 实例并导出 在其他任意页面调用sdk能力
export const quickvo = new QuickVO({ appid: 'A6B499768801DJT8ACA11E5F842DB6DF' })

第二步：注册回调事件 addNotify

• 以 vue 为例 在加入房间前添加一个全局的房间用户变化回调，用来检测整个房间的变化。
• (这里你能做到几乎所有的事情，如果你不喜欢这种方式，那么可以跳过，sdk 的 绝大部分 api 几乎全部都以 Promise 风格实现 ，你可以直接在相关的 api.then() 得到对应的响应结果。)

<template>
  <video ref="mc_audio_ref"></video>
</template>

<script setup lang="ts">
const mc_audio_ref = ref<HTMLVideoElement>()
</script>

// 监听房间用户变化事件
quickvo.addNotify({
  event: 'onRoomUsers',
  callback: async (res) => {
    // 在这里会返回房间的所有用户以及对应的状态
    const users = res.data

    // 你可用在渲染每一个user时对 updateStreams进行监听 每一个user均包含字段 updateStreams 当用户流发送变化你需要重新获取流并渲染到界面

    // 以第一个用户为例 我们发现他需要更新 麦克风流
    const [user] = users
    const { id, updateStreams } = user

    // 需要更新 麦克风
    if (updateStreams['mc_audio']) {
      const stream = await quickvo.getUserStream(id, 'mc_audio')
      const dom = mc_audio_ref.value // 当然 如果你使用原生js，那么这里也只需要拿到对应的dom
      dom.srcObject = stream

      // 下面的几行代码是非必须的 但是还是建议这样做 先暂停再播放 防止重复赋值播放带来的警告或异常错误
      {
        dom?.load()
        await nextTick()
        await dom?.play()
      }
    }

    if (updateStreams['mc_video']) {
      // ...
    }
    if (updateStreams['ss_audio']) {
      // ...
    }
    if (updateStreams['ss_video']) {
      // ...
    }
  }
})

第三步：设置本地媒体及预览

• 通常如果应用层需要实现本地预览麦克风、摄像头等待发布的媒体流时，你可以尝试调用该 api，目前支持开启以下四种类型：

1. 麦克风 mc_audio
2. 摄像头 mc_video
3. 屏幕音频 ss_audio （由于浏览器内部机制，不能单独选择该媒体，因此在选择屏幕音频时，直接设置共享屏幕音视频）
4. 屏幕视频 ss_video （如果你需要单独共享屏幕画面 而不共享屏幕音频才考虑选择该类型，更多的建议直接开启 ss_audio 然后主动控制流媒体的发布、暂停）

/**
 * 设置本地流
 * @param mediaType MediaType
 * @param active 激活状态
 * @example quickvo.setLocalStream(['mc_audio'], false)
 * @returns Promise<Streams>
 */
quickvo.setLocalStream(['mc_audio'], true).then((streams) => {
  // 因考虑到易用性（与 onLocalStream 保持一致） 这里会返回所有本地流对象
  const stream = streams['mc_audio']
  // 拿到所需要的 stream 然后进行渲染 (这里以原生js使用方式作为参考)
  document.querySelector<HTMLVideoElement>('#my-dom-view')?.srcObject = stream
})

第四步：加入房间 joinRoom

• 这应该是 sdk 最重要的也是第一个阶段，你需要传入以下参数进入房间，该函数返回一个 Promise，并且返回该房间的成员状态。

/**
 * 加入房间
 * @param roomOptions RoomOptions
 * @example quickvo.joinRoom({ userId: '', roomId: '', sdkToken: '', callType: '1', newPublishAutoSubscribe: true })
 * @returns Promise<boolean>
 */
const options: RoomOptions = { userId: '', roomId: '', sdkToken: '', callType: '1', newPublishAutoSubscribe: true }
quickvo.joinRoom(options)

第五步：发布流 publish

• 这里我们尝试发布一个音视频流，发布成功后会返回所有的媒体流 对应处理渲染。（更加建议直接在 onRoomUsers 统一渲染处理，这样你不用解决单一的处理逻辑）

/**
 * 发布流
 * @param mediaTypes MediaType[]
 * @param count 发布失败重试次数
 * @example quickvo.publish(['mc_audio', 'mc_video'], 3)
 * @returns Promise<RoomUser>
 */
quickvo.publish(['mc_audio', 'mc_video'], 3).then((user) => {
  const { id, updateStreams } = user
  // 需要更新 麦克风
  if (updateStreams['mc_audio']) {
    const stream = await quickvo.getUserStream(id, 'mc_audio')
    const dom = mc_audio_ref.value // 当然 如果你使用原生js，那么这里也只需要拿到对应的dom
    dom.srcObject = stream
  }
})

第六步：订阅流 subscribe

• 我们对流的订阅做到随意耦合，你只需要将任意媒体流的 trackName 以数组的方式传入，然后等待 SDK 处理，SDK 会返回最终的处理结果和对应的流数据。

/**
 * 订阅流
 * @param trackNames 轨道名称
 * @param count 订阅失败重试次数
 * @example quickvo.subscribe(['123'])
 * @returns Promise<RoomUser[]>
 */
quickvo.subscribe(['123']).then((users) => {
  for (const user of users) {
    const { id, updateStreams } = user
    // 需要更新 麦克风
    if (updateStreams['mc_audio']) {
      const stream = await quickvo.getUserStream(id, 'mc_audio')
      const dom = mc_audio_ref.value // 当然 如果你使用原生js，那么这里也只需要拿到对应的dom
      dom.srcObject = stream
    }
  }
})

注意：

• 在 sdk 0.1.6 版本之后 加入房间后不在主动进行订阅，并且移除了相关字段 （autoSubscribe），因此将订阅的逻辑全交给应用层控制。示例代码如下：

// 首次进入房间订阅全部用户媒体
export const subscribeAll = async () => {
  const trackNames: string[] = []

  const ids: string[] = []

  // 获取当需要订阅的轨道
  for (const user of roomUsers.value) {
    const { id, tracks } = user
    for (const track of tracks) {
      trackNames.push(track.trackName)
    }
    // 有媒体轨道才进行loading
    if (tracks.length !== 0) {
      ids.push(id)
    }
  }

  addLoadings(ids) // 添加loading状态
  await quickvo.subscribe(trackNames).finally(() => removeLoadings(ids)) // 移除loading状态
}

销毁引擎

• 对 SDK 整体进行销毁

/**
 * 销毁引擎
 * @example quickvo.destroy()
 */

quickvo.destroy()

退出房间

• 退出房间后，通话相关的资源会被释放。并且会调用销毁引擎

/**
 * 退出房间
 * @example quickvo.quitRoom()
 * @returns Promise<boolean>
 */
quickvo.quitRoom()

版本迭代说明

• 版本：1.6.0 (2026-01-28)

api名称变更

setSpeaker => setSpeakerVolume
setVolume => setInputVolume

枚举变更

export const enum_mediaType = {
  ['mc_audio']: '麦克风-默认轨道',
  ['mc_video']: '摄像头-默认轨道',

  ['ss_video']: '屏幕共享-视频轨道',
  ['ss_audio']: '屏幕共享-音频轨道'
} as const

视频渲染变更

• 现在视频流不需要重新渲染 当sdk内部通知有该用户开启即可获取该用户视频流。

const stream = quickvo.getUserStream(props.userInfo.id, 'mc_video')
video_dom.srcObject = stream
video_dom.play()

• 版本：1.5.0 (2025-11-19)

- 优化 屏幕共享时 长时间不授权导致页面视图闪现情况。
- 优化 获取用户发布媒体轨道时逻辑解决授权相关问题。。
- 优化 关闭房间时没有正确关闭媒体设备。
- 优化 房间网络回调。
- 新增 摄像头p2p能力。
- 调整 原冻结轨道api（ inactiveTracks ）修改为 暂停轨道 ( pauseTracks )

以下是升级指南:
在任何调用 inactiveTracks 的地方 全部修改为 pauseTracks。( 注意：第二个参数 boolean 相反 前者描述的是启用什么轨道 后者描述的是暂停什么轨道 )
如 quickvo.inactiveTracks(['mc_video'], false) // 冻结视频轨道
修改为 quickvo.pauseTracks。(['mc_video'], true) // 暂停视频轨道

• ~~版本：1.4.1 (2025-09-04)~~ 由于编译问题导致引入该包会极大的影响 build 速度 请使用 1.4.4
• 版本：1.4.4 (2025-09-04)

着重优化了网络稳定性以及网络恢复后的数据通道恢复重建等机制。另外新增p2p相关功能。
因优化内部API设计合理性，subscribe、stopSubscribe 这两个接口传入参数 有所变动，并且不在返回最终用户对象结果（请统一使用 onRoomUsersStreams 进行更新渲染）。


以下是升级指南:

由原来的
quickvo.subscribe(['trackName1','trackName2'])
调整为
quickvo.subscribe([{ userId: '123', mediaTypes: ['mc_audio', 'mc_video'] }])

由原来的
quickvo.stopSubscribe(['trackName1','trackName2'])
调整为
quickvo.stopSubscribe([{ userId: '123', mediaTypes: ['mc_audio', 'mc_video'] }])

SDK内部提供了方便开发者升级的api：
/**
* getUsersMediaTypeBytrackNames
* @param trackNames string[]
* @returns [{ userId: '123', mediaTypes: ['mediaTypes', 'mc_video'] }]
*/

const usersMediaType = quickvo.getUsersMediaTypeBytrackNames(['trackName1','trackName2'])

quickvo.subscribe(usersMediaType)

• 版本：0.9.0 (2025-06-20)

优化SDK内部任务队列，新增sdk内部重建机制。

• 版本：0.5.8 (2025-05-30)

优化SDK内部连接建立机制，优化媒体设备切换逻辑和错误，新增 QuickVO.changeScreenSharing()方法 （用于切换共享屏幕流）

• 版本：0.4.0 (2025-05-24)

新版本支持 预连接 模式，使用预连接可以极大的缩短进入房间后发布流的时间，更快的接通会话。详情查阅 预连接专栏。

• 版本：0.2.3 (2025-03-28)

设置输出音频：quickvo.setAudioOutput(devices[0].deviceId) 在此版本之后被移除。
新版本提高更加全面的能力。使用：quickvo.setMediaDeviceKind('audiooutput', devices[0].deviceId) 替换为原来的api

• 版本：0.1.9 (2025-03-21)

QuickVO.joinRoom 新增字段： newPublishAutoSubscribe
新流自动订阅 （默认为true 当房间存在大量用户流多需要分页订阅时则使用false）
用于控制当监听到新媒体轨道发布时 sdk内部是否自动发起订阅并输出最终媒体流。

• 版本：0.1.7 (2025-03-20)

quickvo-sdk-js 现已更新至 0.1.7 版本。调整了 api 内部与 cf 交互的逻辑，使用流程和方法几乎不变。

应用层升级指南：
  QuickVO.joinRoom 现在发生了变化：移除了 自动订阅（ autoSubscribe 字段）。
  也就是说 现在首次进入房间需要应用层主动调用 QuickVO.subscribe 进行全量订阅。

SDK 内部逻辑改动说明：
  onPublish 之前受 autoSubscribe 影响，现在由[自动订阅/手动订阅] 改为 [自动订阅]。
  （如果之前加入房间一直使用 autoSubscribe：true 则不受影响 可以忽略。）