视频通话

通过 ArRTC.createClient 创建的客户端对象。

提供音视频通话的核心功能，比如加入频道、发布和订阅音视频轨道等。

你可以通过 createClient 创建一个 ArRTCClient 对象。一个 ArRTCClient 对象代表一个本地客户端。

import ArRTC from "ar-rtc-sdk";

/**
 * config 客户端的配置
 * @params mode 通话场景
 * @params codec 编码格式
 */
var config = { mode: "rtc", codec: "h264" };

/**
 * 创建一个客户端
 */
var rtcClient = ArRTC.createClient(config);

事件回调

connection-state-change

connection-state-change(curState: ConnectionState, revState: ConnectionState, reason?: ConnectionDisconnectedReason): void

SDK 与服务器的连接状态发生改变回调。

/**
 * SDK 与服务器的连接状态发生改变回调。
 * @params curState 当前的连接状态。
 */
rtcClient.on("connection-state-change", (curState, revState, reason) => {
  if(curState == "DISCONNECTED") {
     console.log("断开连接的原因", reason)
  }
})
...

参数

curState: ConnectionState

当前的连接状态。
revState: ConnectionState
Optional reason: ConnectionDisconnectedReason

如果 curState 为 "DISCONNECTED"，这里表示断开连接的原因（被踢/网络异常/正常离开）

返回值 void

stream-type-changed

stream-type-changed(uid: UID, streamType: RemoteStreamType): void

订阅的视频流类型发生改变回调。

视频流类型改变指视频大流（高码率、高分辨率）变为视频小流（低码率、低分辨率），或视频小流变为视频大流。

/**
 * SDK 与服务器的连接状态发生改变回调。
 * @params uid 远端流对应的用户 ID。
 * @params streamType 改变后的视频流类型 详情请看 RemoteStreamType (类型：number)
 */
rtcClient.on("stream-type-changed", (uid, streamType) => {
  ...
})
...

参数

uid: UID

远端流对应的用户 ID。
streamType: RemoteStreamType

改变后的视频流类型:
- 视频大流，即高码率、高分辨率的视频流。
- 视频小流，即低码率、低分辨率的视频流。

返回值 void

token-privilege-did-expire

token-privilege-did-expire(): void

Token 已过期回调。

在 token 过期后，会收到该回调。

一般情况下，在收到该消息之后，应向服务端重新申请 token，并调用 join 方法传入新的 token 重新加入频道。

/**
 * Token 已过期回调。
 */
rtcClient.on("token-privilege-did-expire", async function () {
  //进行重新申请 token 操作后 更新 token。
  await rtcClient.renewToken(token);
});

返回值 void

token-privilege-will-expire

token-privilege-will-expire(): void

Token 即将过期回调。

在 token 过期前 30 秒，会收到该回调。

在收到该回调之后，应向服务端重新申请 token，并调用 renewToken 方法传入新的 token。

/**
 * Token 即将过期回调。
 */
rtcClient.on("token-privilege-will-expire", async () => {
  //进行重新申请 token 操作后 更新 token。
  await rtcClient.renewToken(token);
});

返回值 void

user-joined

user-joined(user: ArRTCRemoteUser): void

远端用户/主播加入频道回调。

通信场景下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
直播场景下，该回调提示有主播加入了频道，并返回该主播的 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。建议连麦主播不超过 17 人。

该回调在以下情况下会被触发：

通信场景的远端用户/直播场景的远端主播调用 join 方法加入频道。
直播场景的远端观众加入频道后调用 setClientRole 将用户角色改变为主播。
通信场景的远端用户/直播场景的远端主播网络中断后重新加入频道。
主播通过调用 addInjectStreamUrl 方法成功输入在线媒体流。

/**
 * 远端用户/主播加入频道回调。
 * @@params user 加入频道的用户信息
 */
rtcClient.on("user-joined", (user) => {
 ...
});

参数

user: ArRTCRemoteUser

加入频道的用户信息。

返回值 void

user-left

user-left(user: ArRTCRemoteUser, reason: string): void

远端用户离线回调。

该回调通知 app 有远端用户离线，离线包括以下情况：

正常离开：用户会收到类似“再见”的消息，接收此消息后，判断对方离开频道。
超时掉线：在 20 秒内，用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。
用户角色从主播变为观众。

在直播场景中，只有角色为主播的用户会触发该回调。

/**
 * 远端用户离线回调。
 * @params user 离线的用户信息
 * @params reason 用户离线的原因
 */
rtcClient.on("user-left", (user, reason) => {
 ...
});

参数

user: ArRTCRemoteUser

