API 参考

开发者中心





互动直播

Agora.io 社区





Agora Electron SDK API Reference

概览 AgoraRtcEngine Events 警告码错误码

AgoraRtcEngine

Hierarchy

EventEmitter
- AgoraRtcEngine

Index

Constructors

constructor

Properties

Methods

Constructors

constructor

new AgoraRtcEngine(): AgoraRtcEngine

Returns AgoraRtcEngine

Properties

customRenderer

customRenderer: any

renderMode

renderMode: 1 | 2 | 3

rtcEngine

rtcEngine: NodeRtcEngine

streams

streams: Map<string, IRenderer>

Methods

addInjectStreamUrl

addInjectStreamUrl(url: string, config: InjectStreamConfig): number

导入在线媒体流。

该方法适用于 Native SDK v2.4.1 及之后的版本。

该方法通过在服务端拉取一路视频流并发送到频道中，将正在播出的视频导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。

调用该方法后，SDK 会在本地触发 streamInjectStatus 回调，报告导入在线媒体流的状态。成功导入媒体流后，该音视频流会出现在频道中，频道内所有用户都会收到 userJoined 回调，其中 uid 为 666。
note
- 该方法仅使用于直播。
- 调用该方法前，请确保已开通旁路推流的功能，详见前提条件。
- 请确保在成功加入频道后再调用该接口。
- 该方法每次只能增加一路媒体流地址。若需拉多路流，则需多次调用该方法。
Parameters
- url: string
  添加到直播中的媒体流 URL 地址，支持 RTMP， HLS， FLV 协议传输。
  - 支持的 FLV 音频编码格式：AAC
  - 支持的 FLV 视频编码格式：H264 (AVC)
- config: InjectStreamConfig
  
  外部导入的媒体流的配置。
Returns number
- 0：方法调用成功
- < 0：方法调用失败
  - 2: 输入的 URL 为空。请重新调用该方法，并确认输入的媒体流的 URL 是有效的。
  - 7: 引擎没有初始化。请确认调用该方法前已创建 AgoraRtcEngine 对象并完成初始化。
  - 4: 频道非直播模式。请调用 setChannelProfile 并将频道设置为直播模式再调用该方法。
  - 3: 用户没有加入频道。

addPublishStreamUrl

addPublishStreamUrl(url: string, transcodingEnabled: boolean): number

增加旁路推流地址。

调用该方法后，SDK 会在本地触发 streamPublished 回调，报告增加旁路推流地址的状态。
note
- 该方法仅适用于直播模式，请在加入频道后调用该方法。
- 确保已开通旁路推流的功能，详见前提条件。
- 该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
Parameters
- url: string
  
  CDN 推流地址，格式为 RTMP。该字符长度不能超过 1024 字节，且不支持中文等特殊字符。
- transcodingEnabled: boolean
  设置是否转码：
  - true: 转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 RTMP 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景。如果设为 true，需先调用 setLiveTranscoding 方法。
  - false: 不转码。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

addVideoRenderToHighFPS

addVideoRenderToHighFPS(uid: number): void

将指定用户的视频流添加为高帧率流。添加为高帧率流后，你可以调用 setVideoRenderHighFPS 方法对视频流进行控制。

Parameters
- uid: number
  
  用户 ID
Returns void

adjustAudioMixingPlayoutVolume

adjustAudioMixingPlayoutVolume(volume: number): number

调节音乐文件的本地播放音量。

note

请在频道内调用该方法。

Parameters
- volume: number
  
  音乐文件的本地播放音量，取值范围为 [0, 100]，默认值为 100，表示原始文件音量
Returns number
- 0：方法调用成功
- < 0：方法调用失败

adjustAudioMixingPublishVolume

adjustAudioMixingPublishVolume(volume: number): number

调节音乐文件的远端播放音量。

note

请在频道内调用该方法。

Parameters
- volume: number
  
  音乐文件的远端播放音量，取值范围为 [0, 100]，默认值为 100，表示原始文件音量
Returns number
- 0：方法调用成功
- < 0：方法调用失败

adjustAudioMixingVolume

adjustAudioMixingVolume(volume: number): number

调节音乐文件的播放音量。
note
- 请在频道内调用该方法。
- 调用该方法不影响调用 playEffect 播放音效文件的音量。
Parameters
- volume: number
  
  音乐文件播放音量，取值范围为 [0, 100]，默认值为 100，表示原始文件音量
Returns number
- 0：方法调用成功
- < 0：方法调用失败

adjustPlaybackSignalVolume

adjustPlaybackSignalVolume(volume: number): number

调节播放人声的音量。

Parameters
- volume: number
  播放人声的信号音量，可在 0~400 范围内进行调节：
  - 0：静音
  - 100：原始音量
  - 400：最大可为原始音量的 4 倍（自带溢出保护）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

adjustRecordingSignalVolume

adjustRecordingSignalVolume(volume: number): number

调节录音音量。

Parameters
- volume: number
  录音信号音量，可在 0~400 范围内进行调节：
  - 0：静音
  - 100：原始音量
  - 400：最大可为原始音量的 4 倍（自带溢出保护）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

complain

complain(callId: string, desc: string): number

投诉通话质量。

Parameters
- callId: string
  
  通话 getCallId 方法获取的通话 ID
- desc: string
  
  给通话的描述。可选参数，长度应小于 800 字节
Returns number
- 0：方法调用成功
- < 0：方法调用失败

createDataStream

createDataStream(reliable: boolean, ordered: boolean): number

创建数据流。

该方法用于创建数据流。AgoraRtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。
note
- 频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。
- 请将 reliable 和 ordered 同时设置为 true 或 false，暂不支持交叉设置。
Parameters
- reliable: boolean
  - true：接收方 5 秒内会收到发送方所发送的数据，否则会收到 streamMessageError 回调并获得相应报错信息
  - false：接收方不保证收到，就算数据丢失也不会报错
- ordered: boolean
  - true：接收方 5 秒内会按照发送方发送的顺序收到数据包
  - false：接收方不保证按照发送方发送的顺序收到数据包
Returns number
- 创建数据流成功则返回数据流 ID
- < 0：创建数据流失败。如果返回的错误码是负数，对应错误代码和警告代码里的正整数

destroyRender

destroyRender(key: "local" | "videosource" | number, onFailure?: undefined | function): void

销毁渲染器对象。

Parameters
- key: "local" | "videosource" | number
  
  存储渲染器 Map 的关键标识，如 uid、videoSource 或 local
- Optional onFailure: undefined | function
  
  destroyRenderer 方法的错误回调
Returns void

disableAudio

disableAudio(): number

关闭音频模块。
note
- 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
- 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制音频模块：
  
  enableLocalAudio：是否启动麦克风采集并创建本地音频流
  
  muteLocalAudioStream：是否发布本地音频流
  
  muteRemoteAudioStream：是否接收并播放远端音频流
  
  muteAllRemoteAudioStreams：是否接收并播放所有远端音频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

disableLastmileTest

disableLastmileTest(): number

关闭网络测试。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

disableVideo

disableVideo(): number

关闭视频模块。

该方法可以在加入频道前或者通话中调用：
- 在加入频道前调用，则自动开启纯音频模式；
- 在通话中调用，则由视频模式切换为纯音频频模式。
成功掉调用该方法后，远端会触发 userEnableVideo(fasle) 回调。

若想再次开启视频模块，请调用 enableVideo 方法。
note
- 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
- 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：
  
  enableLocalVideo：是否启动摄像头采集并创建本地视频流
  
  muteLocalVideoStream：是否发布本地视频流
  
  muteRemoteVideoStream：是否接收并播放远端视频流
  
  muteAllRemoteVideoStreams：是否接收并播放所有远端视频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableAudio

enableAudio(): number

启用音频模块（默认为开启状态）。
note
- 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
- 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制音频模块：
  
  enableLocalAudio：是否启动麦克风采集并创建本地音频流
  
  muteLocalAudioStream：是否发布本地音频流
  
  muteRemoteAudioStream：是否接收并播放远端音频流
  
  muteAllRemoteAudioStreams：是否接收并播放所有远端音频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableAudioVolumeIndication

enableAudioVolumeIndication(interval: number, smooth: number): number

启用说话者音量提示。

该方法允许 SDK 定期向 App 反馈当前谁在说话以及说话者的音量。启用该方法后，无论频道内是否有人说话，都会在说话声音音量提示回调 groupAudioVolumeIndication 回调中按设置的间隔时间返回音量提示。

Parameters
- interval: number
  指定音量提示的时间间隔：
  - ≤ 0：不启用音量提示功能
  - > 0：返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 groupAudioVolumeIndication 回调。
- smooth: number
  
  平滑系数，指定音量提示的灵敏度。取值范围为 [0, 10]。建议值为 3，数字越大，波动越灵敏；数字越小，波动越平滑
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableDualStreamMode

enableDualStreamMode(enable: boolean): number

开/关视频双流模式。

该方法设置单流（默认）或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。

其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

Parameters
- enable: boolean
  指定双流或者单流模式：
  - true：开启双流
  - false：不开启双流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableLastmileTest

enableLastmileTest(): number

启用网络测试。

该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。

该方法主要用于以下两种场景：
- 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播模式下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。
note
- 该方法请勿与 startLastmileProbeTest 方法同时使用。
- 调用该方法后，在收到 lastMileQuality 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此回调无法执行。
- 启用该方法会消耗一定的网络流量，影响通话质量。在收到 lastMileQuality 回调后，需调用 stopEchoTest 方法停止测试，再加入频道或切换用户角色。
- 直播模式下，主播在加入频道后，请勿调用该方法。
- 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableLocalAudio

enableLocalAudio(enable: boolean): number

开/关本地音频采集。

当 App 加入频道时，它的语音功能默认是开启的。该方法可以关闭或重新开启本地语音功能，即停止或重新开始本地音频采集。

该方法不影响接收或播放远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。语音功能关闭或重新开启后，会收到回调 microphoneEnabled。
note
- 调用 enableLocalAudio(false) 关闭本地采集后，系统会走媒体音量；调用 enableLocalAudio(true) 重新打开本地采集后，系统会恢复为通话音量。
- 该方法与 muteLocalAudioStream 的区别在于：
  
  enableLocalAudio: 使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
  
  muteLocalAudioStream: 使用 muteLocalAudioStream 停止或继续发送本地音频流后，本地听远端播放不会有短暂中断。
Parameters
- enable: boolean
  - true：开启本地音频采集（默认）
  - false：关闭本地音频采集
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableLocalVideo

enableLocalVideo(enable: boolean): number

开/关本地视频采集。

该方法禁用或重新启用本地视频采集，不影响接收远端视频。

