Agora Web SDK API Reference v4.24.0

Type aliases

AudioEncoderConfigurationPreset

AudioEncoderConfigurationPreset: keyof typeof AUDIO_ENCODER_CONFIG_SETTINGS

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

• AgoraRTC.createCustomAudioTrack

• AgoraRTC.createMicrophoneAudioTrack

• AgoraRTC.createBufferSourceAudioTrack

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

音频属性	配置
"speech_low_quality"	16 kHz 采样率，单声道，编码码率约 24 Kbps
"speech_standard"	32 kHz 采样率，单声道，编码码率约 24 Kbps
"music_standard"	48 kHz 采样率，单声道，编码码率约 32 Kbps
"standard_stereo"	48 kHz 采样率，双声道，编码码率约 64 Kbps
"high_quality"	48 kHz 采样率，单声道， 编码码率约 128 Kbps
"high_quality_stereo"	48 kHz 采样率，双声道，编码码率约 192 Kbps

AudioSourceState

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

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

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

• "playing": 音频源数据正在处理。

• "paused": 音频源数据暂停处理。

CheckVideoVisibleResult

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> 被其他元素遮挡。

ClientRole

ClientRole: "audience" | "host"

用户角色。

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

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

ConnectionState

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

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

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

  • 尚未通过 join 加入频道。

  • 已经通过 leave 离开频道。

  • 被踢出频道或者连接失败等异常情况。

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

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

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

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

DeviceState

DeviceState: "ACTIVE" | "INACTIVE"

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

• "ACTIVE": 该设备已经插入。

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

EncryptionMode

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": 不加密。

LocalAccessPointConfig

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：预留参数，暂不支持。

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

属性	默认值
log.hostname	accessPoints 所包含的 hostname 列表中的第一个
log.port	6444
report.hostname	accessPoints 所包含的 hostname 列表中的前两个
report.port	6443
accessPoints.port	443

JavaScript

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
  }
})  

OptimizationMode

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

视频传输优化模式：

• "detail": 清晰优先。

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

  • 大部分情况下，浏览器不会降低发送分辨率，但是可能会降低帧率。

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

  • 浏览器不会启用最小码率策略。遭遇网络波动时，发送端会降低码率来确保接收端的视频画面不会出现中断和卡顿。

  • 大部分情况下，浏览器不会降低帧率，但是可能会降低发送分辨率。

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

  • 对于屏幕共享视频流，SDK 默认的优化策略为清晰优先。

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

RequiredOnlyOneOf

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

SDK_CODEC

SDK_CODEC: keyof typeof VideoCodec

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

• "vp8": 浏览器使用 VP8 编码。

• "h264": 浏览器使用 H.264 编码。

• "vp9": (Beta) 浏览器使用 VP9 编码。

• "av1": (Beta) 浏览器使用 AV1 编码。

注意

Safari 12.1 之前版本不支持 VP8 编码。

SDK_MODE

SDK_MODE: "live" | "rtc"

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

• "live": 直播场景，有主播和观众两种用户角色，可以通过 setClientRole 方法设置主播和观众的角色。主播可以收发音视频流，而观众只能接收音视频流，无法发送。

• "rtc": 通信场景，用于常见的一对一通话或群聊，频道中的任何用户可以自由说话。

ScreenAudioTrackInitConfig

ScreenAudioTrackInitConfig: AudioTrackInitConfig

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

ScreenEncoderConfigurationPreset

ScreenEncoderConfigurationPreset: keyof typeof SUPPORT_SCREEN_ENCODER_CONFIG_LIST

SDK 预设的 VideoEncoderConfiguration 配置。
你可以在 AgoraRTC.createScreenVideoTrack 方法中传入以下预设值来控制屏幕共享视频编码配置。
下表列出了 SDK 所有预设的屏幕共享视频属性配置。

视频属性	分辨率（宽×高）	帧率（fps）
"480p"	640 × 480	5
"480p_1"	640 × 480	5
"480p_2"	640 × 480	30
"480p_3"	640 × 480	15
"720p"	1280 × 720	5
"720p_1"	1280 × 720	5
"720p_2"	1280 × 720	30
"720p_3"	1280 × 720	15
"720p_auto" ①	1280 × 720	30
"1080p"	1920 × 1080	5
"1080p_1"	1920 × 1080	5
"1080p_2"	1920 × 1080	30
"1080p_3"	1920 × 1080	15

注意

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

ScreenSourceType

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

屏幕共享源的类型。

• "screen": 共享屏幕。

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

• "window": 共享某一个 app 的某一个窗口。

UID

UID: number | string

用于标识用户的 ID。同一频道中每个用户都具有唯一的 ID，且数据类型相同。
为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。详见 join 方法中的说明。

VideoEncoderConfigurationPreset

VideoEncoderConfigurationPreset: keyof typeof SUPPORT_VIDEO_ENCODER_CONFIG_LIST

SDK 预设的 VideoEncoderConfiguration 配置。
你可以在 AgoraRTC.createCameraVideoTrack 方法中传入预设的视频编码配置。
SDK 支持预设的视频属性，以及在各浏览器上的支持情况，请参考设置视频编码属性。

Events

track-updated

Variables

AUDIO_ENCODER_CONFIG_SETTINGS

AUDIO_ENCODER_CONFIG_SETTINGS: object

AgoraRTC

AgoraRTC: IAgoraRTC

SUPPORT_SCREEN_ENCODER_CONFIG_LIST

SUPPORT_SCREEN_ENCODER_CONFIG_LIST: Record<string, VideoEncoderConfiguration>

SUPPORT_SVC_CONFIG_LIST

SUPPORT_SVC_CONFIG_LIST: Record<string, SVCConfiguration>

SUPPORT_VIDEO_ENCODER_CONFIG_LIST

SUPPORT_VIDEO_ENCODER_CONFIG_LIST: Record<string, VideoEncoderConfiguration>