离线的用户信息。
reason: string

用户离线的原因。
- "Quit": 用户调用了 leave 主动离开频道。
- "ServerTimeOut": 因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。
- "BecomeAudience": 用户角色从主播切换为观众。

返回值 void

user-published

user-published(user: ArRTCRemoteUser, mediaType: "audio" | "video"): void

该回调通知远端用户发布了新的音频轨道或者视频轨道。

你可以在该回调中订阅并播放远端用户的音视频轨道。详见 subscribe 和 RemoteTrack.play。

如果用户加入频道时频道内已经有其他用户的音视频轨道，也会收到该回调报告已经存在的远端轨道。

/**
 * 该回调通知远端用户发布了新的音频轨道或者视频轨道。
 * @params user 远端用户信息。
 * @params mediaType 远端用户发布的媒体类型。
 */
rtcClient.on("user-published", async (user, mediaType) => {
  // 订阅远端用户的音视频轨道
  await rtcClient.subscribe(user, mediaType);
  if (mediaType === "video") {
    console.log("subscribe video success");
    // 在页面上播放媒体轨道。
    user.videoTrack.play("xxx");
  }
  if (mediaType === "audio") {
    user.audioTrack.play();
  }
});

参数

user: ArRTCRemoteUser

远端用户信息。
mediaType: "audio" | "video"

远端用户发布的媒体类型。
- "audio": 远端用户发布了音频轨道。
- "video": 远端用户发布了视频轨道。
由于网络和发送端的不确定性，远端用户发布音视频轨道后，可能会出现以下这种情况：
- anyRTC 边缘节点在收到首帧音频包后隔一段时间才收到首帧视频包。
  - 为了避免音频信息的丢失，在收到首帧音频包后 SDK 会立刻触发一次 user-published(mediaType: "audio") 事件。
  - 收到首帧视频包后，SDK 再触发一次 user-published(mediaType: "video") 事件。
我们建议在使用订阅的轨道之前确保 mediaType 或者轨道对象的值不是 undefined。

返回值 void

user-unpublished

user-unpublished(user: ArRTCRemoteUser, mediaType: "audio" | "video"): void

该回调通知远端用户取消发布了音频或视频轨道。

/**
 * 该回调通知远端用户取消发布了音频或视频轨道
 * @params user 远端用户信息。
 * @params mediaType 远端用户取消发布的是音频轨道还是视频轨道
 */
rtcClient.on("user-unpublished", async (user, mediaType) => {
...
});

参数

user: ArRTCRemoteUser

远端用户信息。
mediaType: "audio" | "video"

表示远端用户取消发布的是音频轨道还是视频轨道。

返回值 void

network-quality

network-quality(stats: NetworkQuality): void

网络上下行质量报告回调。

用户加入频道后，SDK 会每 1 秒触发一次该回调，报告本地用户当前的上行和下行网络质量。

我们推荐使用此回调来展示你的网络状态。

/**
 * 该回调通知远端用户取消发布了音频或视频轨道
 * @params stats 网络质量 详情请见上方 NetworkQuality
 */
async function StatusFn (stats){
  // 质量状态
  var oType = [
    "质量未知",
    "质量极好",
    "用户主观感觉和极好差不多，但码率可能略低于极好",
    "用户主观感受有瑕疵但不影响沟通",
    "勉强能沟通但不顺畅",
    "网络质量非常差，基本不能沟通",
    "网络连接断开，完全无法沟通",
  ];
  console.log("上行网络质量", oType[stats.uplinkNetworkQuality]);
  console.log("下行网络质量", oType[stats.downlinkNetworkQuality]);
}

rtcClient.on("network-quality", StatusFn);

参数

stats: NetworkQuality

网络质量。

返回值 void

volume-indicator

volume-indicator(result: object[]): void

该方法允许 SDK 定期报告正在说话的远端用户及其音量。

默认禁用。可以通过 enableAudioVolumeIndicator 方法开启；开启后，无论频道内是否有人说话，都会每两秒返回提示音量。

音量范围为 0 到 100 之间。通常在列表中音量大于 5 的用户为持续说话的人。

