ArRTC

Web SDK 的入口。

SDK 会在全局导出一个 ArRTC 对象，直接访问这个对象即可操作 SDK。ArRTC 包含了以下方法和属性：

import ArRTC from "ar-rtc-sdk";

属性

VERSION

VERSION: string

anyRTC Web SDK 的版本信息。

console.log("anyRTC Web SDK 的版本!", ArRTC.VERSION);

全局事件回调

onCameraChanged

onCameraChanged?: (deviceInfo: DeviceInfo) => void

视频采集设备状态变化回调。

该回调提示有摄像头被添加或移除。

只有在 HTTPS 环境或者本地 localhost、127.0.0.1 下才会被触发。

/**
 * 视频采集设备状态变化回调。
 * @params info: 视频采集设备的信息 详见 DeviceInfo
 */
ArRTC.onCameraChanged = (info) => {
  console.log("camera changed!", info.state, info.device);
};

参数 设备信息，详见 DeviceInfo。

onMicrophoneChanged

onMicrophoneChanged?: (deviceInfo: DeviceInfo) => void

音频采集设备状态变化回调。

该回调提示有麦克风被添加或移除。

只有在 HTTPS 环境或者本地 localhost、127.0.0.1 下才会被触发。

/**
 * 音频采集设备状态变化回调。
 * @params info: 音频采集设备的信息 详见 DeviceInfo
 */
ArRTC.onMicrophoneChanged = (info) => {
  console.log("microphone changed!", info.state, info.device);
};

参数 设备信息，详见 DeviceInfo。

onPlaybackDeviceChanged

onPlaybackDeviceChanged?: (deviceInfo: DeviceInfo) => void

音频播放设备状态变化回调。

该回调提示有音频播放设备被添加或移除。

只有在 HTTPS 环境或者本地 localhost、127.0.0.1 下才会被触发。

/**
 * 音频播放设备状态变化回调。
 * @params info: 音频设备的信息 详见 DeviceInfo
 */
ArRTC.onPlaybackDeviceChanged = (info) => {
  console.log("speaker changed!", info.state, info.device);
};

参数 设备信息，详见DeviceInfo。

onAudioAutoplayFailed

onAudioAutoplayFailed?: () => void

音频自动播放失败回调。

该回调触发通常是因为浏览器的 自动播放策略 变更导致的，媒体进行自动播放时，会被该策略暂停。

Chrome 71 版本之后，该策略正式发布。为了更好的用户体验（比如：广告污染），需要用户交互触发，也就是说需要用户自己手动点击。

Web SDK 内部做了一些兼容的处理，提供以下几种方法，来恢复自动播放：

• 1. 用户在浏览器进行交互时会自动恢复音频播放，比如：页面点击、页面滚动等，届时会自动恢复播放。
• 2. 收到该回调，在页面引导用户去点击触发交互行为。

/**
 * 音频自动播放失败回调。
 */
let isAudioAutoplayFailed = false;
ArRTC.onAudioAutoplayFailed = () => {
  if (isAudioAutoplayFailed) return;
  isAudioAutoplayFailed = true;
  const btn = document.createElement("button");
  btn.innerText = "Click me to resume the audio playback";
  btn.onclick = () => {
    isAudioAutoplayFailed = false;
    btn.remove();
  };
  document.body.append(btn);
};

核心方法

createClient

createClient(config: ClientConfig): IArRTCClient

创建一个客户端对象。

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

/**
 * 创建一个客户端
 * 返回值 rtcClient，详情请查看 ArRTCClient
 */
var rtcClient = ArRTC.createClient(config);
...

参数

• config: ClientConfig

  客户端的配置，包括通话场景、编码格式等，默认使用 vp8 编码，rtc 通话场景。详见 ClientConfig。

返回值 IArRTCClient

本地轨道方法

createBufferSourceAudioTrack

createBufferSourceAudioTrack(config: BufferSourceAudioTrackInitConfig): Promise<IBufferSourceAudioTrack>

通过音频文件或者 AudioBuffer 对象创建一个音频轨道。

该方法支持本地和在线音频文件。音频文件支持以下音频格式：

• MP3
• AAC
• 浏览器支持的其他音频格式