调用 enableVideo 后，本地视频即默认开启。你可以调用 enableLocalVideo(false) 关闭本地视频采集。关闭后如果想要重新开启，则可调用 enableLocalVideo(true)。

成功禁用或启用本地视频采集后，远端会触发 userEnableLocalVideo 回调。

Parameters
- enable: boolean
  - true：开启本地视频采集和渲染（默认）
  - false：关闭本地视频采集和渲染。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableLoopbackRecording

enableLoopbackRecording(enable?: boolean, deviceName?: string | null): number

开启声卡采集。

一旦开启声卡采集，SDK 会采集本地所有的声音。

Parameters
- Default value enable: boolean = false
  是否开启声卡采集：
  - true：开启声卡采集
  - false：关闭声卡采集
- Default value deviceName: string | null = null
  声卡的设备名。
  - 默认设为 null，即使用当前声卡采集。
  - 如果用户使用虚拟声卡，如 “Soundflower”，可以将虚拟声卡名称 "Soundflower" 作为参数，SDK 会找到对应的虚拟声卡设备，并开始采集。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableSoundPositionIndication

enableSoundPositionIndication(enable: boolean): number

开启/关闭远端用户的语音立体声。

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在调用 joinChannel 方法前调用该方法。

Parameters
- enable: boolean
  是否开启远端用户语音立体声：
  - true：开启
  - false：（默认）关闭
Returns number
- 0：方法调用成功
- -1：方法调用失败

enableVideo

enableVideo(): number

启用视频模块。

该方法可以在加入频道前或者通话中调用。
- 在加入频道前调用，则自动开启视频模式；
- 在通话中调用则由音频模式切换为视频模式。
成功调用该方法后，远端会触发 userEnableVideo(true) 回调。

若想关闭视频模式，请调用 disableVideo 方法。
note
- 该方法设置的是内部引擎为开启状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
- 该方法重置整个引擎，响应速度较慢，因此 Agora 建议使用如下方法来控制视频模块：
  
  enableLocalVideo：是否启动摄像头采集并创建本地视频流
  
  muteLocalVideoStream：是否发布本地视频流
  
  muteRemoteVideoStream：是否接收并播放远端视频流
  
  muteAllRemoteVideoStreams：是否接收并播放所有远端视频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

enableWebSdkInteroperability

enableWebSdkInteroperability(enable: boolean): number

打开与 Web SDK 的互通（仅在直播下适用）。

该方法打开或关闭与 Agora Web SDK 的互通。该方法仅在直播模式下适用，通信模式下默认互通是打开的。

如果有用户通过 Web SDK 加入频道，请确保调用该方法，否则 Web 端用户看 Native 端的画面会是黑屏。

Parameters
- enable: boolean
  是否打开与 Agora Web SDK 的互通：
  - true：打开互通
  - false：关闭互通（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

getAudioMixingCurrentPosition

getAudioMixingCurrentPosition(): number

获取音乐文件的播放进度。
note
- 播放进度的单位为毫秒。
- 请在频道内调用该方法。
Returns number
- < 0：方法调用失败
- 其他值：方法调用成功并返回伴奏播放进度

getAudioMixingDuration

getAudioMixingDuration(): number

获取音乐文件的时长。
note
- 该方法获取音乐文件总时长，单位为毫秒。
- 请在频道内调用该方法。
Returns number
- ≥ 0：方法调用成功，返回音乐文件时长。
- < 0：方法调用失败。

getAudioMixingPlayoutVolume

getAudioMixingPlayoutVolume(): number

获取音乐文件的本地播放音量。

该方法获取混音的音乐文件本地播放音量，方便排查音量相关问题。

note

请在频道内调用该方法。

Returns number
- ≥ 0：方法调用成功则返回音量值，范围为 [0,100]
- < 0：方法调用失败

getAudioMixingPublishVolume

getAudioMixingPublishVolume(): number

调节音乐文件远端播放音量。

该方法调节混音音乐文件在远端的播放音量大小。
note
- 请在频道内调用该方法。
- 音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。
Returns number
- ≥ 方法调用成功则返回音量值
- < 0 方法调用失败

getAudioPlaybackDeviceMute

getAudioPlaybackDeviceMute(): boolean

获取当前音频播放设备的静音状态。

Returns boolean
- true：当前音频播放设备静音
- false：当前音频播放设备不静音

getAudioPlaybackDevices

getAudioPlaybackDevices(): Array<Object>

获取音频播放设备列表。

Returns Array<Object>

音频播放设备的 Array

getAudioPlaybackVolume

getAudioPlaybackVolume(): number

获取音频播放设备的音量

Returns number

播放设备音量（分贝）。取值范围 [0,255]

getAudioRecordingDeviceMute

getAudioRecordingDeviceMute(): boolean

获取当前音频录制设备的静音状态。

Returns boolean
- true：当前音频录制设备静音
- false：当前音频录制设备不静音

getAudioRecordingDevices

getAudioRecordingDevices(): Array<Object>

获取音频录制设备

Returns Array<Object>

音频录制设备的 Array

getAudioRecordingVolume

getAudioRecordingVolume(): number

获取录制设备的音量。

Returns number

录音设备音量（分贝）。取值范围 [0,255]

getCallId

getCallId(): string

获取通话 ID。

客户端在每次 joinChannel 后会生成一个对应的 CallId，标识该客户端的此次通话。有些方法如 rate, complain 需要在通话结束后调用，向 SDK 提交反馈，这些方法必须指定 CallId 参数。使用这些反馈方法，需要在通话过程中调用 getCallId 方法获取 CallId，在通话结束后在反馈方法中作为参数传入。

Returns string

通话 ID

getConnectionState

getConnectionState(): ConnectionState

获取当前网络连接状态。

Returns ConnectionState

connect 网络连接状态

getCurrentAudioPlaybackDevice

getCurrentAudioPlaybackDevice(): Object

获取当前的音频播放设备。

Returns Object

音频播放设备对象

getCurrentAudioRecordingDevice

getCurrentAudioRecordingDevice(): Object

获取当前的音频录制设备。

Returns Object

音频录制设备对象

getCurrentVideoDevice

getCurrentVideoDevice(): Object

获取当前的视频设备。

Returns Object

视频设备对象

getEffectsVolume

getEffectsVolume(): number

获取播放音效文件音量。

Returns number
- ≥ 0：方法调用成功则返回音量值，范围为 [0.0, 100.0]
- < 0：方法调用失败

getErrorDescription

getErrorDescription(errorCode: number): string

获取指定错误码的详细错误信息。

Parameters
- errorCode: number
  
  错误码
Returns string

errorCode 描述

getPlaybackDeviceInfo

getPlaybackDeviceInfo(deviceId: string, deviceName: string): number

获取播放设备信息。

Parameters
- deviceId: string
  
  设备 ID
- deviceName: string
  
  设备名称
Returns number
- 0：方法调用成功
- < 0：方法调用失败

getRecordingDeviceInfo

getRecordingDeviceInfo(deviceId: string, deviceName: string): number

获取录制设备信息。

Parameters
- deviceId: string
  
  设备 ID
- deviceName: string
  
  设备名
Returns number
- 0：方法调用成功
- < 0：方法调用失败

getScreenDisplaysInfo

getScreenDisplaysInfo(): Array<Object>

获取屏幕信息。

该方法获取所有的系统（macOS 或 Windows）屏幕 ID，以及相关信息。你可以使用获取到的屏幕 ID 进行屏幕共享。

Returns Array<Object>

系统屏幕 ID 和相关信息列表。Windows 和 macOS 系统中返回的屏幕 ID（displayId）不同。你无需关注返回对象的具体内容，直接使用它进行屏幕共享即可。

getScreenWindowsInfo

getScreenWindowsInfo(): Array<Object>

获取系统窗口信息。

该方法获取所有系统（macOS 或 Windows）窗口 ID，以及相关信息。你可以使用获取到的窗口 ID 进行屏幕共享。

Returns Array<Object>

系统窗口 ID 和相关信息列表

getUserInfoByUid

getUserInfoByUid(uid: number): object

通过 UID 获取用户信息。

远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 userInfoUpdated 回调。你收到这个回调后，可以调用该方法，通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。

Parameters
- uid: number
  
  用户 UID
Returns object
- errCode 方法调用失败，返回错误码
- userInfo 方法调用成功，返回包含了指定用户 User Account 的 UserInfo 对象
- errCode: number
- userInfo: UserInfo

getUserInfoByUserAccount

getUserInfoByUserAccount(userAccount: string): object

通过 User Account 获取用户信息。

远端用户加入频道后，SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发 userInfoUpdated 回调。你收到这个回调后，可以调用该方法，通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。

Parameters
- userAccount: string
  
  用户 User Account
Returns object
- errCode 方法调用失败，返回错误码
- userInfo 方法调用成功，获取包含了指定用户 UID 的 UserInfo 对象
- errCode: number
- userInfo: UserInfo

getVersion

getVersion(): string

获取当前 SDK 的版本和 Build 信息。

Returns string

当前 SDK 的版本

getVideoDevices

getVideoDevices(): Array<Object>

获取视频设备。

Returns Array<Object>

视频设备的 Array

initRender

initRender(key: "local" | "videosource" | number, view: Element): void

初始化渲染器对象。

Parameters
- key: "local" | "videosource" | number
  
  存储渲染器 Map 的关键标识，如 uid、videosource 或 local
- view: Element
  
  渲染视频的 Dom
Returns void

initialize

initialize(appid: string): number

初始化一个 AgoraRtcEngine 实例。

Parameters
- appid: string
  
  Agora 为 App 开发者签发的 App ID，每个项目都应该有一个独一无二的 App ID
Returns number
- 0：方法调用成功
- < 0：方法调用失败

joinChannel

joinChannel(token: string, channel: string, info: string, uid: number): number

加入频道。

该方法让用户加入通话频道，在同一个频道内的用户可以互相通话，多个用户加入同一个频道，可以群聊。使用不同 App ID 的 App 是不能互通的。如果已在通话中，用户必须调用 leaveChannel 退出当前通话，才能进入下一个频道。

成功调用该方加入频道后，本地会触发 joinedChannel 回调；通信模式下的用户和直播模式下的主播加入频道后，远端会触发 userJoined 回调。

在网络状况不理想的情况下，客户端可能会与 Agora 的服务器失去连接；SDK 会自动尝试重连，重连成功后，本地会触发 rejoinedChannel 回调。

Parameters
- token: string
  在 App 服务器端生成的用于鉴权的 Token：
  - 安全要求不高：你可以填入在 Agora Console 获取到的临时 Token。详见获取临时 Token
  - 安全要求高：将值设为在 App 服务端生成的正式 Token。详见获取 Token