rtcClient.on('volume-indicator', (result) => {
  result.forEach(function(volume, index){
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  }
});

参数

result: object[]

返回值 void

channel-media-relay-event

channel-media-relay-event(event: ChannelMediaRelayEvent): void

跨频道媒体流转发事件回调。

rtcClient.on('channel-media-relay-event', (event) => {
  console.log(`channel media relay event: ${event}`);
});

参数

event: ChannelMediaRelayEvent

事件码，详见 ChannelMediaRelayEvent。

返回值 void

channel-media-relay-state

channel-media-relay-state(state: ChannelMediaRelayState, code: ChannelMediaRelayError): void

跨频道媒体流转发状态回调。

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

回调会携带当前跨频道媒体流转发服务的状态 ChannelMediaRelayState，如果状态异常，相应的错误码可以通过 ChannelMediaRelayError 获取（比如 token 过期，重连失败等）。

rtcClient.on('channel-media-relay-state', (state, code) => {
  console.log(`channel media relay state is ${state}, code is ${code}.`);
});

参数

state: ChannelMediaRelayState

跨频道媒体流转发服务的状态。
code: ChannelMediaRelayError

跨频道媒体流转发错误码。

返回值 void

live-streaming-error

live-streaming-error(url: string, err: ArRTCError): void

推流发生错误回调。

在调用 startLiveStreaming 成功开始推流后，推流中途发生错误时，会通过这个事件抛出。

你可以访问 err.code 来获取错误码字符串，下面列出可能出现的错误：

LIVE_STREAMING_INVALID_ARGUMENT: 推流参数错误。 LIVE_STREAMING_INTERNAL_SERVER_ERROR: 推流服务器内部错误。 LIVE_STREAMING_PUBLISH_STREAM_NOT_AUTHORIZED: 推流 URL 被占用。 LIVE_STREAMING_TRANSCODING_NOT_SUPPORTED: 在非转码推流中调用了转码参数。 LIVE_STREAMING_CDN_ERROR: 推流的目标 CDN 出现错误导致推流失败。 LIVE_STREAMING_INVALID_RAW_STREAM: 推流超时，请确认目标流是否存在。

rtcClient.on('live-streaming-error', (url, err) => {
  // TODO
});

参数

url: string

发生错误的直播推流地址。
err: ArRTCError

详细的错误信息。

返回值 void

live-streaming-warning

live-streaming-warning(url: string, err: ArRTCError): void

推流发生警告回调。

在调用 startLiveStreaming 成功开始推流后，推流中途发生警告时，会通过这个事件抛出。

你可以访问 err.code 来获取警告码字符串，下面列举可能出现的警告：

LIVE_STREAMING_WARN_STREAM_NUM_REACH_LIMIT: 推流超过 10 路流。 LIVE_STREAMING_WARN_FAILED_LOAD_IMAGE: 推流中的背景图片或者水印地址无法拉取。 LIVE_STREAMING_WARN_FREQUENT_REQUEST: 推流请求太频繁。

rtcClient.on('live-streaming-warning', (url, warning) => {
  // TODO
});

参数

url: string

发生警告的直播推流地址。
err: ArRTCError

详细的错误信息。

返回值 void

属性

console.log("当前加入的频道名称", rtcClient.channelName);
console.log("SDK 和 anyRTC 服务器的连接状态", rtcClient.connectionState);
console.log("远端用户信息列表", rtcClient.remoteUsers);
console.log("本地用户的用户 ID", rtcClient.uid);

channelName

channelName?: undefined | string

当前加入的频道名称

如果本地用户没有加入频道，该属性值为 undefined。

connectionState

connectionState: ConnectionState

SDK 和 anyRTC 服务器的连接状态。

remoteUsers

remoteUsers: ArRTCRemoteUser[]

远端用户信息列表，包含频道中各个远端用户的用户 ID 和轨道信息。

如果本地用户没有加入频道，该列表为空。

uid

uid?: UID

本地用户的用户 ID。

如果本地用户没有加入频道，该属性值为 undefined。

核心方法

join

join(appid: string, channel: string, token: string | null, uid?: UID | null): Promise<UID>

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话。

调用该方法加入频道时，本地会触发 ArRTCClient.on("connection-state-change") 回调。

通信场景下的用户和直播场景下的主播加入频道后，远端会触发 ArRTCClient.on("user-joined") 回调。

/**
 * 加入频道。
 * @params appid： anyRTC 控制台获取的 App ID （类型：string)
 * @params channel：通话的频道名称 （类型：string)
 * @params token：用于鉴权的 token （类型：string | null)
 * @params uid：当前用户的 ID （类型：string | null)
 */
rtcClient.join(appid, channel, token, uid)
  .then((uid) => {
    // 加入频道成功
  })
  .catch(err => {
    // 加入频道失败
  });

参数

appid: string
channel: string

标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
- 26 个小写字母 a-z。
- 26 个大写字母 A-Z。
- 10 个数字 0-9。
- 空格。
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "*", "{", "}", "|", "~", ","。
token: string | null

用于鉴权的 token。
- 如果你的项目没有开启 token 鉴权，这里填 null。
- 安全要求不高: 你可以使用控制台生成的临时 token，详见获取临时 Token。
- 安全要求高：传入从你的服务端获得的正式 token（不支持 Channel Key），详见获取正式 Token。
Optional uid: UID

标识用户的 ID，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:
- 26 个小写字母 a-z。
- 26 个大写字母 A-Z。
- 10 个数字 0-9。
- 空格。
- "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "*", "{", "}", "|", "~", ","。

返回值 Promise<UID>

Promise 对象，包含本地用户的 ID。异步操作完成说明加入成功。

publish

publish(tracks: ILocalTrack | ILocalTrack[]): Promise<void>

发布本地音视频轨道。

该方法将本地音视频轨道发布至频道中。

发布音视频轨道之后，远端会触发 ArRTCClient.on("user-published") 回调。

注意
发布的轨道之前必须加入房间。
发布的轨道如果被主动释放（close），需要执行取消发布操作。

注意事项：
直播场景里，调用 setClientRole 将用户角色设为主播后才能调用该方法。
你可以多次调用该方法添加要发布的轨道。
一个 ArRTCClient 对象可以发布多个音频轨道，SDK 会自动混音（将多个音频轨道合并为一个音频轨道），但是视频轨道只能发布一个。
Safari 12 之前的版本不支持发布多个音频轨道。

// 设置成主播
rtcClient.setClientRole("host")；
// 发布
rtcClient.publish([videoTrack, audioTrack])
  .then((uid) => {
    // 发布成功
  })
  .catch(err => {
    // 发布失败
  });

参数

tracks: ILocalTrack ｜ ILocalTrack[]

通过 ArRTC.createMicrophoneAudioTrack / ArRTC.createCameraTrack 或其他方法创建的本地 Track 对象。

返回值 Promise<void>

leave

leave(): Promise<void>

离开频道。

离开频道即挂断或退出通话。

调用该方法离开频道时，本地会触发 ArRTCClient.on("connection-state-change") 回调。

通信场景下的用户和直播场景下的主播离开频道后，远端会触发 ArRTCClient.on("user-left") 回调。

/**
 * 离开频道。
 */
audioTrack && audioTrack.close(); // 释放音频设备
videoTrack && videoTrack.close(); // 释放视频设备
rtcClient.leave();

返回值 Promise<void>

unpublish

unpublish(tracks?: ILocalTrack | ILocalTrack[]): Promise<void>

取消发布本地音视频轨道。

取消发布音视频轨道之后，远端会触发 ArRTCClient.on("user-unpublished") 回调。

audioTrack.on("track-ended", () => {
  rtcClient.unpublish(audioTrack);
});
videoTrack.on("track-ended", () => {
  rtcClient.unpublish(videoTrack);
});

参数

Optional tracks: ILocalTrack ｜ ILocalTrack[]

要取消发布的轨道。如果留空，会将所有发布过的音视频轨道取消发布。

返回值 Promise<void>

subscribe(user: ArRTCRemoteUser, mediaType: "video"): Promise<IRemoteVideoTrack>
subscribe(user: ArRTCRemoteUser, mediaType: "audio"): Promise<IRemoteVideoTrack>
subscribe(user: ArRTCRemoteUser, mediaType: "video" | "audio"): Promise<IRemoteTrack>

订阅远端用户的音视频轨道。

rtcClient.on("user-published", async (user, mediaType) => {
  // 订阅远端用户的音视频轨道
  await rtcClient.subscribe(user, mediaType);
  if (mediaType === "video") {
    console.log("subscribe video success");
    // 在页面上播放媒体轨道。
    user.videoTrack.play("xxx");
  }
  if (mediaType === "audio") {
    user.audioTrack.play();
  }
});

参数

user: ArRTCRemoteUser

远端用户对象。
Optional mediaType: "video" | "audio"

订阅的轨道媒体类型。
- "video": 仅订阅指定用户发布的视频轨道。
- “audio”: 仅订阅指定用户发布的音频轨道。
- 不填: 订阅指定用户发布的所有轨道。

返回值 Promise<void>

订阅的异步操作完成后，订阅的内容会在 user.audioTrack 和 user.videoTrack 上更新，之后直接调用 user.audioTrack.play 或 user.videoTrack.play 就可以播放了。

如果指定要订阅的音视频轨道不存在会抛出 TRACK_IS_NOT_PUBLISHED 错误。

unsubscribe

unsubscribe(user: ArRTCRemoteUser, mediaType?: "video" | "audio"): Promise<void>

取消订阅远端用户的音视频轨道。

/**
 * 取消订阅远端用户的音视频轨道
 * @params user 远端用户对象
 */
rtcClient.unsubscribe(user);

参数

user: ArRTCRemoteUser

远端用户对象。
Optional mediaType: "video" | "audio"

取消订阅的轨道媒体类型。
- "video": 仅取消订阅指定用户的视频轨道。
- “audio”: 仅取消订阅指定用户的音频轨道。
- 不填：取消订阅这个用户发布的所有轨道。

返回值 Promise<void>

如果指定的音视频轨道不存在会抛出 TRACK_IS_NOT_SUBSCRIBED 错误。

输入在线媒体流

addInjectStreamUrl

addInjectStreamUrl(url: string, config: InjectStreamConfig): Promise<void>

输入在线媒体流。

该方法通过在服务端拉取视频流并发送到频道中，将正在播出的视频输入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。详见输入在线媒体流。

成功输入媒体流后，该流会出现在频道中，频道内所有用户都会收到 client.on("user-published") 和 client.on("user-joined") 回调，其中 uid 为 share666。

输入媒体流的状态会通过 client.on("stream-inject-status") 通知。

参数

url: string

小流的视频属性。
- 支持的音频编码格式：AAC。
- 支持的视频编码格式：H.264 (AVC)。
config: InjectStreamConfig

输入的在线媒体流的设置，详见 InjectStreamConfig。

返回值 Promise<void>

removeInjectStreamUrl

removeInjectStreamUrl(): Promise<void>

删除输入的在线媒体流。

该方法从直播中删除通过 addInjectStreamUrl 输入的在线媒体流。

删除后频道內所有用户都会收到 client.on("user-left") 和 client.on("user-unpublished") 回调。

返回值 Promise<void>

推流到CDN

setLiveTranscoding

setLiveTranscoding(config: LiveStreamingTranscodingConfig): Promise<void>

设置直播推流转码的配置。

该方法用于旁路推流的视图布局及音频设置等。

使用前请确保已开通旁路推流。

参数

config: LiveStreamingTranscodingConfig

直播转码的设置，详见 LiveStreamingTranscodingConfig。

返回值 Promise<void>

startLiveStreaming

startLiveStreaming(url: string, transcodingEnabled?: undefined | false | true): Promise<void>

将本地流发布到 CDN。

详见推流到 CDN。

注意事项：

该方法每次只能增加一路旁路推流地址。

await client.setLiveTranscoding(config);
await client.startLiveStreaming("rtmp://xxxx", true);

参数

url: string

直播推流的地址，ASCII 字符。支持 RTMP 协议。
Optional transcodingEnabled: undefined | false | true

(可选) 是否启用直播转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 RTMP 服务器，适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 true，需要在调用该方法前先调用 setLiveTranscoding。
- true: 启用转码，需要在调用该方法前先调用 setLiveTranscoding。
- false: （默认）不启用转码，这种情况下需要保证当前用户正在发布。

返回值 Promise<void>

stopLiveStreaming

stopLiveStreaming(url: string): Promise<void>

删除旁路推流地址。

该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

参数

url: string

待删除的推流地址。

返回值 Promise<void>

跨频道媒体流转发

startChannelMediaRelay

startChannelMediaRelay(config: IChannelMediaRelayConfiguration): Promise<void>

开始跨频道媒体流转发。

调用该方法后，SDK 会触发以下回调：

client.on("channel-media-relay-state")，报告当前的跨频道媒体流转发状态和错误码。
- 如果转发中途出现异常，该回调中 state 为 3，code 为错误码。你可以尝试再次调用本方法。
client.on("channel-media-relay-event")，报告跨频道媒体流转发相关的事件。
- 如果跨频道服务开始向目标频道发送数据包，会触发回调，code 为 4.

注意事项：

请在成功加入频道后调用该方法。直播场景下，只有主播可以调用该方法。成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。

client.startChannelMediaRelay(config).then(() => {
  console.log("startChannelMediaRelay success");
}).catch(e => {
  console.log("startChannelMediaRelay failed", e);
})

参数

config: IChannelMediaRelayConfiguration

跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。

返回值 Promise<void>

Promise 对象。当 Promise resolve 后，表示成功开启了跨频道服务。

stopChannelMediaRelay

stopChannelMediaRelay(): Promise<void>

停止跨频道媒体流转发。

一旦停止转发，用户会退出所有的目标频道。

返回值 Promise<void>

Promise 对象。当 Promise resolve 后，表示成功停止了跨频道服务。

updateChannelMediaRelay

updateChannelMediaRelay(config: IChannelMediaRelayConfiguration): Promise<void>

更新媒体流转发的目标频道。

成功开始跨频道转发媒体流后，如果你希望添加或删除媒体流转发的目标频道，可以调用该方法。

注意事项：

请在 startChannelMediaRelay 后调用该方法，更新媒体流转发的频道。跨频道媒体流转发最多支持 4 个目标频道。

参数

config: IChannelMediaRelayConfiguration

跨频道媒体流转发参数配置，详见 ChannelMediaRelayConfiguration。

返回值 Promise<void>

Promise 对象。当 Promise resolve 后，表示更新成功，否则更新失败。出错后跨频道媒体流转发状态会被重置，你需要调用 startChannelMediaRelay 重新开始跨频道媒体流转发。

大小流方法

enableDualStream

enableDualStream(): Promise<void>

开启双流模式。

该方法为本地流开启双流模式。双流为视频大流和视频小流，其中视频大流指高分辨率、高码率的视频流，视频小流指低分辨率、低码率的视频流。

Safari 浏览器不支持本方法

rtcClient
  .enableDualStream()
  .then(() => {
    console.log("Enable Dual stream success!");
  })
  .catch((err) => {
    console.log(err);
  });

返回值 Promise<void>

disableDualStream

disableDualStream(): Promise<void>

关闭双流模式。(必须先开启双流模式)

rtcClient
  .disableDualStream()
  .then(() => {
    console.log("Disable Dual stream success!");
  })
  .catch((err) => {
    console.log(err);
  });

返回值 Promise<void>

setLowStreamParameter

setLowStreamParameter(streamParameter: LowStreamParameter): void

设置小流视频属性。

如果你调用 enableDualStream 开启了双流模式，该方法设置小流的视频属性。

如果你不设置小流的视频属性，SDK 会根据你的视频流属性自动适配小流的视频属性。

注意事项：
Firefox 浏览器上设置帧率不生效，浏览器会把帧率固定在 30 fps。
请在 publish 之前调用此方法。
由于设备和浏览器的限制，部分浏览器设置视频分辨率可能不会生效，这种情况下浏览器会自动调整分辨率，计费也将按照实际分辨率计算。

/**
 * 设置小流视频属性。
 * @params streamParameter 小流的视频属性 详情请见 LowStreamParameter （类型：object)
 */
var streamParameter = {
  height: 180,
  width: 240
}
rtcClient
  .setLowStreamParameter(streamParameter)
  .then(() => {})
  .catch((err) => {
    console.log(err);
  });

参数

streamParameter: LowStreamParameter

小流的视频属性。

返回值 Promise<void>

setRemoteVideoStreamType

setRemoteVideoStreamType(uid: UID, streamType: RemoteStreamType): Promise<void>

设置订阅远端用户视频的类型（大小流）。

如果发送端开启了双流模式，该方法可以在接收端选择订阅大流还是小流。如果不设置，默认订阅大流。

该方法只可在发送端通过 enableDualStream 开启双流模式的情况下使用。

/**
 * 设置小流视频属性。
 * @params uid 远端用户的 ID
 * @params streamType 订阅的视频流类型，详见 RemoteStreamType （类型：number)
 */
rtcClient
  .setRemoteVideoStreamType(uid, streamType)
  .then(() => {})
  .catch((err) => {
    console.log(err);
  });

参数

uid: UID

远端用户的 ID。
streamType: RemoteStreamType

订阅的视频流类型，0 代表大流，1 代表小流，详见 RemoteStreamType。

返回值 Promise<void>

音视频状态方法

getLocalAudioStats

getLocalAudioStats(): LocalAudioTrackStats

获取本地音频相关信息。

/**
 * 本地音频相关信息
 */
var LocalAudioInfo = null;
LocalAudioInfo = rtcClient.getLocalAudioStats();

返回值 LocalAudioTrackStats

getLocalVideoStats

getLocalVideoStats(): LocalVideoTrackStats

获取本地视频相关信息。

/**
 * 本地视频相关信息
 */
var LocalVideoInfo = null;
LocalVideoInfo = rtcClient.getLocalVideoStats();

返回值 LocalVideoTrackStats

getRemoteAudioStats

getRemoteAudioStats(): RemoteAudioTrackStats

获取远端音频相关信息。

/**
 * 远端音频相关信息
 */
var RemoteAudioInfo = null;
RemoteAudioInfo = rtcClient.getRemoteAudioStats();

返回值 RemoteAudioTrackStats

getRemoteNetworkQuality

getRemoteNetworkQuality(): {[uid: string]: NetworkQuality}

获取远端音频相关信息。

/**
 * 远端音频相关信息
 */
const RemoteAudioInfo = await rtcClient.getRemoteNetworkQuality();

如需使用此功能，请先打开 UserQuality 功能，使用 setParameters 方法，开启 UserQuality。

返回值 [uid: string]: NetworkQuality

getRemoteVideoStats

getRemoteVideoStats(): RemoteVideoTrackStats

获取远端视频相关信息。

/**
 * 远端视频相关信息
 */
var RemoteVideoInfo = null;
RemoteVideoInfo = rtcClient.getRemoteVideoStats();

返回值 RemoteVideoTrackStats

getRTCStats

getRTCStats(): ArRTCStats

获取当前通话的统计信息。返回通话相关的统计信息。

/**
 * 当前通话的统计信息
 */
var RTCInfo = null;
RTCInfo = rtcClient.getRTCStats();

返回值 ArRTCStats

通话相关的统计信息。

高级流媒体管理

setStreamFallbackOption

setStreamFallbackOption(uid: UID, fallbackType: RemoteStreamFallbackType): Promise<void>

设置远端用户音视频流回退策略。

该方法用于设置在弱网情况下订阅音视频流的回退策略。网络不理想的情况下，为保证通话质量，可以选择自动订阅视频小流（低分辨率、低码率视频流）或者仅订阅音频流。

// 设置具体某一个用户的音视频回退策略
rtcClient.setStreamFallbackOption(uid, 2);

参数

options:
- uid: UID
远端用户的 ID。
- fallbackType: RemoteStreamFallbackType
回退策略选项，详见 RemoteStreamFallbackType。

返回值 Promise<void>

其他方法

enableAudioVolumeIndicator

enableAudioVolumeIndicator(): void

启用说话者音量提示。该方法允许 SDK 定期报告正在说话的远端用户及其音量。启用音量提示后，无论频道中有没有人说话，SDK 都会每两秒触发 ArRTCClient.on("volume-indicator") 回调。

rtcClient.enableAudioVolumeIndicator();
rtcClient.on("volume-indicator", volumes => {
  volumes.forEach((volume, index) => {
    console.log(`${index} UID ${volume.uid} Level ${volume.level}`);
  });
})

返回值 void[

getListeners

getListeners(event: string): Function[]

指定一个事件名，获取当前所有监听这个事件的回调函数。

/**
 * 获取当前所有监听这个事件的回调函数
 */
var ofn = null;
ofn = rtcClient.getListeners("network-quality")

参数

event: string

事件名称。

返回值 Function[]

off

off(event: string, listener: Function): void

取消一个指定事件的监听。

/**
 * 取消一个指定事件的监听
 */
rtcClient.off("network-quality", StatusFn)

参数

event: string

指定事件的名称。
listener: Function

监听事件时传入的回调函数。

返回值 void

on

on(event: "connection-state-change", listener: event_connection_state_change): void
on(event: "user-joined", listener: event_user_joined): void
on(event: "user-left", listener: event_user_left): void
on(event: "user-published", listener: event_user_published): void
on(event: "user-unpublished", listener: event_user_unpublished): void
on(event: "stream-type-changed", listener: event_stream_type_changed): void
on(event: "stream-fallback", listener: event_stream_fallback): void
on(event: "token-privilege-will-expire", listener: event_token_privilege_will_expire): void
on(event: "token-privilege-did-expire", listener: event_token_privilege_did_expire): void
on(event: "network-quality", listener: event_network_quality): void
on(event: "volume-indicator", listener: event_volume-indicator): void
on(event: "channel-media-relay-event", listener: event_channel-media-relay-event): void
on(event: "channel-media-relay-state", listener: event_channel-media-relay-state): void
on(event: "live-streaming-error", listener: event_live-streaming-error): void
on(event: "live-streaming-warning", listener: event_live-streaming-warning): void
on(event: string, listener: Function): void

...
/**
 *网络上下行质量报告回调
 */
rtcClient.on("network-quality", StatusFn);

参数

event: "connection-state-change"
listener: Function

返回值 void

once

once(event: string, listener: Function): void

监听一个指定的事件，当事件触发时会调用传入的回调函数。

当监听后事件第一次触发时，该监听和回调函数就会被立刻移除，也就是只监听一次指定事件。

...
/**
 *网络上下行质量报告回调 只监听一次
 */
rtcClient.once("network-quality", StatusFn);

参数

event: string

指定事件的名称。
listener: Function

传入的回调函数。

返回值 void

removeAllListeners

removeAllListeners(event?: undefined | string): void

指定一个事件，取消其所有的监听。

...
/**
 *取消其所有的监听
 */
rtcClient.removeAllListeners();

参数

event: undefined | string

指定事件的名称。

返回值 void

renewToken

renewToken(token: string): Promise<void>

更新 token。

如果启用了 token 机制，过一段时间后 token 会失效。当收到 ArRTCClient.on("token-privilege-will-expire") 回调时, 调用该方法传入新的 token，否则 SDK 会无法和服务器建立连接。

rtcClient.on("token-privilege-did-expire", async () => {
  //进行重新申请 token 操作后 更新 token。
  await rtcClient.renewToken(token);
});

参数

token: string

新的 token。

返回值 void

setClientRole

setClientRole(role: ClientRole): Promise<void>

设置用户角色。

直播场景下，用户角色默认为观众。如需发布音视频，必须先调用本方法切换角色为主播。

角色为主播的用户没有限制，角色为观众的用户不能进行 publish 操作。

如果在加入频道后调用该方法切换用户角色，远端会触发 ArRTCClient.on("user-joined") 或者 ArRTCClient.on("user-left") 回调。

注意事项：
如果已经调用了 publish，想要将用户角色切换为 audience 时，必须先调用 unpublish 取消发布后再调用本方法，否则会设置失败并抛出异常。
通信场景（mode 设置为 rtc）无法使用本方法，默认所有用户都是 host 角色。

// 设置成主播
rtcClient.setClientRole("host")；
// 发布
rtcClient.publish([videoTrack, audioTrack]);

参数

role: ClientRole

用户角色。

返回值 Promise<void>

setEncryptionConfig

setEncryptionConfig(encryptionMode: EncryptionMode, secret: string): void

设置加密方案。

该方法用于设置 SDK 内置的加密算法和密钥，开启内置加密功能。

示例

rtcClient.setEncryptionConfig("aes-128-ecb", "<secret>")；

参数

encryptionMode: EncryptionMode

加密模式。默认使用 aes-128-ecb。
secret: string

加密密钥。

返回值 void

setParameters

setParameters(options: ConfigParameters): void

配置 SDK 提供技术预览或特别定制功能。

注意事项
如果配置了私有云服务 ConfPriCloudAddr , 默认的事件上报服务 ConfPriEventAddr 会不生效，如果需要事件上报服务，请配置 ConfPriEventAddr ;

参数	类型	必填	默认值	描述
ConfPriCloudAddr	Object	否	----	配置私有云服务，参数详见下方 ConfPriCloudAddr。
ConfPriMediaAddr	Object	否	----	配置私有云增值服务，参数详见下方 ConfPriMediaAddr。
ConfPriEventAddr	Object	否	----	配置事件上报服务，参数详见下方 ConfPriEventAddr。
SetTurnSvr	Object	否	----	配置 TurnSvr，参数详见下方 SetTurnSvr。
UserQuality	Object	否	----	配置是否上传用户质量，参数详见下方 UserQuality。
AudioVolumeInterval	number	否	----	配置音量检测时间间隔，单位毫秒。
AreaCode	number	否	----	设置访问区域。
Region	string	否	----	设置国家区域。
ConfIOT	Object	否	----	配置是否是 IOT 设备，参数详见下方 ConfIOT。

ConfPriCloudAddr

参数	类型	必填	默认值	描述
ServerAdd	String	是	----	私有云服务域名或 ip。
Port	Number	是	----	私有云服务端口号。
Wss	Boolean	是	----	是否启用 https。

ConfPriEventAddr

参数	类型	必填	默认值	描述
ServerAdd	String	是	----	事件上报服务域名或 ip。

SetTurnSvr

参数	类型	必填	默认值	描述
Uri	String	是	----	TurnSvr 域名或 ip。
Account	String	是	----	TurnSvr 账号。
Pwd	String	是	----	TurnSvr 密码。

UserQuality

参数	类型	必填	默认值	描述
Enable	Boolean	是	----	是否上传用户质量。只有开启上报网络质量，其他用户才能通过 getRemoteNetworkQuality 方法获取到该用户的网络质量。

示例代码：

rtcClient.setParameters({
  // RTC 配置私有云服务
  ConfPriCloudAddr: {
    ServerAdd: "x.x.x.x",
    Port: 6080,
    Wss: false,
  },
  // RTC 配置事件上报服务
  ConfPriEventAddr: {
    ServerAdd: "x.x.x.x",
  },
  // RTC 配置 TurnSvr
  SetTurnSvr: {
    Uri: "x.x.x.x",
    Account: "xxxxxx",
    Pwd: "******",
  },
  // RTC 配置上传用户质量
  UserQuality: {
    Enable: false,
  },
  ...
});