0.1.3 • Published 5 months ago
quickvo-sdk-js v0.1.3
环境要求
- 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 不支持
音视频互动
本节介绍实现音视频互动的主体流程及必用的 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
/**
* 自动订阅流
*/
autoSubscribe?: boolean
}开始
安装
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 当用户流发送变化你需要重新获取流并渲染到界面
// 以第一个用户为例 我们发现他需要更新 摄像头视频流
// 在 0.0.9版本之后,客户端无需再关心和处理音频媒体的播放了 SDK内部已经实现了处理
const [user] = users
const { id, updateStreams } = user
// 需要更新 摄像头视频流
if (updateStreams['microphoneCamera_video']) {
const stream = await quickvo.getUserStream(id, 'microphoneCamera_video')
const dom = microphoneCamera_video_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，目前支持开启以下四种类型：
- 麦克风 microphoneCamera_audio
- 摄像头 microphoneCamera_video
- 屏幕音频 screenSharing_audio （由于浏览器内部机制，不能单独选择该媒体，因此在选择屏幕音频时，直接设置共享屏幕音视频）
- 屏幕视频 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', autoSubscribe: true })
* @returns Promise<boolean>
*/
const options: RoomOptions = { userId: '', roomId: '', sdkToken: '', callType: '1', autoSubscribe: 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 整体进行销毁
/**
* 销毁引擎
* @example quickvo.destroy()
*/
quickvo.destroy()退出房间
- 退出房间后，通话相关的资源会被释放。并且会调用销毁引擎
/**
* 退出房间
* @example quickvo.quitRoom()
* @returns Promise<boolean>
*/
quickvo.quitRoom()