- channel: string
  （必填）标识通话频道的字符，长度在 64 个字节以内的字符串。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - “!”, “#”, “$”, “%”, “&”, “(”, “)”, “+”, “-”, “:”, “;”, “<”, “=”, “.”, “>”, “?”, “@”, “[”, “]”, “^”, “_”, “{”, “}”, “|”, “~”, “,”
- info: string
  
  (非必选项) 开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户
- uid: number
  用户 ID，32 位无符号整数。
  - 建议设置范围：1到 2³²-1，并保证唯一性。
  - 如果不指定（即设为 0），SDK 会自动分配一个
Returns number
- 0：方法调用成功
- < 0：方法调用失败

joinChannelWithUserAccount

joinChannelWithUserAccount(token: string, channel: string, userAccount: string): number

使用 User Account 加入频道。

该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：
- 本地：localUserRegistered 和 userInfoUpdated
- 远端：通信模式下的用户和直播模式下的主播加入频道后，远端会依次触发 userJoined 和 userInfoUpdated 回调
note

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
Parameters
- token: string
  在 App 服务器端生成的用于鉴权的 Token：
  - 安全要求不高：你可以使用 Console 生成的临时 Token，详见获取临时 Token
  - 安全要求高：将值设为你的服务端生成的正式 Token，详见获取正式 Token
- channel: string
  标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
- userAccount: string
  用户 User Account。该参数为必须，最大不超过 255 字节，不可为 NULL。请确保加入频道的 User Account 的唯一性。
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Returns number
- 0：方法调用成功
- < 0：方法调用失败

leaveChannel

leaveChannel(): number

离开频道。

离开频道，即机挂断或退出通话。

该方法会把回话相关的所有资源都释放掉。该方法是异步操作，调用返回时并没有真正退出频道。真正退出频道后，本地会触发 leaveChannel 回调；通信模式下的用户和直播模式下的主播离开频道后，远端会触发 removeStream 回调。
note
- 若想开始下一次通话，必须先调用该方法结束本次通话。
- 不管当前是否在通话中，都可以调用该方法，没有副作用。
- 如果你调用该方法后立即调用 release 方法，SDK 将无法触发 leaveChannel 回调。
- 如果你在输入在线媒体流的过程中调用了该方法， SDK 将自动调用 removeInjectStreamUrl 方法。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteAllRemoteAudioStreams

muteAllRemoteAudioStreams(mute: boolean): number

停止/恢复接收所有音频流。

Parameters
- mute: boolean
  - true：停止接收所有音频流
  - false：继续接收所有音频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteAllRemoteVideoStreams

muteAllRemoteVideoStreams(mute: boolean): number

停止/恢复接收所有视频流。

Parameters
- mute: boolean
  - true：停止接收所有视频流
  - false：继续接收所有视频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteLocalAudioStream

muteLocalAudioStream(mute: boolean): number

停止/恢复发送本地音频流。

成功调用该方法后，远端会触发 userMuteAudio 回调。

note

我们建议你在 setChannelProfile 后调用该方法。因为如果你在该方法后调用 setChannelProfile方法， SDK 会根据你设置的频道模式以及用户角色，重新设置是否停止发送本地音频。

Parameters
- mute: boolean
  - true：停止发送本地音频流
  - false：继续发送本地音频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteLocalVideoStream

muteLocalVideoStream(mute: boolean): number

停止/恢复发送本地视频流。

成功调用该方法后，远端会触发 userMuteVideo 回调。
note
- 调用该方法时，SDK 不再发送本地视频流，但摄像头仍然处于工作状态。
- 我们建议你在 setChannelProfile 后调用该方法。因为如果你在该方法后调用 setChannelProfile方法， SDK 会根据你设置的频道模式以及用户角色，重新设置是否停止发送本地视频。
Parameters
- mute: boolean
  - true：停止发送本地视频流
  - false：发动本地视频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteRemoteAudioStream

muteRemoteAudioStream(uid: number, mute: boolean): number

停止/恢复接收指定音频流。

Parameters
- uid: number
  
  指定的用户 ID
- mute: boolean
  - true：停止接收指定用户的音频流
  - false：继续接收指定用户的音频流
Returns number
- 0：方法调用成功
- < 0：方法调用失败

muteRemoteVideoStream

muteRemoteVideoStream(uid: number, mute: boolean): number

停止/恢复接收指定视频流。

Parameters
- uid: number
  
  指定用户的 ID
- mute: boolean
  - true：停止接收指定用户的视频流
  - false：继续接收指定用户的视频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

off

off(event: string | symbol, listener: function): this

Parameters
- event: string | symbol
- listener: function
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this

on

on(event: string | symbol, listener: function): this
on(evt: "apiCallExecuted", cb: function): this
on(evt: "warning", cb: function): this
on(evt: "error", cb: function): this
on(evt: "joinedChannel", cb: function): this
on(evt: "rejoinedChannel", cb: function): this
on(evt: "audioVolumeIndication", cb: function): this
on(evt: "groupAudioVolumeIndication", cb: function): this
on(evt: "leaveChannel", cb: function): this
on(evt: "rtcStats", cb: function): this
on(evt: "localVideoStats", cb: function): this
on(evt: "localAudioStats", cb: function): this
on(evt: "remoteVideoStats", cb: function): this
on(evt: "remoteAudioStats", cb: function): this
on(evt: "remoteVideoTransportStats", cb: function): this
on(evt: "remoteAudioTransportStats", cb: function): this
on(evt: "audioDeviceStateChanged", cb: function): this
on(evt: "audioMixingStateChanged", cb: function): this
on(evt: "remoteAudioMixingBegin", cb: function): this
on(evt: "remoteAudioMixingEnd", cb: function): this
on(evt: "audioEffectFinished", cb: function): this
on(evt: "videoDeviceStateChanged", cb: function): this
on(evt: "networkQuality", cb: function): this
on(evt: "lastMileQuality", cb: function): this
on(evt: "lastmileProbeResult", cb: function): this
on(evt: "firstLocalVideoFrame", cb: function): this
on(evt: "addStream", cb: function): this
on(evt: "videoSizeChanged", cb: function): this
on(evt: "firstRemoteVideoFrame", cb: function): this
on(evt: "userJoined", cb: function): this
on(evt: "removeStream", cb: function): this
on(evt: "userOffline", cb: function): this
on(evt: "userMuteAudio", cb: function): this
on(evt: "userMuteVideo", cb: function): this
on(evt: "userEnableVideo", cb: function): this
on(evt: "userEnableLocalVideo", cb: function): this
on(evt: "cameraReady", cb: function): this
on(evt: "videoStopped", cb: function): this
on(evt: "connectionLost", cb: function): this
on(evt: "connectionBanned", cb: function): this
on(evt: "streamMessage", cb: function): this
on(evt: "streamMessageError", cb: function): this
on(evt: "mediaEngineStartCallSuccess", cb: function): this
on(evt: "requestChannelKey", cb: function): this
on(evt: "fristLocalAudioFrame", cb: function): this
on(evt: "firstRemoteAudioFrame", cb: function): this
on(evt: "firstRemoteAudioDecoded", cb: function): this
on(evt: "activeSpeaker", cb: function): this
on(evt: "clientRoleChanged", cb: function): this
on(evt: "audioDeviceVolumeChanged", cb: function): this
on(evt: "videoSourceJoinedSuccess", cb: function): this
on(evt: "videoSourceRequestNewToken", cb: function): this
on(evt: "videoSourceLeaveChannel", cb: function): this
on(evt: "remoteVideoStateChanged", cb: function): this
on(evt: "cameraFocusAreaChanged", cb: function): this
on(evt: "cameraExposureAreaChanged", cb: function): this
on(evt: "tokenPrivilegeWillExpire", cb: function): this
on(evt: "streamPublished", cb: function): this
on(evt: "streamUnpublished", cb: function): this
on(evt: "transcodingUpdated", cb: function): this
on(evt: "streamInjectStatus", cb: function): this
on(evt: "localPublishFallbackToAudioOnly", cb: function): this
on(evt: "remoteSubscribeFallbackToAudioOnly", cb: function): this
on(evt: "microphoneEnabled", cb: function): this
on(evt: "connectionStateChanged", cb: function): this
on(evt: "localUserRegistered", cb: function): this
on(evt: "userInfoUpdated", cb: function): this
on(evt: "localVideoStateChanged", cb: function): this
on(evt: "localAudioStateChanged", cb: function): this
on(evt: "remoteAudioStateChanged", cb: function): this
on(evt: "channelMediaRelayState", cb: function): this
on(evt: "channelMediaRelayEvent", cb: function): this
on(evt: string, listener: Function): this

Parameters
- event: string | symbol
- listener: function
  - - (...args: any[]): void
    - Parameters
      - Rest ...args: any[]
      Returns void
Returns this
API 方法已执行回调。

Parameters
- evt: "apiCallExecuted"
- cb: function
  - - (api: string, err: number): void
    - Parameters
      - api: string
        
        SDK 执行的 API
      - err: number
        
        当该方法调用失败时 SDK 返回的错误码
      Returns void
Returns this
发生警告回调。

Parameters
- evt: "warning"
- cb: function
  - - (warn: number, msg: string): void
    - Parameters
      - warn: number
        
        警告码
      - msg: string
        
        详细的警告信息
      Returns void
Returns this
发生错误回调。

Parameters
- evt: "error"
- cb: function
  - - (err: number, msg: string): void
    - Parameters
      - err: number
        
        错误码
      - msg: string
        
        详细的错误信息
      Returns void
Returns this
成功加入频道。

Parameters
- evt: "joinedChannel"
- cb: function
  - - (channel: string, uid: number, elapsed: number): void
    - Parameters
      - channel: string
        
        频道名
      - uid: number
        
        用户 ID
      - elapsed: number
        
        从调用 joinChannel 开始到发生此事件过去的时间（毫秒)
      Returns void
Returns this
重新加入频道回调。

有时候由于网络原因，客户端可能会和服务器失去连接，SDK 会进行自动重连，自动重连成功后触发此回调方法。

Parameters
- evt: "rejoinedChannel"
- cb: function
  - - (channel: string, uid: number, elapsed: number): void
    - Parameters
      - channel: string
        
        频道名
      - uid: number
        
        用户 ID
      - elapsed: number
        
        从调用 joinChannel 开始到发生此事件过去的时间（毫秒)
      Returns void
Returns this
提示频道内谁在说话以及说话者音量的回调。