/**
 * 通过音频文件或者 AudioBuffer 对象创建一个音频轨道。
 * @params config 配置指定文件路径、缓存策略和编码配置 详情请见 BufferSourceAudioTrackInitConfig
 * @params audioTrack 直接通过音频数据源创建的音频轨道 详情请见返回值 BufferSourceAudioTrack
 */
ArRTC.createBufferSourceAudioTrack(config).then((audioTrack) => {
  ...
});

参数

• config: BufferSourceAudioTrackInitConfig

  通过该配置指定文件路径、缓存策略和编码配置。

返回值 IBufferSourceAudioTrack

createCameraVideoTrack

createCameraVideoTrack(config?: CameraVideoTrackInitConfig): Promise<ICameraVideoTrack>

通过摄像头采集的视频创建一个视频轨道。

使用同一个摄像头多次采集摄像头的不同分辨率时，画面会模糊，原因是一个摄像头不能同时采集多种分辨率。如果项目真实需要，我们可以使用以下方法实现：
1.多摄像头采集 —— 采集时指定另外一个摄像头。
2.单摄像头采集 —— 调用第一次采集获取到的 videoTrack 的 setEncoderConfiguration 方法，动态调整分辨率。
3.单摄像头采集 —— 释放第一次采集到的 track，然后重新采集。建议使用上面的方法。

/**
 * 通过摄像头采集的视频创建一个视频轨道。
 * @params config 配置指定文件路径、缓存策略和编码配置 详情请见 CameraVideoTrackInitConfig
 * @params videoTrack 本地摄像头视频轨道 详情请见返回值 CameraVideoTrack
 */
ArRTC.createCameraVideoTrack(config).then((videoTrack) => {
  ...
});

参数

• Optional config: CameraVideoTrackInitConfig

  通过该配置指定文件路径、缓存策略和编码配置。详见 CameraVideoTrackInitConfig。

返回值 Promise<ICameraVideoTrack>

createCustomAudioTrack

createCustomAudioTrack(config: CustomAudioTrackInitConfig): ILocalAudioTrack

创建一个自定义的音频轨道。

你可以使用这个方法将自己维护的 MediaStreamTrack 转换成一个可以用于 SDK 的音频轨道。

/**
 * 创建一个自定义的音频轨道
 * @params config 自定义音频的配置 详情请见 CustomAudioTrackInitConfig
 * @params audioTrack 自定义的音频轨道 详情请见返回值 LocalAudioTrack
 */
ArRTC.createCustomAudioTrack(config).then((audioTrack) => {
  ...
});

参数

• config: CustomAudioTrackInitConfig

  自定义音频的配置，详见 CustomAudioTrackInitConfig。

返回值 ILocalAudioTrack

createCustomVideoTrack

createCustomVideoTrack(config: CustomVideoTrackInitConfig): ILocalVideoTrack

创建一个自定义的视频轨道。

你可以使用这个方法将自己维护的 MediaStreamTrack 转换成一个可以用于 SDK 的视频轨道。

/**
 * 创建一个自定义的视频轨道。
 * @params config 自定义视频的配置 详情请见 CustomVideoTrackInitConfig
 * @params videoTrack 本地摄像头视频轨道 详情请见返回值 LocalVideoTrack
 */
ArRTC.createCustomVideoTrack(config).then((videoTrack) => {
  ...
});

参数

• config: CustomVideoTrackInitConfig

  自定义视频轨道的配置，详见 CustomVideoTrackInitConfig。

  自定义视频轨道无法设置具体的编码参数，只能通过 config 来设置发送码率。

返回值 ILocalVideoTrack

createMicrophoneAndCameraTracks

createMicrophoneAndCameraTracks(audioConfig?: MicrophoneAudioTrackInitConfig, videoConfig?: CameraVideoTrackInitConfig): Promise<[IMicrophoneAudioTrack, ICameraVideoTrack]>

同时创建麦克风音频轨道和摄像头视频轨道。

通过麦克风采集的音频创建一个音频轨道，同时通过摄像头采集的视频创建一个视频轨道。

调用该方法和分别调用 createMicrophoneAudioTrack 以及 createCameraVideoTrack 的区别是：

