Agora Web SDK API Reference

EnumerationsCopy Anchor Link

• AREAS
• AppType
• AudienceLatencyLevelType
• AudioCodec
• ChannelMediaRelayError
• ChannelMediaRelayEvent
• ChannelMediaRelayState
• ConnectionDisconnectedReason
• ImageModerationConnectionState
• InspectState
• RemoteStreamFallbackType
• RemoteStreamType
• SIMULCAST_STREAM_MODE
• StreamType
• VideoCodec
• VideoState

ClassesCopy Anchor Link

• EventEmitter

InterfacesCopy Anchor Link

• AgoraRTCStats
• AudioEncoderConfiguration
• AudioSourceOptions
• AudioTrackInitConfig
• BufferSourceAudioTrackInitConfig
• CameraVideoTrackInitConfig
• ChannelMediaRelayInfo
• ClientConfig
• ClientRoleOptions
• ConstrainLong
• CustomAudioTrackInitConfig
• CustomVideoTrackInitConfig
• DeviceInfo
• ElectronDesktopCapturerSource
• EventCustomReportParams
• IAgoraRTC
• IAgoraRTCClient
• IAgoraRTCRemoteUser
• IBufferSourceAudioTrack
• ICameraVideoTrack
• IChannelMediaRelayConfiguration
• IJoinOptions
• ILocalAudioTrack
• ILocalTrack
• ILocalVideoTrack
• IMicrophoneAudioTrack
• IRemoteAudioTrack
• IRemoteTrack
• IRemoteVideoTrack
• ImageModerationConfiguration
• ImageTypedData
• InspectConfiguration
• LastmileProbeResult
• LiveStreamingTranscodingConfig
• LiveStreamingTranscodingImage
• LiveStreamingTranscodingUser
• LocalAudioTrackStats
• LocalVideoTrackStats
• LowStreamParameter
• MicrophoneAudioTrackInitConfig
• NetworkQuality
• RTMConfiguration
• RemoteAudioTrackStats
• RemoteVideoTrackStats
• ScreenVideoTrackInitConfig
• VideoEncoderConfiguration
• VideoPlayerConfig
• VisibleHiddenResult

Type aliasesCopy Anchor Link

AudioEncoderConfigurationPresetCopy Anchor Link

AudioEncoderConfigurationPreset: keyof typeof AUDIO_ENCODER_CONFIG_SETTINGS

你可以在以下方法中传入预设值来控制本地音频的编码配置：

• AgoraRTC.createCustomAudioTrack
• AgoraRTC.createMicrophoneAudioTrack
• AgoraRTC.createBufferSourceAudioTrack

下表列出了 SDK 所有内置的音频属性配置，SDK 默认使用 "music_standard"。

AudioSourceStateCopy Anchor Link

AudioSourceState: "stopped"|"playing"|"paused"

音频源数据处理状态，通过 BufferSourceAudioTrack.on("source-state-change") 获取。

• "stopped": 音频源数据处理停止。可能是因为数据处理完毕，也可能是手动触发了停止。
• "playing": 音频源数据正在处理。
• "paused": 音频源数据暂停处理。

CheckVideoVisibleResultCopy Anchor Link

CheckVideoVisibleResult: CheckVisibleResult

<video> 标签的可见状态信息。

可通过以下方法或事件获取：

• localVideoTrack.on("video-element-visible-status")
• localVideoTrack.getVideoElementVisibleStatus
• remoteVideoTrack.on("video-element-visible-status")
• remoteVideoTrack.getVideoElementVisibleStatus

包含以下字段：

• visible: Boolean 型，<video> 标签是否可见。

• reason: 仅当 visible 为 false 时有效，不可见原因：

  • "SIZE": <video> 尺寸太小，导致 <video> 完全不可见或很难看到。
  • "STYLE": <video> 或其祖先元素的 CSS 样式导致 <video> 不可见、颜色暗淡或模糊不清。
  • "POSITION": <video> 或其祖先元素被定位到视口区域外，导致 <video> 只有小面积区域在视口内或全部不在视口内。
  • "COVERED": <video> 被其他元素遮挡。

ClientRoleCopy Anchor Link

ClientRole: "audience"|"host"

用户角色。

• "host": 直播场景中的主播，可以发布和订阅音视频轨道。
• "audience": 直播场景中的观众，只能订阅，不能发布音视频轨道。

ConnectionStateCopy Anchor Link

ConnectionState: "DISCONNECTED"|"CONNECTING"|"RECONNECTING"|"CONNECTED"|"DISCONNECTING"