该回调提示正在说话的一个用户的信息。默认禁用。可以通过 enableAudioVolumeIndication 方法开启；开启后，无论频道内是否有人说话，都会按方法中设置的时间间隔返回提示音量。
note
- 本地用户返回 uid 为 0，speakerNumber 始终为 1。
- 用户调用 muteLocalAudioStream 方法会对该回调产生影响：
  
  本地用户：随即不再返回该回调。
  
  远端用户：15 秒后，该回调的报告中不再包含该远端用户。
Parameters
- evt: "audioVolumeIndication"
- cb: function
  - - (uid: number, volume: number, speakerNumber: number, totalVolume: number): void
    - Parameters
      - uid: number
        
        用户 ID
      - volume: number
        
        该用户音量
      - speakerNumber: number
        
        音量较高的用户人数
      - totalVolume: number
      Returns void
Returns this
提示频道内谁在说话以及说话者音量的回调。

该回调提示频道内瞬时音量较高的几个用户的用户 ID 及他们的音量。默认禁用。可以通过 enableAudioVolumeIndication 方法开启；开启后，无论频道内是否有人说话，都会按方法中设置的时间间隔返回提示音量。
note
- 本地用户返回 uid 为 0，speakerNumber 始终为 1。
- 用户调用 muteLocalAudioStream 方法会对该回调产生影响：
  
  本地用户：随即不再返回该回调。
  
  远端用户：15 秒后，该回调的报告中不再包含该远端用户。
Parameters
- evt: "groupAudioVolumeIndication"
- cb: function
  - - (speakers: object[], speakerNumber: number, totalVolume: number): void
    - Parameters
      - speakers: object[]
        
        音量较高的说话者的信息，包含：
        
        uid：用户 ID
        
        volume：该用户的说话音量
      - speakerNumber: number
        
        音量较高的用户人数
      - totalVolume: number
        
        混音后总音量（分贝）。取值范围 [0,255]
      Returns void
Returns this
离开频道回调。

调用 leaveChannel 方法成功离开频道后，SDK 会触发该回调。

Parameters
- evt: "leaveChannel"
- cb: function
  - - (): void
    - Returns void
Returns this
通话相关统计信息。

Parameters
- evt: "rtcStats"
- cb: function
  - - (stats: RtcStats): void
    - Parameters
      - stats: RtcStats
        
        通话信息详情
      Returns void
Returns this
通话中本地视频流的统计信息回调。

note

如果你此前调用 enableDualStreamMode 方法，则本回调描述本地设备发送的视频大流的统计信息。

Parameters
- evt: "localVideoStats"
- cb: function
  - - (stats: LocalVideoStats): void
    - Parameters
      - stats: LocalVideoStats
        
        本地视频流统计信息
      Returns void
Returns this
通话中本地音频流的统计信息回调。

Parameters
- evt: "localAudioStats"
- cb: function
  - - (stats: LocalAudioStats): void
    - Parameters
      - stats: LocalAudioStats
        
        本地音频流统计信息
      Returns void
Returns this
通话中远端视频流的统计信息回调。

Parameters
- evt: "remoteVideoStats"
- cb: function
  - - (stats: RemoteVideoStats): void
    - Parameters
      - stats: RemoteVideoStats
        
        远端视频流统计信息
      Returns void
Returns this
通话中远端音频流的统计信息回调。

Parameters
- evt: "remoteAudioStats"
- cb: function
  - - (stats: RemoteAudioStats): void
    - Parameters
      - stats: RemoteAudioStats
        
        远端音频流统计信息
      Returns void
Returns this
deprecated

该回调已废弃。请改用 remoteVideoStats 回调。

通话中远端视频流传输的统计信息回调。

该回调描述远端用户通话中端到端的网络统计信息，通过视频包计算，用客观的数据，如丢包、网络延迟等，展示当前网络状态。

通话中，当用户收到远端用户/主播发送的视频数据包后，会每 2 秒触发一次该回调。和 remoteVideoStats 回调相比，该回调以数据展示当前网络状态，因此更客观。

Parameters
- evt: "remoteVideoTransportStats"
- cb: function
  - - (stats: RemoteVideoTransportStats): void
    - Parameters
      - stats: RemoteVideoTransportStats
        
        远端视频流传输的统计信息
      Returns void
Returns this
deprecated

该回调已废弃。请改用 remoteAudioStats 回调。

通话中远端音频流传输的统计信息回调。

Parameters
- evt: "remoteAudioTransportStats"
- cb: function
  - - (stats: RemoteAudioTransportStats): void
    - Parameters
      - stats: RemoteAudioTransportStats
        
        远端音频流传输的统计信息
      Returns void
Returns this
音频设备状态已改变回调。

Parameters
- evt: "audioDeviceStateChanged"
- cb: function
  - - (deviceId: string, deviceType: number, deviceState: number): void
    - Parameters
      - deviceId: string
        
        设备 ID
      - deviceType: number
        
        设备类型，详见 MediaDeviceType
      - deviceState: number
        
        设备状态
        
        1：设备正在使用
        
        2：设备被禁用
        
        4：没有此设备
        
        8：设备被拔出
      Returns void
Returns this
本地用户的音乐文件播放状态改变。

Parameters
- evt: "audioMixingStateChanged"
- cb: function
  - - (state: number, err: number): void
    - Parameters
      - state: number
        
        状态码
        
        710：音乐文件正常播放
        
        711：音乐文件暂停播放
        
        713：音乐文件停止播放
        
        714：音乐文件报错。SDK 会在 err 中返回具体的报错原因
      - err: number
        
        错误码
        
        701：音乐文件打开出错
        
        702：音乐文件打开太频繁
        
        703：音乐文件播放异常中断
      Returns void
Returns this
远端音乐文件播放已开始回调。

当远端有用户调用 startAudioMixing 播放本地音乐文件，SDK 会触发该回调。

Parameters
- evt: "remoteAudioMixingBegin"
- cb: function
  - - (): void
    - Returns void
Returns this
远端音乐文件播放已结束回调。

Parameters
- evt: "remoteAudioMixingEnd"
- cb: function
  - - (): void
    - Returns void
Returns this
本地音效文件播放已结束回调。

当播放音效结束后，会触发该回调。

Parameters
- evt: "audioEffectFinished"
- cb: function
  - - (soundId: number): void
    - Parameters
      - soundId: number
        
        指定音效的 ID。每个音效均有唯一的 ID。
      Returns void
Returns this
视频设备变化回调。

该回调提示系统视频设备状态发生改变，比如被拔出或移除。如果设备已使用外接摄像头采集，外接摄像头被拔开后，视频会中断。

Parameters
- evt: "videoDeviceStateChanged"
- cb: function
  - - (deviceId: string, deviceType: number, deviceState: number): void
    - Parameters
      - deviceId: string
        
        设备 ID
      - deviceType: number
        
        设备类型，详见 MediaDeviceType
      - deviceState: number
        
        设备状态
        
        1：设备正在使用
        
        2：设备被禁用
        
        4：没有此设备
        
        8：设备被拔出
      Returns void
Returns this
通话中每个用户的网络上下行 last mile 质量报告回调。

该回调描述每个用户在通话中的 last mile 网络状态，其中 last mile 是指设备到 Agora 边缘服务器的网络状态。

该回调每 2 秒触发一次。如果远端有多个用户，该回调每 2 秒会被触发多次。

Parameters
- evt: "networkQuality"
- cb: function
  - - (uid: number, txquality: AgoraNetworkQuality, rxquality: AgoraNetworkQuality): void
    - Parameters
      - uid: number
        
        用户 ID。表示该回调报告的是持有该 ID 的用户的网络质量。当 uid 为 0 时，返回的是本地用户的网络质量
      - txquality: AgoraNetworkQuality
        
        该用户的上行网络质量，基于上行发送码率、上行丢包率、平均往返时延和网络抖动计算。
      - rxquality: AgoraNetworkQuality
        
        该用户的下行网络质量，基于下行网络的丢包率、平均往返延时和网络抖动计算。
      Returns void
Returns this
通话前网络上下行 last mile 质量报告回调。

该回调描述本地用户在加入频道前的 last mile 网络探测的结果，其中 last mile 是指设备到 Agora 边缘服务器的网络状态。

在调用 enableLastmileTest 之后，该回调函数每 2 秒触发一次。如果远端有多个用户/主播，该回调每 2 秒会被触发多次。

Parameters
- evt: "lastMileQuality"
- cb: function
  - - (quality: AgoraNetworkQuality): void
    - Parameters
      - quality: AgoraNetworkQuality
        
        网络上下行质量，基于上下行网络的丢包率和抖动计算，探测结果主要反映上行网络的状态。
      Returns void
Returns this
通话前网络质量探测报告回调。

在调用 startLastmileProbeTest 之后，SDK 会在约 30 秒内返回该回调。

Parameters
- evt: "lastmileProbeResult"
- cb: function
  - - (result: LastmileProbeResult): void
    - Parameters
      - result: LastmileProbeResult
        
        上下行 Last mile 质量探测结果。
      Returns void
Returns this
已显示本地视频首帧回调。

本地视频首帧显示在本地视图上时，SDK 会触发此回调。

Parameters
- evt: "firstLocalVideoFrame"
- cb: function
  - - (width: number, height: number, elapsed: number): void
    - Parameters
      - width: number
        
        本地渲染视频的宽 (px)
      - height: number
        
        本地渲染视频的高 (px)
      - elapsed: number
        
        从本地调用 joinChannel 到发生此事件过去的时间（毫秒)
      Returns void
Returns this
deprecated
这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

已接收到远端视频并完成解码回调。

引擎收到第一帧远端视频流并解码成功时，触发此调用。有两种情况：
- 远端用户首次上线后发送视频
- 远端用户视频离线再上线后发送视频。出现这种中断的可能原因包括：
  
  远端用户离开频道
  
  远端用户掉线
  
  远端用户调用 muteLocalVideoStream 方法停止发送本地视频流
  
  远端用户调用 disableVideo 方法关闭视频模块
Parameters
- evt: "addStream"
- cb: function
  - - (uid: number, elapsed: number): void
    - Parameters
      - uid: number
        
        用户 ID，指定是哪个用户的视频流
      - elapsed: number
        
        从本地调用 joinChannel 到发生此事件过去的时间（毫秒)
      Returns void
Returns this
本地或远端视频大小和旋转信息发生改变回调。

Parameters
- evt: "videoSizeChanged"
- cb: function
  - - (uid: number, width: number, height: number, rotation: number): void
    - Parameters
      - uid: number
        
        图像尺寸和旋转信息发生变化的用户的用户 ID（本地用户的 uid 为 0）
      - width: number
        
        视频流的宽度（px）
      - height: number
        
        视频流的高度（px）
      - rotation: number
        
        旋转信息 [0, 360]
      Returns void
