Agora Web API Reference

Parameters

• appid: string

  你的声网项目的 App ID。

• channel: string

  标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

  • 26 个小写字母 a-z。
  • 26 个大写字母 A-Z。
  • 10 个数字 0-9。
  • 空格。
  • "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", "{", "}", "|", "~", ","。

• token: string | null

  用于鉴权的 token。

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

• Optional uid: UID | null

  标识用户的 ID。整数或字符串，ASCII 字符，需保证唯一性。如果不指定或设为 null，服务器会自动分配一个整数型 uid 并在 Promise 中返回。

  • 如果使用整数作为用户 ID，需为 32 位无符号整数。建议设置范围：0 到 (2³²-1)。
  • 如果使用字符串作为用户 ID，长度不超过 255 个字符。

  为保证最佳的用户体验，声网强烈建议你不要使用字符串作为用户 ID。

  注意事项：

  • 一个频道内的所有用户必须使用同样类型的 uid，即必须都为整数或都为字符串。
  • 使用字符串作为用户 ID 支持与 Native SDK 2.8 及以上版本互通，请确保 Native SDK 使用 User Account 加入频道。详见使用 String 型的用户名。
  • 为保证水晶球数据的准确性，建议自行指定 uid 并保证唯一性。

Returns Promise<UID>

Promise 对象，包含本地用户的 ID：

• 如果你使用整数型 uid 加入频道，则返回整数型 uid。
• 如果你使用字符串型 uid 加入频道，则返回字符串型 uid。
• 如果你不指定或设为 null，声网服务器自动分配一个整数型 uid 并返回。

Returns Promise<void>

Parameters

• tracks: ILocalTrack | ILocalTrack[]

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

Returns Promise<void>

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  远端用户对象。

• mediaType: "video"

  订阅的轨道媒体类型。

  • "video": 订阅指定用户发布的视频轨道。
  • "audio": 订阅指定用户发布的音频轨道。

Returns Promise<IRemoteVideoTrack>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 user.audioTrack 和 user.videoTrack 上更新， 之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。

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

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  远端用户对象。

• mediaType: "audio"

  订阅的轨道媒体类型。

  • "video": 订阅指定用户发布的视频轨道。
  • "audio": 订阅指定用户发布的音频轨道。

Returns Promise<IRemoteAudioTrack>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 user.audioTrack 和 user.videoTrack 上更新， 之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。

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

await client.subscribe(user，"audio");
user.audioTrack.play();

Parameters

• user: IAgoraRTCRemoteUser

  远端用户对象。

• mediaType: "video" | "audio"

  订阅的轨道媒体类型。

  • "video": 订阅指定用户发布的视频轨道。
  • "audio": 订阅指定用户发布的音频轨道。

Returns Promise<IRemoteTrack>

订阅的异步操作完成后，返回远端轨道对象，该对象也会在 user.audioTrack 和 user.videoTrack 上更新， 之后直接调用 audioTrack.play 或 videoTrack.play 就可以播放了。

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

Parameters

• Optional tracks: ILocalTrack | ILocalTrack[]

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

Returns Promise<void>

Parameters

• user: IAgoraRTCRemoteUser

  远端用户对象。

• Optional mediaType: "video" | "audio"

  取消订阅的轨道媒体类型。

  • "video": 仅取消订阅指定用户的视频轨道。
  • “audio”: 仅取消订阅指定用户的音频轨道。
  • 如不填，取消订阅该用户发布的所有轨道。

Returns Promise<void>

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

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

Parameters

• config: IChannelMediaRelayConfiguration

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

Returns Promise<void>

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

Returns Promise<void>

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

Parameters

• config: IChannelMediaRelayConfiguration

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

Returns Promise<void>

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

Returns Promise<void>

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

Returns Promise<void>

Parameters

• streamParameter: LowStreamParameter

  小流的视频属性。

Returns void

Parameters

• streamType: RemoteStreamType

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

Returns Promise<void>

Parameters

• uid: UID

  远端用户的 ID。

• streamType: RemoteStreamType

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

Returns Promise<void>

Parameters

• uid: UID

  远端用户的 UID

• fallbackType: RemoteStreamFallbackType

  回退策略选项，详见 RemoteStreamFallbackType。

Returns Promise<void>

Parameters

• config: LiveStreamingTranscodingConfig

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

Returns Promise<void>

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

Parameters

• url: string

  直播推流的地址，ASCII 字符。支持 RTMP 协议。

• Optional transcodingEnabled: undefined | false | true

  (可选) 是否启用直播转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 RTMP 服务器，适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 true，需要在调用该方法前先调用 setLiveTranscoding。

  • true: 启用转码，需要在调用该方法前先调用 setLiveTranscoding。
  • false: （默认）不启用转码，这种情况下需要保证当前用户正在发布。

