quickvo-sdk-js

环境要求

• 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 microphoneCamera_audio: '麦克风-默认轨道'
  readonly microphoneCamera_video: '摄像头-默认轨道'
  readonly screenSharing_video: '屏幕共享-视频轨道'
  readonly screenSharing_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="microphoneCamera_audio_ref"></video>
</template>

<script setup lang="ts">
const microphoneCamera_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['microphoneCamera_audio']) {
      const stream = await quickvo.getUserStream(id, 'microphoneCamera_audio')
      const dom = microphoneCamera_audio_ref.value // 当然 如果你使用原生js，那么这里也只需要拿到对应的dom
      dom.srcObject = stream

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

    if (updateStreams['microphoneCamera_video']) {
      // ...
    }
    if (updateStreams['screenSharing_audio']) {
      // ...
    }
    if (updateStreams['screenSharing_video']) {
      // ...
    }
  }
})

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

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

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

/**
 * 设置本地流
 * @param mediaType MediaType
 * @param active 激活状态
 * @example quickvo.setLocalStream(['microphoneCamera_audio'], false)
 * @returns Promise<Streams>
 */
quickvo.setLocalStream(['microphoneCamera_audio'], true).then((streams) => {
  // 因考虑到易用性（与 onLocalStream 保持一致） 这里会返回所有本地流对象
  const stream = streams['microphoneCamera_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(['microphoneCamera_audio', 'microphoneCamera_video'], 3)
 * @returns Promise<RoomUser>
 */
quickvo.publish(['microphoneCamera_audio', 'microphoneCamera_video'], 3).then((user) => {
  const { id, updateStreams } = user
  // 需要更新 麦克风
  if (updateStreams['microphoneCamera_audio']) {
    const stream = await quickvo.getUserStream(id, 'microphoneCamera_audio')
    const dom = microphoneCamera_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['microphoneCamera_audio']) {
      const stream = await quickvo.getUserStream(id, 'microphoneCamera_audio')
      const dom = microphoneCamera_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()

版本迭代说明

• 版本：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 则不受影响 可以忽略。）