Returns this
已显示首帧远端视频回调。

第一帧远端视频显示在视图上时，触发此调用。

Parameters
- evt: "firstRemoteVideoFrame"
- cb: function
  - - (uid: number, width: number, height: number, elapsed: number): void
    - Parameters
      - uid: number
        
        用户 ID，指定是哪个用户的视频流
      - width: number
        
        视频流宽（px）
      - height: number
        
        视频流高（px）
      - elapsed: number
        
        从本地调用 joinChannel 到发生此事件过去的时间（毫秒)
      Returns void
Returns this
远端用户（通信模式）/主播（直播模式）加入当前频道回调。
- 通信模式下，该回调提示有远端用户加入了频道，并返回新加入用户的 ID；如果加入之前，已经有其他用户在频道中了，新加入的用户也会收到这些已有用户加入频道的回调。
- 直播模式下，该回调提示有主播加入了频道，并返回该主播的 ID。如果在加入之前，已经有主播在频道中了，新加入的用户也会收到已有主播加入频道的回调。声网建议连麦主播不超过 17 人。
该回调在如下情况下会被触发：
- 远端用户/主播调用 joinChannel 方法加入频道
- 远端用户加入频道后调用 setClientRole 将用户角色改变为主播
- 远端用户/主播网络中断后重新加入频道
- 主播通过调用 addInjectStreamUrl 方法成功导入在线媒体流
note
直播场景下
- 主播间能相互收到新主播加入频道的回调，并能获得该主播的 uid
- 观众也能收到新主播加入频道的回调，并能获得该主播的 uid
- 当 Web 端加入直播频道时，只要 Web 端有推流，SDK 会默认该 Web 端为主播，并触发该回调。
Parameters
- evt: "userJoined"
- cb: function
  - - (uid: number, elapsed: number): void
    - Parameters
      - uid: number
        
        新加入频道的远端用户/主播 ID
      - elapsed: number
        
        从本地调用 joinChannel 到发生此事件过去的时间（毫秒)
      Returns void
Returns this
远端用户离开当前频道回调。

用户离开频道有两个原因：
- 正常离开的时候，远端用户/主播会发送类似“再见”的消息。接收此消息后，判断用户离开频道。
- 超时掉线的依据是，在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。声网建议使用信令系统来做可靠的掉线检测。
Parameters
- evt: "removeStream"
- cb: function
  - - (uid: number, reason: number): void
    - Parameters
      - uid: number
        
        离线用户或主播的用户 ID。
      - reason: number
        
        离线原因
        
        0：用户主动离开。
        
        1：因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线。
        
        2：用户身份从主播切换为观众。
      Returns void
Returns this
远端用户（通信模式）/主播（直播模式）离开当前频道回调。

用户离开频道有两个原因，即正常离开和超时掉线：
- 正常离开的时候，远端用户/主播会收到类似“再见”的消息，接收此消息后，判断用户离开频道
- 超时掉线的依据是，在一定时间内（通信场景为 20 秒，直播场景稍有延时），用户没有收到对方的任何数据包，则判定为对方掉线。在网络较差的情况下，有可能会误报。Agora 建议使用信令系统来做可靠的掉线检测
Parameters
- evt: "userOffline"
- cb: function
  - - (uid: number, reason: number): void
    - Parameters
      - uid: number
        
        主播 ID
      - reason: number
        
        离线原因
        
        用户主动离开
        
        因过长时间收不到对方数据包，超时掉线。注意：由于 SDK 使用的是不可靠通道，也有可能对方主动离开本方没收到对方离开消息而误判为超时掉线
        
        （直播模式下）用户身份从主播切换为观众
      Returns void
Returns this
远端用户暂停/重新发送音频流回调。

该回调是由远端用户调用 muteLocalAudioStream 方法关闭或开启音频发送触发的。

note

当频道内的主播超过 20 人时，该回调不生效。

Parameters
- evt: "userMuteAudio"
- cb: function
  - - (uid: number, muted: boolean): void
    - Parameters
      - uid: number
        
        远端用户 ID
      - muted: boolean
        
        该用户是否暂停发送音频流
        
        true：该用户已暂停发送音频流
        
        false：该用户已重新发送音频流
      Returns void
Returns this
远端用户暂停/重新发送视频流回调。

该回调是由远端用户调用 muteLocalVideoStream 方法关闭或开启音频发送触发的。

note

当频道内的主播超过 20 人时，该回调不生效。

Parameters
- evt: "userMuteVideo"
- cb: function
  - - (uid: number, muted: boolean): void
    - Parameters
      - uid: number
        
        远端用户 ID
      - muted: boolean
        
        该用户是否暂停发送视频流
        
        true：该用户已暂停发送视频流
        
        false：该用户已重新发送视频流
      Returns void
Returns this
deprecated

这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

远端用户开启/关闭视频模块回调。

该回调是由远端用户调用 enableVideo 或 disableVideo 方法开启或关闭视频模块触发的。

note

Agora 视频模块指视频处理过程，而不是 SDK 中的模块实物。发送视频流时，视频模块指视频采集、前处理、编码等处理过程；接收视频流时，视频模块指视频解码、后处理、渲染/播放等处理过程。

Parameters
- evt: "userEnableVideo"
- cb: function
  - - (uid: number, enabled: boolean): void
    - Parameters
      - uid: number
        
        用户 ID
      - enabled: boolean
        
        该用户是否开启或关闭视频模块：
        
        true：该用户已启用视频模块。启用后，该用户可以进行视频通话或直播。
        
        false：该用户已关闭视频模块。关闭后，该用户只能进行语音通话或直播，不能显示、发送自己的视频，也不能接收、显示别人的视频。
      Returns void
Returns this
deprecated

这个回调已被废弃，请改用 remoteVideoStateChanged 回调。

远端用户开启/关闭本地视频采集。

该回调是由远端用户调用 enableLocalVideo 方法开启或关闭视频采集触发的。

Parameters
- evt: "userEnableLocalVideo"
- cb: function
  - - (uid: number, enabled: boolean): void
    - Parameters
      - uid: number
        
        用户 ID
      - enabled: boolean
        
        该用户是否开启或关闭本地视频采集：
        
        true：该用户已启用本地视频采集。启用后，其他用户可以接收到该用户的视频流。
        
        false：该用户已关闭视频采集。关闭后，该用户仍然可以接收其他用户的视频流，但其他用户接收不到该用户的视频流。
      Returns void
Returns this
deprecated

该回调已废弃。请改用 localVideoStateChanged 回调。

摄像头就绪回调。

Parameters
- evt: "cameraReady"
- cb: function
  - - (): void
    - Returns void
Returns this
deprecated

该回调已废弃。请改用 localVideoStateChanged 回调。

视频停止播放回调。

Parameters
- evt: "videoStopped"
- cb: function
  - - (): void
    - Returns void
Returns this
网络连接中断，且 SDK 无法在 10 秒内连接服务器回调。

note

SDK 在调用 joinChannel 后，无论是否加入成功，只要 10 秒和服务器无法连接就会触发该回调。如果 SDK 在断开连接后，20 分钟内还是没能重新加入频道，SDK 会停止尝试重连。

Parameters
- evt: "connectionLost"
- cb: function
  - - (): void
    - Returns void
Returns this
deprecated

该回调已废弃。请改用 connectionStateChanged 回调。

网络连接已被服务器禁止回调。

当你被服务端禁掉连接的权限时，会触发该回调。

Parameters
- evt: "connectionBanned"
- cb: function
  - - (): void
    - Returns void
Returns this
接收到对方数据流消息的回调。

该回调表示本地用户收到了远端用户调用 sendStreamMessage 方法发送的流消息。

Parameters
- evt: "streamMessage"
- cb: function
  - - (uid: number, streamId: number, msg: string, len: number): void
    - Parameters
      - uid: number
        
        用户 ID
      - streamId: number
        
        数据流 ID
      - msg: string
        
        接收到的流消息
      - len: number
        
        流消息数据长度
      Returns void
Returns this
接收对方数据流小时发生错误回调。

该回调表示本地用户未收到远端用户调用 sendStreamMessage 方法发送的流消息。

Parameters
- evt: "streamMessageError"
- cb: function
  - - (uid: number, streamId: number, code: number, missed: number, cached: number): void
    - Parameters
      - uid: number
        
        用户 ID
      - streamId: number
        
        数据流 ID
      - code: number
      - missed: number
        
        丢失的消息数量
      - cached: number
        
        数据流中断后，后面缓存的消息数量
      Returns void
Returns this
媒体引擎成功启动的回调。

Parameters
- evt: "mediaEngineStartCallSuccess"
- cb: function
  - - (): void
    - Returns void
Returns this
Token 已过期回调。

调用 joinChannel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中 SDK 可能由于网络原因和服务器失去连接，重连时可能需要新的 Token。

该回调通知 App 需要生成新的 Token，并需调用 renewToken 为 SDK 指定新的 Token。

Parameters
- evt: "requestChannelKey"
- cb: function
  - - (): void
    - Returns void
Returns this
已发送本地音频首帧回调。

Parameters
- evt: "fristLocalAudioFrame"
- cb: function
  - - (elapsed: number): void
    - Parameters
      - elapsed: number
        
        从本地用户调用 joinChannel 方法直至该回调被触发的延迟（毫秒）
      Returns void
Returns this
已接收远端音频首帧回调。

Parameters
- evt: "firstRemoteAudioFrame"
- cb: function
  - - (uid: number, elapsed: number): void
    - Parameters
      - uid: number
        
        发送音频帧的远端用户的 ID
      - elapsed: number
        
        从调用 joinChannel 方法直至该回调被触发的延迟（毫秒）
      Returns void
Returns this
已解码远端音频首帧的回调

SDK 完成远端音频首帧解码，并发送给音频模块用以播放时，会触发此回调。有两种情况：
- 远端用户首次上线后发送音频
- 远端用户音频离线再上线发送音频。音频离线指本地在 15 秒内没有收到音频包，可能有如下原因：
  - 远端用户离开频道
  - 远端用户掉线
  - 远端用户停止发送音频流（通过调用 muteLocalAudioStream 方法）
  - 远端用户关闭音频（通过调用 disableAudio 方法）
Parameters
- evt: "firstRemoteAudioDecoded"
- cb: function
  - - (uid: number, elapsed: number): void
    - Parameters
      - uid: number
        
        用户 ID，指定是哪个用户的音频流
      - elapsed: number
        
        从本地用户调用 joinChannel 方法加入频道直至该回调触发的延迟，单位为毫秒
      Returns void
