Interface IAgoraRTC

Agora Web SDK NG 的入口。

Hierarchy

  • IAgoraRTC

Index

Global Callback Properties

Optional onAudioAutoplayFailed

onAudioAutoplayFailed: undefined | function

音频轨道自动播放失败回调。

该回调在音频轨道自动播放失败的时候触发。音频自动播放失败是因为浏览器的自动播放策略导致的,视频轨道的播放不受此影响。

在 Agora Web SDK NG 中,只要用户和页面发生过一次点击交互,就会自动解锁浏览器音频自动播放的限制,所以针对音频自动播放有两种解决方案:

  • 如果不希望收到 onAudioAutoplayFailed 回调,就确保在调用 RemoteAudioTrack.playLocalAudioTrack.play 之前用户已经和页面发生了点击交互。
  • 如果无法保证在调用 RemoteAudioTrack.playLocalAudioTrack.play 之前用户已经和页面发生点击交互,就监听 onAudioAutoplayFailed 回调,通过回调在页面上显示一个按钮引导用户点击。

    无论使用何种方案,只要浏览器启用了自动播放策略,都需要用户至少触发一次点击交互操作才能播放音频。随着用户使用某个页面的次数变多,浏览器会在这个页面上默认关闭自动播放策略,此时不需要任何交互也可以播放音频了,但是我们无法通过 JavaScript 去感知浏览器这个行为。

下面的示例代码演示了当检测到自动播放失败后的处理:在页面上动态显示一个按钮让用户点击。

需要注意的是,短时间内可能会有多个音频轨道对象都调用了 play(),此时会触发多次 onAudioAutoplayFailed。示例代码中通过 isAudioAutoplayFailed 这个对象防止创建重复的按钮对象。

 let isAudioAutoplayFailed = false;
 AgoraRTC.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);
};

Optional onCameraChanged

onCameraChanged: undefined | function

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

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

注意事项:当该回调提示有设备被添加时,如果该设备是虚拟设备,可能无法采集到音频或视频。

AgoraRTC.onCameraChanged = (info) => {
  console.log("camera changed!", info.state, info.device);
};

Parameters

  • deviceInfo:设备信息,详见 DeviceInfo

Optional onMicrophoneChanged

onMicrophoneChanged: undefined | function

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

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

注意事项:当该回调提示有设备被添加时,如果该设备是虚拟设备,可能无法采集到音频或视频。

AgoraRTC.onMicrophoneChanged = (info) => {
  console.log("microphone changed!", info.state, info.device);
};

Parameters

  • deviceInfo:设备信息,详见 DeviceInfo

Optional onPlaybackDeviceChanged

onPlaybackDeviceChanged: undefined | function

自从
   4.1.0

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

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

AgoraRTC.onPlaybackDeviceChanged = (info) => {
  console.log("speaker changed!", info.state, info.device);
};

Parameters

  • deviceInfo:设备信息,详见 DeviceInfo

Other Properties

VERSION

VERSION: string

Agora Web SDK NG 的版本信息。

setArea

setArea: function

自从
   4.2.0

设置访问区域。

该功能为高级设置,适用于有访问安全限制的场景。

默认情况下,SDK 会就近选择 Agora 服务器进行连接。设置访问区域之后,SDK 只会连接到指定区域内的 Agora 服务器。

注意事项:仅支持指定单个访问区域。

param

服务器的访问区域,详见 AREAS

Type declaration

    • Parameters

      Returns void

Agora Core Methods

createClient

  • 创建一个客户端对象用于通话/直播管理,通常来说这是使用 Agora Web SDK NG 的第一步。

    Parameters

    • config: ClientConfig

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

    Returns IAgoraRTCClient

Local Track Methods

createBufferSourceAudioTrack

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

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

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

    Parameters

    Returns Promise<IBufferSourceAudioTrack>

    返回的音频轨道对象相对于普通的音频轨道对象增加了一些控制音频播放流程的方法。包括播放、暂停、跳转、实时播放状态获取等。

createCameraVideoTrack

createCustomAudioTrack

createCustomVideoTrack

createMicrophoneAndCameraTracks

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

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

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

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

    Parameters

    Returns Promise<[IMicrophoneAudioTrack, ICameraVideoTrack]>

createMicrophoneAudioTrack

