urtc-sdk

v1.8.9

Published

a year ago

UCloud RTC javascript SDK

Downloads

0High
0Medium
0Low

UCloud RTC URTC UCLoudRTC javascript sdk

UCloudRTC Web SDK API 手册

UCloudRTC 包含以下方法、类或对象：

注：想要了解使用此 SDK 的简单步骤，请查看使用说明

一、Client 类

Client 类包含以下方法：

1. 构造函数

用于创建一个 URTC Client 对象，示例代码：

new Client(AppId, Token, ClientOptions);

参数说明

AppId: string 类型, 必传，可从 UCloud 控制台查看
Token: string 类型, 必传，需按规则生成，测试阶段，可使用 generateToken 临时生成
ClientOptions: object 类型, 选传，类型说明如下

{
  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 方法

加入房间，示例代码：

client.joinRoom(RoomId, UserId, onSuccess, onFailure)

参数说明

RoomId: string 类型，必传，房间号
UserId: string 类型，必传，用户ID
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(Users, Streams) {}

函数参数 Users 为返回值，User 类型的数组，代表当前房间内已有的其他用户的信息，User 类型说明见 User；函数参数 Streams 为返回值，Stream 类型的数组，代表当前房间内其他用户正在发布的流。Stream 类型说明见 Stream

注：当加入房间成功后，当前房间内已有的其他用户的信息以及正在发布的流，都会分别由 user-added 和 stream-added 事件再进行通知。如需订阅正在发布的流，建议在 stream-added 事件函数中统一处理，此处 onSuccess 函数的参数 Users 和 Streams 数据仅用于展示。

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

3. leaveRoom 方法

离开房间，示例代码：

client.leaveRoom(onSuccess, onFailure)

参数说明

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

4. publish 方法

发布本地流，自 1.4.0 版本开始支持同时发布两条流（且摄像头，屏幕共享各一条，不可同时为同一类），示例代码：

client.publish(PublishOptions, onFailure)

参数说明

PublishOptions: object 类型，选传，类型说明如下

{
  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 。此外，对于推流时所传参数的生效将采用此类优先级：mediaStream > file > filePath > video = screen；即用户指定媒体流（MediaStream）时，该媒体流将被发布，不再考虑其他情况生成的流；若指定了 file ，而没指定媒体流（MediaStream），那么将用 file 生成图片媒体流并被发布，依次类推。 file 和 filePath 参数说明，请参见 switchImage 接口的参数说明。

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Error) {}

Error 为错误信息

可能的错误名称（即 error.name）有：
AbortError［中止错误］尽管用户和操作系统都授予了访问设备硬件的权利，而且未出现可能抛出NotReadableError异常的硬件问题，但仍然有一些问题的出现导致了设备无法被使用。
NotAllowedError［拒绝错误］用户拒绝了当前的浏览器实例的访问请求；或者用户拒绝了当前会话的访问；或者用户在全局范围内拒绝了所有媒体访问请求。
NotFoundError［找不到错误］找不到满足请求参数的媒体类型。
NotReadableError［无法读取错误］尽管用户已经授权使用相应的设备，操作系统上某个硬件、浏览器或者网页层面发生的错误导致设备无法被访问。
OverconstrainedError［无法满足要求错误］指定的要求无法被设备满足。

5. unpublish 方法

取消发布本地流，示例代码：

client.unpublish(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，选传，不传时，若仅有一条本地流，那么该流将被取消发布，若有两条本地流，那么最早发布的那条本地流将被取消发布
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(Stream) {}

函数参数 Stream 为返回值，object 类型，为流信息，类型说明见 Stream

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

6. subscribe 方法

订阅远端流，注：订阅的远端流如果有音频时，可能存在播放问题，请查看关于浏览器的自动播放问题的说明及处理，示例代码：

client.subscribe(StreamId, onFailure)

参数说明

StreamId: string 类型，必传，为需要订阅的远端流的 sid
onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

7. unsubscribe 方法

取消订阅远端流，示例代码：

client.unsubscribe(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，必传，为需要订阅的远端流的 sid
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(Stream) {}

函数参数 Stream 为返回值，object 类型，为流信息，类型说明见 Stream

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

8. on 方法

给事件绑定监听函数，示例代码：

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' | 'first-key-frame' | 'audio-track-ended' 这些事件可绑定监听函数
Listener: function 类型，事件监听函数
- 当事件类型为 'user-added' | 'user-removed' | 'kick-off' 时，可用 function Listener(User) {} 类型的函数，其中函数的参数类型见 User
- 当事件类型为 'stream-added' | 'stream-removed' | 'stream-published' | 'stream-subscribed' | 'mute-video' | 'unmute-video' | 'mute-audio' | 'unmute-audio' | 'screenshare-stopped' 时，可用 function Listener(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': （异常）表示加流失败
  - '24160': （异常）CDN收流节点不可达，多次重试后仍失败，任务被终止
- 当事件类型为 'volume-indicator' 时（通过 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次的次数限制，服务器拒绝执行（一般不会达到次数限制，可忽略此事件）
  - '3024': 发布（推流）/订阅（拉流）时，若 ICE 建连失败，则会触发该事件，导致 ICE 建连失败的主要原因是客户端的 UDP 端口异常（可能是用户电脑防火墙或路由器防火墙端口限制）引起，具体端口参考端口白名单，可根据此事件提示用户切换网络或检查网络防火墙设置
- 当事件类型为 'player-status-change' 时，可用 function Listener(PlayerStatusEvent) {} 类型的函数，函数的参数为PlayerStatusEvent { type: string, status: string, stream: Stream }，其中 type 的值为 'audio' | 'video'，status 的值为 'playing' | 'paused'，stream 为流信息，参见 Stream
- 当事件类型为 'first-key-frame' 时，可用 function Listener(Stream) {} 类型的函数，其中函数的参数类型见 Stream
- 当事件类型为 'audio-track-ended' 时，可用 function Listener(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 方法恢复播放该流 first-key-frame | 播放流时，完成第一帧视频解码后会触发此事件 audio-track-ended | 本地流的音频被挂起/终止，可能无法恢复，一般需要重新推流，可根据此事件提示用户进行相关操作

9. off 方法

解除绑定事件的监听函数，示例代码：

client.off(EventType, Listener)

参数说明

EventType: 参见 on 方法
Listener: 为调用 on 方法时绑定的监听函数

10. play 方法

播放一条流的音视频，示例代码：

client.play(PlayOptions, callback)

参数说明

PlayOptions: object 类型，必传，详细类型说明如下

{
  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" // 选填，设置播放时内部使用的 <audio> 或 <video> 元素的控制面板的显示或隐藏。"show" 为一直显示，"hide" 为一直隐藏，"auto" 为正常播放时隐藏，没播放时显示，默认为 "auto"
}

关于 VideoFitType 的说明：
cover 模式：优先保证容器被填满。视频尺寸等比缩放，直至整个容器被视频填满。如果视频长宽与容器不同，则视频流会按照容器的比例进行周边裁剪或图像拉伸后填满容器。
contain 模式：优先保证视频内容全部显示。视频尺寸等比缩放，直至视频窗口的一边与容器边框对齐。播放视频流默认使用 cover 模式，屏幕共享默认使用 contain 模式。

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error) {}

Error 为返回值，为空（undefined) 时，说明已执行成功，否则执行失败，此时，播放元素将会打开控制面板，显示播放按钮等操作工具。

注：受浏览器策略影响，在 Chrome 70+ 和 Safari 浏览器上，该方法必须由用户手势触发，请查看关于浏览器的自动播放问题的说明及处理。

11. resume 方法

恢复一条流的音视频播放，该方法一般在调用 play 失败后，提示用户进行手势触发之后调用（该方法需用手势触发）。示例代码：

client.resume(StreamId, callback)

参数说明

StreamId: string 类型，必传，指流的 ID，特别地，恢复播放的流为预览的流时，可传 'preview'。
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error) {}

Error 为返回值，为空（undefined) 时，说明已执行成功，否则执行失败，此时，播放元素将会打开控制面板，显示播放按钮等操作工具。

12. stop 方法

停止播放一条流的音视频。示例代码：

client.stop(StreamId, callback)

参数说明

StreamId: string 类型，必传，指流的 ID，特别地，停止播放的流为预览的流时，可传 'preview'。
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error) {}