SDK 和声网服务器的连接状态，可以通过 connectionState 获取。

SDK 和服务器有以下 5 种连接状态:

• "DISCONNECTED": 连接断开。该状态表示用户处于以下任一阶段：

  • 尚未通过 join 加入频道。
  • 已经通过 leave 离开频道。
  • 被踢出频道或者连接失败等异常情况。

• "CONNECTING": 正在连接中。当调用 join 时为此状态。

• "CONNECTED": 已连接。该状态表示用户已经加入频道，可以在频道内发布或订阅媒体流。

• "RECONNECTING": 正在重连中。因网络断开或切换而导致 SDK 与服务器的连接中断，SDK 会自动重连，此时连接状态变为 "RECONNECTING"。

• "DISCONNECTING": 正在断开连接。在调用 leave 的时候为此状态。

DeviceStateCopy Anchor Link

DeviceState: "ACTIVE"|"INACTIVE"

采集设备当前的插拔状态。

• "ACTIVE": 该设备已经插入。
• "INACTIVE": 该设备已经被拔出。

EncryptionModeCopy Anchor Link

EncryptionMode: "aes-128-xts"|"aes-256-xts"|"aes-128-ecb"|"sm4-128-ecb"|"aes-128-gcm"|"aes-256-gcm"|"aes-128-gcm2"|"aes-256-gcm2"|"none"

加密方案，在调用 setEncryptionConfig 时使用。包含以下几种：

• "aes-128-xts": 128 位 AES 加密，XTS 模式。
• "aes-256-xts": 256 位 AES 加密，XTS 模式。
• "aes-128-gcm": 128 位 AES 加密，GCM 模式。
• "aes-256-gcm": 256 位 AES 加密，GCM 模式。
• "aes-128-gcm2": 128 位 AES 加密，GCM 模式，加盐。
• "aes-256-gcm2": 256 位 AES 加密，GCM 模式，加盐。
• "aes-128-ecb": 128 位 AES 加密，ECB 模式。
• "sm4-128-ecb": 128 位 SM4 加密，ECB 模式。
• "none": 不加密。

LocalAccessPointConfigCopy Anchor Link

LocalAccessPointConfig: object&object

混合云/私有化平台的配置参数。用于 setLocalAccessPointsV2 方法。

• accessPoints：访问节点，包含以下属性：

  • serverList：IP 地址列表或 hostname（主机名，用于指定 SDK 访问的 Agora SD-RTN™ 边缘节点）列表。
  • domain：域名。如果传入的 serverList 为 IP 地址列表，SDK 会拼接传入的 IP 地址和 domain 生成 hostname 列表。此时 domain 用于指定 SDK 接入 Agora SD-RTN™ 的网关。
  • port：（可选）端口号。如果传入，端口号会和 hostname 拼在一起。

• log：（可选）日志上传服务。包含可选属性 hostname 和 port。如果要设置日志上传服务，请确保你已经调用 enableLogUpload 开启 SDK 的日志上传功能。

• report：（可选）事件上报服务。默认关闭。包含可选属性 hostname 和 port。

• cds：预留参数，暂不支持。

可选属性如果不填，将使用对应的默认值：

client.setLocalAccessPointsV2({
  accessPoints: {
    serverList:["192.168.1.1","192.168.2.2"],
    domain: 'test.agora.io'
  },
  // 必须先调用 enableLogUpload，下面的日志服务设置才生效
  log:{
    hostname:["abc.com"],
    port: 3000
  },
  // 开启事件上报服务并配置参数
  report:{
    hostname:["example.com"],
    port: 8080
  }
})

OptimizationModeCopy Anchor Link

OptimizationMode: "motion"|"detail"|"balanced"

视频传输优化模式：

• "detail": 清晰优先。

  • 浏览器会自动根据你的采集分辨率和帧率设定一个最小码率。即使遭遇网络波动，发送码率也不会低于这个值，从而确保清晰的视频画面。
  • 大部分情况下，浏览器不会降低发送分辨率，但是可能会降低帧率。

• "motion": 自 4.21.0 开始，浏览器默认开启流畅优先模式。

  • 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。
  • 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。

• "balanced": 默认的传输优化模式。

  • 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。
  • 对于其他视频流，SDK 默认的优化策略为坚固清晰合流畅，弱网条件下，帧率和分辨率都会被调整。

RequiredOnlyOneOfCopy Anchor Link

RequiredOnlyOneOf<T, K>: object[K] extends infer O? object: never

SDK_CODECCopy Anchor Link

SDK_CODEC: keyof typeof VideoCodec