调用该方法会同时要求麦克风和摄像头的授权，用户只需授权一次。 分别创建音频轨道和视频轨道需要用户分别对麦克风和摄像头进行授权，也就是说用户需要授权两次。

/**
 * 同时创建麦克风音频轨道和摄像头视频轨道。
 * @params audioConfig 采集音频的配置，包括采集设备、编码配置等 详情请见 MicrophoneAudioTrackInitConfig
 * @params videoConfig 采集视频的配置，包括采集设备、编码配置等 详情请见 CameraVideoTrackInitConfig
 * @params audioTrack 本地麦克风音频轨道 详情请见返回值 MicrophoneAudioTrack
 * @params videoTrack 本地摄像头视频轨道 详情请见返回值 CameraVideoTrack
 */
ArRTC.createMicrophoneAndCameraTracks(audioConfig, videoConfig).then(([audioTrack, videoTrack]) => {
  ...
});

参数

• Optional audioConfig: MicrophoneAudioTrackInitConfig

  采集音频的配置，包括采集设备、编码配置等。

• Optional videoConfig: CameraVideoTrackInitConfig

  采集视频的配置，包括采集设备、编码配置等。

返回值 Promise<[IMicrophoneAudioTrack, ICameraVideoTrack]>

createMicrophoneAudioTrack

createMicrophoneAudioTrack(config?: MicrophoneAudioTrackInitConfig): Promise<IMicrophoneAudioTrack>

通过麦克风采集的音频创建一个音频轨道。

/**
 * 通过麦克风采集的音频创建一个音频轨道。
 * @params audioConfig 麦克风采集音频的配置，包括采集设备、音频编码配置等 详情请见 MicrophoneAudioTrackInitConfig
 * @params audioTrack 本地麦克风音频轨道 详情请见返回值 MicrophoneAudioTrack
 */
ArRTC.createMicrophoneAudioTrack(audioConfig).then((audioTrack) => {
  ...
});

参数

• audioConfig: MicrophoneAudioTrackInitConfig

  麦克风采集音频的配置，包括采集设备、音频编码配置等，详见 MicrophoneAudioTrackInitConfig。

返回值 Promise<IMicrophoneAudioTrack>

createScreenVideoTrack

createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "enable"): Promise<[ILocalVideoTrack, ILocalAudioTrack]>
createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio: "disable"): Promise<ILocalVideoTrack>
createScreenVideoTrack(config: ScreenVideoTrackInitConfig, withAudio?: "enable" | "disable" | "auto"): Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

创建用于屏幕共享的视频轨道。

多次采集屏幕共享，画面会模糊，原因是因为不能同时采集不同分辨率的画面。如果项目需要，我们可以释放第一次采集到的 ScrenVideoTrack，然后重新采集。

/**
 * 创建用于屏幕共享的视频轨道。
 * @params config 屏幕共享的视频配置，包括编码配置、采集配置等 详情请见 ScreenVideoTrackInitConfig
 * @params withAudio 标记屏幕共享时是否同时分享设备输出的音频 详情请见
 * @params audioTrack 本地麦克风音频轨道 详情请见返回值 LocalAudioTrack
 * @params videoTrack 本地摄像头视频轨道 详情请见返回值 LocalVideoTrack
 */
ArRTC.createScreenVideoTrack(config, withAudio).then(([audioTrack, videoTrack]) => {
  ...
});

参数

• config: ScreenVideoTrackInitConfig

  屏幕共享的视频配置，包括编码配置、采集配置等。

• withAudio: "enable" | "disable" | "auto"

  标记屏幕共享时是否同时分享设备输出的音频。

  • "enable": 分享设备输出的音频。

  • "disable": 不分享设备输出的音频。

  • "auto": 自动判断是否支持音频分享，如果支持音频则分享。

    注意事项：
    该功能仅支持 Windows 平台下的 Chrome 浏览器 73 及以上版本。
    设置了 withAudio 为 "enable" 后，还需要在屏幕共享的弹出框上，勾选分享音频才能真正生效。

返回值 Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