Error 为返回值，为空（undefined) 时，说明已执行成功，否则执行失败。

13. muteAudio 方法

关闭流的音频，示例代码：

const result = client.muteAudio(StreamId)

参数说明

StreamId: string 类型，选传，指流的 ID

注：StreamId 不传时，为 mute 第一条发布流的音频，并会通知到其他用户；传时，为 mute StreamId 对应的发布或订阅流的音频，若为订阅流时，只是影响到本地订阅的流的音频，并不是指远端流推送或不推送音频。

返回值说明

result: boolean 类型，成功时为 true，失败时为 false

14. unmuteAudio 方法

启用流的音频，示例代码：

const result = client.unmuteAudio(StreamId)

参数说明

StreamId: string 类型，选传，指流的 ID

注：StreamId 不传时，为 unmute 第一条发布流的音频，并会通知到其他用户；传时，为 unmute StreamId 对应的发布或订阅流的音频，若为订阅流时，只是影响到本地订阅的流的音频，并不是指远端流推送或不推送音频。

返回值说明

result: boolean 类型，成功时为 true，失败时为 false

15. muteVideo 方法

关闭流的视频，示例代码：

const result = client.muteVideo(StreamId)

StreamId: string 类型，选传，指流的 ID

注：StreamId 不传时，为 mute 第一条发布流的视频，并会通知到其他用户；传时，为 mute 对应的发布或订阅流的视频，若为订阅流时，只是影响到本地订阅的流的视频，并不是指远端流推送或不推送视频。

返回值说明

result: boolean 类型，成功时为 true，失败时为 false

16. unmuteVideo 方法

启用流的视频，示例代码：

const result = client.unmuteVideo(StreamId)

StreamId: string 类型，选传，指流的 ID

注：StreamId 不传时，为 unmute 发布流的视频，并会通知到其他用户；传时，为 unmute 对应的发布或订阅流的视频，若为订阅流时，只是影响到本地订阅的流的视频，并不是指远端流推送或不推送视频。

返回值说明

result: boolean 类型，成功时为 true，失败时为 false

startRecording 方法 - 已废弃

开启录制，请使用 startRecord

client.startRecording(RecordOptions, onSuccess, onFailure)

参数说明

RecordOptions: object 类型，必传，录制的配置信息，类型说明如下

{
  bucket: string  // 必传，存储的 bucket, URTC 使用 UCloud 的 UFile 产品进行在存储，相关信息见控制台操作文档
  region: string  // 必传，存储服务所在的地域
  uid?: string,                         // 选传，指定某用户的流作为主画面，不传时，默认为当前开启录制的用户的流作为主画面
  mainViewType?: 'screen' | 'camera',   // 选传，指定主画面使用的流的媒体类型（当同一用户推多路流时），不传时，默认使用 camera
  mixStream?: MixStreamOptions // 选传，混流的相关配置，无混流时，不用填写
  waterMark?: WaterMarkOptions // 选传，水印的相关配置，不需要添加水印时，不用填写
  relay?: RelayOptions         // 选传，转推相关配置，不需要转推时，不用填写
}

WaterMarkOptions: object 类型，选传，添加的水印相关配置，类型说明如下

{
  position?: 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' // 选传，指定水印的位置，前面四种类型分别对应 左上，左下，右上，右下，默认 'left-top'
  type?: 'time' | 'image' | 'text' // 选传，水印类型，分别对应时间水印、图片水印、文字水印，默认为 'time'
  remarks?:  string,   // 选传，水印备注，当为时间水印时，传空字符串，当为图片水印时，此处需为图片的 URL（此时必传），当为文字水印时，此处需为水印文字
}

MixStreamOptions: object 类型，选传，混流相关配置，类型说明如下

{
  width?: number,      // 选传，设置混流后视频的宽度，不传时，默认为 1280
  height?: number,     // 选传，设置混流后视频的高度，不传时，默认为 720
  template?: number,   // 选传，指定混流布局模板，可使用 1-9 对应的模板，默认为 1
  isAverage?: boolean, // 选传，是否均分，均分对应平铺风格，不均分对应垂直风格，默认为 true
}

RelayOptions: object 类型，选传，转推相关配置，类型说明如下

{
  time?: number,        // 转推开启时间的Unix时间戳（单位：秒），不填时，将默认使用当前时间的Unix时间戳
  fragment: number,     // 切片大小（单位：秒），默认 60s
}

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(Record) {}

函数参数 Record 为返回值，object 类型，为流信息，类型说明如下

{
  FileName: string  // 录制到的文件的名称
  RecordId: string  // 录制 ID
}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

stopRecording 方法 - 已废弃

结束录制，请使用 stopRecord

client.stopRecording(onSuccess, onFailure)

参数说明

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

17. getUser 方法

获取本地用户的信息，示例代码：

const result = client.getUser()

返回值说明

result: User 类型，类型说明如下

User:

{
  uid: string   // 为用户ID
}

18. getUsers 方法

获取当前加入房间的远端用户的信息，示例代码：

const result = client.getUsers()

返回值说明

result: User 类型的数组，User 类型说明见 User

19. getStream 方法

获取单条发布（本地）/订阅（远端）流的信息，示例代码：

const result = client.getStream(StreamId)

参数说明

StreamId: string 类型，选传，流的 ID，当不传时，默认返回第一条发布流（当有两条发布流时）

返回值说明

result: Stream 类型或 undefined（未找到对应流），Stream 类型说明如下

Stream:

{
  sid: string                     // 流ID
  uid: string                     // 对应的用户的ID
  type: 'publish' | 'subscribe'   // 流类型，为 publish 和 subscribe 两种，分别对应本地流和远端流
  audio: boolean                  // 是否包含音频
  video: boolean                  // 是否包含视频
  muteAudio: boolean              // 音频轨道是否禁用，已废弃
  muteVideo: boolean              // 视频轨道是否禁用，已废弃
  audioMuted: boolean             // 音频本地是否已 mute，本地/发布流 mute 时，将不推音频数据到服务器，远端/订阅流 mute 时，将不从服务器拉取音频数据
  videoMuted: boolean             // 视频本地是否已 mute，本地/发布流 mute 时，将不推视频数据到服务器，远端/订阅流 mute 时，将不从服务器拉取视频数据
  sourceAudioMuted?: boolean      // 音频源是否已 mute，只针对远端流有效（本地流无此属性），代表远端流的音频源是否已 mute（不推数据）
  sourceVideoMuted?: boolean      // 视频源是否已 mute，只针对远端流有效（本地流无此属性），代表远端流的视频源是否已 mute（不推数据）
  mediaType?: 'camera' | 'screen' // 流的媒体类型，目前存在两种媒体类型 'camera' 及 'screen'，同一用户可发布的各类型的流只能存在一个，以此来区分不同媒体类型的发布/订阅流
  mediaStream?: MediaStream       // 使用的媒体流，可用 HTMLMediaElement 进行播放，此属性的值可能为空，当流被正常发布或订阅流，此值有效
  previewId?: string              // 通过 createStream 方法创建的流将包含此字段，且未发布状态时会与 sid 相同，当流被发布之后 sid 将被替换为服务器生成的流 ID，而 previewId 仍为用户自定义的 streamId
}

注：原 muteAudio 和 muteVideo 已废弃，请使用 audioMuted 和 videoMuted，以及 sourceAudioMuted 和 sourceVideoMuted 更准确的判断流的 mute 状态

20. getLocalStreams 方法

获取所有发布（本地）流的信息（ 1.4.0 及以上版本支持），示例代码：

const result = client.getLocalStreams()

返回值说明

result: Stream 类型的数组，Stream 类型说明见 Stream

21. getRemoteStreams 方法

获取所有订阅流（远端流）的信息（ 1.4.0 及以上版本支持），示例代码：

const result = client.getRemoteStreams()

返回值说明

result: Stream 类型的数组，Stream 类型说明见 Stream

getStreams 方法 - 已废弃

获取订阅流（远端流）的信息，1.4.0 及以上版本请使用 getRemoteStreams

22. getMediaStream 方法