createScreenVideoTrack

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

    Parameters

    • config: ScreenVideoTrackInitConfig

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

    • withAudio: "enable"

      屏幕共享时是否同时分享屏幕共享输入源的音频。

      • enable: 分享音频。
      • disable: (默认)不分享音频。
      • auto: 根据浏览器是否支持决定是否分享音频。

        注意事项:

        • 该功能仅支持 Windows 和 macOS 平台下的 Chrome 浏览器 74 及以上版本。
        • Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频,不支持在共享应用窗口时分享音频。macOS 平台仅支持在共享 Chrome 标签页时分享音频。
        • 设置了 withAudioenable 后,还需要在屏幕共享的弹出框上,勾选分享音频才能真正生效。

    Returns Promise<[ILocalVideoTrack, ILocalAudioTrack]>

    • 如果 withAudio 设为 enable,返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选分享音频,SDK 会抛出错误。
    • 如果 withAudio 设为 disable,返回屏幕共享的视频轨道。
    • 如果 withAudio 设为 auto,在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。
      • 如果用户勾选了分享音频,会返回包含屏幕共享视频轨道和一个音频轨道的列表。
      • 如果用户没有勾选分享音频,只返回屏幕共享视频轨道。
  • 创建用于屏幕共享的视频轨道。

    Parameters

    • config: ScreenVideoTrackInitConfig

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

    • withAudio: "disable"

      屏幕共享时是否同时分享屏幕共享输入源的音频。

      • enable: 分享音频。
      • disable: (默认)不分享音频。
      • auto: 根据浏览器是否支持决定是否分享音频。

        注意事项:

        • 该功能仅支持 Windows 和 macOS 平台下的 Chrome 浏览器 74 及以上版本。
        • Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频,不支持在共享应用窗口时分享音频。macOS 平台仅支持在共享 Chrome 标签页时分享音频。
        • 设置了 withAudioenable 后,还需要在屏幕共享的弹出框上,勾选分享音频才能真正生效。

    Returns Promise<ILocalVideoTrack>

    • 如果 withAudio 设为 enable,返回包含屏幕共享视频轨道和一个音频轨道的列表。如果用户没有勾选分享音频,SDK 会抛出错误。
    • 如果 withAudio 设为 disable,返回屏幕共享的视频轨道。
    • 如果 withAudio 设为 auto,在支持屏幕共享音频的浏览器上 SDK 会默认尝试分享音频。
      • 如果用户勾选了分享音频,会返回包含屏幕共享视频轨道和一个音频轨道的列表。
      • 如果用户没有勾选分享音频,只返回屏幕共享视频轨道。
  • 创建用于屏幕共享的视频轨道。

    Parameters

    • config: ScreenVideoTrackInitConfig

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

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

      屏幕共享时是否同时分享屏幕共享输入源的音频。

      • enable: 分享音频。
      • disable: (默认)不分享音频。
      • auto: 根据浏览器是否支持决定是否分享音频。

        注意事项:

        • 该功能仅支持 Windows 和 macOS 平台下的 Chrome 浏览器 74 及以上版本。
        • Windows 平台支持在共享整个屏幕和共享 Chrome 标签页时分享音频,不支持在共享应用窗口时分享音频。macOS 平台仅支持在共享 Chrome 标签页时分享音频。
        • 设置了 withAudioenable 后,还需要在屏幕共享的弹出框上,勾选分享音频才能真正生效。

    Returns Promise<[ILocalVideoTrack, ILocalAudioTrack] | ILocalVideoTrack>

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

Logger Methods

disableLogUpload

  • disableLogUpload(): void
  • 关闭日志上传。

    日志上传默认是关闭状态,如果你调用了开启日志上传(enableLogUpload),可以通过本方法停止上传日志。

    Returns void

enableLogUpload

  • enableLogUpload(): void
  • 开启日志上传。开启后 SDK 的日志会上传到 Agora 的服务器。

    日志上传功能默认为关闭状态,如果你需要开启此功能,请确保在所有方法之前调用本方法。

    如果没有成功加入频道,则服务器上无法查看日志信息。

    Returns void

setLogLevel

  • setLogLevel(level: number): void
  • 设置 SDK 的日志输出级别。

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

    Parameters

    • level: number

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

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

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

    Returns void

Media Devices Methods