浏览器使用的编码格式，有以下选择：

• "vp8": 浏览器使用 VP8 编码。
• "h264": 浏览器使用 H.264 编码。
• "vp9": (Beta) 浏览器使用 VP9 编码。
• "av1": (Beta) 浏览器使用 AV1 编码。
• "h265": 浏览器使用 H.265 编码。如果频道内有客户端不支持使用 H.265 编码，则会回退到现有编码格式。

各编码格式在浏览器上的支持限制如下：

• VP8 编码在 Safari 12.1 及之前版本不支持

• H.265 编码在如下浏览器支持：

  • macOS/Windows/Android 端 Chrome 136 及以上版本
  • macOS 端 Safari 18 及以上版本
  • iOS 端 Safari 18 及以上版本

• H.265 编码在如下浏览器不支持：

  • macOS/Windows 端 Firefox 浏览器
  • Windows 端 Edge 浏览器

如果使用 H.265 编码，请确保参与互通的 Native SDK 版本为 v4.6.0 以上，否则 Native 端会收不到 H265 的流。

SDK_MODECopy Anchor Link

SDK_MODE: "live"|"rtc"

频道场景。

Agora Web SDK 需知道 app 的使用场景（例如通信模式或直播模式），从而使用不同的优化手段。

声网频道支持以下场景:

• "live": 直播场景，有主播和观众两种用户角色，可以通过 setClientRole 方法设置主播和观众的角色。主播可以收发音视频流，而观众只能接收音视频流，无法发送。
• "rtc": 通信场景，用于常见的一对一通话或群聊，频道中的任何用户可以自由说话。

ScreenAudioTrackInitConfigCopy Anchor Link

ScreenAudioTrackInitConfig: object

创建屏幕共享音频轨道时的配置参数。当使用 AgoraRTC.createScreenVideoTrack 创建屏幕共享视频轨道时，可以通过此配置共享音频轨道。

Type declarationCopy Anchor Link

ScreenEncoderConfigurationPresetCopy Anchor Link

ScreenEncoderConfigurationPreset: keyof typeof SUPPORT_SCREEN_ENCODER_CONFIG_LIST

SDK 预设的 VideoEncoderConfiguration 配置。

你可以在 AgoraRTC.createScreenVideoTrack 方法中传入以下预设值来控制屏幕共享视频编码配置。

下表列出了 SDK 所有预设的屏幕共享视频属性配置。

① "720p_auto" 仅推荐在 Safari 上设置，用于确保能够动态调整编码分辨率，详见发版说明。

ScreenSourceTypeCopy Anchor Link

ScreenSourceType: "screen"|"window"|"application"

屏幕共享源的类型。

• "screen": 共享屏幕。
• "application": 共享某一个 app 的所有窗口。
• "window": 共享某一个 app 的某一个窗口。

UIDCopy Anchor Link

UID: number|string

用于标识用户的 ID。同一频道中每个用户都具有唯一的 ID，且数据类型相同。

为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。详见 join 方法中的说明。

VideoEncoderConfigurationPresetCopy Anchor Link

VideoEncoderConfigurationPreset: keyof typeof SUPPORT_VIDEO_ENCODER_CONFIG_LIST

SDK 预设的 VideoEncoderConfiguration 配置。

你可以在 AgoraRTC.createCameraVideoTrack 方法中传入预设的视频编码配置。

SDK 支持预设的视频属性，以及在各浏览器上的支持情况，请参考设置视频编码属性。

EventsCopy Anchor Link

track-updatedCopy Anchor Link

track-updated(track: MediaStreamTrack): void

媒体轨道有更新时触发。

VariablesCopy Anchor Link

Const AUDIO_ENCODER_CONFIG_SETTINGSCopy Anchor Link

AUDIO_ENCODER_CONFIG_SETTINGS: object

Type declarationCopy Anchor Link

Const AgoraRTCCopy Anchor Link

AgoraRTC: IAgoraRTC

Const SUPPORT_SCREEN_ENCODER_CONFIG_LISTCopy Anchor Link

SUPPORT_SCREEN_ENCODER_CONFIG_LIST: Record<string,VideoEncoderConfiguration>

Const SUPPORT_SVC_CONFIG_LISTCopy Anchor Link

SUPPORT_SVC_CONFIG_LIST: Record<string,SVCConfiguration>

Const SUPPORT_VIDEO_ENCODER_CONFIG_LISTCopy Anchor Link

SUPPORT_VIDEO_ENCODER_CONFIG_LIST: Record<string,VideoEncoderConfiguration>