获取发布（本地）/ 订阅（远端）流对应的媒体流（ 1.4.0 及以上版本支持），获取后，可通过 HtmlMediaElement（如：video）进行播放，建议直接利用 HtmlMediaElement 对本地流进行播放时，需将 HtmlMediaElement 的 muted 属性设为 true，否则会听到自己的声音，感觉像回音，示例代码：

const result = client.getMediaStream(StreamId)

参数说明

StreamId: string 类型，选传，流的 ID，当不传时，默认返回第一条发布流（当有两条发布流时），传时，返回 StreamId 对应的发布或订阅流的的媒体流

返回值说明

result: MediaStream 类型，类型说明见 MediaStream

getLocalMediaStream 方法 - 已废弃

获取发布流对应的媒体流，1.4.0 及以上版本请使用 getMediaStream

getRemoteMediaStream 方法 - 已废弃

获取订阅流对应的媒体流，1.4.0 及以上版本请使用 getMediaStream

23. getMicrophones 方法

获取麦克风设备，示例代码：

注：若站点未经过用户授权浏览器使用麦克风设备，可能会弹出提示要求用户进行授权

client.getMicrophones(GetDevicesOptions, onSuccess, onFailure)

参数说明

GetDevicesOptions 参见 GetDevicesOptions
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(MediaDeviceInfos) {}

函数参数 MediaDeviceInfos 为返回值，为 MediaDeviceInfo 类型的数组，点击 MediaDeviceInfo 查看 MediaDeviceInfo 详情

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

24. getCameras 方法

获取摄像头设备，示例代码：

注：若站点未经过用户授权浏览器使用摄像头设备，可能会弹出提示要求用户进行授权

client.getCameras(GetDevicesOptions, onSuccess, onFailure)

参数说明

GetDevicesOptions 参见 GetDevicesOptions
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(MediaDeviceInfos) {}

函数参数 MediaDeviceInfos 为返回值，为 MediaDeviceInfo 类型的数组，点击 MediaDeviceInfo 查看 MediaDeviceInfo 详情

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

25. getLoudspeakers 方法

获取音响/声音输出设备，示例代码：

client.getLoudspeakers(onSuccess, onFailure)

参数说明

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(MediaDeviceInfos) {}

函数参数 MediaDeviceInfos 为返回值，为 MediaDeviceInfo 类型的数组，点击 MediaDeviceInfo 查看 MediaDeviceInfo 详情

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

26. setVideoProfile 方法

设置视频的 profile（通过 getSupportProfileNames 获取到视频质量的值，不设置时，默认为 "640*480"）限制 client 使用的视频大小、帧率、带宽等。示例代码：

client.setVideoProfile(Profile, onSuccess, onFailure)

参数说明

Profile 为 string 或 CustomVideoProfile 或 VideoProfileOptions 类型，必传，类型说明如下
- 为 string 类型时，使用预定义的视频 Profile（可用 getSupportProfileNames 获取预定义的 Profile），如 client.setVideoProfile('640*480', onSuccess, onFailure);
- 为 CustomVideoProfile 时，使用用户自定义的视频 Profile，如 client.setVideoProfile({width:640, height:480, framerate:20, bitrate:500}, onSuccess, onFailure)，具体参见下面说明;
- 为 VideoProfileOptions 时，对指定的本地（预览）流设置视频 Profile，如 client.setVideoProfile({streamId: 'xxx', profile: '640*480'}, onSuccess, onFailure)，具体参见下面说明;

CustomVideoProfile 自定义视频 Profile:

{
  width: number,      // 必填，指定宽
  height: number,     // 必填，指定高
  framerate: number,  // 必填，指定帧率
  bitrate: number,    // 必填，指定码率
}

VideoProfileOptions 指定流的视频 Profile:

{
  streamId: string                      // 必填，本地流的流 ID (sid)
  profile: string | CustomVideoProfile  // 必填，指定 video profile，可用预定义或自定义的 Profile
}

注：
参数为预定义 Profile 或 CustomVideoProfile 时，为全局生效，后续创建的流的视频都将设置为此 Profile。
屏幕共享流创建后，无法变更 video profile，故请在创建前通过更改全局的 Profile。
参数为 VideoProfileOptions 类型时，只对指定流ID的流生效。
VideoProfileOptions 中指定流 ID 在 1.6.12 及以下版本时需使用 previewId 作为属性名，1.6.13 及以上版本也可使用 previewId 但更建议使用 streamId。

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

27. switchDevice 方法

当发布（本地麦克风、摄像头）流已经发布，可通过此方法在不中断当前发布的情况下，用指定的音视频设备采集的音视频流代替正在发布的音视频流，示例代码：

注： 1、在部分华为手机的微信浏览器中，播放音效时不支持切换麦克风

client.switchDevice(SwitchDeviceOptions, onSuccess, onFailure)

参数说明

SwitchDeviceOptions: object 类型，必传，详细类型说明如下

{
  streamId?: string       // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  type: 'audio' | 'video' // 必填，指定音频或视频设备
  deviceId: string        // 必填，设备 ID
}

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

可能的错误信息有：参见

28. switchScreen 方法

当屏幕共享流已经发布，可通过此方法在不中断当前发布的情况下，用屏幕共享来代替正在发布的屏幕共享流，示例代码：