Returns this
检测到活跃用户回调。

如果用户开启了 enableAudioVolumeIndication 功能，则当音量检测模块监测到频道内有新的活跃用户说话时，会通过本回调返回该用户的 uid。

Parameters
- evt: "activeSpeaker"
- cb: function
  - - (uid: number): void
    - Parameters
      - uid: number
        
        当前时间段内声音最大的用户的 uid（本地用户 uid 为 0）
      Returns void
Returns this
用户角色已切换回调。该

回调由本地用户在加入频道后调用 setClientRole 改变用户角色触发的。

Parameters
- evt: "clientRoleChanged"
- cb: function
  - - (oldRole: ClientRoleType, newRole: ClientRoleType): void
    - Parameters
      - oldRole: ClientRoleType
        
        切换前的角色
      - newRole: ClientRoleType
        
        切换后的角色
      Returns void
Returns this
回放、录音设备、或 App 的音量发生改变。

Parameters
- evt: "audioDeviceVolumeChanged"
- cb: function
  - - (deviceType: MediaDeviceType, volume: number, muted: boolean): void
    - Parameters
      - deviceType: MediaDeviceType
        
        设备类型
      - volume: number
        
        当前音量（分贝）。取值范围 [0, 255]
      - muted: boolean
        
        音频设备是否为静音状态
        
        true：音频设备已静音
        
        false：音频设备未被静音
      Returns void
Returns this
屏幕共享对象成功加入频道回调。

Parameters
- evt: "videoSourceJoinedSuccess"
- cb: function
  - - (uid: number): void
    - Parameters
      - uid: number
        
        该对象的用户 ID
      Returns void
Returns this
屏幕共享对象 Token 已过期回调。

Parameters
- evt: "videoSourceRequestNewToken"
- cb: function
  - - (): void
    - Returns void
Returns this
屏幕共享对象离开频道回调。

Parameters
- evt: "videoSourceLeaveChannel"
- cb: function
  - - (): void
    - Returns void
Returns this
远端用户视频流状态发生改变回调。

Parameters
- evt: "remoteVideoStateChanged"
- cb: function
  - - (uid: number, state: RemoteVideoState, reason: RemoteVideoStateReason, elapsed: number): void
    - Parameters
      - uid: number
        
        发生视频流状态改变的远端用户的用户 ID。
      - state: RemoteVideoState
        
        远端视频流状态
      - reason: RemoteVideoStateReason
        
        远端视频流状态改变的具体原因
      - elapsed: number
        
        从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为 ms。
      Returns void
Returns this
相机对焦区域已改变回调。

Parameters
- evt: "cameraFocusAreaChanged"
- cb: function
  - - (x: number, y: number, width: number, height: number): void
    - Parameters
      - x: number
        
        发生改变的对焦区域相对于左上角的 x 坐标。
      - y: number
        
        发生改变的对焦区域相对于左上角的 y 坐标。
      - width: number
        
        发生改变的对焦区域的宽度 (px)。
      - height: number
        
        发生改变的对焦区域的高度 (px)。
      Returns void
Returns this
摄像头曝光区域已改变回调。

Parameters
- evt: "cameraExposureAreaChanged"
- cb: function
  - - (x: number, y: number, width: number, height: number): void
    - Parameters
      - x: number
        
        发生改变的曝光区域相对于左上角的 x 坐标。
      - y: number
        
        发生改变的曝光区域相对于左上角的 y 坐标。
      - width: number
        
        发生改变的曝光区域的宽度 (px)。
      - height: number
        
        发生改变的曝光区域的高度 (px)。
      Returns void
Returns this
Token 服务即将过期回调。

在调用 joinChannel 时如果指定了 Token，由于 Token 具有一定的时效，在通话过程中如果 Token 即将失效，SDK 会提前 30 秒触发该回调，提醒 App 更新 Token。当收到该回调时，用户需要重新在服务端生成新的 Token，然后调用 renewToken 将新生成的 Token 传给 SDK。

Parameters
- evt: "tokenPrivilegeWillExpire"
- cb: function
  - - (token: string): void
    - Parameters
      - token: string
        
        即将服务失效的 Token
      Returns void
Returns this
开启旁路推流的结果回调。

该回调返回 addPublishStreamUrl 方法的调用结果。用于通知主播是否推流成功。如果不成功，你可以在 error 参数中查看详细的错误信息。

Parameters
- evt: "streamPublished"
- cb: function
  - - (url: string, error: number): void
    - Parameters
      - url: string
        
        新增的推流地址。
      - error: number
        
        详细的错误信息
        
        0：推流成功
        
        1：推流失败
        
        2：参数错误。如果你在调用 addPublishStreamUrl 前没有调用 setLiveTranscoding 配置 LiveTranscoding，SDK 会返回该错误
        
        10：推流超时未成功
        
        19：推流地址已经在推流
        
        130：推流已加密不能推流
      Returns void
Returns this
停止旁路推流的结果回调。

该回调返回 removePublishStreamUrl 方法的调用结果。用于通知主播是否停止推流成功。

Parameters
- evt: "streamUnpublished"
- cb: function
  - - (url: string): void
    - Parameters
      - url: string
        
        主播停止推流的 RTMP 地址。
      Returns void
Returns this
旁路推流设置被更新回调。该

回调用于通知主播 CDN 转码已成功更新。

setLiveTranscoding 方法中的转码合图参数（LiveTranscoding）更新时，transcodingUpdated 回调会被触发并向主播报告更新信息。

note

首次调用 setLiveTranscoding 方法设置转码合图参数（LiveTranscoding）时，不会触发此回调。

Parameters
- evt: "transcodingUpdated"
- cb: function
  - - (): void
    - Returns void
Returns this
导入在线媒体流状态回调。

该回调表明向直播导入的外部视频流的状态。

Parameters
- evt: "streamInjectStatus"
- cb: function
  - - (url: string, uid: number, status: number): void
    - Parameters
      - url: string
        
        导入进直播的外部视频源的 URL 地址。
      - uid: number
        
        用户 ID。
      - status: number
        
        导入的外部视频源状态
        
        0：外部视频流导入成功
        
        1：外部视频流已存在
        
        2：外部视频流导入未经授权
        
        3：导入外部视频流超时
        
        4：外部视频流导入失败
        
        5：外部视频流停止导入失败
        
        6：未找到要停止导入的外部视频流
        
        7：要停止导入的外部视频流未经授权
        
        8：停止导入外部视频流超时
        
        9：停止导入外部视频流失败
        
        10：导入的外部视频流被中断
      Returns void
Returns this
本地发布流已回退为音频流回调。

如果你调用了设置本地推流回退选项 setLocalPublishFallbackOption 并将 option 设置为 2 时，当上行网络环境不理想、本地发布的媒体流回退为音频流时，或当上行网络改善、媒体流恢复为音视频流时，会触发该回调。

如果本地推流已回退为音频流，远端的 App 上会收到 userMuteVideo 的回调事件。

Parameters
- evt: "localPublishFallbackToAudioOnly"
- cb: function
  - - (isFallbackOrRecover: boolean): void
    - Parameters
      - isFallbackOrRecover: boolean
        
        本地推流已回退或恢复：
        
        true：由于网络环境不理想，本地发布的媒体流已回退为音频流
        
        false：由于网络环境改善，发布的音频流已恢复为音视频流
      Returns void
Returns this
远端订阅流已回退为音频流回调。

如果你调用了设置远端订阅流回退选项 setRemoteSubscribeFallbackOption 并将 option 设置为 2 时，当下行网络环境不理想、仅接收远端音频流时，或当下行网络改善、恢复订阅音视频流时，会触发该回调。

远端订阅流因弱网环境不能同时满足音视频而回退为小流时，你可以使用 remoteVideoStats 回调来监控远端视频大小流的切换。

Parameters
- evt: "remoteSubscribeFallbackToAudioOnly"
- cb: function
  - - (uid: number, isFallbackOrRecover: boolean): void
    - Parameters
      - uid: number
        
        远端用户的 ID
      - isFallbackOrRecover: boolean
        
        远端订阅流已回退或恢复：
        
        true：由于网络环境不理想，远端订阅流已回退为音频流
        
        false：由于网络环境改善，订阅的音频流已恢复为音视频流
      Returns void
Returns this
deprecated

这个回调已被废弃，请改用 localAuidoStateChanged 回调。

麦克风状态已改变回调。

该回调由本地用户开启或关闭本地音频采集触发的。

Parameters
- evt: "microphoneEnabled"
- cb: function
  - - (enabled: boolean): void
    - Parameters
      - enabled: boolean
        
        是否开启麦克风：
        
        true：麦克风已启用
        
        false：麦克风已禁用
      Returns void
Returns this
网络连接状态已改变回调。

该回调在网络连接状态发生改变的时候触发，并告知用户当前的网络连接状态，和引起网络状态改变的原因。

Parameters
- evt: "connectionStateChanged"
- cb: function
  - - (state: ConnectionState, reason: ConnectionChangeReason): void
    - Parameters
      - state: ConnectionState
        
        当前的网络连接状态
      - reason: ConnectionChangeReason
        
        引起当前网络连接状态发生改变的原因
      Returns void
Returns this
本地用户成功注册 User Account 回调。

本地用户成功调用 registerLocalUserAccount 方法注册用户 User Account，或调用 joinChannelWithUserAccount 加入频道后，SDK 会触发该回调，并告知本地用户的 UID 和 User Account。包含如下参数：

Parameters
- evt: "localUserRegistered"
- cb: function
  - - (uid: number, userAccount: string): void
    - Parameters
      - uid: number
        
        本地用户的 UID
      - userAccount: string
        
        本地用户的 User account
      Returns void
Returns this
远端用户信息已更新回调。

远端用户加入频道后， SDK 会获取到该远端用户的 UID 和 User Account，然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表，并在本地触发该回调。

Parameters
- evt: "userInfoUpdated"
- cb: function
  - - (uid: number, userInfo: UserInfo): void
    - Parameters
      - uid: number
        
        远端用户的 ID
      - userInfo: UserInfo
        
        标识用户信息的 UserInfo 对象，包含用户 UID 和 User account
      Returns void
Returns this
本地视频状态发生改变回调。

本地视频的状态发生改变时，SDK 会触发该回调返回当前的本地视频状态；当状态码为 3 时，你可以在错误码查看返回的错误信息。该接口在本地视频出现故障时，方便你了解当前视频的状态以及出现故障的原因。