• 如果 withAudio 设为 "enable"，返回包含屏幕共享视频轨道和一个音频轨道的列表。
• 如果 withAudio 设为 "disable" 或未设置，返回屏幕共享的视频轨道。
• 如果 withAudio 设为 auto，在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。
  • 如果用户勾选了分享音频，会返回包含屏幕共享视频轨道和一个音频轨道的列表。
  • 如果用户没有勾选分享音频，只返回屏幕共享视频轨道。

日志方法

setLogLevel

setLogLevel(level: number): void

设置 SDK 的日志输出级别。

选择一个级别，你就可以看到在该级别及该级别以上所有级别的日志信息。

参数

• level: number

  SDK 日志输出级别。按照输出日志最全到最少排列：

  • 0: DEBUG。输出所有的 SDK 日志。
  • 1: INFO。输出 INFO、WARNING 和 ERROR 级别的日志。
  • 2: WARNING。输出 WARNING 和 ERROR 级别的日志。
  • 3: ERROR。输出 ERROR 级别的日志。
  • 4: NONE。不输出日志。

  例如，如果你输入代码 ArRTC.setLogLevel(1);，就可以看到 INFO，WARNING 和 ERROR 级别的日志信息。

返回值 void

媒体设备查询

getCameras

getCameras(skipPermissionCheck: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的视频输入设备，比如摄像头。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的视频输入设备。

注意：
1. 在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
2. 调用本方法如果获取不到摄像头信息或者获取到的摄像头数量与实际摄像头数量不符时，可能是由于浏览器安全策略对获取摄像头的行为做了限制，可以尝试在 localhost、127.0.0.1 或者安全的 https 环境下进行该操作。

示例

/**
 * 枚举可用的视频输入设备
 * @params cameras 可用的视频输入设备 (类型：array)
 */
ArRTC.getCameras()
  .then((cameras) => {
    console.log("可用的视频输入设备", cameras);
  })
  .catch((e) => {
    console.log(e);
  });

参数

• Optional skipPermissionCheck: undefined | false | true

  是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

  • true: 跳过权限检查。
  • false:（默认）不跳过权限检查。

返回值 Promise<MediaDeviceInfo[]>

getDevices

getDevices(skipPermissionCheck: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的媒体输入/输出设备，比如麦克风、摄像头、耳机等。 调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的媒体设备。

注意：
1. 在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
2. 调用本方法如果获取不到摄像头信息或者获取到的摄像头数量与实际摄像头数量不符时，可能是由于浏览器安全策略对获取摄像头的行为做了限制，可以尝试在 localhost、127.0.0.1 或者安全的 https 环境下进行该操作。

示例

/**
 * 枚举可用的媒体输入/输出设备
 * @params devices 可用的媒体设备 (类型：array)
 */
ArRTC.getDevices()
  .then((devices) => {
    console.log("可用的媒体设备", devices);
  })
  .catch((e) => {
    console.log(e);
  });

参数

• Optional skipPermissionCheck: undefined | false | true

  是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

  • true: 跳过权限检查。
  • false:（默认）不跳过权限检查。

返回值 Promise<MediaDeviceInfo[]>

getElectronScreenSources

getElectronScreenSources(type?: ScreenSourceType): Promise<ElectronDesktopCapturerSource[]>

在 Electron 环境下获取屏幕共享源。

调用成功后 SDK 会返回一组 ElectronDesktopCapturerSource 对象。

/**
 * 在 Electron 环境下获取屏幕共享源
 * @params type 共享源类型，详情请看 ScreenSourceType
 * @params desktopcapturersource 屏幕共享源信息 (类型：array)
 */
var type = "screen";
ArRTC.getElectronScreenSources(type)
  .then((desktopcapturersource) => {
    console.log("获取的屏幕共享源信息", desktopcapturersource);
  })
  .catch((e) => {
    console.log(e);
  });

参数

• Optional type: ScreenSourceType

  需要获取的共享源类型（窗口/应用/屏幕），详见 ScreenSourceType。如果为空则获取所有可以获取的共享源。

返回值 Promise<ElectronDesktopCapturerSource[]>

getMicrophones

getMicrophones(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的音频输入设备，比如麦克风。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频输入设备。

注意：
1. 在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
2. 调用本方法如果获取不到摄像头信息或者获取到的摄像头数量与实际摄像头数量不符时，可能是由于浏览器安全策略对获取摄像头的行为做了限制，可以尝试在 localhost、127.0.0.1 或者安全的 https 环境下进行该操作。

示例

/**
 * 枚举可用的音频输入设备
 * @params microhones 可用的音频输入设备 (类型：array)
 */
ArRTC.getMicrophones()
  .then((microhones) => {
    console.log("可用的音频输入设备", microhones);
  })
  .catch((e) => {
    console.log(e);
  });

参数

• Optional skipPermissionCheck: undefined | false | true

  是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

  • true: 跳过权限检查。
  • false:（默认）不跳过权限检查。

返回值 Promise<MediaDeviceInfo[]>

getPlaybackDevices

getPlaybackDevices(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>

该方法枚举可用的音频播放设备，比如扬声器。

调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的音频播放设备。

注意：
1. 在 Chrome 81+、Firefox、 Safari 等浏览器上，没有媒体设备权限时无法获取到准确的设备信息。
2. 调用本方法如果获取不到摄像头信息或者获取到的摄像头数量与实际摄像头数量不符时，可能是由于浏览器安全策略对获取摄像头的行为做了限制，可以尝试在 localhost、127.0.0.1 或者安全的 https 环境下进行该操作。

示例

/**
 * 枚举可用的音频播放设备
 * @params devices 可用的音频播放设备 (类型：array)
 */
ArRTC.getPlaybackDevices()
  .then((devices) => {
    console.log("可用的音频播放设备", devices);
  })
  .catch((e) => {
    console.log(e);
  });

参数

• Optional skipPermissionCheck: undefined | false | true

  是否跳过权限检查。你可以通过将该参数设置成 true 来跳过媒体设备权限申请步骤，但是 SDK 无法保证可以通过本方法获取准确的媒体设备信息。

  • true: 跳过权限检查。
  • false:（默认）不跳过权限检查。

返回值 Promise<MediaDeviceInfo[]>

其他方法

checkSystemRequirements

checkSystemRequirements(): boolean

检查 anyRTC Web SDK 对正在使用的浏览器的适配情况。

注意：
该方法必须在创建客户端对象 createClient 之前调用。

/**
 * 检查 anyRTC Web SDK 对正在使用的浏览器的适配情况。（必须在创建客户端对象之前调用）
 * @params boolean 正在使用的浏览器的适配情况 (类型：boole)
 */
ArRTC.checkSystemRequirements()
  .then((boolean) => {
    console.log("正在使用的浏览器的适配情况", boolean);
  })
  .catch((e) => {
    console.log(e);
  });

返回值 boolean

是否支持当前浏览器。

• true: 支持。
• false: 不支持。

getSupportedCodec

getSupportedCodec(): Promise<object>

获取 anyRTC Web SDK 对当前浏览器支持的编解码格式。

调用该方法会返回 anyRTC 服务与当前浏览器同时支持的编解码格式。目前而言，视频支持 VP8 及 H.264 格式，音频支持 OPUS 格式。

注意事项：
该方法支持所有浏览器。对于不支持 WebRTC 或无法识别的浏览器环境，编解码列表返回为空。
返回的音视频编码为浏览器通过 SDP 声称的编码类型，为参考值。
目前部分安卓手机 H.264 与其他平台 H.264 存在无法互通或单通问题，对于这部分机型推荐使用 VP8 编码格式。

/**
 * 获取 anyRTC Web SDK 对当前浏览器支持的编解码格式。
 * @params result anyRTC 服务与当前浏览器同时支持的编解码格式 (类型：object)
 */
ArRTC.getSupportedCodec().then(result => {
 console.log(`Supported video codec: ${result.video.join(",")}`);
 console.log(`Supported audio codec: ${result.audio.join(",")}`);
});

返回值 Promise<object>

调用该方法会返回一个 Promise 对象，在 .then(function(result){}) 回调中，result 包含以下属性：

• video: 数组类型，支持的视频编解码格式。可能含有 "H264"、"VP8" 两种取值，或为空数组。
• audio: 数组类型，支持的音频编解码格式。可能含有 "OPUS"，或为空数组。