client.switchScreen(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，选传，不传时，为第一条发布流（请确保第一条发布为屏幕共享流）
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

29. switchImage 方法

当本地流已经发布，可通过此方法在不中断当前发布的情况下，用静态图片来代替正在发布的视频流，示例代码：

client.switchImage(SwitchImageOptions, onSuccess, onFailure)

参数说明

SwitchImageOptions: object 类型，必传，详细类型说明如下

{
  streamId?: string       // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  file?: File             // 选填，指（图片）文件，更多请参考下面的备注
  filePath?: string       // 选填，指图片文件的网络路径（URL)，支持以下图片格式：PNG，JPEG 以及浏览器支持的其他图片格式，注：当图片文件为其他站点的网络文件时，可能会有跨域访问问题
}

注：
file 和 filePath 两者不可同时为空，至少填一项。特别地，若都填时，将优先使用 file 的值。
file 请参考 File 对象，一般可通过 <input type="file" accept="image/*"></input> 来上传来获取

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess() {}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

30. getAudioVolume 方法

获取音频的音量，返回值范围 [0,100]，示例代码：

注： 1、在部分华为手机的微信浏览器中，不支持该方法

client.getAudioVolume(StreamId)

参数说明

StreamId: string 类型，选传，本地或远端流的 ID 即 Stream 的 sid 属性值，当不传时，默认获取第一条本地流的音量大小

31. setAudioVolume 方法

设置音频的音量，可设置的音量范围 [0,100]，示例代码：

注： 1、在部分华为手机的微信浏览器中，不支持该方法

client.setAudioVolume(AudioVolumeOptions, callback)

参数说明

AudioVolumeOptions: object 类型，必传，详细类型说明如下

{
  streamId?: string   // 选填，发布/订阅流的 ID，不填时，为第一条发布流
  element?: HTMLMediaElement // 仅当为订阅（远端）流，且通过直接将 mediaStream 赋值给 element.srcObject 属性进行播放时必填该 element。若为发布（本地）流，或通过 play 方法进行播放的订阅（远端）流时，不需要填写。
  volume: number      // 必填，音量大小，取值范围 [0, 100]
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

32. getAudioStats 方法

获取流的音频状态，示例代码：

client.getAudioStats(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，选传，本地或远端流的 ID 即 Stream 的 sid 属性值，当不传时，默认获取第一条本地流的音频状态
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(AudioStats) {}

函数参数 AudioStats 为返回值，为 object 类型，类型说明如下：

{
  br: number        // 码率
  lostpre: number   // 丢包率
  vol: number       // 声音大小
  mime: string      // 编码格式，固定为 opus
}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

33. getVideoStats 方法

获取流的视频状态，示例代码：

client.getVideoStats(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，选传，本地或远端流的 ID 即 Stream 的 sid 属性值，当不传时，默认获取第一条本地流的视频状态
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(VideoStats) {}

函数参数 VideoStats 为返回值，为 object 类型，类型说明如下：

{
  br: number        // 码率
  lostpre: number   // 丢包率
  frt: number       // 帧率
  w: number         // 视频宽度
  h: number         // 视频高度
  mime: string      // 编码格式，'vp8' 或 'h264'
}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

34. getNetworkStats 方法

获取流的网络状态，示例代码：

client.getNetworkStats(StreamId, onSuccess, onFailure)

参数说明

StreamId: string 类型，可选，本地或远端流的 ID 即 Stream 的 sid 属性值，当不传时，默认获取第一条本地流的网络状态
onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(NetworkStats) {}

函数参数 NetworkStats 为返回值，为 object 类型，类型说明如下：

{
  rtt: number   //  往返时延，单位 ms
}

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

35. preloadEffect 方法

预加载音效资源，示例代码：

client.preloadEffect(EffectId, FilePath, callback)

参数说明

EffectId: number 类型，必传，指音效资源 ID，须唯一，用于区分不同的音效资源
FilePath: string 类型，必传，指音效文件的路径（URL)，支持以下音频格式：MP3，AAC 以及浏览器支持的其他音频格式。此外，音效文件不应过大，否则可能会影响通信的流畅性，注：当音效文件为其他站点的网络文件时，可能会有跨域访问问题
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

36. unloadEffect 方法

卸载音效资源，示例代码：：

client.unloadEffect(EffectId)

参数说明

EffectId: number 类型，必传，指音效资源 ID，须唯一，用于区分不同的音效资源

37. playEffect 方法

播放音效，示例代码：

注： 1、在部分华为手机的微信浏览器中，播放音效时会替换麦克风声音，不能同时发送2类声音。

client.playEffect(EffectOptions, callback)

参数说明

EffectOptions: object 类型，必传，详细类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  effectId: number    // 必填，音效资源 ID
  filePath?: string   // 选填，音效文件的路径，当音效文件已经使用 preloadEffect 进行预加载后，可不填此项
  loop?: boolean      // 选填，是否循环播放音效，默认不循环
  playTime?: number   // 选填，音效从 playTime 秒处开始播放，默认为0，即从头开始
  replace?: boolean   // 选填，是否替换当前音轨，即只使用音效，不混音，默认不替换
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

38. pauseEffect 方法

暂停播放音效，示例代码：

注： 1、在部分华为手机的微信浏览器中，不支持该方法。

client.pauseEffect(EffectOptions, callback)

参数说明

EffectOptions: object 类型, 必传，详细的类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  effectId: number    // 必填，音效资源 ID
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

39. resumeEffect 方法

恢复播放音效，示例代码：

注： 1、在部分华为手机的微信浏览器中，不支持该方法。

client.resumeEffect(EffectOptions, callback)

参数说明

EffectOptions: object 类型, 必传，详细的类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  effectId: number    // 必填，音效资源 ID
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

40. stopEffect 方法

停止播放音效，示例代码：

注： 1、在部分华为手机的微信浏览器中，停止音效时会切换回麦克风声音。

client.stopEffect(EffectOptions, callback)

参数说明

EffectOptions: object 类型, 必传，详细的类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  effectId: number    // 必填，音效资源 ID
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

41. setEffectVolume 方法

设置正在播放的音效的音量大小，示例代码：

注： 1、在部分华为手机的微信浏览器中，不支持该方法

client.setEffectVolume(EffectVolumeOptions, callback)

参数说明

EffectVolumeOptions: object 类型, 必传，详细的类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  effectId: number    // 必填，音效资源 ID
  volume: number      // 必填，音量大小，取值范围 [0, 100]
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

42. snapshot 方法

可将指定的发布（本地）/订阅（远端）流截屏用于页面展示，或下载截屏图片，示例代码：

client.snapshot(SnapshotOptions, onSuccess, onFailure);

注：为保证 API 的易用性，此 API 自 1.4.0 版本进行了重新设计，由于无法做到向前（ 1.3.7 - 1.3.10 版本）兼容，请使用 1.3.7 - 1.3.10 版本的用户调整调用方式。

参数说明

SnapshotOptions: object 类型，选传，详细的类型说明如下

{
  streamId?: string             // 选填，发布/订阅流的 ID，不填时，为第一条发布流，
  download?: boolean 或 string  // 选填，是否要下载图片，或指定下载图片的文件名，传 true 时，可将截屏下载到本地（文件名自动生成），传非空字符串时，将会以该字符串命名下载时保存到本地的图片名，不传或传 false 或空字符串时，都将不下载图片
}

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(ImgString) {}

ImgString: string 类型，是图片转化的 base64 编码的 Data URLs，可将其赋值给 Image 元素 - 详见 HTMLImageElement 的 src 属性。

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

43. startPreviewing 方法

启动预览，示例代码：

client.startPreviewing(DeviceOptions, onSuccess, onFailure);

参数说明

DeviceOptions: object 类型，选传，详细的类型说明如下

{
  audio: boolean          // 必填，指定是否使用麦克风设备
  video: boolean          // 必填，指定是否使用摄像头设备
  facingMode?: FacingMode // 选填，在移动设备上，可以设置该参数选择使用前置或后置摄像头，其中，FacingMode 为 'user'（前置摄像头）或 'environment'（后置摄像头）
  microphoneId?: string   // 选填，指定使用的麦克风设备的ID，可通过 getMicrophones 方法查询获得该ID，不填时，将使用默认麦克风设备
  cameraId?: string       // 选填，指定使用的摄像头设备的ID，可以通过 getCameras 方法查询获得该ID，不填时，将使用默认的摄像头设备
}

onSuccess: function 类型，选传，方法调用成功时执行的回调函数，函数说明如下

function onSuccess(result) {}

result: MediaStream 类型，类型说明见 MediaStream，可通过 HtmlMediaElement（如：video）进行播放
onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

可能的错误信息有：参见

44. stopPreviewing 方法

停止预览，示例代码：

client.stopPreviewing();

deviceDetection 方法 - 已转移

此 API 已转移至 UCloudRTC 中，详见 UCloudRTC.deviceDetection

45. replaceTrack 方法

替换发布流的音频轨道或视频轨道，可在保持发布流的发布状态下，切换音频或视频，示例代码：

client.replaceTrack(ReplaceTrackOptions, callback)

参数说明

ReplaceTrackOptions: object 类型, 必传，详细的类型说明如下

{
  streamId?: string   // 选填，发布（本地）流的 ID，不填时，为第一条发布流
  track: MediaStreamTrack   // 必填，需要替换的新的音轨或视轨，MediaStreamTrack 参见下面注释
  retain?: boolean    // 选填，是否需要保持被替换的老的音轨或视轨可用，一般情况下，如果后面需要切换回老的音轨或视轨，建议保持其可用，否则可不用保持
}

MediaStreamTrack 类型，类型说明见 MediaStreamTrack

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Err, OldTrack) {}

Err 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

OldTrack 为返回值，MediaStreamTrack 类型，不为空时，值为被替换的音频轨道或视频轨道

startMix 方法 - 已废弃

开启录制，请使用 startRecord，开启转推，请使用 startRelay

client.startMix(MixOptions, callback)

参数说明

MixOptions: object 类型, 必传，详细的类型说明如下

{
  type?: MixType  // 选传，MixType 为 'relay' | 'record' | 'relay-and-record' 其中之一，分别代表 '转推' | '录制' | '录制并转推'，不传时，默认为 'record' 录制。
  bucket?: string  // 当 type 为 '录制' 和 '录制并转推时'，必传，存储的 bucket, URTC 使用 UCloud 的 UFile 产品进行在存储，相关信息见控制台操作文档
  region?: string  // 当 type 为 '录制' 和 '录制并转推时'，必传，存储服务所在的地域

  pushURL?: string[]          // 当 type 为 '转推' 和 '录制并转推时'，必传，为转推的 URL 的列表
  layout?: MixLayoutOptions   // 选传，录制/转推后的视频的布局设置，类型说明见下面的 MixLayoutOptions 类型，不传时，将使用默认值
  audio?: MixAudioOptions     // 选传，录制/转推后的音频的设置，类型说明见下面的 MixAudioOptions 类型，不传时，将使用默认值
  video?: MixVideoOptions     // 选传，录制/转推后的视频的设置，类型说明见下面的 MixVideoOptions 类型，不传时，将使用默认值

  width?: number      // 选传，录制转推后的视频的宽度，不传时，默认为 1280
  height?: number     // 选传，录制转推后的视频的高度，不传时，默认为 720
  backgroundColor?: BackgroundColorOptions  // 选传，背景色，类型说明见下面的 BackgroundColorOptions 类型，不传时，默认为 #000 黑色

  waterMark?: WaterMarkOptions  // 选传，水印设置，类型说明见下面的 WaterMarkOptions 类型，不传时将不添加水印

  streams?: MixStream[]         // 选传，指定需要混合的流，类型说明见下面的 MixStream 类型
}

MixLayoutOptions 类型，类型说明

{
  type: MixLayoutType           // MixLayoutType 为 'flow' | 'main' | 'custom'，分别代表：1 平铺风格，流式(均分)布局；2 垂直风格，讲课模式，主讲人占大部分屏幕，其他人小屏居于底部；3 自定义布局；4 模板自适应一；5 模板自适应二；6 单画面；默认为 'flow'
  custom?: Object[]             // type 为 'custom'时，自定义布局填在custom里，格式参照RFC5707 Media Server Markup Language (MSML)
  mainViewUId?: string          // 指定某用户的流为主画面，默认为当前用户
  mainViewType?: MainViewType   // 主画面类型，'screen' | 'camera'，默认为用户发布的 'camera'
}

MixAudioOptions 类型，类型说明

{
  codec: MixAudioCodec    // 音频的编码格式，MixAudioCodec 为 'aac'，不传时默认为 'aac'
}

MixVideoOptions 类型，类型说明

{
  codec: MixVideoCodec    // 视频的编码格式，MixVideoCodec 为 'h264' | 'h265' 其中之一，默认为 'h264'
  quality?: H264Quality   // 视频质量，当 codec 为 h264 时，此项起作用，H264Quality 为 'B' | 'CB' | 'M' | 'E' | 'H' 其中之一，默认为 'CB'
  frameRate?: number      // 视频帧率，可选值 6 | 12 | 15 | 24 | 30 | 48 | 60，默认为 15
  bitRate?: number        // 视频码率，默认为 500
}

BackgroundColorOptions 类型，类型说明

{
  r: number   // r 通道值，默认为 0
  g: number   // g 通道值，默认为 0
  b: number   // b 通道值，默认为 0
}

WaterMarkOptions: object 类型，选传，添加的水印相关配置，类型说明如下

{
  position?: 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' // 选传，指定水印的位置，前面四种类型分别对应 左上，左下，右上，右下，默认 'left-top'
  type?: 'time' | 'image' | 'text' // 选传，水印类型，分别对应时间水印、图片水印、文字水印，默认为 'time'
  remarks?:  string,   // 选传，水印备注，当为时间水印时，传空字符串，当为图片水印时，此处需为图片的 URL（此时必传），当为文字水印时，此处需为水印文字
}

MixStream: object 类型，选传，添加的水印相关配置，类型说明如下

{
  uid: string,        // 用户 ID，指定需要混合的流的用户ID（远端用户）
  mediaType: string   // 流的媒体类型，指定需要混合的流的媒体类型，有 'camera' 和 'screen' 两种可选，默认为 'camera'
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，MixResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

MixResult: object 类型，类型说明如下

{
  MixId?: string        // 混流 ID
  FileName?: string     // 混流文件名
  Type?: MixType        // 混流类型，MixType 为 'relay' | 'record' | 'relay-and-record'，注：queryMix 操作时会返回此项
  PushURL?: string[]    // 转推的 URL 列表
}

stopMix 方法 - 已废弃

结束录制，请使用 stopRecord 结束转推，请使用 stopRelay

client.stopMix(StopMixOptions, callback)

参数说明

StopMixOptions: object 类型, 必传，详细的类型说明如下

{
  type?: MixType      // 选传，MixType 为 'relay' | 'record' | 'relay-and-record' 其中之一，分别代表 '转推' | '录制' | '录制并转推'，不传时，默认为 'record'
  pushURL?: string[]  // 字符串数组，若 type 为 relay 或 relay-and-record 时，可用此参数指定需要停止转推的 URL，或留空停止对所有 URL 的转推
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，MixResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

46. queryMix 方法

查询房间内是否有正在开启的录制或转推任务，示例代码：

client.queryMix(callback)

参数说明

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，MixResult 类型，此值为执行结果，若 Result 中的 MixId 为空（undefined），则说明房间没有开启录制/转推任务。

addMixStreams 方法 - 已废弃

向录制的音视频中添加流，请使用 updateRecordStreams 向转推的音视频中添加流，请使用 updateRelayStreams

client.addMixStreams(AddMixStreamsOptions, callback)

参数说明

AddMixStreamsOptions: object 类型, 必传，详细的类型说明如下

{
  streams: MixStream[]  // 必传，指定需要混合的新流
}

点击 MixStream 见详细的类型说明

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，MixResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

removeMixStreams 方法 - 已废弃

移除录制中的音视频中部分流，请使用 updateRecordStreams 移除转推中的音视频中部分流，请使用 updateRelayStreams

client.removeMixStreams(RemoveMixStreamsOptions, callback)

参数说明

RemoveMixStreamsOptions: object 类型, 必传，详细的类型说明如下

{
  streams: MixStream[]  // 必传，指定需要混合的新流
}

点击 MixStream 见详细的类型说明

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，MixResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

47. setRole 方法

设置用户角色，本方法仅适用于直播模式（live 模式），加入房间前/后，都可通过调用本方法设置用户角色。示例代码：

const result = client.setRole(Role)

参数说明

Role: "pull" | "push" | "push-and-pull", // 设置用户角色，可设 "pull" | "push" | "push-and-pull" 三种角色，分别对应拉流、推流、推+拉流，默认为 "push-and-pull"，特别地，当房间类型为连麦模式（rtc）时，此参数将被忽视，会强制为 "push-and-pull"，即推+拉流

返回值说明

result: boolean 类型，成功时为 true，失败时为 false

48. startRecord 方法

开启录制，示例代码：

client.startRecord(StartRecordOptions, callback)

参数说明

StartRecordOptions: object 类型, 必传，详细的类型说明如下

{
  bucket: string      // 必传，存储的 bucket, URTC 使用 UCloud 的 UFile 产品进行在存储，相关信息见控制台操作文档
  region: string      // 必传，存储服务所在的地域

  layout?: MixLayoutOptions   // 选传，多路混流时视频的布局设置，类型说明见下面的 MixLayoutOptions 类型，不传时，将使用默认值

  audio?: MixAudioOptions     // 选传，录制后的音频的设置，类型说明见下面的 MixAudioOptions 类型，不传时，将使用默认值
  video?: MixVideoOptions     // 选传，录制后的视频的设置，类型说明见下面的 MixVideoOptions 类型，不传时，将使用默认值

  width?: number      // 选传，录制后的视频的宽度，不传时，默认为 1280
  height?: number     // 选传，录制后的视频的高度，不传时，默认为 720
  backgroundColor?: BackgroundColorOptions  // 选传，背景色，类型说明见下面的 BackgroundColorOptions 类型，不传时，默认为 #000 黑色

  waterMark?: WaterMarkOptions  // 选传，水印设置，类型说明见下面的 WaterMarkOptions 类型，不传时将不添加水印

  streams?: MixStream[]         // 选传，指定需要录制的流，类型说明见下面的 MixStream 类型。不传或传空数组时，会自动添加房间内所有用户的流，如果指定了流，则仅录制指定的流

  outputMode?: MixOutputMode    // 选传，录制时输出模式，MixOutputMode 为字符串，有 'audio-video' | 'audio' 两种可填，分别代表：输出音视频 | 只输出音频，不填时，默认为 'audio-video'

  streamAddMode?: MixStreamAddMode  // 选传，录制时流的添加模式，MixStreamAddMode 为字符串，有 'automatic' | 'manual' 两种可填，分别代表：自动添加（有新流时） | 手动添加，不填时，默认为 'automatic'

  keyUser?: string;             // 选传，用户ID，指定关键用户（userId）不再推流后，录制任务自动关闭，不填时，默认为房间内没有用户推流后录制任务自动关闭
}

MixLayoutOptions 类型，类型说明

{
  type: MixLayoutType           // MixLayoutType 为 'flow' | 'main' | 'custom' | 'customMain' | 'customFlow' | 'single'，分别代表：1 平铺风格，流式（均分）布局；2 垂直风格，讲课模式，主讲人占大部分屏幕，其他人小屏居于右侧或底部；3 自定义布局；4 定制讲课模式布局；5 定制流式（均分）布局；默认为 'flow'；6 单画面布局（只显示主画面，其他不显示）
  custom?: Object[]             // type 为 'custom'时，自定义布局填在custom里，格式参照RFC5707 Media Server Markup Language (MSML)
  mainViewUId?: string          // type 为 'main' 或 'customMain' 时，指定某用户的流为主画面，默认为当前用户
  mainViewType?: MainViewType   // 主画面类型，'screen' | 'camera'，默认为用户发布的 'camera'
}

MixAudioOptions 类型，类型说明

{
  codec: MixAudioCodec    // 音频的编码格式，MixAudioCodec 为 'aac'，不传时默认为 'aac'
}

MixVideoOptions 类型，类型说明

{
  codec: MixVideoCodec    // 视频的编码格式，MixVideoCodec 为 'h264' | 'h265' 其中之一，默认为 'h264'
  quality?: H264Quality   // 视频质量，当 codec 为 h264 时，此项起作用，H264Quality 为 'B' | 'CB' | 'M' | 'E' | 'H' 其中之一，默认为 'CB'
  frameRate?: number      // 视频帧率，可选值 6 | 12 | 15 | 24 | 30 | 48 | 60，默认为 15
  bitRate?: number        // 视频码率，默认为 500
}

注：关于布局风格, 请参见详细的混流说明混流风格

BackgroundColorOptions 类型，类型说明

{
  r: number   // r 通道值，默认为 0
  g: number   // g 通道值，默认为 0
  b: number   // b 通道值，默认为 0
}

WaterMarkOptions: object 类型，选传，添加的水印相关配置，类型说明如下

{
  position?: 'left-top' | 'left-bottom' | 'right-top' | 'right-bottom' // 选传，指定水印的位置，前面四种类型分别对应 左上，左下，右上，右下，默认 'left-top'
  type?: 'time' | 'image' | 'text' // 选传，水印类型，分别对应时间水印、图片水印、文字水印，默认为 'time'
  remarks?:  string,   // 选传，水印备注，当为时间水印时，传空字符串，当为图片水印时，此处需为图片的 URL（此时必传），当为文字水印时，此处需为水印文字
}

MixStream: object 类型，选传，添加的水印相关配置，类型说明如下

{
  uid: string,        // 用户 ID，指定需要混合的流的用户ID（远端用户）
  mediaType: string   // 流的媒体类型，指定需要混合的流的媒体类型，有 'camera' 和 'screen' 两种可选，默认为 'camera'
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明录制任务已成功开启，否则为开启失败，值为开启失败的错误信息

Result 为返回值，RecordResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

RecordResult: object 类型，类型说明如下

{
  Id: string            // 录制 ID
  FileName?: string     // 录制 文件名
}

注：此处若 Error 为空（undefined）时，只代表录制任务已由服务器开启，并不代表已成功录制，当混流服务器接收到了正确的流并成功录制，或有其他错误导致录制失败时，都将会通过 record-notify 事件进行通知。

49. stopRecord 方法

结束录制，示例代码：

client.stopRecord(callback)

参数说明

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误信息

Result 为返回值，RecordResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

50. updateRecordStreams 方法

增加/删除录制的流，示例代码：

client.updateRecordStreams(UpdateMixStreamsOptions, callback)

参数说明

UpdateMixStreamsOptions: object 类型, 必传，详细的类型说明如下

UpdateMixStreamsOptions 类型，类型说明

{
  type: UpdateMixStreamsType    // 必传，操作类型，UpdateMixStreamsType 值为 'add' | 'remove' | 'replace' 之一，分别对应：'add' - 添加新流进行录制/转推，'remove' - 移除录制/转推中的部分流，'replace' - 用新流替换掉正在录制/转推的流，即移除录制/转推中全部的流并添加新流进行录制/转推
  streams: MixStream[]          // 必传，MixStream 类型的数组，可指定需要被添加、移除的流或替换的流
}

MixStream 类型参见 MixStream

注：关于 replace - 替换流，由于是进行全部代替，那么将使用 streams 里的第一条流作为主画面，若在有指定某条流作为主画面的需求，请务必将该流放在 streams 数组中的第一个。

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则为执行失败，值为执行失败的错误信息

Result 为返回值，RecordResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

51. startRelay 方法

开启转推，示例代码：

client.startRelay(StartRelayOptions, callback)

参数说明

StartRelayOptions: object 类型, 必传，详细的类型说明如下

{
  pushURL: string[]           // 必传，为转推到的 RTMP URL 的列表

  layout?: MixLayoutOptions   // 选传，多路混流时视频的布局设置，类型说明见下面的 MixLayoutOptions 类型，不传时，将使用默认值

  audio?: MixAudioOptions     // 选传，转推后的音频的设置，类型说明见下面的 MixAudioOptions 类型，不传时，将使用默认值
  video?: MixVideoOptions     // 选传，转推后的视频的设置，类型说明见下面的 MixVideoOptions 类型，不传时，将使用默认值

  width?: number      // 选传，转推后的视频的宽度，不传时，默认为 1280
  height?: number     // 选传，转推后的视频的高度，不传时，默认为 720
  backgroundColor?: BackgroundColorOptions  // 选传，背景色，类型说明见下面的 BackgroundColorOptions 类型，不传时，默认为 #000 黑色

  waterMark?: WaterMarkOptions  // 选传，水印设置，类型说明见下面的 WaterMarkOptions 类型，不传时将不添加水印

  streams?: MixStream[]         // 选传，指定需要转推的流，类型说明见下面的 MixStream 类型。不传或传空数组时，会自动添加房间内所有用户的流，如果指定了流，则仅转推指定的流

  outputMode?: MixOutputMode    // 选传，转推后输出模式，MixOutputMode 为字符串，有 'audio-video' | 'audio' 两种可填，分别代表：输出音视频 | 只输出音频，不填时，默认为 'audio-video'

  streamAddMode?: MixStreamAddMode  // 选传，转推流的添加模式，MixStreamAddMode 为字符串，有 'automatic' | 'manual' 两种可填，分别代表：自动添加（有新流时） | 手动添加，不填时，默认为 'automatic'

  keyUser?: string;             // 选传，用户ID，指定关键用户（userId）不再推流后，转推任务自动关闭，不填时，默认为房间内没有用户推流后转推任务自动关闭
}

MixLayoutOptions 类型，类型说明

{
  type: MixLayoutType           // MixLayoutType 为 'flow' | 'main' | 'custom' | 'customMain' | 'customFlow' | 'single'，分别代表：1 平铺风格，流式（均分）布局；2 垂直风格，讲课模式，主讲人占大部分屏幕，其他人小屏居于右侧或底部；3 自定义布局；4 定制讲课模式布局；5 定制流式（均分）布局；默认为 'flow'；6 单画面布局（只显示主画面，其他不显示）
  standbyTypes?: MixLayoutType[]    // 指定待切换的布局，针对直播中有切换布局的需求，可在启动时指定需要切换的布局，未指定的无法切换，且最多可指定两种可切换的类型（不包含 type 中指定的，即一次转推任务最多有三种布局可相互切换），多余的将被忽略，譬如 `{ type: 'flow', standbyTypes: ['main', 'customMain', 'customFlow'] }`，那么 standbyTypes 中的 'customFlow' 将会被忽略。特别地，由于 'custom' 的特殊性，待切换的布局中不可包含该类型的布局，若填写，则会被忽略。
  custom?: Object[]             // type 为 'custom'时，自定义布局填在custom里，格式参照RFC5707 Media Server Markup Language (MSML)
  mainViewUId?: string          // type 为 'main' 或 'customMain' 时，指定某用户的流为主画面，默认为当前用户
  mainViewType?: MainViewType   // 主画面类型，'screen' | 'camera'，默认为用户发布的 'camera'
}

注：关于布局风格, 请参见详细的混流说明混流风格

MixAudioOptions 类型说明详见 MixAudiooptions

MixVideoOptions 类型说明详见 MixVideoOptions

BackgroundColorOptions 类型说明详见 BackgroundColorOptions

WaterMarkOptions 类型说明详见 WaterMarkOptions

MixStream 类型说明详见 MixStream

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空（undefined）时，说明转推任务已成功开启，否则为开启失败，值为开启失败的错误信息

Result 为返回值，RelayResult 类型，开启失败时，此值为空，开启成功时，此值为执行结果

RelayResult: object 类型，类型说明如下

{
  Id: string            // 转推 ID
  PushURL?: string[]    // 转推 URL
}

注：此处若 Error 为空（undefined）时，只代表转推任务已由服务器开启，并不代表已成功转推，当混流服务器接收到了正确的流并成功转推，或有其他错误导致转推失败，都将会通过 record-notify 事件进行通知。

52. stopRelay 方法

结束转推，示例代码：

client.stopRelay(callback)

参数说明

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Result 为返回值，RelayResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

53. updateRelayStreams 方法

增加/删除转推的流，示例代码：

client.updateRelayStreams(UpdateMixStreamsOptions, callback)

参数说明

UpdateMixStreamsOptions: object 类型, 必传，详细的类型说明见 UpdateMixStreamsOptions

注：关于 replace - 替换流，由于是进行全部代替，那么将使用 streams 里的第一条流作为主画面，若在有指定某条流作为主画面的需求，请务必将该流放在 streams 数组中的第一个。

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Result 为返回值，RelayResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

54. updateRelayPushURL 方法

增加/删除转推地址，示例代码：

client.updateRelayPushURL(UpdateRelayPushURLOptions, callback)

参数说明

UpdateRelayPushURLOptions: object 类型, 必传，详细的类型说明：

{
  type: UpdateRelayPushURLType, // 必传，值为 'add' | 'remove'，分别对应 增加 | 删除 转推地址。
  pushURL: string[]             // 必传，转推地址（转推到的 URL）的列表，指定需要新增或删除转推的 URL；删除时如果留空会停止对所有 URL 的转推
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Result 为返回值，RelayResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

55. updateRelayLayout 方法

更换转推的布局，示例代码：

client.updateRelayLayout(UpdateRelayLayoutOptions, callback)

参数说明

UpdateRelayLayoutOptions: object 类型, 必传，详细的类型说明：

{
  layout: MixLayoutOptions  // 必传，转推多路时视频的布局设置，类型说明见下面的 MixLayoutOptions 类型
}

注：MixLayoutOptions 类型说明详见 MixLayoutOptions

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Result) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Result 为返回值，RelayResult 类型，执行失败时，此值为空，执行成功时，此值为执行结果

56. createStream 方法

创建一条本地流，可用于进行预览，也可将其直接发布（publishStream），示例代码：

client.createStream(CreateStreamOptions, callback)

参数说明

CreateStreamOptions: object 类型，选传，类型说明如下

{
  audio: boolean          // 必填，指定是否使用麦克风设备。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  video: boolean          // 必填，指定是否使用摄像头设备。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  facingMode?: FacingMode // 选填，在移动设备上，可以设置该参数选择使用前置或后置摄像头。具体参数说明可参考 publish 方法 PublishOptions （见注1）的对应项
  screen: boolean         // 必填，指定是否为屏幕共享。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  screenAudio?: boolean   // 选填，指定是否采集屏幕共享的音频。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  microphoneId?: string   // 选填，指定使用的麦克风设备的ID。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  cameraId?: string       // 选填，指定使用的摄像头设备的ID。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  extensionId?: string    // 选填，指定使用的 Chrome 插件的 extensionId。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  mediaStream?: MediaStream  // 选填，允许用户发布自定义的媒体流。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  file?: File             // 选填，发布时指定使用图片文件生成视频源。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  filePath?: string       // 选填，发布时指定使用网络图片生成视频源。具体参数说明可参考 publish 方法 PublishOptions 的对应项
  streamId?: string       // 选填，指定该本地流的预览 ID（后续可通过该 ID 将其直接发布），该 ID 可由用户自定义，非重复、非空的字符串即可，不传时，将使用随机生成值
  userId?: string         // 选填，joinRoom 之前创建的流将使用此值（或 'unknown' - 未填此字段时）指定为流的 uid，joinRoom 之后，将忽略此值，直接使用加入房间时指定的 userId 为流的 uid
  audioProcessing?: AudioProcessingOptions, // 选填，可开启或关闭 3A，默认开启 3A，见下面详细说明
}

AudioProcessingOptions 音频处理参数

{
  AEC?: boolean; // 声学回声消除，默认为 true，即开启。可将 AEC 设为 false 来关闭声学回声消除。
  AGC?: boolean; // 自动增益控制，默认为 true，即开启。可将 AGC 设为 false 来关闭自动增益控制。
  ANS?: boolean; // 自动噪声抑制，默认为 true，即开启。可将 ANS 设为 false 来关闭自动噪声抑制。
}

callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Stream) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Stream 为返回值，Stream 类型，执行失败时，此值为空，执行成功时，此值为执行结果

注:
PublishOptions
传入的 streamId 不可重复
创建成功后，流的 sid 与 previewId 将和传入的 streamId 的值相同，可使用 play 方法传入该值进行播放

57. publishStream 方法

发布一条本地（预览）流，示例代码：

client.publishStream(streamId, callback)

参数说明

streamId: string 类型，必传，为调用 createStream 时传的 streamId
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Stream) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Stream 为返回值，Stream 类型，执行失败时，此值为空，执行成功时，此值为执行结果

注:
发布的流必须为使用通过 createStream 方法创建并为非发布状态的本地流。
当该本地（预览）流被发布成功后，流的数据将更新，特别的，sid 将被替换为服务器创建的流 ID，previewId 仍保持创建时传入的值。
若发布前该流已经被播放（通过调用 play 方法进行播放），发布成功后请使用更新后的流进行重新播放。

58. unpublishStream 方法

取消发布一条本地（预览）流（须为使用 createStream 方法创建并为发布状态的本地流），示例代码：

client.unpublishStream(streamId, callback)

参数说明

streamId: string 类型，必传，为调用 createStream 时传的 streamId
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error, Stream) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

Stream 为返回值，Stream 类型，执行失败时，此值为空，执行成功时，此值为执行结果

注:
取消发布的流请使用通过 createStream 方法创建并为发布状态的本地流。
通过 publish 方法直接发布时生成的本地流，请使用 unpublish 方法进行取消发布。
若之前该流已经被播放（通过调用 play 方法进行播放），取消发布后请使用更新后的流进行重新播放。

59. destroyStream 方法

销毁一条本地（预览）流（须为非发布状态的本地流），示例代码：

client.destroyStream(streamId, callback)

参数说明

streamId: string 类型，必传，为调用 createStream 时传的 streamId
callback: function 类型，选传，方法的回调函数，函数说明如下

function callback(Error) {}

Error 为返回值，为空时，说明已执行成功，否则执行失败，值为执行失败的错误

注:
被销毁的流必须为未发布状态的本地（预览）流，如通过 createStream 方法创建但并未发布的本地流，或使用 unpublishStream 方法取消发布了的本地流。
当一条本地（预览）流已经被播放（通过调用 play 方法进行播放），此销毁操作将自动停止该流的播放，无须额外调用 stop 方法。

60. enableAudioVolumeIndicator 方法

开启远程流音量指示器，开启后将通过 'volume-indicator' 事件定时报告有音频的远端（订阅）流的音量，示例代码：

client.enableAudioVolumeIndicator(interval)

参数说明

interval: number 类型，选传，指定收集音量的时间间隔，单位 ms，须为大于等于 200 的整数，不填时，默认为 2000ms

注:
调用该方法后，请通过监听 'volume-indicator' 事件，以获取各远端流的音量。
为了开启此功能时，不占用过多的系统资源，interval 的值不可小于 200，否则对该方法的调用将不生效。

二、getDevices 方法

用于获取当前浏览器可访问的音视频设备的设备信息，包括麦克风、摄像头、音频输出设备

UCloudRTC.getDevices(GetDevicesOptions, onSuccess, onFailure)

参数说明

GetDevicesOptions: object 类型，选传，类型说明如下

{
  microphone?: boolean; // 是否强制获取设备 ID 等详细的设备信息，默认为 true
  camera?: boolean; // 是否强制获取设备 ID 等详细的设备信息，默认为 true
}

注：关于 GetDevicesOptions 的说明，部分浏览器（如 Safari）在未经过用户授权时，仅能获取部分设备信息，如设备个数、类型等，并不能获取像设备 ID 等更详细的信息，开启强制获取设备详细信息，将提示用户授权。因为默认为开启强制获取设备详细信息，因此可能会弹出提示要求用户进行授权。

onSuccess: 必传，函数类型，方法调用成功时执行的回调函数。

function onSuccess(MediaDeviceInfos) {}

函数参数 MediaDeviceInfos 为返回值，MediaDeviceInfo 类型的数组，为一组输入、输出设备的描述信息，点击 MediaDeviceInfo 查看其详情。

onFailure: 选传，函数类型，方法调用失败时执行的回调函数。

function onFailure(Err) {}

Err 为错误信息

三、getSupportProfileNames 方法

用于获取当前 SDK 预定义的视频 Profile 的名称

const profileNames = UCloudRTC.getSupportProfileNames();

返回值说明

profileNames: string 类型的数组，如当前可用的 ["240*180", "320*180", "320*240", "480*360", "640*360", "640*480", "640*480_1", "1280*720", "1280*720_1", "1280*720_2", "1280*720_3", "1920*1080", "1920*1080_1", "1920*1080_2", "1920*1080_3"]

名称 | 视频宽高 | 帧率 | 视频最小带宽 | 视频最大带宽 :-: | :-: | :-: | :-: | :-: "240*180" | 240*180 | 20 | 100 | 200 "320*180" | 320*180 | 20 | 100 | 300 "320*240" | 320*240 | 20 | 100 | 400 "480*360" | 480*360 | 20 | 100 | 400 "640*360" | 640*360 | 20 | 100 | 500 "640*480" | 640*480 | 20 | 100 | 600 "640*480_1" | 640*480 | 5 | 100 | 600 "1280*720" | 1280*720 | 15 | 120 | 1000 "1280*720_1" | 1280*720 | 15 | 120 | 1500 "1280*720_2" | 1280*720 | 30 | 120 | 2000 "1280*720_3" | 1280*720 | 5 | 120 | 1000 "1920*1080" | 1920*1080 | 15 | 120 | 1500 "1920*1080_1" | 1920*1080 | 15 | 120 | 2000 "1920*1080_2" | 1920*1080 | 30 | 120 | 2500 "1920*1080_3" | 1920*1080 | 5 | 120 | 1500

四. getSupportedCodec 方法

检测当前浏览器支持的音视频的编解码格式

UCloudRTC.getSupportedCodec(callback);

参数说明

callback: function 类型，必传，方法的回调函数，函数说明如下

function callback(Codecs) { }

Codecs 为返回值，object 类型，详细的类型说明如下

{
  audio: string[],  // 字符串数组，支持的音频编解码格式。可能含有 "opus"，或为空数组。
  video: string[],  // 字符串数组，支持的视频编解码格式。可能含有 "h264"、"vp8" 两种取值，或为空数组。
}

五. isSupportWebRTC 方法

检测当前浏览器对 WebRTC 的适配情况

const result = UCloudRTC.isSupportWebRTC();

返回值说明

result: boolean 类型，
- true: 当前使用的浏览器支持 WebRTC。
- false: 当前使用的浏览器不支持 WebRTC。

六. deviceDetection 方法

发布本地流或启动预览时，有可能因为麦克风或摄像头设备问题（如驱动问题，或未经授权等），导致无法正常发布或预览。此方法可用于发布或预览前的设备检测，根据检测结果，再自行决定在发布或预览时启用麦克风或摄像头或麦克风和摄像头，示例代码：

UCloudRTC.deviceDetection(DeviceDetectionOptions, callback);

参数说明

DeviceDetectionOptions: object 类型, 必传，详细的类型说明如下

{
  audio: boolean          // 必填，指定是否检测麦克风设备
  video: boolean          // 必填，指定是否检测摄像头设备
  microphoneId?: string   // 选填，指定需要检测的麦克风设备的ID，可通过 getMicrophones 方法查询获得该ID，不填时，将检测默认的麦克风设备
  cameraId?: string       // 选填，指定需要检测的摄像头设备的ID，可以通过 getCameras 方法查询获得该ID，不填时，将检测默认的摄像头设备
}

callback: function 类型，必传，方法的回调函数，函数说明如下

function callback(Result) {
  if (Result.audio && Result.video) {
    // 麦克风和摄像头都可有和，发布或预览时可启用麦克风和摄像头
    // client.publish({audio: true, video: true});
  } else if (Result.audio) {
    // 麦克风可用，发布或预览时能启用麦克风
    // client.publish({audio: true, video: false});
  } else if (Result.video) {
    // 摄像头可用，发布或预览时能启用摄像头
    // client.publish({audio: false, video: true});
  } else {
    // 麦克风和摄像头都不可用
  }
}

Result 为返回值，DeviceDetectionResult 类型，详细的类型说明如下

{
  audio: boolean,       // 指麦克风设备是否可用
  audioError?: string   // 当麦克风不可用时，此字段可说明设备不可用的原因
  video: boolean        // 指摄像头设备是否可用
  videoError?: string   // 当摄像头不可用时，此字段可说明设备不可用的原因
}

audioError 和 videoError 可能的错误信息有：参见

七、version 属性

version 属性用于显示当前 sdk 的版本

八、generateToken 方法

generateToken 方法仅用于试用 URTC 产品时替代服务器生成 sdk 所需 token 的方法，正式使用 URTC 产品时，需要搭建后台服务按规则生成 token

const token = UCloudRTC.generateToken(AppId, AppKey, RoomId, UserId);

参数说明

AppId: string 类型, 必传，可从 UCloud 控制台查看
AppKey: string 类型, 必

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

UCloudRTC Web SDK API 手册

一、Client 类

1. 构造函数

参数说明

2. joinRoom 方法

参数说明

3. leaveRoom 方法

参数说明

4. publish 方法

参数说明

5. unpublish 方法

参数说明

6. subscribe 方法

参数说明

7. unsubscribe 方法

参数说明

8. on 方法

参数说明

事件名解释：

9. off 方法

参数说明

10. play 方法

参数说明

11. resume 方法

参数说明

12. stop 方法

参数说明

13. muteAudio 方法

参数说明

返回值说明

14. unmuteAudio 方法

参数说明

返回值说明

15. muteVideo 方法

返回值说明

16. unmuteVideo 方法

返回值说明

~~startRecording 方法 - 已废弃~~

开启录制，请使用 startRecord

参数说明

~~stopRecording 方法 - 已废弃~~

结束录制，请使用 stopRecord

参数说明

17. getUser 方法

返回值说明

18. getUsers 方法

返回值说明

19. getStream 方法

参数说明

返回值说明

20. getLocalStreams 方法

返回值说明

21. getRemoteStreams 方法

返回值说明

~~getStreams 方法 - 已废弃~~

22. getMediaStream 方法

参数说明

返回值说明

~~getLocalMediaStream 方法 - 已废弃~~

~~getRemoteMediaStream 方法 - 已废弃~~

23. getMicrophones 方法

参数说明

24. getCameras 方法

参数说明

25. getLoudspeakers 方法

参数说明

26. setVideoProfile 方法

参数说明

27. switchDevice 方法

参数说明

28. switchScreen 方法

参数说明

29. switchImage 方法

参数说明

startRecording 方法 - 已废弃

stopRecording 方法 - 已废弃

getStreams 方法 - 已废弃

getLocalMediaStream 方法 - 已废弃

getRemoteMediaStream 方法 - 已废弃

deviceDetection 方法 - 已转移

startMix 方法 - 已废弃

stopMix 方法 - 已废弃