Parameters
- evt: "localVideoStateChanged"
- cb: function
  - - (localVideoState: number, error: number): void
    - Parameters
      - localVideoState: number
        
        当前的本地视频状态码：
        
        0：本地视频默认初始状态
        
        1：本地视频采集设备启动成功
        
        2：本地视频首帧编码成功
        
        3：本地视频启动失败
      - error: number
        
        本地视频错误码：
        
        0：本地视频状态正常
        
        1：出错原因不明确
        
        2：没有权限启动本地视频采集设备
        
        3：本地视频采集设备正在使用中
        
        4：本地视频采集失败，建议检查采集设备是否正常工作
        
        5：本地视频编码失败
      Returns void
Returns this
本地音频状态发生改变回调。

本地音频的状态发生改变时（包括本地麦克风录制状态和音频编码状态），SDK 会触发该回调报告当前的本地音频状态。在本地音频出现故障时，该回调可以帮助你了解当前音频的状态以及出现故障的原因，方便你排查问题。

note

当状态码为 3 时，你可以在错误码中查看返回的错误信息。

Parameters
- evt: "localAudioStateChanged"
- cb: function
  - - (state: number, error: number): void
    - Parameters
      - state: number
        
        当前的本地音频状态：
        
        0 本地音频默认初始状态。
        
        1 本地音频录制设备启动成功。
        
        2 本地音频首帧编码成功。
        
        3 本地音频启动失败。
      - error: number
        
        本地音频错误码：
        
        0 本地音频状态正常。
        
        1 本地音频出错原因不明确。
        
        2 没有权限启动本地音频录制设备。
        
        3 本地音频录制设备已经在使用中。
        
        4 本地音频录制失败，建议你检查录制设备是否正常工作。
        
        5 本地音频编码失败。
      Returns void
Returns this
远端音频流状态发生改变回调。

远端用户/主播音频状态发生改变时，SDK 会触发该回调向本地用户报告当前的远端音频流状态。

Parameters
- evt: "remoteAudioStateChanged"
- cb: function
  - - (uid: number, state: RemoteAudioState, reason: RemoteAudioStateReason, elapsed: number): void
    - Parameters
      - uid: number
        
        发生音频状态改变的远端用户 ID。
      - state: RemoteAudioState
        
        远端音频流状态码
      - reason: RemoteAudioStateReason
        
        远端音频流状态改变的原因码
      - elapsed: number
        
        从本地用户调用 joinChannel 方法到发生本事件经历的时间，单位为 ms。
      Returns void
Returns this
跨频道媒体流转发状态发生改变回调。

当跨频道媒体流转发状态发生改变时，SDK 会触发该回调，并报告当前的转发状态以及相关的错误信息。

Parameters
- evt: "channelMediaRelayState"
- cb: function
  - - (state: ChannelMediaRelayState, code: ChannelMediaRelayError): void
    - Parameters
      - state: ChannelMediaRelayState
        
        跨频道媒体流转发状态码
      - code: ChannelMediaRelayError
        
        跨频道媒体流转发出错的错误码
      Returns void
Returns this
跨频道媒体流转发事件回调。

该回调报告跨频道媒体流转发过程中发生的事件。

Parameters
- evt: "channelMediaRelayEvent"
- cb: function
  - - (event: ChannelMediaRelayEvent): void
    - Parameters
      - event: ChannelMediaRelayEvent
        
        跨频道媒体流转发事件码
      Returns void
Returns this
Parameters
- evt: string
- listener: Function
Returns this

pauseAllEffects

pauseAllEffects(): number

暂停所有音效文件播放。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

pauseAudio

pauseAudio(): number

deprecated

该方法已废弃。请改用 disableAudio 禁用频道内的音频功能。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

pauseAudioMixing

pauseAudioMixing(): number

暂停播放音乐文件及混音。请在频道内调用该方法。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

pauseEffect

pauseEffect(soundId: number): number

暂停音效文件播放。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID
Returns number
- 0：方法调用成功
- < 0：方法调用失败

playEffect

playEffect(soundId: number, filePath: string, loopcount: number, pitch: number, pan: number, gain: number, publish: number): number

播放指定音效文件。

该方法播放指定的本地或在线音效文件。你可以在该方法中设置音效文件的播放次数、音调、音效的空间位置和增益，以及远端用户是否能听到该音效。

你可以多次调用该方法，通过传入不同的音效文件的 soundID 和 filePath，同时播放多个音效文件，实现音效叠加。为获得最佳用户体验，我们建议同时播放的音效文件不要超过 3 个。

调用该方法播放音效结束后，SDK 会触发 audioEffectFinished 回调。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID
- filePath: string
  
  指定音效文件的绝对路径或 URL 地址（包含文件后缀名）。支持的音频格式包括：mp3、mp4、m4a、aac、3gp、mkv 及 wav
- loopcount: number
  设置音效循环播放的次数：
  - 0：播放音效一次
  - 1：播放音效两次
  - -1：无限循环播放音效，直至调用 stopEffect 或 stopAllEffects 后停止
- pitch: number
  
  设置音效的音调，取值范围为 [0.5, 2]。默认值为 1.0，表示不需要修改音调。取值越小，则音调越低
- pan: number
  设置是否改变音效的空间位置。取值范围为 [-1.0, 1.0]：
  - 0.0：音效出现在正前方
  - 1.0：音效出现在右边
  - -1.0：音效出现在左边
- gain: number
  
  设置是否改变单个音效的音量。取值范围为 [0.0, 100.0]。默认值为 100.0。取值越小，则音效的音量越低
- publish: number
  设置是否将音效传到远端：
  - true：音效在本地播放的同时，会发布到 Agora 云上，因此远端用户也能听到该音效
  - false：音效不会发布到 Agora 云上，因此只能在本地听到该音效
Returns number
- 0：方法调用成功
- < 0：方法调用失败

preloadEffect

preloadEffect(soundId: number, filePath: string): number

预加载音效文件。

为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel 前就使用该方法完成音效预加载。音效文件支持以下音频格式：mp3，aac，m4a，3gp，wav。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID。
- filePath: string
  
  音效文件的绝对路径
Returns number
- 0：方法调用成功
- < 0：方法调用失败

rate

rate(callId: string, rating: number, desc: string): number

给通话评分。

Parameters
- callId: string
  
  通过 getCallId 函数获取的通话 ID
- rating: number
  
  给通话的评分，最低 1 分，最高 5 分
- desc: string
  
  （非必选项）给通话的描述，可选，长度应小于 800 字节
Returns number
- 0：方法调用成功
- < 0：方法调用失败

registerLocalUserAccount

registerLocalUserAccount(appId: string, userAccount: string): number

注册本地用户 User account。

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。成功注册 User Account 后，本地会触发 onLocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：
- 先调用 registerLocalUserAccount 方法注册 Account，再调用 joinChannelWithUserAccount 方法加入频道。
- 直接调用 joinChannelWithUserAccount 方法加入频道。
两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Agora Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
note
- 请确保 userAccount 不能为空，否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
Parameters
- appId: string
  
  你的项目在 Agora Console 注册的 App ID
- userAccount: string
  用户 User Account。该参数为必填，最大不超过 255 字节，不可填 null。请确保注册的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
Returns number
- 0：方法调用成功
- < 0：方法调用失败

release

release(): number

释放 AgoraRtcEngine 实例。

调用该方法后，用户将无法再使用和回调该 SDK 内的其它方法。
note
- 该方法需要在子线程中操作。
- 如需再次使用，必须重新初始化 initialize 一个 AgoraRtcEngine 实例。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

removeInjectStreamUrl

removeInjectStreamUrl(url: string): number

删除导入的在线媒体流。

成功删除后，会触发 removeStream 回调，其中 uid 为 666

Parameters
- url: string
  
  已导入、待删除的外部视频流 URL 地址
Returns number
- 0：方法调用成功
- < 0：方法调用失败

removePublishStreamUrl

removePublishStreamUrl(url: string): number

删除旁路推流地址。

调用该方法后，SDK 会在本地触发 streamUnpublished 回调，报告删除旁路推流地址的状态。
note
- 该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。
- 推流地址不支持中文等特殊字符。
- 该方法只适用于直播模式。
Parameters
- url: string
  
  待删除的推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

removeVideoRenderFromHighFPS

removeVideoRenderFromHighFPS(uid: number): void

将指定用户的视频从高帧率流中删除。删除后，你可以调用 setVideoRenderFPS 方法对视频流进行控制。

Parameters
- uid: number
  
  用户 ID
Returns void

renewToken

renewToken(newtoken: string): number

更新 Token。

如果启用了 Token 机制，过一段时间后使用的 Token 会失效。当报告错误码 109或 tokenPrivilegeWillExpire 回调时，你应重新获取 Token，然后调用该 API 更新 Token，否则 SDK 无法和服务器建立连接。

Parameters
- newtoken: string
  
  新的 Token
Returns number
- 0：方法调用成功
- < 0：方法调用失败

resizeRender

resizeRender(key: "local" | "videosource" | number): void

更新渲染尺寸。当视图尺寸发生改变时，该方法可以根据视窗尺寸长宽比更新缩放比例，在收到下一个视频帧时，按照新的比例进行渲染。该方法可以防止视图不连贯的问题。

Parameters
- key: "local" | "videosource" | number
  
  存储渲染器 Map 的关键标识，如 uid、videoSource 或 local
Returns void

resumeAllEffects

resumeAllEffects(): number

恢复播放所有音效文件。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

resumeAudio

resumeAudio(): number

deprecated

该方法已弃用。请改用 enableAudio 启用频道内的音频功能。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

resumeAudioMixing

resumeAudioMixing(): number

恢复播放音乐文件及混音。请在频道内调用该方法。

Returns number
- 0：方法调用成功
- < 0：方法调用失败

resumeEffect

resumeEffect(soundId: number): number

恢复播放指定音效文件。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID
Returns number
- 0：方法调用成功
- < 0：方法调用失败

sendStreamMessage

sendStreamMessage(streamId: number, msg: string): number

发送数据流。

该方法发送数据流消息到频道内所有用户。

SDK 对该方法的实现进行了如下限制：频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。每个客户端每秒最多能发送 6 KB 数据。频道内每人最多能同时有 5 个数据通道。

成功调用该方法后，远端会触发 streamMessage 回调，远端用户可以在该回调中获取接收到的流消息；若调用失败，远端会触发 streamMessageError 回调。

note

该方法仅适用于通信模式以及直播模式下的主播用户，如果直播模式下的观众调用此方法可能会造成观众变主播。

Parameters
- streamId: number
  
  数据流 ID，createDataStream 的返回值
- msg: string
  
  待发送的数据
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioMixingPosition

setAudioMixingPosition(position: number): number

设置音乐文件的播放位置。

该方法可以设置音频文件的播放位置，这样你可以根据实际情况播放文件，而不是非得从头到尾播放一个文件。