getCameras

  • getCameras(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>
  • 该方法枚举可用的视频输入设备,比如摄像头。

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

    调用本方法会暂时打开摄像头以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上,没有媒体设备权限时无法获取到准确的设备信息。

    Parameters

    • Optional skipPermissionCheck: undefined | false | true

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

      • true: 跳过权限检查。
      • false:(默认)不跳过权限检查。

    Returns Promise<MediaDeviceInfo[]>

getDevices

  • getDevices(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>
  • 该方法枚举可用的媒体输入和输出设备,比如麦克风、摄像头、耳机等。 调用成功后 SDK 会通过 MediaDeviceInfo 对象返回可用的媒体设备。

    调用本方法会暂时打开摄像头和麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上,没有媒体设备权限时无法获取到准确的设备信息。

    getDevices().then(devices => {
      console.log("first device id", devices[0].deviceId);
    }).catch(e => {
      console.log("get devices error!", e);
    });

    Parameters

    • Optional skipPermissionCheck: undefined | false | true

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

      • true: 跳过权限检查。
      • false:(默认)不跳过权限检查。

    Returns Promise<MediaDeviceInfo[]>

getElectronScreenSources

getMicrophones

  • getMicrophones(skipPermissionCheck?: undefined | false | true): Promise<MediaDeviceInfo[]>
  • 该方法枚举可用的音频输入设备,比如麦克风。

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

    调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上,没有媒体设备权限时无法获取到准确的设备信息。

    Parameters

    • Optional skipPermissionCheck: undefined | false | true

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

      • true: 跳过权限检查。
      • false:(默认)不跳过权限检查。

    Returns Promise<MediaDeviceInfo[]>

getPlaybackDevices

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

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

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

    调用本方法会暂时打开麦克风以触发浏览器的媒体设备权限申请。在 Chrome 81+、Firefox、 Safari 等浏览器上,没有媒体设备权限时无法获取到准确的设备信息。

    Parameters

    • Optional skipPermissionCheck: undefined | false | true

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

      • true: 跳过权限检查。
      • false:(默认)不跳过权限检查。

    Returns Promise<MediaDeviceInfo[]>

Other Methods

checkAudioTrackIsActive

  • 检测音频轨道是否活跃。

    SDK 通过检测指定时间范围内音量是否发生变化来判断音频轨道是否活跃。

    Agora 建议通过此方法在开始通话前对音频输入设备进行可用性检测。你可以将麦克风采集到的音频轨道作为参数传入该方法,判断麦克风是否正常运行。

    注意事项:

    • 极为安静的环境下可能检测失败,所以 Agora 建议你在使用此方法的时候提示用户发出声响。
    • 当音频轨道被 mute 时,会返回 false
    • 不建议频繁调用此方法。
    const audioTrack = await AgoraRTC.createMicrophoneAudioTrack({ microphoneId });
    AgoraRTC.checkAudioTrackIsActive(audioTrack).then(result => {
      console.log(`${ microphoneLabel } is ${ result ? "available" : "unavailable" }`);
    }).catch(e => {
      console.log("check audio track error!", e);
    });

    Parameters

    • track: ILocalAudioTrack | IRemoteAudioTrack

      需要进行检测的本地或远端音频轨道。

    • Optional timeout: undefined | number

      音频轨道检测的超时时间,单位为毫秒,默认 5,000 毫秒。

    Returns Promise<boolean>

    传入该方法的音频轨道中的音量大小是否发生了变化:

    • true: 音量大小有变化。对于麦克风音频轨道,说明音频采集设备采集到了声音。
    • false: 音量大小未变化,说明音频采集设备没有采集到声音,或自定义音频轨道中没有音量变化,或音频轨道被 mute。

checkSystemRequirements

  • checkSystemRequirements(): boolean
  • 检查 Agora Web SDK NG 对正在使用的浏览器的适配情况。

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

    Returns boolean

    是否支持当前浏览器。

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

checkVideoTrackIsActive

  • 检测视频轨道是否活跃。

    SDK 通过检测指定时间范围内视频图像是否发生变动来判断视频轨道是否活跃。

    Agora 建议通过此方法在开始通话前对视频输入设备进行可用性检测。你可以将摄像头采集到的视频轨道作为参数传入该方法,判断摄像头是否正常运行。

    注意事项:

    • 当视频轨道被 mute 时,会返回 false
    • 不建议频繁调用此方法。
    const videoTrack = await AgoraRTC.createCameraVideoTrack({ cameraId });
    AgoraRTC.checkVideoTrackIsActive(videoTrack).then(result => {
      console.log(`${ cameraLabel } is ${ result ? "available" : "unavailable" }`);
    }).catch(e => {
      console.log("check video track error!", e);
    });

    Parameters

    • track: ILocalVideoTrack | IRemoteVideoTrack

      需要进行检测的本地或远端视频轨道。

    • Optional timeout: undefined | number

      视频轨道检测的超时时间,单位为毫秒,默认 5,000 毫秒。

    Returns Promise<boolean>

    传入该方法的视频轨道中的图像是否发生了变动:

    • true: 视频画面发生变动。对于摄像头视频轨道,说明视频采集设备采集到了画面。
    • false: 视频画面未变动,说明视频采集设备异常或被完全遮挡,或视频轨道被 mute。

createChannelMediaRelayConfiguration

getSupportedCodec

  • getSupportedCodec(): Promise<object>
  • 获取 Agora Web SDK NG 对当前浏览器支持的编解码格式。

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

    注意事项:

    • 该方法支持所有浏览器。对于不支持 WebRTC 或无法识别的浏览器环境,编解码列表返回为空。
    • 返回的音视频编码为浏览器通过 SDP 声称的编码类型,为参考值。
    • 目前部分安卓手机 H.264 与其他平台 H.264 存在无法互通或单通问题,对于这部分机型推荐使用 VP8 编码格式。
    AgoraRTC.getSupportedCodec().then(result => {
     console.log(`Supported video codec: ${result.video.join(",")});
     console.log(`Supported audio codec: ${result.audio.join(",")});
    });

    Returns Promise<object>

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

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