# urtc-sdk-web
**Repository Path**: ucloud-cn/urtc-sdk-web
## Basic Information
- **Project Name**: urtc-sdk-web
- **Description**: No description available
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2021-02-01
- **Last Updated**: 2021-02-05
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# UCloudRTC Web SDK API 手册
UCloudRTC 包含以下方法、类或对象：
* [一、Client 类](#client)
* [二、getDevices 方法](#getdevices)
* [三、getSupportProfileNames 方法](#getsupportprofilenames)
* [四、getSupportedCodec 方法](#getsupportedcodec)
* [五、isSupportWebRTC 方法](#issupportwebrtc)
* [六、deviceDetection 方法](#devicedetection)
* [七、version 属性](#version)
* [八、generateToken 方法](#generateToken)
* [九、Logger 对象](#logger)
* [十、setServers 方法](#setservers)
> 注： 想要了解使用此 SDK 的简单步骤，请查看 [使用说明](./Manual.md)
---
## 一、Client 类
Client 类包含以下方法：
* [构造函数 - 创建客户端](#client-constructor)
* [joinRoom 方法 - 加入房间](#client-joinroom)
* [leaveRoom 方法 - 离开房间](#client-leaveroom)
* [publish 方法 - 发布本地流](#client-publish)
* [unpublish 方法 - 取消发布本地流](#client-unpublish)
* [subscribe 方法 - 订阅远端流](#client-subscribe)
* [unsubscribe 方法 - 取消订阅远端流](#client-unsubscribe)
* [on 方法 - 绑定事件处理函数](#client-on)
* [off 方法 - 解绑事件处理函数](#client-off)
* [play 方法 - 播放一条流的音视频](#client-play)
* [resume 方法 - 恢复一条流的音视频播放](#client-resume)
* [stop 方法 - 停止播放一条流的音视频](#client-stop)
* [muteAudio 方法 - 禁用音频轨道](#client-muteaudio)
* [unmuteAudio 方法 - 启用音频轨道](#client-unmuteaudio)
* [muteVideo 方法 - 禁用视频轨道](#client-mutevideo)
* [unmuteVideo 方法 - 启用视频轨道](#client-unmutevideo)
* [~~startRecording 方法 - 已废弃~~](#client-startrecording)
* [~~stopRecording 方法 - 已废弃~~](#client-stoprecording)
* [getUser 方法 - 获取当前用户信息](#client-getuser)
* [getUsers 方法 - 获取所有远端用户信息](#client-getusers)
* [getStream 方法 - 获取某条流信息](#client-getstream)
* [getLocalStreams 方法 - 获取所有本地流信息](#client-getlocalstreams)
* [getRemoteStreams 方法 - 获取所有远端流信息](#client-getremotestreams)
* [~~getStreams 方法 - 已废弃~~](#client-getstreams)
* [getMediaStream 方法 - 获取某条流对应的媒体流](#client-getmediastream)
* [~~getLocalMediaStream 方法 - 已废弃~~](#client-getlocalmediastream)
* [~~getRemoteMediaStream 方法 - 已废弃~~](#client-getremotemediastream)
* [getMicrophones 方法 - 获取麦克风设备信息](#client-getmicrophones)
* [getCameras 方法 - 获取摄像头设备信息](#client-getcameras)
* [getLoudspeakers 方法 - 获取扬声器设备信息](#client-getloudspeakers)
* [setVideoProfile 方法 - 设置视频属性](#client-setvideoprofile)
* [switchDevice 方法 - 切换音视频输入设备](#client-switchdevice)
* [switchScreen 方法 - 切换屏幕共享](#client-switchscreen)
* [switchImage 方法 - 切换图片推送](#client-switchimage)
* [getAudioVolume 方法 - 获取音频音量](#client-getaudiovolume)
* [setAudioVolume 方法 - 设置音频音量](#client-setaudiovolume)
* [getAudioStats 方法 - 获取音频状态](#client-getaudiostats)
* [getVideoStats 方法 - 获取视频状态](#client-getvideostats)
* [getNetworkStats 方法 - 获取网络状态](#client-getnetworkstats)
* [preloadEffect 方法 - 预加载音效文件](#client-preloadeffect)
* [unloadEffect 方法 - 卸载音效文件](#client-unloadeffect)
* [playEffect 方法 - 开始播放音效](#client-playeffect)
* [pauseEffect 方法 - 暂停播放音效](#client-pauseeffect)
* [resumeEffect 方法 - 恢复播放音效](#client-resumeeffect)
* [stopEffect 方法 - 停止播放音效](#client-stopeffect)
* [setEffectVolume 方法 - 设置播放音效的音量](#client-seteffectvolume)
* [snapshot 方法 - 截屏](#client-snapshot)
* [startPreviewing 方法 - 开启预览](#client-startpreviewing)
* [stopPreviewing 方法 - 停止预览](#client-stoppreviewing)
* [~~deviceDetection 方法 - 已转移~~](#client-devicedetection)
* [replaceTrack 方法 - 替换音频轨道或视频轨道](#client-replacetrack)
* [~~startMix 方法 - 已废弃~~](#client-startmix)
* [~~stopMix 方法 - 已废弃~~](#client-stopmix)
* [queryMix 方法 - 查询房间内录制或转推任务](#client-querymix)
* [~~addMixStreams 方法 - 已废弃~~](#client-addmixstreams)
* [~~removeMixStreams 方法 - 已废弃~~](#client-removemixstreams)
* [setRole 方法 - 设置用户角色](#client-setrole)
* [startRecord 方法 - 开启录制](#client-startrecord)
* [stopRecord 方法 - 结束录制](#client-stoprecord)
* [updateRecordStreams 方法 - 增加/删除录制的流](#client-updaterecordstreams)
* [startRelay 方法 - 开启转推](#client-startrelay)
* [stopRelay 方法 - 结束转推](#client-stoprelay)
* [updateRelayStreams 方法 - 增加/删除转推的流](#client-updaterelaystreams)
* [updateRelayPushURL 方法 - 增加/删除转推地址](#client-updaterelaypushurl)
* [updateRelayLayout 方法 - 更换转推的布局](#client-updaterelaylayout)
* [createStream 方法 - 创建一条本地流](#client-createstream)
* [publishStream 方法 - 发布一条本地流](#client-publishstream)
* [unpublishStream 方法 - 取消发布一条本地流](#client-unpublishstream)
* [destroyStream 方法 - 销毁一条本地流](#client-destroystream)
* [enableAudioVolumeIndicator 方法 - 开启远程流音量指示器](#client-enableaudiovolumeindicator)
### 1. 构造函数
用于创建一个 URTC Client 对象，示例代码：
```js
new Client(AppId, Token, ClientOptions);
```
#### 参数说明
- AppId: string 类型, 必传，可从 UCloud 控制台查看
- Token: string 类型, 必传，需按规则生成，测试阶段，可使用 [generateToken](#generateToken) 临时生成
- ClientOptions: object 类型, 选传，类型说明如下
```js
{
type?: "rtc" | "live", // 选填，设置房间类型，有两种 "live" 和 "rtc" 类型可选 ，分别对应直播模式和连麦模式，默认为 rtc
role?: "pull" | "push" | "push-and-pull", // 选填，设置用户角色，可设 "pull" | "push" | "push-and-pull" 三种角色，分别对应拉流、推流、推+拉流，默认为 "push-and-pull"，特别地，当房间类型为连麦模式（rtc）时，此参数将被忽视，会强制为 "push-and-pull"，即推+拉流
codec?: "vp8" | "h264", // 选填，设置视频编码格式，可设 "vp8" 或 "h264"，默认为 "vp8"
}
```
### 2. joinRoom 方法
加入房间，示例代码：
```js
client.joinRoom(RoomId, UserId, onSuccess, onFailure)
```
#### 参数说明
- RoomId: string 类型，必传，房间号
- UserId: string 类型，必传，用户ID
- onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下
```js
function onSuccess(Users, Streams) {}
```
函数参数 Users 为返回值，User 类型的数组，代表当前房间内已有的其他用户的信息，User 类型说明见 [User](#user)；函数参数 Streams 为返回值，Stream 类型的数组，代表当前房间内其他用户正在发布的流。Stream 类型说明见 [Stream](#stream)
> 注：当加入房间成功后，当前房间内已有的其他用户的信息以及正在发布的流，都会分别由 `user-added` 和 `stream-added` 事件再进行通知。如需订阅正在发布的流，建议在 `stream-added` 事件函数中统一处理，此处 `onSuccess` 函数的参数 `Users` 和 `Streams` 数据仅用于展示。
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Err) {}
```
Err 为错误信息
### 3. leaveRoom 方法
离开房间，示例代码：
```js
client.leaveRoom(onSuccess, onFailure)
```
#### 参数说明
- onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下
```js
function onSuccess() {}
```
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Err) {}
```
Err 为错误信息
### 4. publish 方法
发布本地流，自 1.4.0 版本开始支持同时发布两条流（且摄像头，屏幕共享各一条，不可同时为同一类），示例代码：
```js
client.publish(PublishOptions, onFailure)
```
#### 参数说明
- PublishOptions: object 类型，选传，类型说明如下
```js
{
audio: boolean // 必填，指定是否使用麦克风设备。若传了 mediaStream 参数，将不再采集麦克风的音频，直接使用 mediaStream 中的音频。
video: boolean // 必填，指定是否使用摄像头设备。若传了 mediaStream 参数，将不再采集摄像头的视频，直接使用 mediaStream 中的视频；若传了 file 或 filePath 参数，将不再采集摄像头的视频，直接使用图片生成的视频。
facingMode?: FacingMode // 选填，在移动设备上，可以设置该参数选择使用前置或后置摄像头，其中，FacingMode 为 'user'（前置摄像头）或 'environment'（后置摄像头），注：1. 请务必确定是在移动设备上设置该参数，否则可能会报 'OverConstrainedError［无法满足要求错误]' 的错误；2. 当在设备上使用前置摄像头时，设备（如苹果设备，以及没有设置摄像头为 "自拍镜像" 的 Android 设备）本地显示的图像是左右相反的（以 Y 轴对称），此时可为 video 元素添加样式 'transform: rotateY(180deg);' 来指定视频在本地显示的时候做镜像翻转。
screen: boolean // 必填，指定是否为屏幕共享，audio, video, screen 不可同时为 true，更不可同时为 false
screenAudio?: boolean // 选填，指定是否采集屏幕共享的音频（部分浏览器支持），默认为 false
microphoneId?: string // 选填，指定使用的麦克风设备的ID，可通过 getMicrophones 方法查询获得该ID，不填时，将使用默认麦克风设备
cameraId?: string // 选填，指定使用的摄像头设备的ID，可以通过 getCameras 方法查询获得该ID，不填时，将使用默认的摄像头设备
extensionId?: string // 选填，指定使用的 Chrome 插件的 extensionId，可使 72 以下版本的 Chrome 浏览器进行屏幕共享。
mediaStream?: MediaStream // 选填，允许用户发布自定义的媒体流
file?: File // 选填，发布时指定使用图片文件生成视频源，具体参数说明可参考 switchImage 接口
filePath?: string // 选填，发布时指定使用网络图片生成视频源，具体参数说明可参考 switchImage 接口
}
```
> 对于屏幕共享各浏览器兼容性，请参见 [getDisplayMedia](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getDisplayMedia) 。
> 此外，对于推流时所传参数的生效将采用此类优先级：mediaStream > file > filePath > video = screen；即用户指定媒体流（MediaStream）时，该媒体流将被发布，不再考虑其他情况生成的流；若指定了 file ，而没指定媒体流（MediaStream），那么将用 file 生成图片媒体流并被发布，依次类推。
> file 和 filePath 参数说明，请参见 [switchImage](#client-switchimage) 接口的参数说明。
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Error) {}
```
[Error](https://developer.mozilla.org/zh-CN/docs/Web/JavaScript/Reference/Global_Objects/Error) 为错误信息
> 可能的错误名称（即 error.name）有：
>
> - AbortError［中止错误］ 尽管用户和操作系统都授予了访问设备硬件的权利，而且未出现可能抛出NotReadableError异常的硬件问题，但仍然有一些问题的出现导致了设备无法被使用。
> - NotAllowedError［拒绝错误］ 用户拒绝了当前的浏览器实例的访问请求；或者用户拒绝了当前会话的访问；或者用户在全局范围内拒绝了所有媒体访问请求。
> - NotFoundError［找不到错误］ 找不到满足请求参数的媒体类型。
> - NotReadableError［无法读取错误］ 尽管用户已经授权使用相应的设备，操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。
> - OverConstrainedError［无法满足要求错误］ 指定的要求无法被设备满足。
### 5. unpublish 方法
取消发布本地流，示例代码：
```js
client.unpublish(StreamId, onSuccess, onFailure)
```
#### 参数说明
- StreamId: string 类型，选传，不传时，若仅有一条本地流，那么该流将被取消发布，若有两条本地流，那么最早发布的那条本地流将被取消发布
- onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下
```js
function onSuccess(Stream) {}
```
函数参数 Stream 为返回值，object 类型，为流信息，类型说明见 [Stream](#stream)
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Err) {}
```
Err 为错误信息
### 6. subscribe 方法
订阅远端流，注：订阅的远端流如果有音频时，可能存在播放问题，请查看 [关于浏览器的自动播放问题的说明及处理](./AutoPlay.md)
，示例代码：
```js
client.subscribe(StreamId, onFailure)
```
#### 参数说明
- StreamId: string 类型，必传，为需要订阅的远端流的 sid
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Err) {}
```
Err 为错误信息
### 7. unsubscribe 方法
取消订阅远端流，示例代码：
```js
client.unsubscribe(StreamId, onSuccess, onFailure)
```
#### 参数说明
- StreamId: string 类型，必传，为需要订阅的远端流的 sid
- onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下
```js
function onSuccess(Stream) {}
```
函数参数 Stream 为返回值，object 类型，为流信息，类型说明见 [Stream](#stream)
- onFailure: 选传，函数类型，方法调用失败时执行的回调函数。
```js
function(Err) {}
```
Err 为错误信息
### 8. on 方法
给事件绑定监听函数，示例代码：
```js
client.on(EventType, Listener)
```
#### 参数说明
- EventType: string 类型， 必传，目前有 'user-added' | 'user-removed' |
'stream-added' | 'stream-removed' | 'stream-published' | 'stream-subscribed' |
'mute-video' | 'unmute-video' | 'mute-audio' | 'unmute-audio' | 'screenshare-stopped' |
'connection-state-change' | 'kick-off' | 'network-quality' | 'stream-reconnected' |
'record-notify' | 'relay-notify' | 'volume-indicator' | 'error-notify' | 'player-status-change' 这些事件可绑定监听函数
- Listener: function 类型，事件监听函数
- 当事件类型为 'user-added' | 'user-removed' | 'kick-off' 时，可用 `function Listener(User) {}` 类型的函数，其中函数的参数类型见 [User](#user)
- 当事件类型为 'stream-added' | 'stream-removed' | 'stream-published' | 'stream-subscribed' | 'mute-video' | 'unmute-video' | 'mute-audio' | 'unmute-audio' | 'screenshare-stopped' 时，可用 `function Listener(Stream) {}` 类型的函数，其中函数的参数类型见 [Stream](#stream)
- 当事件类型为 'connection-state-change' 时，可用 `function Listener(States) {}` 类型的函数，函数的参数为 `{previous: State, current: State}`，其中 State 为 'OPEN' | 'CONNECTING' | 'CLOSING' | 'RECONNECTING' | 'CLOSED' 四种类型之一。
- 当事件类型为 'network-quality' 时，可用 `function Listener(Stats) {}` 类型的函数，函数的参数为 `{uplink: Quality, downlink: Quality}`，其中，uplink 代表上行网络质量，downlink 代表下行网络质量，其值 Quality 为字符串，是 '0' | '1' | '2' | '3' | '4' | '5' | '6' 几种类型之一。
- '0': 网络质量未知
- '1': 网络质量优秀
- '2': 网络质量良好
- '3': 网络质量一般
- '4': 网络质量较差
- '5': 网络质量糟糕
- '6': 网络连接断开
- 当事件类型为 'stream-reconnected' 时，可用 `function Listener(Streams) {}` 类型的函数，函数的参数为 `{previous: Stream, current: Stream}`，其中 previous 是重连前的发布/订阅流，current 是重连后的发布/订阅流，请使用 current 来更新业务代码中的缓存。
- 当事件类型为 'record-notify' 时，可用 `function Listener(MixNotification) {}` 类型的函数，函数的参数为 MixNotification 的 `{ code: string, message: string }`，code 有以下可能的值：
- '0': （正常）录制任务开启后10秒左右，如果收到这个消息，表示录制任务开启成功
- '24151': （正常) 如果收到这个消息，表示加流成功
- '24149': （异常）任务被停止，可能的原因有房间内所有用户的推流已停止
- '24150': （异常）任务开启后10秒，如果收到这个消息，则表示任务开启失败
- '24152': （异常）表示加流失败
- 当事件类型为 'relay-notify' 时，可用 `function Listener(MixNotification) {}` 类型的函数，函数的参数为 MixNotification 的 `{ code: string, message: string }`，code 有以下可能的值：
- '0': （正常）转推任务开启后10秒左右，如果收到这个消息，表示转推任务开启成功
- '24151': （正常) 如果收到这个消息，表示加流成功
- '24149': （异常）任务被停止，可能的原因有房间内所有用户的推流已停止，或到推流地址（PushURL）的连接已断开
- '24150': （异常）任务开启后10秒，如果收到这个消息，则表示任务开启失败
- '24152': （异常）表示加流失败
- 当事件类型为 'volume-indicator' 时（通过 [enableAudioVolumeIndicator](#client-enableaudiovolumeindicator) 方法开启），可用 `function Listener(VolumeIndication[]) {}` 类型的函数，函数参数为 VolumeIndication 类型的数组（已按 volume 的值进行了降序排序，第一个为音量最大的），VolumeIndication 为 `{ sid: string, uid: string, mediaType: string, volume: number }`，其中 mediaType 为 'camera' 或 'screen' 两种之一，volume 为 0 - 100 的值，通常在列表中音量大于 5 的用户为持续说话的人。
- 当事件类型为 'error-notify' 时，可用 `function Listener(ErrorNotification) {}` 类型的函数，函数的参数为 ErrorNotification `{ code: string, message: string }`，code 有以下可能的值：
- '24147': 10秒内连续操作 mute/unmute audio 或 video 次数超过了150次的次数限制，服务器拒绝执行（一般不会达到次数限制，可忽略此事件）
- 当事件类型为 'player-status-change' 时，可用 `function Listener(PlayerStatusEvent) {}` 类型的函数，函数的参数为PlayerStatusEvent `{ type: string, status: string, stream: Stream }`，其中 type 的值为 'audio' | 'video'，status 的值为 'playing' | 'paused'，stream 为流信息，参见 [Stream](#stream)
#### 事件名解释：
事件名 | 描述
:--: | :--
user-added | 有其他用户加入房间
user-removed | 有其他用户离开房间
stream-added | 有其他用户发布了一条流，当收到此事件通知时，可调用 subscribe 方法订阅该流
stream-removed | 有其他用户取消发布了一条流
stream-published | 本地流已发布，可在页面中播放该流
stream-subscribed | 远端流已订阅，可在页面中播放该流
mute-video | 流的 video 被 mute
unmute-video | 流的 video 被取消 mute
mute-audio | 流的 audio 被 mute
unmute-audio | 流的 audio 被取消 mute
screenshare-stopped | 屏幕共享已被手动停止，当收到此事件通知时，需调用 unpublish 方法取消发布本地流
connection-state-change | 当 URTC client 与服务器的连接状态变化时，会由此事件通知。特别地，当因网络问题导致连接断开时，sdk 将在5-15秒内尝试自动重连，此时将收到内容为 `{previous: "OPEN", current: "RECONNECTING"}` 的通知，表示开始重连，若重连成功，将收到内容为 `{previous: "RECONNECTING", current: "OPEN"}` 的通知，若不能重连成功，将收到内容为 `{previous: "RECONNECTING", current: "CLOSED"}` 的通知，表示重连失败，此时需要依次调用 leaveRoom 和 joinRoom 以重新进入房间。`注意，断线重连后，对于已发布或订阅的流会触发下面的 stream-reconnected 流的重连事件，请处理该事件，对流进行重新播放`
kick-off | 当前用户被踢出了房间。URTC 限制了多设备同时登录，同一用户（userId）不可同时在多处加入房间，即当同一用户（userId）分别在利用两个设备（譬如电脑、手机等）先后加入房间时，前一个加入房间的设备将在后一个加入房间时收到此事件的通知，此时业务层可提示用户。
network-quality | 报告本地用户的上下行网络质量。每 1 秒触发一次，报告本地用户当前的上行和下行网络质量。`该功能目前处于实验阶段，网络质量评分仅供参考。部分浏览器无法获取网络质量数据，评分仅有1，6两值，如 Edge 79 以下等。`
stream-reconnected | 当发布/订阅流断开时，会自动重连，发布流会被重新发布，订阅流会被重新订阅，完成后会触发此事件，请注意在此事件的回调函数中更新业务代码中的缓存
record-notify | 当房间内开启了录制任务，那么录制任务的成功开启或异常中止，都将通过此事件进行通知，业务上可根据此通知来提示用户录制任务相应的状态
relay-notify | 当房间内开启了转推任务，那么转推任务的成功开启或异常中止，都将通过此事件进行通知，业务上可根据此通知来提示用户转推任务相应的状态
volume-indicator | 当通过 enableAudioVolumeIndicator 方法开启了远端流音量指示器，那么可以通过此通知来获取各远端流的当前音量
error-notify | 当房间内有错误时，将通过此方法进行通知
player-status-change | 当流的音视频播放状态变化时，将通过此方法进行通知。注：频繁的 DOM 操作可能会导致播放器被浏览器暂停。为了避免这种情况，需要侦听该事件，并尝试调用 resume 方法恢复播放该流
### 9. off 方法
解除绑定事件的监听函数，示例代码：
```js
client.off(EventType, Listener)
```
#### 参数说明
- EventType: 参见 on 方法
- Listener: 为调用 on 方法时绑定的监听函数
### 10. play 方法
播放一条流的音视频，示例代码：
```js
client.play(PlayOptions, callback)
```
#### 参数说明
- PlayOptions: object 类型，必传，详细类型说明如下
```js
{
streamId: string, // 必填，发布/订阅流的 ID，特别地，对于调用预览方法时的视频，可通过填写 'preview' 进行播放
container: HTMLElement | string, // 必填，指定音视频嵌入的容器元素，或该容器元素的 ID，容器元素一般为一个指定了宽高的 div 元素
mute?: boolean, // 选填，是否进行静音播放，注：由于部分浏览器的限制，播放带声音的音视频时，必须以手势触发，但也可以通过进行静音播放来绕过此限制，此处设置 mute 为 true 时，即为静音播放。不填时，默认为 false
mirror?: boolean, // 选填，播放视频时是否进行镜像翻转，特别地，在播放本地流，且发布本地流时指定的为前置摄像头时，将不受此项影响，直接为镜像翻转。不填时，默认为 false
fit?: VideoFitType // 选填，指定视频播放时的显示模式，VideoFitType 值为 'cover' | 'contain' 两种
controls?: "auto" | "show" | "hide" // 选填，设置播放时内部使用的