Parameters
- position: number
  
  当前播放进度，单位为毫秒
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioPlaybackDevice

setAudioPlaybackDevice(deviceId: string): number

通过设备 ID 指定音频播放设备

Parameters
- deviceId: string
  
  音频播放设备的 ID
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioPlaybackDeviceMute

setAudioPlaybackDeviceMute(mute: boolean): number

设置当前音频播放设备为静音/不静音。

Parameters
- mute: boolean
  是否设置当前音频播放设备静音：
  - true：设置当前音频播放设备静音
  - false：设置当前音频播放设备不静音
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioPlaybackVolume

setAudioPlaybackVolume(volume: number): number

设置音频播放设备的音量

Parameters
- volume: number
  
  播放设备音量（分贝）。取值范围 [0,255]
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioProfile

setAudioProfile(profile: 0 | 1 | 2 | 3 | 4 | 5, scenario: 0 | 1 | 2 | 3 | 4 | 5): number

设置音频编码配置。

note

请在 joinChannel 之前调用该方法，否则不生效。

Parameters
- profile: 0 | 1 | 2 | 3 | 4 | 5
  设置采样率、码率、编码模式和声道数：
  - 0：默认设置
    - 通信模式下，为 1
    - 直播模式下，指定32 kHz 采样率，音乐编码，单声道，编码码率最大值为 44 Kbps
  - 1：Speech standard：指定 32 kHz 采样率，语音编码，单声道，编码码率最大值为 18 Kbps
  - 2：Music standard：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 48 Kbps
  - 3：Music standard stereo：指定 48 kHz采样率，音乐编码，双声道，编码码率最大值为 56 Kbps
  - 4：Music high quality：指定 48 kHz 采样率，音乐编码，单声道，编码码率最大值为 128 Kbps
  - 5：Music high quality stereo：指定 48 kHz 采样率，音乐编码，双声道，编码码率最大值为 192 Kbps
- scenario: 0 | 1 | 2 | 3 | 4 | 5
  设置音频应用场景：
  - 0：默认的音频应用场景
  - 1：Chatroom entertainment：娱乐应用，需要频繁上下麦的场景
  - 2：Education：教育应用，流畅度和稳定性优先
  - 3：Game streaming：游戏直播应用，需要外放游戏音效也直播出去的场景
  - 4：Showroom：秀场应用，音质优先和更好的专业外设支持
  - 5：Chatroom gaming：游戏开黑
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioRecordingDevice

setAudioRecordingDevice(deviceId: string): number

设备音频录制设备

Parameters
- deviceId: string
  
  设备 ID
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioRecordingDeviceMute

setAudioRecordingDeviceMute(mute: boolean): number

设置当前音频录制设备静音/不静音。

Parameters
- mute: boolean
  是否设置当前音频录制设备静音：
  - true：设置静音
  - false：设置不静音
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setAudioRecordingVolume

setAudioRecordingVolume(volume: number): number

设置录音设备的音量

Parameters
- volume: number
  
  录音设备的音量（分贝）。取值范围 [0, 255]
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setBeautyEffectOptions

setBeautyEffectOptions(enable: boolean, options: object): number

开启或关闭本地美颜功能，并设置美颜效果选项。

Parameters
- enable: boolean
  是否开启美颜功能：
  - true：开启
  - false：（默认）关闭
- options: object
  
  设置美颜选项，包含如下字段：
  - lighteningContrastLevel: 0 | 1 | 2
    对比度，与 lighteningLevel 搭配使用。取值越大，明暗对比越强烈：
    - 0 低对比度
    - 1 （默认）正常对比度
    - 2 高对比度
  - lighteningLevel: number
    
    亮度，可用来实现美白等视觉效果。取值范围为 [0.0, 1.0]，其中 0.0 表示原始亮度，默认值为 0.7。
  - rednessLevel: number
    
    红润度，可用来实现红润肤色等视觉效果。取值范围为 [0.0, 1.0]，其中 0.0 表示原始红润度，默认值为 0.1。
  - smoothnessLevel: number
    
    平滑度，可用来实现祛痘、磨皮等视觉效果。取值范围为 [0.0, 1.0]，其中 0.0 表示原始平滑等级，默认值为 0.5。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setCameraCapturerConfiguration

setCameraCapturerConfiguration(config: CameraCapturerConfiguration): number

设置摄像头的采集偏好。

一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数通常无法满足需求，或可能引起设备性能问题，我们推荐调用该接口设置摄像头的采集偏好：
- 使用裸数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时，会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，避免性能问题。
- 如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1)，以优化 CPU 和内存的资源分配
- 如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)
note

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo
Parameters
- config: CameraCapturerConfiguration
  
  摄像头采集偏好
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setChannelProfile

setChannelProfile(profile: number): number

设置频道模式。

Agora 会根据你的 app 使用场景进行不同的优化。
note
- 该方法必须在 joinChannel 方法之前调用
- 相同频道内的所有用户必须使用相同的频道模式
Parameters
- profile: number
  频道模式：
  - 0：（默认）通信
  - 1：直播
  - 2：游戏
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setClientRole

setClientRole(role: ClientRoleType): number

设置直播模式下的用户角色。

加入频道前，用户需要通过本方法设置观众或主播模式。

加入频道后，用户可以通过本方法切换用户模式。直播模式下，如果你在加入频道后调用该方法切换用户角色，调用成功后，本地会触发 clientRoleChanged 事件；远端会触发 userJoined 事件。

Parameters
- role: ClientRoleType
  用户角色：
  - 1：主播
  - 2：（默认）观众
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setCustomRenderer

setCustomRenderer(customRenderer: IRenderer): void

当 setRenderMode 方法中的渲染模式设置为 3 时，调用该方法可以设备自定义的渲染器。 customRender 是一个类.

Parameters
- customRenderer: IRenderer
  
  自定义渲染器
Returns void

setDefaultMuteAllRemoteAudioStreams

setDefaultMuteAllRemoteAudioStreams(mute: boolean): number

设置是否默认接收音频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteAudioStreams (true)，会接收不到后面加入频道的用户的音频流。

note

停止接收音频流后，如果想要恢复接收，请调用 muteRemoteAudioStream(false)，并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的音频流，则需要多次调用 muteRemoteAudioStream(false)。setDefaultMuteAllRemoteAudioStreams (false) 只能恢复接收后面加入频道的用户的音频流。

Parameters
- mute: boolean
  - true：默认不接收所有音频流
  - false：默认接收所有音频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setDefaultMuteAllRemoteVideoStreams

setDefaultMuteAllRemoteVideoStreams(mute: boolean): number

设置是否默认接收视频流。

该方法在加入频道前后都可调用。如果在加入频道后调用 setDefaultMuteAllRemoteVideoStreams (true)，会接收不到设置后加入频道的用户的视频流。

note

停止接收视频流后，如果想要恢复接收，请调用 muteRemoteVideoStream(false)，并指定你想要接收的远端用户 uid；如果想恢复接收多个用户的视频流，则需要多次调用 muteRemoteVideoStream(false)。 setDefaultMuteAllRemoteVideoStreams (false) 只能恢复接收后面加入频道的用户的视频流。

Parameters
- mute: boolean
  - true：默认不接收任何视频流
  - false：默认继续接收所有视频流（默认）
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setEffectsVolume

setEffectsVolume(volume: number): number

设置播放音效文件音量。

Parameters
- volume: number
  
  音效文件的音量。取值范围为 [0.0, 100.0]，100.0 为默认值，表示原始音量。
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setEncryptionMode

setEncryptionMode(mode: string): number

设置内置的加密方案。

Agora Native SDK 支持内置加密功能，默认使用 AES-128-XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。

同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

note

调用本方法前，请先调用 setEncryptionSecret 方法启用内置加密功能。

Parameters
- mode: string
  加密方式。目前支持以下几种：
  - "aes-128-xts"：128 位 AES 加密，XTS 模式
  - "aes-128-ecb"：128 位 AES 加密，ECB 模式
  - "aes-256-xts"：256 位 AES 加密，XTS 模式
  - ""：设置为空字符串时，默认使用加密方式 aes-128-xts
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setEncryptionSecret

setEncryptionSecret(secret: string): number

启用内置加密，并设置数据加密密码。

如需启用加密，请在 joinChannel 前调用该方法，并设置加密的密码。同一频道内的所有用户应设置相同的密码。当用户离开频道时，该频道的密码会自动清除。如果未指定密码或将密码设置为空，则无法激活加密功能。

note

为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

Parameters
- secret: string
  
  加密密码
Returns number
- 0：方法调用成功
- < 0：方法调用失败

setHighQualityAudioParameters

setHighQualityAudioParameters(fullband: boolean, stereo: boolean, fullBitrate: boolean): number

deprecated

该方法已废弃。请改用 setAudioProfile 设置音频高音质选项。

请在加入频道前调用该方法，对其中的三个模式完成设置。加入频道后调用该方法不生效。

Parameters
- fullband: boolean
  是否启用全频带编解码器（48 kHz 采样率）：
  - true：启用全频带编解码器
  - false：禁用全频带编解码器
- stereo: boolean
  是否启用立体声编解码器：
  - true：启用立体声编解码器
  - false：禁用立体声编解码器
- fullBitrate: boolean
  
  是否启用高码率模&

Hierarchy

Index

Constructors

Properties

Methods

Constructors

constructor

Returns AgoraRtcEngine

Properties

customRenderer

renderMode

rtcEngine

streams

Methods

addInjectStreamUrl

Parameters

url: string

config: InjectStreamConfig

Returns number

addPublishStreamUrl

Parameters

url: string

transcodingEnabled: boolean

Returns number

addVideoRenderToHighFPS

Parameters

uid: number

Returns void

adjustAudioMixingPlayoutVolume

Parameters

volume: number

Returns number

adjustAudioMixingPublishVolume

Parameters

volume: number

Returns number

adjustAudioMixingVolume

Parameters

volume: number

Returns number

adjustPlaybackSignalVolume

Parameters

volume: number

Returns number

adjustRecordingSignalVolume

Parameters

volume: number

Returns number

complain

Parameters

callId: string

desc: string

Returns number

createDataStream

Parameters

reliable: boolean

ordered: boolean

Returns number

destroyRender

Parameters

key: "local" | "videosource" | number

Optional onFailure: undefined | function

Returns void

disableAudio

Returns number

disableLastmileTest

Returns number

disableVideo

Returns number

enableAudio

Returns number

enableAudioVolumeIndication

Parameters

interval: number

smooth: number

Returns number

enableDualStreamMode

Parameters

enable: boolean

Returns number