Returns Promise<void>

Parameters

• url: string

  待删除的推流地址。

Returns Promise<void>

Returns Promise<void>

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

Returns void

client.enableContentInspect({
  // 设置每 5000ms 对本地视频轨道截一次图
  interval:5000,
  // 设置第三方云存储地址的前缀
  ossFilePrefix:`${channelName}/${uid}`,
  // 设置附加信息，附加信息随截图一起发送给你的服务器
  extraInfo:"fromAgora",
})

Parameters

• inspectConfig: InspectConfiguration

  视频截图上传配置。

Returns Promise<void>

Returns LocalAudioTrackStats

Returns LocalVideoTrackStats

Returns AgoraRTCStats

通话相关的统计信息。

Returns object

• [uid: string]: RemoteAudioTrackStats

Returns object

• [uid: string]: NetworkQuality

Returns object

• [uid: string]: RemoteVideoTrackStats

const result = await client.massSubscribe([{user:userA, mediaType:'audio'}, {user: userB, mediaType:'audio'}]);

for(const {track, mediaType, error} of result) {
  if(error) {
    console.error(error);
    continue;
  }

  if(track) {
    if(mediaType === 'audio') {
      track.play();
    }else{
      track.play(document.querySelector('.video-container'));
    }
  }
}

Parameters

• subscribeList: object[]

  订阅的远端用户列表。列表中的每一条都包含以下信息：

  • user：远端用户对象，详见 AgoraRTCRemoteUser。
  • mediaType：订阅的轨道媒体类型。
    • "video": 订阅指定用户的视频轨道。
    • "audio": 订阅指定用户的音频轨道。

Returns Promise<object[]>

正常情况下，返回列表的长度与顺序和 subscribeList 一致。列表中的每一条都包含以下信息：

• user：远端用户对象，详见 AgoraRTCRemoteUser。
• mediaType：已订阅的轨道媒体类型。
  • "video": 已订阅指定用户发布的视频轨道。
  • "audio": 已订阅指定用户发布的音频轨道。
• track：远端轨道对象，详见 RemoteTrack。
• error：错误信息。如果对单个用户的音视频轨道订阅失败，会通过这个参数返回错误。

client.massUnsubscribe([{user:userA}, {user: userB}]);

Parameters

• unsubscribeList: object[]

  取消订阅的远端用户列表。列表中的每一条都包含以下信息：

  • user：远端用户对象，详见 AgoraRTCRemoteUser。
  • mediaType：取消订阅的轨道媒体类型。
    • "video": 取消订阅指定用户的视频轨道。
    • "audio": 取消订阅指定用户的音频轨道。
    • 如不填，取消订阅该用户发布的所有轨道。

Returns Promise<void>

Parameters

• token: string

  新的 token。

Returns Promise<void>

Parameters

• reports: EventCustomReportParams[] | EventCustomReportParams

Returns Promise<void>

Parameters

• role: ClientRole

  用户角色。

• Optional options: ClientRoleOptions

  用户具体设置，包含观众延时级别。

Returns Promise<void>

Parameters

• encryptionMode: EncryptionMode

  加密模式。

• secret: string

  ASCII 字符。当用户设置的密码为弱密码时，SDK 会在控制台打印警告信息，提醒用户设置强密码，即密码必须包含大写字母、小写字母、数字和特殊字符，以及长度至少 8 个字符。由于浏览器加密算法限制，密钥长度不能超过 62 个字符。声网推荐你在服务端使用 OpenSSL 生成密钥，详见媒体流加密。

• Optional salt: Uint8Array

  盐值，仅当加密模式为 "aes-128-gcm2" 或 "aes-256-gcm2" 时有效。声网推荐你在服务端使用 OpenSSL 生成盐值，详见媒体流加密。

Returns void

Parameters

• license: string

Returns void

client.setLocalAccessPointsV2({
  accessPoints: {
    serverList:["192.168.1.1","192.168.2.2"],
    domain: 'test.agora.io'
  },
  log:{
     hostname:"abc.com",
     port: 3000
  },
  report:{}
})

Parameters

• config: LocalAccessPointConfig

  混合云或私有化平台的配置参数。详见 LocalAccessPointConfig。

Returns void

Parameters

• proxyServer: string

  你的代理服务器域名，ASCII 字符。

Returns void

Parameters

• Optional mode: undefined | number

  云代理模式：

  • 3: UDP 协议的云代理，即 Force UDP 云代理模式。在该模式下，SDK 始终通过 UDP 协议传输数据。
  • 5: TCP（加密）协议的云代理，即 Force TCP 云代理模式。在该模式下，SDK 始终通过 TLS 443 传输数据。

  注意事项： 自 v4.15.0 起，mode 的默认值为 3。

Returns void

Returns void