文档中心





视频通话 (Legacy)

Console 官网社区技术支持





React Native API Reference

概览 RtcEngine RtcEngineEvents RtcChannel RtcChannelEvents 警告码错误码

RtcEngine 类提供了供 App 调用的主要接口方法。

Hierarchy

RtcEngine

Implements

RtcEngineInterface

Index

Methods

addListener

addListener<EventType>(event: EventType, listener: RtcEngineEvents[EventType]): Subscription

添加 RtcEngineEvents 回调事件。

设置后，你可以通过 RtcEngineEvents 回调监听对应 RtcEngine 对象的事件、获取数据。

Type parameters
- EventType: keyof RtcEngineEvents
Parameters
- event: EventType
  
  事件类型。
- listener: RtcEngineEvents[EventType]
  
  RtcEngineEvents 回调事件。
Returns Subscription

addPublishStreamUrl

addPublishStreamUrl(url: string, transcodingEnabled: boolean): Promise<void>

增加旁路推流地址。
deprecated
该方法自 3.6.2 版废弃，替代方案请参考发版说明。

调用该方法后，你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告增加旁路推流地址的状态。

Note
- 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
- 该方法仅适用直播场景。
- 请确保在成功加入频道后才能调用该接口。
- 该方法每次只能增加一路旁路推流地址。如需推送多路流，则需多次调用该方法。
- 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
Parameters
- url: string
  
  CDN 推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。url 不支持中文等特殊字符。
- transcodingEnabled: boolean
  是否转码。如果设为 true，则需要在该方法前先调用 setLiveTranscoding 方法。
  - true：转码。转码是指在旁路推流时对音视频流进行转码处理后，再推送到其他 CDN 服务器服务器。多适用于频道内有多个主播，需要进行混流、合图的场景。
  - false：不转码。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument)：参数无效，一般是 URL 为空或是长度为 0 的字符串
  - 7(NotInitialized)：推流时未初始化引擎。

addVideoWatermark

addVideoWatermark(watermarkUrl: string, options: WatermarkOptions): Promise<void>

添加本地视频水印。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的观众、旁路直播观众和录制设备都能看到或采集到该水印图片。声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系：
- 如果视频编码方向/ORIENTATION_MODE 固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
- 如果视频编码方向/ORIENTATION_MODE 固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
- 设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。
Note
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 如果你只是在旁路直播（推流到CDN）中添加水印，你可以使用本方法或 setLiveTranscoding 方法设置水印。
- 待添加图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览，那么本方法的 visibleInPreview 可设置水印在预览时是否可见。
- 如果你已设置本地视频为镜像模式，那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像，声网建议你不要对本地视频同时使用镜像和水印功能，请在应用层实现本地水印功能。
Parameters
- watermarkUrl: string
  
  待添加的水印图片的本地路径。本方法支持从本地路径和 assets 路径添加水印图片。如果使用 assets 路径，需要以 /assets/ 开头。
- options: WatermarkOptions
  
  待添加的水印图片的设置选项。
Returns Promise<void>

adjustAudioMixingPlayoutVolume

adjustAudioMixingPlayoutVolume(volume: number): Promise<void>

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

该方法调节混音里音乐文件在本端播放的音量大小。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- volume: number
  
  伴奏音量范围为 [0,100]。默认 100 为原始文件音量。
Returns Promise<void>

adjustAudioMixingPublishVolume

adjustAudioMixingPublishVolume(volume: number): Promise<void>

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

Note

该方法调节混音里音乐文件在远端播放的音量大小。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- volume: number
  
  伴奏音量范围为 [0,100]。默认 100 为原始文件音量。
Returns Promise<void>

adjustAudioMixingVolume

adjustAudioMixingVolume(volume: number): Promise<void>

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

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Note
- 该方法调节混音里伴奏在本端和远端播放的音量大小。请在频道内调用该方法。
- 调用该方法不影响调用 playEffect 播放音效文件的音量。
Parameters
- volume: number
  
  伴奏音量范围为 [0,100]。默认 100 为原始文件音量。
Returns Promise<void>

adjustPlaybackSignalVolume

adjustPlaybackSignalVolume(volume: number): Promise<void>

调节本地播放的所有远端用户音量。

Note
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 静音本地音频需同时调用该方法和 adjustAudioMixingVolume 方法，并将 volume 参数设置为 0。
Parameters
- volume: number
  播放音量。取值范围为 [0,400]，其中：
  - 0: 静音
  - 100:（默认）原始音量
  - 400: 原始音量的 4 倍（自带溢出保护）
Returns Promise<void>

adjustRecordingSignalVolume

adjustRecordingSignalVolume(volume: number): Promise<void>

调节麦克风采集信号音量。

Parameters
- volume: number
  麦克风采集信号音量。取值范围为 [0,400]，其中：
  - 0: 静音
  - 100:（默认）原始音量
  - 400: 原始音量的 4 倍（自带溢出保护）
Returns Promise<void>

adjustUserPlaybackSignalVolume

adjustUserPlaybackSignalVolume(uid: number, volume: number): Promise<void>

调节本地播放的指定远端用户音量。

你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量，则需多次调用该方法。

Note
- 该方法要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
- 该方法每次只能调整一位远端用户在本地播放的音量。如需调整多位远端用户在本地播放的音量，则需多次调用该方法。
Parameters
- uid: number
  
  远端用户的 ID。
- volume: number
  播放音量，取值范围为 [0,100]。
  - 0：静音。
  - 100：（默认）原始音量。
Returns Promise<void>

clearVideoWatermarks

clearVideoWatermarks(): Promise<void>

删除本地视频水印。

该方法删除使用 addVideoWatermark 方法添加的本地视频水印。

Returns Promise<void>

complain

complain(callId: string, description: string): Promise<void>

投诉通话质量。

该方法让用户就通话质量进行投诉。一般在通话结束后调用。

Parameters
- callId: string
  
  通话 getCallId 函数获取的通话 ID。
- description: string
  
  （非必选项）给通话的描述，可选，长度应小于 800 字节。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument): 参数无效。
  - 3(NotReady)：SDK 初始化失败，请尝试重新初始化 SDK。

configRhythmPlayer

configRhythmPlayer(config: RhythmPlayerConfig): Promise<void>

配置虚拟节拍器。

自从 v3.4.2

调用 startRhythmPlayer 后，你可以调用该方法重新配置虚拟节拍器。

Note 重新配置虚拟节拍器后，SDK 会从头开始播放指定的音效文件，并根据你设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。

Parameters
- config: RhythmPlayerConfig
  
  节拍器配置，详见 RhythmPlayerConfig。
Returns Promise<void>

createDataStream

createDataStream(reliable: boolean, ordered: boolean): Promise<number>

创建数据流。

deprecated

This method is deprecated from v3.3.1. Use the createDataStreamWithConfig method instead.

该方法用于创建数据流。RtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。频道内数据通道最多允许数据延迟 5 秒，若超过 5 秒接收方尚未收到数据流，则数据通道会向 App 报错。

Parameters
- reliable: boolean
  是否可靠。
  - true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 StreamMessageError 回调并获得相应报错信息。
  - false: 接收方不保证收到，就算数据丢失也不会报错。
- ordered: boolean
  是否有序。
  - true: 接收方会按照发送方发送的顺序收到数据包。
  - false: 接收方不保证按照发送方发送的顺序收到数据包。
Returns Promise<number>
- 方法调用成功时，返回创建的数据流 ID。
- 方法调用失败时，返回错误码。

createDataStreamWithConfig

createDataStreamWithConfig(config: DataStreamConfig): Promise<number>

创建数据流。

自从 v3.3.1

该方法用于创建数据流。每个用户在每个频道内最多只能创建 5 个数据流。

该方法不支持数据可靠，接收方会丢弃超出发送时间 5 秒后的数据包。

Parameters
- config: DataStreamConfig
  
  数据流设置。详见 DataStreamConfig。
Returns Promise<number>
- 方法调用成功时，返回创建的数据流 ID。
- 方法调用失败时，返回错误码。

destroy

destroy(): Promise<void>

销毁 RtcEngine 实例。

该方法释放声网 SDK 使用的所有资源。有些 app 只在用户需要时才进行语音通话，不需要时则将资源释放出来用于其他操作，该方法对这类程序可能比较有用。只要调用了 destroy 方法，用户将无法再使用和回调该 SDK 内的其它方法。如需再次使用通信功能，必须重新创建一个 RtcEngine 实例。

Note
- 该方法需要在子线程中操作。
- 该方法为同步调用。在等待 RtcEngine 实例资源释放后再返回。 APP 不应该在 SDK 产生的回调中调用该接口，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。
- 如果需要在销毁后再次创建 RtcEngine 实例，需要等待 destroy 方法执行结束，收到返回值后才能再创建实例。
Returns Promise<void>

disableAudio

disableAudio(): Promise<void>

关闭音频模块。

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

disableLastmileTest

disableLastmileTest(): Promise<void>

关闭网络测试。

Returns Promise<void>

disableVideo

disableVideo(): Promise<void>

关闭视频模块。

该方法用于关闭视频。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启纯音频模式，在通话中调用则由视频模式切换为纯音频频模式。调用 enableVideo 方法可开启视频模式。

成功调用该方法后，远端会触发 UserEnableVideo(false) 回调。

Note
- 该方法设置的是音频模块为禁用状态，在频道内和频道外均可调用，且在 leaveChannel 后仍然有效。
- 该方法关闭整个音频模块，响应速度较慢，因此声网建议使用如下方法来控制视频模块：
  - enableLocalVideo：是否启动摄像头采集并创建本地视频流。
  - muteLocalVideoStream：是否发布本地视频流。
  - muteRemoteVideoStream：是否接收并播放远端视频流。
  - muteAllRemoteVideoStreams：是否接收并播放所有远端视频流。
Returns Promise<void>

enableAudio

enableAudio(): Promise<void>

启用音频模块（默认为开启状态）。

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

enableAudioVolumeIndication

enableAudioVolumeIndication(interval: number, smooth: number, report_vad: boolean): Promise<void>

启用说话者音量提示。

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

Parameters
- interval: number
  指定音量提示的时间间隔：
  - ≤ 0：禁用音量提示功能。
  - > 0：返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 AudioVolumeIndication 回调。
- smooth: number
  
  平滑系数，指定音量提示的灵敏度。取值范围为 [0, 10]，建议值为 3，数字越大，波动越灵敏；数字越小，波动越平滑。
- report_vad: boolean
  是否开启人声检测
  - true: 开启本地人声检测功能。开启后，AudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
  - false: （默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，AudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
Returns Promise<void>

enableContentInspect

enableContentInspect(enabled: boolean, config: ContentInspectConfig): Promise<void>

开启/关闭视频截图上传。
since
v3.6.2

开启视频截图上传后，SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率对本地用户发送的视频进行截图和上传。截图完成后，声网服务器会以 HTTPS 请求的形式，向你的服务器发送回调通知，并将所有截图发送至你指定的第三方云存储。

Note 调用该方法前，请确保满足以下要求：
- 联系技术支持开通声网视频截图上传服务。
- 已将以下动态库集成到项目中：
- Android：libagora_ci_extension.so
- iOS：AgoraCIExtension.xcframework
Parameters
- enabled: boolean
  设置是否开启视频截图上传：
  - true：开启。
  - false：关闭。
- config: ContentInspectConfig
  
  视频截图上传配置。详见 ContentInspectConfig。
Returns Promise<void>

enableDeepLearningDenoise

enableDeepLearningDenoise(enabled: boolean): Promise<void>

开启或关闭 AI 降噪模式。

自从 v3.3.1

SDK 默认开启传统降噪模式，以消除大部分平稳噪声。如果你还需要消除非平稳噪声，声网推荐你按如下步骤开启 AI 降噪模式：
- 1. 将 libs 文件夹中的以下文件集成到项目中：
  - Android: libagora_ai_denoise_extension.so
  - iOS: AgoraAIDenoiseExtension.xcframework
- 1. 调用 enableDeepLearningDenoise(true)。
AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。

成功开启 AI 降噪模式后，如果 SDK 检测到当前设备的性能不足，SDK 会自动关闭 AI 降噪模式，并开启传统降噪模式。

在频道内，如果你调用了 enableDeepLearningDenoise(false) 或 SDK 自动关闭了 AI 降噪模式，当你需要重新开启 AI 降噪模式时，你需要先调用 leaveChannel，再调用 enableDeepLearningDenoise(true)。

Note
- 该方法需要动态加载 libagora_ai_denoise_extension.so（Android）或 AgoraAIDenoiseExtension.xcframework（iOS），所以声网推荐在加入频道前调用该方法。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
Parameters
- enabled: boolean
  是否开启 AI 降噪模式：
  - true：开启。
  - false：关闭。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - -157 (ERR_MODULE_NOT_FOUND)：未集成 AI 降噪库。

enableDualStreamMode

enableDualStreamMode(enabled: boolean): Promise<void>

开/关视频双流模式。

该方法设置单流或者双流模式。发送端开启双流模式后，接收端可以选择接收大流还是小流。其中，大流指高分辨率、高码率的视频流，小流指低分辨率、低码率的视频流。

Parameters
- enabled: boolean
  指定双流或者单流模式：
  - true: 双流。
  - false: （默认）单流。
Returns Promise<void>

enableEncryption

enableEncryption(enabled: boolean, config: EncryptionConfig): Promise<void>

开启或关闭内置加密。

自从 v3.1.2。

在安全要求较高的场景下，声网建议你在加入频道前，调用 enableEncryption 方法开启内置加密。

用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

自 v3.4.5 起，声网推荐使用 AES128GCM2 或 AES256GCM2 加密模式。这两种模式支持设置盐，安全性更高。设置方法详见《媒体流加密》。

Warning 同一频道内所有用户必须使用相同的加密模式、密钥和盐，否则用户之间无法互通。

Note
- 如果开启了内置加密，则不能使用 RTMP 推流功能。
- 为加强安全性，声网建议每次启用媒体流加密时都更换新的密钥和盐。
Parameters
- enabled: boolean
  是否开启内置加密：
  - true：开启内置加密。
  - false：开启内置加密。
- config: EncryptionConfig
  
  配置内置加密方案。详见 EncryptionConfig。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument): 参数无效。
  - 4(NotSupported): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
  - 7(NotInitialized): SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。

enableFaceDetection

enableFaceDetection(enable: boolean): Promise<void>

开启/关闭本地人脸检测。

开启本地人脸检测后，SDK 会触发 FacePositionChanged 回调向你报告人脸检测的信息：
- 摄像头采集的画面大小。
- 人脸在画面中的位置。
- 人脸距设备屏幕的距离。
Note 该方法在加入频道前后都能调用。
Parameters
- enable: boolean
  是否开启人脸检测：
  - true: 开启人脸检测。
  - false: （默认）关闭人脸检测。
Returns Promise<void>

enableInEarMonitoring

enableInEarMonitoring(enabled: boolean): Promise<void>

开启耳返功能。

Parameters
- enabled: boolean
  是否开启耳返功能：
  - true: 开启耳返功能。
  - false: （默认）关闭耳返功能。
Returns Promise<void>

enableLastmileTest

enableLastmileTest(): Promise<void>

启用网络测试。

该方法启用网络连接质量测试，用于检测用户网络接入质量。默认该功能为关闭状态。该方法主要用于以下两种场景：
- 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。无论哪种场景，启用该方法会消耗一定的网络流量，影响通话质量。在收到 LastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换用户角色。
Note

该方法请勿与 startLastmileProbeTest 同时使用。
- 调用该方法后，在收到 LastmileQuality 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此回调无法执行。
- 直播场景下，主播在加入频道后，请勿调用该方法。
- 加入频道前调用该方法检测网络质量后，SDK 会占用一路视频的带宽，码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后，无论是否调用了 disableLastmileTest，SDK 均会自动停止带宽占用。
Returns Promise<void>

enableLocalAudio

enableLocalAudio(enabled: boolean): Promise<void>

开启/关闭本地音频采集。

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

该方法不影响接收远端音频流，enableLocalAudio(false) 适用于只听不发的用户场景。

语音功能关闭或重新开启后，会收到回调 LocalAudioStateChanged，并报告 Stopped 或 Recording。

Note 该方法与 muteLocalAudioStream 的区别在于：
- enableLocalAudio 开启或关闭本地语音采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
- muteLocalAudioStream 停止或继续发送本地音频流。
Parameters
- enabled: boolean
  是否开启本地语音。
  - true:（默认）重新开启本地语音，即开启本地语音采集。
  - false: 关闭本地语音，即停止本地语音采集。
Returns Promise<void>

enableLocalVideo

enableLocalVideo(enabled: boolean): Promise<void>

开启/关闭本地视频采集。

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

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

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

Note

该方法设置的是内部引擎为启用或禁用状态，在 leaveChannel 后仍然有效。

Parameters
- enabled: boolean
  是否启用本地视频：
  - true: 开启本地视频采集和渲染（默认）。
  - false: 关闭使用本地摄像头设备。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。
Returns Promise<void>

enableLocalVoicePitchCallback

enableLocalVoicePitchCallback(interval: number): Promise<void>

开启本地语音音调回调。

since

v3.7.0

该方法允许 SDK 定期向 app 报告本地用户的语音音调。开启本地音频采集并调用该方法后，SDK 会按设置的时间间隔触发 LocalVoicePitchInHz 回调。\

Note 该方法在加入频道前后均可调用。

Parameters
- interval: number
  设置 SDK 触发 LocalVoicePitchInHz 回调的时间间隔：
  - ≤ 0：关闭 LocalVoicePitchInHz 回调。
  - > 0：SDK 触发 LocalVoicePitchInHz 回调的时间间隔，单位为毫秒。取值需大于等于 10 毫秒，如果小于 10 毫秒，SDK 会自动调整为 10 毫秒。
Returns Promise<void>

enableRemoteSuperResolution

enableRemoteSuperResolution(uid: number, enable: boolean): Promise<void>

开启/关闭远端视频超分辨率。(beta 功能）

自从 v3.5.2

该功能可以有效地提升本地用户看到的远端视频画面的分辨率。远端用户视频的原始分辨率为 a × b，开启该功能后，本地设备会以 2a × 2b 的分辨率显示该远端视频。

调用该方法后，SDK 会触发 UserSuperResolutionEnabled 回调报告超分辨率是否成功开启。

Warning 超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗，只可以对一个远端用户开启超分辨率，并且远端用户视频的原始分辨率不能超过一定范围。如果本地用户在 Android 系统上应用超分辨率，远端视频原始分辨率不能超过 640 × 360；如果本地用户在 iOS 系统上应用超分辨率，远端视频原始分辨率不能超过 640 × 480。当超出限制时，SDK 会触发 Warning 回调，并返回相应的警告码：
- SuperResolutionStreamOverLimitation(1610)：远端用户的原始视频分辨率超出了可以应用超分辨率的范围。
- SuperResolutionUserCountOverLimitation(1611)：已对一个远端用户的视频使用超分辨率。
- SuperResolutionDeviceNotSupported(1612)：设备不支持使用超分辨率。
Note 该方法对用户设备具有一定要求，声网推荐你使用如下或更好的设备：
- Android：
  - VIVO：V1821A，NEX S，1914A，1916A，1962A，1824BA，X60，X60 Pro
  - OPPO：PCCM00，Find X3
  - 一加：A6000
  - 小米：Mi 8，Mi 9，Mi 10，Mi 11，MIX3，Redmi K20 Pro
  - 三星：SM-G9600，SM-G9650，SM-N9600，SM-G9708，SM-G960U，SM-G9750，S20，S21
  - 华为：SEA-AL00，ELE-AL00，VOG-AL00，YAL-AL10，HMA-AL00，EVR-AN00，nova 4，nova 5 Pro，nova 6 5G，nova 7 5G，Mate 30，Mate 30 Pro，Mate 40，Mate 40 Pro，P40，P40 Pro，华为平板 M6，MatePad 10.8
- iOS（系统版本 12 或之后）：
  - iPhone XR
  - iPhone XS
  - iPhone XS Max
  - iPhone 11
  - iPhone 11 Pro
  - iPhone 11 Pro Max
  - iPhone 12
  - iPhone 12 mini
  - iPhone 12 Pro
  - iPhone 12 Pro Max
  - iPhone 12 SE（第二代）
  - iPad Pro 11-inch（第三代）
  - iPad Pro 12.9-inch（第三代）
  - iPad Air（第三代）
  - iPad Air（第四代）
Parameters
- uid: number
  
  远端用户 ID。
- enable: boolean
  是否对远端视频开启超分辨率：
  - true: 开启。
  - false: 关闭。
Returns Promise<void>
- 0：方法调用成功。
- < 0：方法调用失败。
  - 157 (ModuleNotFound)：未集成超分辨率动态库。

enableSoundPositionIndication

enableSoundPositionIndication(enabled: boolean): Promise<void>

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

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

Parameters
- enabled: boolean
  是否开启远端用户语音立体声：
  - true: 开启。
  - false: （默认）关闭。
Returns Promise<void>

enableVideo

enableVideo(): Promise<void>

启用视频模块。

该方法用于打开视频模式。可以在加入频道前或者通话中调用，在加入频道前调用，则自动开启视频模式，在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。

成功调用该方法后，远端会触发 UserEnableVideo(true) 回调。

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

enableVirtualBackground

enableVirtualBackground(enabled: boolean, backgroundSource: VirtualBackgroundSource): Promise<void>

开启/关闭虚拟背景。

自从 v3.5.0.3

开启虚拟背景功能后，你可以使用自定义的背景图替代本地用户原来的背景图。替换后，频道内所有用户都能看到自定义的背景图。你可以从 VirtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。

Note
- 请在 enableVideo 后调用该方法。
- 该功能对设备性能要求较高，声网推荐你在如下设备上使用：
  - Android：搭载如下芯片的设备：
    - 骁龙 700 系列 750G 及以上
    - 骁龙 800 系列 835 及以上
    - 天玑 700 系列 720 及以上
    - 麒麟 800 系列 810 及以上
    - 麒麟 900 系列 980 及以上
  - iOS：载 A9 及以上芯片的如下设备：
    - iPhone 6S 及以上
    - iPad Air 第三代及以上
    - iPad 第五代及以上
    - iPad Pro 第一代及以上
    - iPad mini 第五代及以上
- 声网建议你在满足如下条件的场景中使用该功能：
  - 使用高清摄像设备、摄像环境光照均匀。
  - 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。
- 对早于 3.6.2 版，虚拟背景功能不支持 Texture 格式视频。
Parameters
- enabled: boolean
  设置是否开启虚拟背景：
  - true：开启。
  - false：关闭。
- backgroundSource: VirtualBackgroundSource
  
  自定义的背景图。详见 VirtualBackgroundSource。注意：为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配，SDK 会在保证自定义背景图内容不变形的前提下，对自定义背景图进行缩放和裁剪。
Returns Promise<void>

enableWebSdkInteroperability

enableWebSdkInteroperability(enabled: boolean): Promise<void>

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

deprecated

该方法已废弃。自 v3.0.1 起，SDK 自动开启与 Web SDK 的互通，无需调用该方法开启。

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

该方法仅在直播场景下适用，通信场景下默认互通是打开的。

Parameters
- enabled: boolean
  是否打开与 Web SDK 的互通：
  - true: 打开互通。
  - false: （默认）关闭互通。
Returns Promise<void>

enableWirelessAccelerate

enableWirelessAccelerate(enabled: boolean): Promise<void>

开启或关闭 Wi-Fi 加速功能。
since
v3.6.2

当 SDK 发现集成加速插件的 Wi-Fi 路由器后，该功能才会生效，使路由器合理分配 Wi-Fi 频谱资源，以降低丢包率和时延，从而减少音视频卡顿。

当路由器提供加速服务后，SDK 会周期性触发 WlAccStats 回调，报告 Wi-Fi 连接优化数据，并在 Wi-Fi 连接质量不佳时触发 WlAccMessage 回调，报告 Wi-Fi 连接质量不佳的原因和改善 Wi-Fi 连接的操作建议。

Note
- Wi-Fi 加速功能默认开启，但必须与集成加速插件的路由器配合使用才能生效，详见哪些 Wi-Fi 路由器可支持加速功能。
- 加速功能生效后，路由器的 app 会显示加速效果和被加速 app 的名称。如果你不想在路由器的 app 中展示被加速 app 的名称，请调用 enableWirelessAccelerate(false) 关闭加速功能。如果 Wi-Fi 路由器不支持加速功能，系统性能不会受损。
- 请在加入频道前或离开频道后调用该方法。
- 声网提供的 Wi-Fi 加速功能除应用于音视频流，还可以应用于其他第三方业务流，如私有信令、课件、RTMP 协议等。如有需要，请联系 sales@agora.io。
Parameters
- enabled: boolean
  设置是否开启 Wi-Fi 加速功能：
  - true：开启。
  - false：关闭。
Returns Promise<void>

getAudioFileInfo

getAudioFileInfo(filePath: string): Promise<void>

获取指定音频文件信息。

自从 v3.5.2

成功调用该方法后，SDK 会触发 RequestAudioFileInfo 回调，报告指定音频文件的时长等信息。你可以多次调用该方法，获取多个音频文件的信息。

Note
- 该方法需要在加入频道后调用。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Parameters
- filePath: string
  文件路径。需精确到文件名及后缀。
  - Android：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note: 通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
  - iOS：音频文件的绝对路径或 URL 地址。例如：/var/mobile/Containers/Data/audio.mp4。
Returns Promise<void>

getAudioMixingCurrentPosition

getAudioMixingCurrentPosition(): Promise<number>

获取音乐文件的播放进度。

Note
- 该方法获取当前伴奏播放进度，单位为毫秒。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。
- 如需多次调用 getAudioMixingCurrentPosition，请确保调用间隔大于 500 ms。
Returns Promise<number>
- 方法调用成功时，返回伴奏播放进度。
- 方法调用失败时，返回错误码。

getAudioMixingDuration

getAudioMixingDuration(filePath?: undefined | string): Promise<number>

获取音乐文件的时长。

deprecated

该方法自 v3.5.2 起废弃，请改用 getAudioFileInfo。

Note

该方法获取音乐文件时长，单位为毫秒。你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- Optional filePath: undefined | string
  自从 v3.4.2 文件路径，需精确到文件名及后缀。
  - Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Android 支持的媒体格式。
  - iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Best Practices for iOS Audio。
Returns Promise<number>
- 方法调用成功时，返回伴奏时长。
- 方法调用失败时，返回错误码。

getAudioMixingPlayoutVolume

getAudioMixingPlayoutVolume(): Promise<number>

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

该方法获取音乐文件的本地播放音量。该接口可以方便开发者排查音量相关问题。

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Returns Promise<number>
- 方法调用成功时，返回音量值，范围为 [0,100]。
- 方法调用失败时，返回错误码。

getAudioMixingPublishVolume

getAudioMixingPublishVolume(): Promise<number>

获取音乐文件的远端播放音量。

该方法获取音乐文件的远端播放音量。该接口可以方便开发者排查音量相关问题。

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Returns Promise<number>
- 方法调用成功则返回音量值，范围为 [0,100]。
- 方法调用失败时，返回错误码。

getAudioTrackCount

getAudioTrackCount(): Promise<number>

获取当前音乐文件的音轨数量。

自从 v3.5.2

Note
- 你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Returns Promise<number>
- 方法调用成功，返回当前音乐文件的音轨数量。
- 方法调用失败，返回错误码。

getCallId

getCallId(): Promise<string>

获取通话 ID。

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

Returns Promise<string>

通话 ID。

getCameraMaxZoomFactor

getCameraMaxZoomFactor(): Promise<number>

获取摄像头支持最大缩放比例。

Returns Promise<number>

该相机支持的最大缩放比例。

getConnectionState

getConnectionState(): Promise<ConnectionStateType>

获取当前网络连接状态。

Returns Promise<ConnectionStateType>

getEffectCurrentPosition

getEffectCurrentPosition(soundId: number): Promise<number>

获取指定音效文件的播放进度。

自从 v3.4.2

Note 该方法需要在 playEffect 后调用。

Parameters
- soundId: number
  
  音效 ID。请确保与 playEffect 中设置的 soundId 一致。
Returns Promise<number>
- 方法调用成功时，返回指定音效文件的播放进度（毫秒）。
- 方法调用失败时，返回错误码。

getEffectDuration

getEffectDuration(filePath: string): Promise<number>

获取指定音效文件总时长。

自从 v3.4.2

Note
- 该方法需要在加入频道后调用。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Parameters
- filePath: string
  文件路径，需精确到文件名及后缀。
  - Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。
  - iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。
Returns Promise<number>
- 方法调用成功时，返回指定音效文件时长（毫秒）。
- 方法调用失败时，返回错误码。

getEffectsVolume

getEffectsVolume(): Promise<number>

获取所有音效文件播放音量, 范围为 [0.0,100.0]。

Returns Promise<number>
- 方法调用成功时，返回音效的音量值。
- 方法调用失败时，返回错误码。

getNativeHandle

getNativeHandle(): Promise<number>

该方法获取 native SDK engine 的 C++ handle，用于包括注册音视频帧观测器在内的特殊场景。

Returns Promise<number>

getUserInfoByUid

getUserInfoByUid(uid: number): Promise<UserInfo>

通过 UID 获取用户信息。

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

Parameters
- uid: number
  
  用户 ID。该参数为必填。
Returns Promise<UserInfo>

getUserInfoByUserAccount

getUserInfoByUserAccount(userAccount: string): Promise<UserInfo>

通过 User Account 获取用户信息。

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

Parameters
- userAccount: string
  
  用户 User Account。该参数为必填。
Returns Promise<UserInfo>

isCameraAutoFocusFaceModeSupported

isCameraAutoFocusFaceModeSupported(): Promise<boolean>

检测设备是否支持人脸对焦功能。

Returns Promise<boolean>
- true：设备支持人脸对焦功能。
- false：设备不支持人脸对焦功能。

isCameraExposurePositionSupported

isCameraExposurePositionSupported(): Promise<boolean>

检测设备是否支持手动曝光功能。

Returns Promise<boolean>
- true：设置支持手动曝光功能。
- false：设备不支持手动曝光功能。

isCameraFocusSupported

isCameraFocusSupported(): Promise<boolean>

检测设备是否支持手动对焦功能。

Returns Promise<boolean>
- true：设备支持手动对焦功能。
- false：设备不支持手动对焦功能。

isCameraTorchSupported

isCameraTorchSupported(): Promise<boolean>

检查设备是否支持打开闪光灯。

SDK 默认使用前置摄像头，因此如果你直接调用 isCameraTorchSupported，你可以从返回值中了解使用前置摄像头时是否支持打开闪光灯。如果你想检查使用后置摄像头时设备是否支持打开闪光灯，请先调用 switchCamera 切换 SDK 使用的摄像头为后置摄像头，再调用 isCameraTorchSupported。

Note 该方法需在摄像头启动后调用。

Returns Promise<boolean>
- true：设备支持打开闪光灯。
- false：设备不支持打开闪光灯。

isCameraZoomSupported

isCameraZoomSupported(): Promise<boolean>

检测设备是否支持摄像头缩放功能。

Returns Promise<boolean>
- true：设备支持相机缩放功能。
- false：设备不支持相机缩放功能。

isSpeakerphoneEnabled

isSpeakerphoneEnabled(): Promise<boolean>

检查扬声器状态启用状态。

Note 该方法在加入频道前后都能调用。

Returns Promise<boolean>
- true：扬声器已开启，语音会输出到扬声器。
- false：扬声器未开启，语音会输出到非扬声器（听筒，耳机等）。

joinChannel

joinChannel(token: string | undefined | null, channelName: string, optionalInfo: string | undefined | null, optionalUid: number, options?: ChannelMediaOptions): Promise<void>

加入频道。

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

成功调用该方加入频道后，本地会触发 JoinChannelSuccess 回调；通信场景下的用户和直播场景下的主播加入频道后，远端会触发 UserJoined 回调。

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

用户成功加入频道后，默认发布本地音视频流并自动订阅频道内所有其他用户的音视频流。订阅音视频流会产生用量并影响计费。如果想取消订阅，可以通过设置 options 参数或相应的 mute 方法实现。

Note
- 频道内每个用户的 UID 必须是唯一的。如果将 uid 设为 0，系统将自动分配一个 UID。如果想要从不同的设备同时接入同一个频道，请确保每个设备上使用的 UID 是不同的。
- 请确保用于生成 Token 的 App ID 和 create 方法创建 RtcEngine 对象时用的 App ID 一致。
Parameters
- token: string | undefined | null
  
  在你的服务器上生成的 Token。详见使用 Token 鉴权。
- channelName: string
  标识通话的频道名称，长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
- optionalInfo: string | undefined | null
  
  （非必选项）开发者需加入的任何附加信息。一般可设置为空字符串，或频道相关信息。该信息不会传递给频道内的其他用户。
- optionalUid: number
  
  （非必选项）用户 ID，32 位无符号整数。建议设置范围：1 到 (2^32-1)，并保证唯一性。如果不指定（即设为 0），SDK 会自动分配一个，并在 JoinChannelSuccess 回调方法中返回，App 层必须记住该返回值并维护，SDK 不对该返回值进行维护。
- Optional options: ChannelMediaOptions
  
  自从 v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument): 参数无效。
  - 3(NotReady): SDK 初始化失败，请尝试重新初始化 SDK。
  - 5(Refused): 调用被拒绝。可能有如下两个原因：
    - 已经创建了一个同名的 RtcChannel 频道。
    - 已经通过 RtcChannel 加入了一个频道，并在该 RtcChannel 频道中发布了音视频流。由于通过 RtcEngine 加入频道会默认发布音视频流，而 SDK 不支持同时在两个频道发布音视频流，因此会报错。
  - 7(NotInitialized): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。
  - 17(JoinChannelRejected)：加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 RtcEngine 频道，当已经加入 RtcEngine 频道的用户使用有效的频道名再次调用 RtcEngine 类中的加入频道方法时，会返回此错误码。

joinChannelWithUserAccount

joinChannelWithUserAccount(token: string | undefined | null, channelName: string, userAccount: string, options?: ChannelMediaOptions): Promise<void>

使用 User Account 加入频道。

该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：
- 本地：LocalUserRegistered 和 JoinChannelSuccess 回调。
- 通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 UserJoined 和 UserInfoUpdated 回调。
用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

Note
- 为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。
- 如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。
- 请确保在使用 String 型用户名前阅读如何使用 String 型用户 ID，了解使用限制及实现方法。
Parameters
- token: string | undefined | null
  
  在你的服务器上生成的 Token。详见使用 Token 鉴权。
- channelName: string
  标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
- userAccount: string
  用户 User Account。该参数为必需，最大不超过 255 字节，不可为 null。请确保加入频道的 User Account 的唯一性。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
- Optional options: ChannelMediaOptions
  
  自从 v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument): 参数无效。
  - 3(NotReady): SDK 初始化失败，请尝试重新初始化 SDK。
  - 5(Refused): 调用被拒绝。
  - 17(JoinChannelRejected)：加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 RtcEngine 频道，当已经加入 RtcEngine 频道的用户使用有效的频道名再次调用 RtcEngine 类中的加入频道方法时，会返回此错误码。

leaveChannel

leaveChannel(): Promise<void>

离开频道。

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

调用 joinChannel 后，必须调用 leaveChannel 结束通话，否则无法开始下一次通话。

不管当前是否在通话中，都可以调用 leaveChannel，没有副作用。

该方法会把会话相关的所有资源释放掉。该方法是异步操作，调用返回时并没有真正退出频道。

成功调用该方法离开频道后，本地会触发 LeaveChannel 回调；通信场景下的用户和直播场景下的主播离开频道后，远端会触发 UserOffline 回调。

Note
- 如果你调用了 leaveChannel 后立即调用 destroy 方法，SDK 将无法触发 LeaveChannel 回调。
- 如果你在旁路推流过程中调用了 leaveChannel 方法， SDK 将自动调用 removePublishStreamUrl 方法。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 1(Failed): 一般性的错误（未明确归类）。
  - 2(InvalidArgument): 参数无效。
  - 7(NotInitialized): SDK 尚未初始化。

muteAllRemoteAudioStreams

muteAllRemoteAudioStreams(muted: boolean): Promise<void>

取消或恢复订阅所有远端用户的音频流。

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的音频流，包括在调用该方法后加入频道的用户的音频流。

Note
- 该方法需要在加入频道后调用。
- - 自 v3.3.1 起，该方法包含了 setDefaultMuteAllRemoteAudioStreams 的功能。声网建议不要一起调用 muteAllRemoteAudioStreams 和 setDefaultMuteAllRemoteAudioStreams，否则设置可能会不生效。详见《设置订阅状态》。
Parameters
- muted: boolean
  
  是否取消订阅所有远端用户的音频流。 - true: 取消订阅。 - false:（默认）订阅。
Returns Promise<void>

muteAllRemoteVideoStreams

muteAllRemoteVideoStreams(muted: boolean): Promise<void>

取消或恢复订阅所有远端用户的视频流。

成功调用该方法后，本地用户会取消或恢复订阅所有远端用户的视频流，包括在调用该方法后加入频道的用户的视频流。

Note
- 该方法需要在加入频道后调用。
- 自 v3.3.1 起，该方法包含了 setDefaultMuteAllRemoteVideoStreams 的功能。声网建议不要一起调用 muteAllRemoteVideoStreams 和 setDefaultMuteAllRemoteVideoStreams，否则设置可能会不生效。详见《设置订阅状态》。
Parameters
- muted: boolean
  是否取消订阅所有远端用户的视频流。
  - true: 取消订阅。
  - false:（默认）订阅。
Returns Promise<void>

muteLocalAudioStream

muteLocalAudioStream(muted: boolean): Promise<void>

取消或恢复发布本地音频流。

自 v3.4.5 起，该方法仅设置用户在 RtcEngine 频道中的音频发布状态。

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

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalAudioStream(false)，否则方法会调用失败并返回 -5 (ERR_REFUSED)。

Note
- 该方法不会改变音频采集设备的使用状态。
- 该方法的调用是否生效受 joinChannel 和 setClientRole 方法的影响，详见《设置发布状态》。
Parameters
- muted: boolean
  是否取消发布本地音频流。
  - true：取消发布。
  - false：发布。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - -5 (ERR_REFUSED)：调用被拒绝。

muteLocalVideoStream

muteLocalVideoStream(muted: boolean): Promise<void>

取消或恢复发布本地视频流。

自 v3.4.5 起，该方法仅设置用户在 RtcEngine 频道中的视频发布状态。

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

同一时间，本地的音视频流只能发布到一个频道。如果你创建了多个频道，请确保你只在一个频道中调用 muteLocalVideoStream(false)，否则方法会调用失败并返回 -5 (ERR_REFUSED)。

Note
- 该方法不会改变视频采集设备的使用状态。
- 该方法的调用是否生效受 joinChannel and setClientRole 方法的影响，详见《设置发布状态》。
Parameters
- muted: boolean
  是否取消发布本地视频流。
  - true：取消发布。
  - false：发布。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - -5 (ERR_REFUSED)：调用被拒绝。

muteRemoteAudioStream

muteRemoteAudioStream(uid: number, muted: boolean): Promise<void>

取消或恢复订阅指定远端用户的音频流。

Note
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
Parameters
- uid: number
  
  指定用户的用户 ID。
- muted: boolean
  是否取消订阅指定远端用户的音频流。
  - true：取消订阅。
  - false：（默认）订阅。
Returns Promise<void>

muteRemoteVideoStream

muteRemoteVideoStream(uid: number, muted: boolean): Promise<void>

取消或恢复订阅指定远端用户的视频流。

Note
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
Parameters
- uid: number
  
  指定用户的用户 ID。
- muted: boolean
  是否取消订阅指定远端用户的视频流。
  - true: 取消订阅。
  - false: （默认）订阅。
Returns Promise<void>

pauseAllChannelMediaRelay

pauseAllChannelMediaRelay(): Promise<void>

暂停向所有目标频道转发媒体流。

自从 v3.5.2

开始跨频道转发媒体流后，如果你需要暂停向所有频道转发媒体流，可以调用该方法；暂停后，如果要恢复跨频道媒体流转发，可以调用 resumeAllChannelMediaRelay 方法。

成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调，并在回调中报告是否成功暂停媒体流转发。

Note 该方法需要在 startChannelMediaRelay 后调用。

Returns Promise<void>

pauseAllEffects

pauseAllEffects(): Promise<void>

暂停播放所有音效文件。

Returns Promise<void>

pauseAudioMixing

pauseAudioMixing(): Promise<void>

暂停播放音乐文件及混音。

该方法暂停播放伴奏。请在频道内调用该方法。

Returns Promise<void>

pauseEffect

pauseEffect(soundId: number): Promise<void>

暂停播放指定音效文件。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID。
Returns Promise<void>

playEffect

playEffect(soundId: number, filePath: string, loopCount: number, pitch: number, pan: number, gain: number, publish: Boolean, startPos?: undefined | number): Promise<void>

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

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

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

Note 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

Parameters
- soundId: number
  
  音效文件的 ID。每个音效均有唯一的 ID。如果你已通过 preloadEffect 将音效加载至内存，确保这里的 soundID 与 preloadEffect 设置的 soundId 相同。
- filePath: string
  文件路径，需精确到文件名及后缀。
  - Android：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。
  - iOS：支持文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。
- loopCount: number
  音效文件循环播放的次数：
  - ≥ 0：循环播放次数。例如，1 表示循环播放 1 次，即总计播放 2 次。
  - -1：无限循环播放。
- pitch: number
  
  音效的音调。取值范围为 [0.5,2.0]。默认值为 1.0，代表原始音调。取值越小，则音调越低。
- pan: number
  音效的空间位置。取值范围为 [-1.0,1.0]：
  - -1.0: 音效出现在左边。
  - 0: 音效出现在正前边。
  - 1.0: 音效出现在右边。
- gain: number
  
  音效的音量。取值范围为 [0.0,100.0]。100.0 为默认值，代表原始音量。取值越小，则音量越低。
- publish: Boolean
  是否将音效发布到远端：
  - true: 音效在本地播放的同时，会发布到声网云上，因此远端用户也能听到该音效。
  - false: 音效不会发布到声网云上，因此只能在本地听到该音效。
- Optional startPos: undefined | number
  
  自从 v3.4.2 音乐文件的播放位置，单位为毫秒。
Returns Promise<void>

preloadEffect

preloadEffect(soundId: number, filePath: string): Promise<void>

将音效文件预加载至内存。

支持音频格式为 mp3、mp4、m4a、aac、3gp、mkv 和 wav。

Note
- 该方法不支持预加载在线音效文件。
- 为保证通话流畅度，请注意控制音效文件的大小。声网推荐你在加入频道前调用该方法。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Parameters
- soundId: number
  
  音效文件的 ID。
- filePath: string
  文件路径，需精确到文件名及后缀。
  - Android：支持本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note：通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。
  - iOS：支持文件的绝对路径，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。
Returns Promise<void>

rate

rate(callId: string, rating: Rate, description?: undefined | string): Promise<void>

给通话评分。

Parameters
- callId: string
  
  通过 getCallId 函数获取的通话 ID。
- rating: Rate
  
  给通话的评分，最低 1 分，最高 5 分，如超过这个范围，SDK 会返回 InvalidArgument(2) 错误。
- Optional description: undefined | string
  
  （非必选项）给通话的描述，可选，长度应小于 800 字节。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument): 参数无效。
  - 3(NotReady)：SDK 初始化失败，请尝试重新初始化 SDK。

registerLocalUserAccount

registerLocalUserAccount(appId: string, userAccount: string): Promise<void>

注册本地用户 User Account。

该方法为本地用户注册一个 User Account。注册成功后，该 User Account 即可标识该本地用户的身份，用户可以使用它加入频道。

成功注册 User Account 后，本地会触发 LocalUserRegistered 回调，告知本地用户的 UID 和 User Account。

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

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

registerMediaMetadataObserver

registerMediaMetadataObserver(): Promise<void>

注册媒体 Metadata 观测器。

该接口通过在直播的视频帧中同步添加 Metadata，实现发送商品链接、分发优惠券、发送答题等功能，构建更为丰富的直播互动方式。

Note

请在调用 joinChannel 加入频道前调用该方法。

Returns Promise<void>

removeAllListeners

removeAllListeners<EventType>(event?: EventType): void

删除所有的回调句柄。

Type parameters
- EventType: keyof RtcEngineEvents
Parameters
- Optional event: EventType
  
  事件类型。
Returns void

removeListener

removeListener<EventType>(event: EventType, listener: RtcEngineEvents[EventType], subscription?: EmitterSubscription): void

删除指定的 RtcEngineEvents 回调句柄。

该方法删除指定的回调句柄。对于某些注册的回调句柄，如果你在收到相应回调事件后无需再次接收回调消息，可以调用该方法移除回调句柄。

Type parameters
- EventType: keyof RtcEngineEvents
Parameters
- event: EventType
  
  事件类型。
- listener: RtcEngineEvents[EventType]
  
  RtcEngineEvents 回调句柄。
- Optional subscription: EmitterSubscription
Returns void

removePublishStreamUrl

removePublishStreamUrl(url: string): Promise<void>

删除旁路推流地址。
deprecated
该方法自 3.6.2 版废弃，替代方案请参考发版说明。

调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告删除旁路推流地址的状态。

Note
- 调用该方法前，请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
- 该方法只适用于直播场景。
- 该方法每次只能删除一路旁路推流地址。如需删除多路流，则需多次调用该方法。
Parameters
- url: string
  
  待删除的推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。
Returns Promise<void>

renewToken

renewToken(token: string): Promise<void>

更新 Token。

该方法用于更新 Token。如果启用了 Token 机制，过一段时间后使用的 Token 会失效。以下两种情况下，app 应重新获取 Token，然后调用 renewToken 更新 Token，否则 SDK 无法和服务器建立连接：
- 发生 TokenPrivilegeWillExpire 回调时。
- ConnectionStateChanged 回调报告 TokenExpired(9) 时。
Parameters
- token: string
  
  新的 Token。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 1(Failed): 一般性的错误（未明确归类）。
  - 2(InvalidArgument): 参数无效。
  - 7(NotInitialized): SDK 尚未初始化。

resumeAllChannelMediaRelay

resumeAllChannelMediaRelay(): Promise<void>

恢复向所有目标频道转发媒体流。

自从 v3.5.2

调用 pauseAllChannelMediaRelay 方法后，如果你需要恢复向所有目标频道转发媒体流，可以调用该方法。

成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调，并在回调中报告是否成功恢复媒体流转发。

Note 该方法需要在 pauseAllChannelMediaRelay 后调用。

Returns Promise<void>

resumeAllEffects

resumeAllEffects(): Promise<void>

恢复播放所有音效文件。

Returns Promise<void>

resumeAudioMixing

resumeAudioMixing(): Promise<void>

恢复播放音乐文件及混音。

该方法恢复混音，继续播放伴奏。请在频道内调用该方法。

Returns Promise<void>

resumeEffect

resumeEffect(soundId: number): Promise<void>

恢复播放指定音效文件。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID。
Returns Promise<void>

selectAudioTrack

selectAudioTrack(index: number): Promise<void>

指定当前音乐文件的播放音轨。

自从 v3.5.2

获取音乐文件的音轨数量后，你可以调用该方法指定任一音轨进行播放。例如，如果一个多音轨文件的不同音轨存放了不同语言的歌曲，则你可以调用该方法设置音乐文件的播放语言。

Note
- 你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Parameters
- index: number
Returns Promise<void>

sendCustomReportMessage

sendCustomReportMessage(id: string, category: string, event: string, label: string, value: number): Promise<void>

声网提供自定义数据上报和分析服务。

该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据，每条自定义数据不能超过 256 字节，每个字符串不能超过 100 字节。如需试用该服务，请联系 sales@agora.io 开通并商定自定义数据格式。

Parameters
- id: string
- category: string
- event: string
- label: string
- value: number
Returns Promise<void>

sendMetadata

sendMetadata(metadata: string): Promise<void>

发送 Metadata。

Parameters
- metadata: string
  
  想要发送的 Metadata。
  
  Note 请确保在该方法中传入的 Metadata 大小不超过 setMaxMetadataSize 中设定的值。
Returns Promise<void>

sendStreamMessage

sendStreamMessage(streamId: number, message: string): Promise<void>

发送数据流。

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

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

Note
- 请确保在调用该方法前，已调用 createDataStream 创建了数据通道。
- 该方法仅适用于通信场景以及直播场景下的主播用户。
Parameters
- streamId: number
  
  数据流 ID，createDataStream 的返回值。
- message: string
  
  待发送的数据。
Returns Promise<void>

setAVSyncSource

setAVSyncSource(channelId: string, uid: number): Promise<void>

设置发流端音画同步。

since

v3.6.2

同一用户可能使用两个设备分别发送音频流和视频流，为保证接收端听到和看到的音频和视频的时间同步性，你可以在视频发送端调用该方法，并传入音频发送端的频道名、用户 ID。SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流，以保证即使在两个发送端的上行网络情况不一致（如分别使用 Wi-Fi 和 4G 网络）的情况下，也能让接收到的音视频具有时间同步性。

Note 声网推荐你在加入频道前调用该方法。

Parameters
- channelId: string
  
  标识音频发送端所在频道的频道名。
- uid: number
  
  音频发送端的用户 ID。
Returns Promise<void>

setAgoraLibPath

setAgoraLibPath(path: string): Promise<void>

设置 .so 文件的存储目录
since
v3.6.2

默认情况下，SDK 从 app 的 nativeLibraryPath 中加载 .so 文件。你可以调用该方法指定 .so 文件的存储目录，SDK 会在初始化 RtcEngine 实例时根据指定的目录自动加载 .so 文件。

一般情况下，你需要在编译 app 时打包所需的 .so 文件，但这样可能会增加 app 的包体积。你可以调用该方法，使 app 在运行时动态加载需要的 .so 文件，从而减小 app 的包体积，详见减少 App 体积。

Note
- 该方法仅适用于 Android 平台。
- 请在创建 RtcEngine 实例前调用该方法。
- 该方法仅适用于手动集成 SDK，不适用于通过 Maven Central 或 JitPack 集成 SDK 的情况。
Parameters
- path: string
  
  .so 文件的存储目录，必须为 app 的私有目录，可以通过 Context.getDir() 获取。请确保指定的目录存在，否则 SDK 会报 InvalidParameterException 错误。
Returns Promise<void>

setAudioEffectParameters

setAudioEffectParameters(preset: AudioEffectPreset, param1: number, param2: number): Promise<void>

设置 SDK 预设人声音效的参数。

自从 v3.2.0。

调用该方法可以对本地发流用户进行如下设置：
- 3D 人声音效：设置 3D 人声音效的环绕周期。
- 电音音效：设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效，声网推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后，频道内所有用户都能听到该效果。

Note
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
- 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  - setAudioEffectPreset
  - setVoiceBeautifierPreset
  - setLocalVoiceReverbPreset
  - setLocalVoiceChanger
  - setLocalVoicePitch
  - setLocalVoiceEqualization
  - setLocalVoiceReverb
  - setVoiceConversionPreset
Parameters
- preset: AudioEffectPreset
  SDK 预设的音效：
  - 3D 人声音效：RoomAcoustics3DVoice
    - 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicStandardStereo(3) 或 MusicHighQualityStereo(5)，否则该枚举设置无效。
    - 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。
  - 电音音效：PitchCorrection。获取更好的人声效果，声网建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality(4) or MusicHighQualityStereo(5)。
- param1: number
  - 如果 preset 设为 RoomAcoustics3DVoice，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。
  - 如果 preset 设为 PitchCorrection，则 param1 表示电音音效的基础调式。可设为如下值：
    - 1: （默认）自然大调。
    - 2: 自然小调。
    - 3: 和风小调。
- param2: number
  - 如果 preset 设为 RoomAcoustics3DVoice，你需要将 param2 设置为 0。
  - 如果 preset 设为 PitchCorrection，则 param2 表示电音音效的主音音高。可设为如下值：
    - 1: A 调
    - 2: A# 调
    - 3: B 调
    - 4: （默认） C 调
    - 5: C# 调
    - 6: D 调
    - 7: D# 调
    - 8: E 调
    - 9: F 调
    - 10: F# 调
    - 11: G 调
    - 12: G# 调
Returns Promise<void>

setAudioEffectPreset

setAudioEffectPreset(preset: AudioEffectPreset): Promise<void>

设置 SDK 预设的人声音效。

自从 v3.2.0。

调用该方法可以为本地发流用户设置 SDK 预设的人声音效，且不会改变原声的性别特征。设置音效后，频道内所有用户都能听到该效果。

根据不同的场景，你可以为用户设置不同的音效。

为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。

Note
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
- 如果调用该方法并设置除 RoomAcoustics3DVoice 或 PitchCorrection 外的枚举，请勿再调用 setAudioEffectParameters，否则该方法设置的效果会被覆盖。
- 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  - setVoiceBeautifierPreset
  - setLocalVoiceReverbPreset
  - setLocalVoiceChanger
  - setLocalVoicePitch
  - setLocalVoiceEqualization
  - setLocalVoiceReverb
  - setVoiceConversionPreset
Parameters
- preset: AudioEffectPreset
  
  预设的音效选项。详见 AudioEffectPreset。
Returns Promise<void>

setAudioMixingDualMonoMode

setAudioMixingDualMonoMode(mode: AudioMixingDualMonoMode): Promise<void>

设置当前音乐文件的声道模式。

自从 v3.5.2

在双声道音乐文件中，左声道和右声道可以存储不同的音频数据。根据实际需要，你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如，在 KTV 场景中，音乐文件的左声道存储了伴奏，右声道存储了原唱的歌声。如果你只需听伴奏，调用该方法设置音乐文件的声道模式为左声道模式；如果你需要同时听伴奏和原唱，调用该方法设置声道模式为混合模式。

Note
- 你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。
- 该方法仅适用于双声道的音乐文件。
Parameters
- mode: AudioMixingDualMonoMode
  
  声道模式。详见 AudioMixingDualMonoMode。
Returns Promise<void>

setAudioMixingPitch

setAudioMixingPitch(pitch: number): Promise<void>

调整本地播放的音乐文件的音调。

本地人声和播放的音乐文件混音时，调用该方法可以仅调节音乐文件的音调。

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- pitch: number
  
  按半音音阶调整本地播放的音乐文件的音调，默认值为 0，即不调整音调。取值范围为 [-12,12]，每相邻两个值的音高距离相差半音。取值的绝对值越大，音调升高或降低得越多。
Returns Promise<void>

setAudioMixingPlaybackSpeed

setAudioMixingPlaybackSpeed(speed: number): Promise<void>

设置当前音乐文件的播放速度。

自从 v3.5.2

Note 你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- speed: number
  播放速度。推荐取值范围为 [50,400]，其中：
  - 50：0.5 倍速。
  - 100：原始速度。
  - 400：4 倍速。
Returns Promise<void>

setAudioMixingPosition

setAudioMixingPosition(pos: number): Promise<void>

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

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

你需要在调用 startAudioMixing 并收到 AudioMixingStateChanged(Playing) 回调后调用该方法。

Parameters
- pos: number
  
  整数。进度条位置，单位为毫秒。
Returns Promise<void>

setAudioProfile

setAudioProfile(profile: AudioProfile, scenario: AudioScenario): Promise<void>

设置音频编码配置。

Note
- 该方法需要在 joinChannel 之前设置好，joinChannel 后设置不生效。
- 通信和直播场景下，音质（码率）会有网络自适应的调整，通过该方法设置的是一个最高码率。
- 在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 MusicHighQuality(4)，scenario 设置为 GameStreaming(3)。
Parameters
- profile: AudioProfile
  
  设置采样率，码率，编码模式和声道数。
- scenario: AudioScenario
  
  设置音频应用场景。不同的音频场景下，设备的系统音量是不同的。
Returns Promise<void>

setAudioSessionOperationRestriction

setAudioSessionOperationRestriction(restriction: AudioSessionOperationRestriction): Promise<void>

该方法仅适用于 iOS 平台。该方法在加入频道前后都能调用。

该方法限制声网 SDK 对 Audio Session 的操作权限。在默认情况下，SDK 和 App 对 Audio Session 都有控制权，但某些场景下，App 会希望限制声网 SDK 对 Audio Session 的控制权限，而使用其他应用或第三方组件对 Audio Session 进行操控。调用该方法可以实现该功能。

该接口可以在任意时候调用，可以在任意时候通过该方法把控制权交还给 SDK。

Note 一旦调用该方法限制了声网 SDK 对 Audio Session 的控制权限， SDK 将无法对 Audio Session 进行相关设置，而需要用户自己或第三方组件进行维护。

Parameters
- restriction: AudioSessionOperationRestriction
  
  声网 SDK 对 Audio Session 的控制权限，详见 AudioSessionOperationRestriction。该 restriction 为 Bit Mask，每个 Bit 对应一个权限。
Returns Promise<void>

setBeautyEffectOptions

setBeautyEffectOptions(enabled: boolean, options: BeautyOptions): Promise<void>

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

Note
- 该方法需要在 enableVideo 之后调用。
- 在 Android 平台，该方法仅适用于 Android 4.4 及以上版本。
Parameters
- enabled: boolean
  是否开启美颜功能：
  - true: 开启。
  - false: （默认）关闭。
- options: BeautyOptions
  
  美颜选项。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 4(NotSupported)：当前设备版本低于 Android 4.4，不支持该操作。

setCameraAutoFocusFaceModeEnabled

setCameraAutoFocusFaceModeEnabled(enabled: boolean): Promise<void>

设置是否开启人脸对焦功能。

Parameters
- enabled: boolean
  是否开启人脸对焦：
  - true: 开启人脸对焦功能。
  - false: （默认）关闭人脸对焦功能。
Returns Promise<void>

setCameraCapturerConfiguration

setCameraCapturerConfiguration(config: CameraCapturerConfiguration): Promise<void>

设置摄像头的采集偏好。

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

请在启动摄像头之前调用该方法，如 joinChannel，enableVideo 或者 enableLocalVideo。
Parameters
- config: CameraCapturerConfiguration
  
  摄像头采集偏好。
Returns Promise<void>

setCameraExposurePosition

setCameraExposurePosition(positionXinView: number, positionYinView: number): Promise<void>

设置手动曝光位置。

成功调用该方法后，本地会触发 CameraExposureAreaChanged 回调。

Parameters
- positionXinView: number
  
  触摸点相对于视图的横坐标。
- positionYinView: number
  
  触摸点相对于视图的纵坐标。
Returns Promise<void>

setCameraFocusPositionInPreview

setCameraFocusPositionInPreview(positionX: number, positionY: number): Promise<void>

设置手动对焦位置，并触发对焦。

成功调用该方法后，本地会触发 CameraFocusAreaChanged 回调。

Parameters
- positionX: number
  
  触摸点相对于视图的横坐标。
- positionY: number
  
  触摸点相对于视图的纵坐标。
Returns Promise<void>

setCameraTorchOn

setCameraTorchOn(isOn: boolean): Promise<void>

设置是否打开闪光灯。

Note 该方法需在摄像头启动后调用。

Parameters
- isOn: boolean
  是否打开闪光灯：
  - true：打开。
  - false：关闭。
Returns Promise<void>

setCameraZoomFactor

setCameraZoomFactor(factor: number): Promise<void>

设置摄像头缩放比例。

Parameters
- factor: number
  
  相机缩放比例，有效范围从 1.0 到最大缩放。
Returns Promise<void>

setChannelProfile

setChannelProfile(profile: ChannelProfile): Promise<void>

设置频道场景。

SDK 初始化后默认的频道场景为通信场景，你可以该方法用于设置声网频道的使用场景。声网 SDK 会针对不同的使用场景采用不同的优化策略，如通信场景偏好流畅，直播场景偏好画质。

Parameters
- profile: ChannelProfile
  
  频道使用场景。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument)：参数无效。
  - 7(NotInitialized): SDK 尚未初始化。

setClientRole

setClientRole(role: ClientRole, options?: ClientRoleOptions): Promise<void>

设置直播场景下的用户角色。

调用 setChannelProfile(LiveBroadcasting) 后，SDK 会默认设置用户角色为观众，你可以调用 setClientRole 设置用户角色为主播。

该方法在加入频道前后均可调用。如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 ClientRoleChanged 或 ClientRoleChangeFailed。
- 远端触发 UserJoined 或 UserOffline (BecomeAudience)。
Note
- 该方法仅适用于直播场景（setChannelProfile 中 profile 设为 LiveBroadcasting）。
- 自 3.2.0 版本起，该方法新增 options 参数，支持设置用户级别。
  - 用户角色 (role) 确定用户在 SDK 层的权限，包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
  - 用户级别 (level) 需要与角色结合使用，确定用户在其权限范围内，可以操作和享受到的服务级别。例如对于观众，选择接收低延时还是超低延时的视频流。用户级别会影响计费。
Parameters
- role: ClientRole
  
  直播场景中的用户角色，详见 ClientRole。
- Optional options: ClientRoleOptions
  
  用户具体设置，包含用户级别，详见 ClientRoleOptions。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 1(Failed): 一般性的错误（未明确归类）。
  - 2(InvalidArgument): 参数无效。
  - 5(Refused): 调用被拒绝。在多频道场景中，如果你已在一个频道中进行如下设置，则用户在另一个频道内切换角色为主播时会返回该错误码：
    - 调用带 options 参数的 joinChannel，并使用默认设置 publishLocalAudio = true 或 publishLocalVideo = true。
    - 调用 setClientRole，并设置用户角色为主播。
    - 调用 muteLocalAudioStream(false) 或 muteLocalVideoStream(false)。
  - 7(NotInitialized): SDK 尚未初始化。

setCloudProxy

setCloudProxy(proxyType: CloudProxyType): Promise<void>

设置声网云代理服务。

当用户的网络访问受到防火墙限制时，你需要将声网提供的 IP 和端口号添加到防火墙白名单，然后调用该方法开启云代理，并通过 proxyType 参数设置云代理类型。

成功连接云代理后，SDK 会触发 ConnectionStateChanged(Connecting, SettingProxyServer) 回调。

自 v3.6.2 起，当用户调用该方法并成功加入频道后，SDK 会触发 ProxyConnected 回调，报告用户 ID、连接的代理类型和用户调用 joinChannel 到 SDK 触发该回调的经过的时间等。

如果你想关闭已设置的 Force UDP 或 Force TCP 云代理，请调用 setCloudProxy(None)。如果你想更改已设置的云代理类型，请先调用 setCloudProxy(None)，再调用 setCloudProxy 并传入你期望的 proxyType 值。

Note
- 声网推荐你在频道外调用该方法。
- 对 3.3.x 版 SDK，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。对 3.4.0 及之后版 SDK，如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。
- 使用 Force TCP 云代理时：
  - 调用 startAudioMixing 方法时无法播放 HTTP 协议的在线音频文件。
  - 旁路推流和跨频道媒体流转发功能会用 TCP 协议的云代理。
Parameters
- proxyType: CloudProxyType
  
  云代理类型。详见 CloudProxyType。该参数为必填参数，如果你不赋值，SDK 会报错。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - -2(ERR_INVALID_ARGUMENT): 传入的参数无效。
  - -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

setColorEnhanceOptions

setColorEnhanceOptions(enabled: boolean, options: ColorEnhanceOptions): Promise<void>

设置色彩增强功能。
since
v3.6.2

摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性，提升视频色彩丰富度和色彩还原度，最终使视频画面更生动。

你可以调用该方法开启色彩增强功能并设置色彩增强的效果。

Note
- 调用该方法前，请确保已集成以下动态库：
  
  Android：libagora_video_process_extension.so
  
  iOS：AgoraVideoProcessExtension.xcframework
- 请在 enableVideo 后调用该方法。
- 色彩增强对设备性能有一定要求。开启色彩增强后，如果设备出现严重发烫等问题，声网推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
Parameters
- enabled: boolean
  是否开启色彩增强功能：
  - true：开启。
  - false：（默认）关闭。
- options: ColorEnhanceOptions
  
  色彩增强选项，用于设置色彩增强的效果。详见 ColorEnhanceOptions。
Returns Promise<void>

setDefaultAudioRoutetoSpeakerphone

setDefaultAudioRoutetoSpeakerphone(defaultToSpeaker: boolean): Promise<void>

设置默认的音频路由。

如果 SDK 默认的音频路由（参考《设置音频路由》）无法满足你的需求，你可以调用该方法切换默认的音频路由。成功切换音频路由后，SDK 会触发 AudioRouteChanged 回调提示音频路由已更改。

Note
- 该方法需要在 joinChannel 前调用。如需在加入频道后切换音频路由，请调用 setEnableSpeakerphone。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效，音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。
Parameters
- defaultToSpeaker: boolean
  设置默认的音频路由：
  - true：默认的音频路由为扬声器。
  - false：默认的音频路由为听筒。
Returns Promise<void>

setDefaultMuteAllRemoteAudioStreams

setDefaultMuteAllRemoteAudioStreams(muted: boolean): Promise<void>

设置是否默认接收音频流。
deprecated
该方法自 v3.3.0 起废弃。

默认取消或恢复订阅远端用户的音频流。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note 取消订阅音频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：
- 如果需要恢复订阅单个用户的音频流，调用 muteRemoteAudioStream(false)，并指定你想要订阅的远端用户 ID。
- 如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteAudioStream(false)。
Parameters
- muted: boolean
  是否默认取消订阅远端用户的音频流：
  - true：默认取消订阅。
  - false：（默认）默认订阅。
Returns Promise<void>

setDefaultMuteAllRemoteVideoStreams

setDefaultMuteAllRemoteVideoStreams(muted: boolean): Promise<void>

设置是否默认接收视频流。
deprecated
该方法自 v3.3.1 起废弃。

默认取消或恢复订阅远端用户的视频流。

该方法需要在加入频道后调用。调用成功后，本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。

Note 取消订阅视频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：
- 如果需要恢复订阅单个用户的视频流，调用 muteRemoteVideoStream(false)，并指定你想要订阅的远端用户 ID。
- 如果想恢复订阅多个用户的视频流，则需要多次调用 muteRemoteVideoStream(false)。
Parameters
- muted: boolean
  是否默认取消订阅远端用户的视频流：
  - true：默认取消订阅。
  - false：（默认）默认订阅。
Returns Promise<void>

setEffectPosition

setEffectPosition(soundId: number, pos: number): Promise<void>

设置指定音效文件的播放位置。

自从 v3.4.2

成功设置后，本地音效文件会在指定位置开始播放。

Note 该方法需要在 playEffect 后调用。

Parameters
- soundId: number
  
  音效 ID。请确保与 playEffect 中设置的 soundId 一致。
- pos: number
  
  音效文件的播放位置，单位为毫秒。
Returns Promise<void>

setEffectsVolume

setEffectsVolume(volume: number): Promise<void>

设置所有音效文件的播放音量。

Parameters
- volume: number
  
  所有音效文件的播放音量，取值范围为 [0.0,100.0]。 100.0 为默认值。
Returns Promise<void>

setEnableSpeakerphone

setEnableSpeakerphone(enabled: boolean): Promise<void>

启用/关闭扬声器播放。

如果 SDK 默认的音频路由（参考《设置音频路由》）或 setDefaultAudioRoutetoSpeakerphone 的设置无法满足你的需求，你可以调用 setEnableSpeakerphone 切换当前的音频路由。成功切换音频路由后，SDK 会触发 AudioRouteChanged 回调提示音频路由已更改。

该方法只设置用户在当前频道内使用的音频路由，不会影响 SDK 默认的音频路由。如果用户离开当前频道并加入新的频道，则用户还是会使用 SDK 默认的音频路由。

Note
- 该方法需要在 joinChannel 前调用。如需在加入频道后切换音频路由，请调用 setEnableSpeakerphone。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备，则该方法的设置无效，音频只会通过外接设备播放。当有多个外接设备时，音频会通过最后一个接入的设备播放。
Parameters
- enabled: boolean
  设置是否开启扬声器播放：
  - true：开启。音频路由为扬声器。
  - false：关闭。音频路由为听筒。
Returns Promise<void>

setEncryptionMode

setEncryptionMode(encryptionMode: EncryptionMode): Promise<void>

设置内置的加密方案。

deprecated

自 v3.1.2 起废弃。请改用 enableEncryption。

声网 SDK 支持内置加密功能，默认使用 AES128XTS 加密方式。如需使用其他加密方式，可以调用该 API 设置。同一频道内的所有用户必须设置相同的加密方式和密码才能进行通话。关于这几种加密方式的区别，请参考 AES 加密算法的相关资料。

Note

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

Parameters
- encryptionMode: EncryptionMode
  
  加密方式。
Returns Promise<void>

setEncryptionSecret

setEncryptionSecret(secret: string): Promise<void>

启用内置加密，并设置数据加密密码。
deprecated
自 v3.1.2 起废弃。请改用 enableEncryption。

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

Note
- 为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
- 请勿在转码推流场景中使用该方法。
Parameters
- secret: string
  
  加密密码。
Returns Promise<void>

setInEarMonitoringVolume

setInEarMonitoringVolume(volume: number): Promise<void>

设置耳返音量。

Parameters
- volume: number
  
  设置耳返音量，取值范围在 0 到 100 间。默认值为 100。
Returns Promise<void>

setLiveTranscoding

setLiveTranscoding(transcoding: LiveTranscoding): Promise<void>

设置直播转码。
deprecated
该方法自 3.6.2 版废弃，替代方案请参考发版说明。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码参数 LiveTranscoding 时，SDK 会触发 TranscodingUpdated 回调。首次调用该方法设置转码参数时，不会触发 TranscodingUpdated 回调。

Note
- 请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
- 该方法仅适用于直播场景下的主播用户。
- 请确保先调用过该方法，再调用 addPublishStreamUrl。
- 声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
Parameters
- transcoding: LiveTranscoding
  
  旁路推流布局相关设置。
Returns Promise<void>

setLocalPublishFallbackOption

setLocalPublishFallbackOption(option: StreamFallbackOptions): Promise<void>

设置弱网条件下发布的音视频流回退选项。

网络不理想的环境下，直播音视频的质量都会下降。使用该接口并将 option 设置为 AudioOnly(2) 后， SDK 会在上行弱网且音视频质量严重受影响时，自动关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当本地推流回退为音频流时，或由音频流恢复为音视频流时， SDK 会触发本地发布的媒体流已回退为音频流 LocalPublishFallbackToAudioOnly 回调。

Note

旁路推流场景下，设置本地推流回退为 AudioOnly(2) 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下，声网建议不开启该功能。

Parameters
- option: StreamFallbackOptions
  
  本地推流回退处理选项。
Returns Promise<void>

setLocalVoiceChanger

setLocalVoiceChanger(voiceChanger: AudioVoiceChanger): Promise<void>

设置本地语音变声、美音或语聊美声效果。

deprecated

该方法从 v3.2.0 起废弃，请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

Note

该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。

Parameters
- voiceChanger: AudioVoiceChanger
  
  本地语音的变声、美音或语聊美声效果选项。
Returns Promise<void>

setLocalVoiceEqualization

setLocalVoiceEqualization(bandFrequency: AudioEqualizationBandFrequency, bandGain: number): Promise<void>

设置本地语音音效均衡。

Parameters
- bandFrequency: AudioEqualizationBandFrequency
  
  频谱子带索引，取值范围是 [0,9]，分别代表 10 个频带，对应的中心频率是 [31，62，125，250，500，1k，2k，4k，8k，16k] Hz。
- bandGain: number
  
  每个 band 的增益，单位是 dB，每一个值的范围是 [-15,15]，默认值为 0。
Returns Promise<void>

setLocalVoicePitch

setLocalVoicePitch(pitch: number): Promise<void>

设置本地语音音调。

该方法改变本地说话人声音的音调。

Parameters
- pitch: number
  
  语音频率。可以在 [0.5,2.0] 范围内设置。取值越小，则音调越低。默认值为 1.0，表示不需要修改音调。
Returns Promise<void>

setLocalVoiceReverb

setLocalVoiceReverb(reverbKey: AudioReverbType, value: number): Promise<void>

设置本地音效混响。

Note

SDK 在 v3.2.1 版本中提供一个使用更为简便的方法 setAudioEffectPreset，直接实现流行、R&B、KTV 等预置的混响效果。

Parameters
- reverbKey: AudioReverbType
  
  混响音效 Key。
- value: number
  
  各混响音效 Key 所对应的值。
Returns Promise<void>

setLocalVoiceReverbPreset

setLocalVoiceReverbPreset(preset: AudioReverbPreset): Promise<void>

设置本地语音混响（含虚拟立体声效果）。
deprecated
该方法从 v3.2.0 起废弃，请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后，频道内的所有用户均可听到声音效果。

Note
- 该方法不能与 setLocalVoiceReverb 方法一同使用。
- 该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。
Parameters
- preset: AudioReverbPreset
  
  本地语音混响选项。
Returns Promise<void>

setLogFile

setLogFile(filePath: string): Promise<void>

设置声网 SDK 输出的日志文件。

deprecated

该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 LogConfig 参数设置日志文件路径。

默认情况下，SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后，SDK 会从 1-4 中删除修改时间最早的一个文件，然后将 agorasdk.log 重命名为该文件，并建立新的 agorasdk.log 写入最新的日志。

Note

如需调用本方法，请在调用 create 方法初始化 RtcEngine 对象后立即调用，否则可能造成输出日志不完整。

Parameters
- filePath: string
  日志文件的完整路径。
  - Android 平台: 默认路径为 /storage/emulated/0/Android/data/<package name>/files/agorasdk.log。
  - iOS 平台：默认路径为 App Sandbox/Library/caches/agorasdk.log。
  请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。
Returns Promise<void>

setLogFileSize

setLogFileSize(fileSizeInKBytes: number): Promise<void>

设置日志文件大小。

deprecated

该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 LogConfig 参数设置日志文件路径。

设置 SDK 输出的单个日志文件大小，单位为 KB。

默认情况下，SDK 会生成 agorasdk.log、agorasdk_1.log、agorasdk_2.log、agorasdk_3.log、agorasdk_4.log 这 5 个日志文件。每个文件的默认大小为 1024 KB。日志文件为 UTF-8 编码。最新的日志永远写在 agorasdk.log 中。agorasdk.log 写满后，SDK 会从 1-4 中删除修改时间最早的一个文件，然后将 agorasdk.log 重命名为该文件，并建立新的 agorasdk.log 写入最新的日志。

Parameters
- fileSizeInKBytes: number
  
  单个日志文件的大小，单位为 KB。默认值为 1024 KB。如果你将 fileSizeInKByte 设为 1024 KB，SDK 会最多输出 5 MB 的日志文件。如果你将 fileSizeInKByte 设为小于 1024 KB，单个日志文件最大仍为 1024 KB。
Returns Promise<void>

setLogFilter

setLogFilter(filter: LogFilter): Promise<void>

设置日志输出等级。

deprecated

该方法从 v3.3.1 起废弃，请改用 createWithConfig 中的 LogConfig 参数设置日志文件路径。

该方法设置 SDK 的日志输出等级。不同的等级可以单独或组合使用。

日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

Parameters
- filter: LogFilter
  
  日志输出等级。
Returns Promise<void>

setLowLightEnhanceOptions

setLowLightEnhanceOptions(enabled: boolean, options: LowLightEnhanceOptions): Promise<void>

设置暗光增强功能。
since
v3.6.2

暗光增强功能可以在光线亮度偏低（如背光、阴天、暗场景）和亮度不均匀的环境下自适应调整视频画面的亮度值，恢复或凸显图像的细节信息，最终提升视频图像的整体视觉效果。

你可以调用该方法开启暗光增强功能并设置暗光增强的效果。

Note
- 调用该方法前，请确保已集成以下动态库：
  
  Android：libagora_video_process_extension.so
  
  iOS：AgoraVideoProcessExtension.xcframework
- 请在 enableVideo 后调用该方法。
- 暗光增强对设备性能有一定要求。开启暗光增强后，如果设备出现严重发烫等问题，声网推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。
Parameters
- enabled: boolean
  是否开启暗光增强功能：
  - true：开启。
  - false：（默认）关闭。
- options: LowLightEnhanceOptions
  
  暗光增强选项，用于设置暗光增强的效果。详见 LowLightEnhanceOptions。
Returns Promise<void>

setMaxMetadataSize

setMaxMetadataSize(size: number): Promise<void>

设置 Metadata 的最大数据大小。

Parameters
- size: number
  
  Metadata 的最大数据大小，单位为 Byte，最大值不超过 1024。
Returns Promise<void>

setRemoteDefaultVideoStreamType

setRemoteDefaultVideoStreamType(streamType: VideoStreamType): Promise<void>

设置默认订阅的视频流类型。

Note
- 该方法只能在加入频道前调用。声网不支持你在加入频道后修改默认订阅的视频流类型。
- 如果你既调用了该方法，也调用了 setRemoteVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。
Parameters
- streamType: VideoStreamType
  
  视频流类型。
Returns Promise<void>

setRemoteSubscribeFallbackOption

setRemoteSubscribeFallbackOption(option: StreamFallbackOptions): Promise<void>

设置弱网条件下订阅的音视频流回退选项。

网络不理想的环境下，直播音视频的质量都会下降。使用该接口并将 option 设置为 VideoStreamLow(1) 或者 AudioOnly(2) 后， SDK 会在下行弱网且音视频质量严重受影响时，将视频流切换为小流，或关断视频流，从而保证或提高音频质量。同时 SDK 会持续监控网络质量，并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时，或由音频流恢复为音视频流时，SDK 会触发远端订阅流已回退为音频流 RemoteSubscribeFallbackToAudioOnly 回调。

Parameters
- option: StreamFallbackOptions
  
  远端订阅流回退处理选项。
Returns Promise<void>

setRemoteUserPriority

setRemoteUserPriority(uid: number, userPriority: UserPriority): Promise<void>

设置用户媒体流优先级。

如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。该方法可以与 setRemoteSubscribeFallbackOption 搭配使用。如果开启了订阅流回退选项，弱网下 SDK 会优先保证高优先级用户收到的流的质量。

Note

目前声网 SDK 仅允许将一名远端用户设为高优先级。

Parameters
- uid: number
  
  远端用户的 ID。
- userPriority: UserPriority
  
  远端用户的优先级。
Returns Promise<void>

setRemoteVideoStreamType

setRemoteVideoStreamType(uid: number, streamType: VideoStreamType): Promise<void>

设置订阅的视频流类型。

在网络条件受限的情况下，如果发送端没有调用 enableDualStreamMode(false) 关闭双流模式，接收端可以选择接收大流还是小流。其中，大流可以接为高分辨率高码率的视频流，小流则是低分辨率低码率的视频流。

正常情况下，用户默认接收大流。如需节约带宽和计算资源，则可以调用该方法动态调整对应远端视频流的大小。 SDK 会根据该方法中的设置，切换大小流。

视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

调用本方法的执行结果将在 ApiCallExecuted 中返回。

Note 该方法在加入频道前后都能调用。如果既调用了 setRemoteVideoStreamType，也调用了 setRemoteDefaultVideoStreamType，则 SDK 以 setRemoteVideoStreamType 中的设置为准。

Parameters
- uid: number
  
  用户 ID。
- streamType: VideoStreamType
  
  视频流类型。
Returns Promise<void>

setRemoteVoicePosition

setRemoteVoicePosition(uid: number, pan: number, gain: number): Promise<void>

设置远端用户声音的空间位置和音量，方便本地用户听声辨位。

用户通过调用该接口，设置远端用户声音出现的位置，左右声道的声音差异会让用户产生声音的方位感，从而判断出远端用户的实时位置。在多人在线游戏场景，如吃鸡游戏中，该方法能有效增加游戏角色的方位感，模拟真实场景。

Note
- 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
- 为获得最佳听觉体验，我们建议用户佩戴有线耳机。
Parameters
- uid: number
  
  远端用户的 ID。
- pan: number
  设置远端用户声音出现的位置，取值范围为 [-1.0,1.0]：
  - 0.0：（默认）声音出现在正前方。
  - -1.0：声音出现在左边。
  - 1.0：声音出现在右边。
- gain: number
  
  设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低。
Returns Promise<void>

setVideoDenoiserOptions

setVideoDenoiserOptions(enabled: boolean, options: VideoDenoiserOptions): Promise<void>

设置视频降噪功能。
since
v3.6.2

采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声，影响视频画质。在实时互动场景下，视频噪声还会在编码过程中占用码流资源并降低编码效率。

你可以调用该方法开启视频降噪功能并设置视频降噪的效果。

Note
- 调用该方法前，请确保已集成以下动态库：
  
  Android：libagora_video_process_extension.so
  
  iOS：AgoraVideoProcessExtension.xcframework
- 请在 enableVideo 后调用该方法。
- 视频降噪对设备性能有一定要求。开启视频降噪后，如果设备出现严重发烫等问题，声网推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。
Parameters
- enabled: boolean
  是否开启视频降噪功能：
  - true：开启。
  - false：（默认）关闭。
- options: VideoDenoiserOptions
  
  视频降噪选项，用于设置视频降噪的效果。详见 VideoDenoiserOptions。
Returns Promise<void>

setVideoEncoderConfiguration

setVideoEncoderConfiguration(config: VideoEncoderConfiguration): Promise<void>

设置视频编码属性。

该方法设置视频编码属性。每个属性对应一套视频参数，如分辨率、帧率、码率、视频方向等。所有设置的参数均为理想情况下的最大值。当视频引擎因网络环境等原因无法达到设置的分辨率、帧率或码率的最大值时，会取最接近最大值的那个值。

如果用户加入频道后不需要重新设置视频编码属性，则声网建议在 enableVideo 前调用该方法，可以加快首帧出图的时间。

Parameters
- config: VideoEncoderConfiguration
  
  视频编码属性。
Returns Promise<void>

setVoiceBeautifierParameters

setVoiceBeautifierParameters(preset: VoiceBeautifierPreset, param1: number, param2: number): Promise<void>

设置 SDK 预设美声效果的参数。

自从 3.3.1

调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后，频道内所有用户都能听到该效果。

为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

Note
- 该方法在加入频道前后都能调用
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
- 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  - setAudioEffectPreset
  - setAudioEffectParameters
  - setVoiceBeautifierPreset
  - setLocalVoiceReverbPreset
  - setLocalVoiceChanger
  - setLocalVoicePitch
  - setLocalVoiceEqualization
  - setLocalVoiceReverb
  - setVoiceConversionPreset
Parameters
- preset: VoiceBeautifierPreset
  SDK 预设的音效：
  - SingingBeautifier：歌唱美声。
- param1: number
  歌声的性别特征：
  - 1：男声。
  - 2：女声。
- param2: number
  歌声的混响效果：
  - 1：歌声在小房间的混响效果。
  - 2：歌声在大房间的混响效果。
  - 3：歌声在大厅的混响效果。
Returns Promise<void>

setVoiceBeautifierPreset

setVoiceBeautifierPreset(preset: VoiceBeautifierPreset): Promise<void>

设置 SDK 预设的美声效果。

自从 v3.2.0。

调用该方法可以为本地发流用户设置 SDK 预设的人声美化效果。设置美声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的美声效果。

为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

Note
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法会调用失败。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
- 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  - setAudioEffectPreset
  - setAudioEffectParameters
  - setLocalVoiceReverbPreset
  - setLocalVoiceChanger
  - setLocalVoicePitch
  - setLocalVoiceEqualization
  - setLocalVoiceReverb
  - setVoiceConversionPreset
Parameters
- preset: VoiceBeautifierPreset
  
  预设的美声效果选项。详见 VoiceBeautifierPreset。
Returns Promise<void>

setVoiceConversionPreset

setVoiceConversionPreset(preset: VoiceConversionPreset): Promise<void>

设置 SDK 预设的变声效果。

自从 v3.3.1

调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后，频道内所有用户都能听到该效果。根据不同的场景，你可以为用户设置不同的变声效果，各变声效果的适用场景可参考《设置人声效果》。

为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)，并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

Note
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
- 该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
- 调用该方法后，声网不推荐调用以下方法，否则该方法设置的效果会被覆盖：
  - setAudioEffectPreset
  - setAudioEffectParameters
  - setVoiceBeautifierPreset
  - setVoiceBeautifierParameters
  - setLocalVoiceReverbPreset
  - setLocalVoiceChanger
  - setLocalVoicePitch
  - setLocalVoiceEqualization
  - setLocalVoiceReverb
Parameters
- preset: VoiceConversionPreset
  
  预设的变声效果选项，详见 VoiceConversionPreset。
Returns Promise<void>

setVolumeOfEffect

setVolumeOfEffect(soundId: number, volume: number): Promise<void>

设置指定音效文件的播放音量。

Parameters
- soundId: number
  
  指定音效的 ID。每个音效均有唯一的 ID。
- volume: number
  
  指定音效文件的播放音量，取值范围为 [0.0,100.0]。 100.0 为默认值。
Returns Promise<void>

startAudioMixing

startAudioMixing(filePath: string, loopback: boolean, replace: boolean, cycle: number, startPos?: undefined | number): Promise<void>

开始播放音乐文件及混音。

该方法指定本地或在线音频文件来和麦克风采集的音频流进行混音或替换。替换是指用音频文件替换麦克风采集的音频流。该方法可以选择是否让对方听到本地播放的音频，并指定循环播放的次数。成功调用该方法后，本地会触发 AudioMixingStateChanged 回调且状态码为 Playing。播放结束后，会收到 AudioMixingStateChanged 回调且状态码为 Stopped。

Note
- 如需在 Android 平台调用该方法，请确保使用 Android 4.2 或以上设备，且 API Level ≥ 16。
- 如果播放的是在线音乐文件，请确保重复调用该 API 的间隔超过 100 ms，否则 SDK 会返回 TooFrequentCall(702) 警告码，表示音乐文件打开过于频繁。
- 如果播放的是在线音乐文件，声网建议不要使用重定向地址。重定向地址在某些机型上可能会出现无法打开的情况。
- 如果本地音乐文件不存在、文件格式不支持、无法访问在线音乐文件 URL 都会返回警告码 CanNotOpen(701)。
- 如果在模拟器上使用该 API，暂时只支持存放在 /sdcard/ 中的 mp3 文件。
- 该方法支持的音频文件格式见声网RTC SDK 支持播放哪些格式的音频文件。
Parameters
- filePath: string
  文件路径，需精确到文件名及后缀。
  - Android：支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 Note: 通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如："content://com.android.providers.media.documents/document/audio%3A14441"。
  - iOS：支持文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4。
- loopback: boolean
  - true：只有本地可以听到混音或替换后的音频流。
  - false：本地和对方都可以听到混音或替换后的音频流。
- replace: boolean
  - true：只推动设置的本地音频文件或者线上音频文件，不传输麦克风收录的音频。
  - false：音频文件内容将会和麦克风采集的音频流进行混音。
- cycle: number
  音频文件循环播放的次数：
  - 正整数：循环的次数。
  - -1：无限循环。
- Optional startPos: undefined | number
  
  自从 3.4.2 音乐文件的播放位置，单位为毫秒。
Returns Promise<void>

startAudioRecording

startAudioRecording(filePath: string, sampleRate: AudioSampleRateType, quality: AudioRecordingQuality): Promise<void>

开始客户端录音。
deprecated
从 v3.4.2 起废弃。请改用 startAudioRecordingWithConfig。

声网 SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为：
- .wav：文件大，音质保真度较高。
- .aac：文件小，音质保真度较低。
Note
- 请确保你在该方法中指定的路径存在并且可写。
- 该接口需要在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。
- 为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设为 Medium 或 High。
Parameters
- filePath: string
  
  录音文件在本地保存的绝对路径，由用户自行制定，需精确到文件名及格式，例如：/dir1/dir2/dir3/audio.aac。
- sampleRate: AudioSampleRateType
  
  录音采样率 (Hz)。
- quality: AudioRecordingQuality
  
  录音音质。
Returns Promise<void>

startAudioRecordingWithConfig

startAudioRecordingWithConfig(config: AudioRecordingConfiguration): Promise<void>

开始客户端录音。

自从 v3.4.2

声网 SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内用户的音频，并得到一个录音文件。录音文件格式可以为:
- WAV: 音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 Medium，录音时长为 10 分钟的文件大小约为 2 M。
一旦用户离开频道，录音会自动停止。

Note 该方法需要在加入频道后调用。
Parameters
- config: AudioRecordingConfiguration
  
  录音配置。详见 AudioRecordingConfiguration。
Returns Promise<void>

startChannelMediaRelay

startChannelMediaRelay(channelMediaRelayConfiguration: ChannelMediaRelayConfiguration): Promise<void>

开始跨频道媒体流转发。

该方法可用于实现跨频道媒体流转发。

成功调用该方法后，SDK 会触发 ChannelMediaRelayStateChanged 和 ChannelMediaRelayEvent 回调，并在回调中报告当前的跨频道媒体流转发状态和事件。
- 如果 ChannelMediaRelayStateChanged 回调报告 Running(2) 和 None(0) 且 ChannelMediaRelayEvent 回调报告 SentToDestinationChannel(4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 ChannelMediaRelayStateChanged 回调报告 Failure(3)，则表示跨频道媒体流转发出现异常。
Note
- 跨频道媒体流转发功能需要联系 sales@agora.io 开通。
- 该功能不支持 String 型 UID。
- 请在成功加入频道后调用该方法。
- 该方法仅适用于直播场景下的主播。
- 成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
Parameters
- channelMediaRelayConfiguration: ChannelMediaRelayConfiguration
  
  跨频道媒体流转发参数配置。
Returns Promise<void>

startEchoTest

startEchoTest(intervalInSeconds?: undefined | number, config?: EchoTestConfiguration): Promise<void>

开始音频通话回路测试。

加入频道前，为测试用户本地发流、收流是否正常，你可以调用该方法进行音频通话回路测试，即测试系统的音频设备和用户的上下行网络是否正常。

开始测试后，用户需发出声音，音频会在约 2 秒后播放出来。如果音频播放正常，则表示系统音频设备和用户上下行网络均正常。

Note
- 请在加入频道前调用该方法。
- 调用该方法后，必须调用 stopEchoTest 结束测试，否则该用户无法进行下一次音频通话回路测试，也无法加入频道。
- 直播场景下，该方法仅能由主播调用。
Parameters
- Optional intervalInSeconds: undefined | number
  
  设置返回语音通话回路测试结果的时间间隔，取值范围为 [2,10]，单位为秒，默认为 10 秒。
- Optional config: EchoTestConfiguration
  
  音频通话回路测试的配置。详见 EchoTestConfiguration。
Returns Promise<void>

startLastmileProbeTest

startLastmileProbeTest(config: LastmileProbeConfig): Promise<void>

开始通话前网络质量探测，向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。

启用该方法后，SDK 会依次返回如下 2 个回调：
- LastmileQuality：视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
- LastmileProbeResult：视网络情况约 30 秒内返回。该回调通过客观数据反馈上下行网络质量，因此更客观。
该方法主要用于以下两种场景：
- 用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。
Note
- 该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要同时使用该方法和 enableLastmileTest。
- 调用该方法后，在收到 LastmileQuality 和 LastmileProbeResult 回调之前请不用调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 直播场景下，如果本地用户为主播，请勿在加入频道后调用该方法。
Parameters
- config: LastmileProbeConfig
  
  Last-mile 网络探测配置。
Returns Promise<void>

startPreview

startPreview(): Promise<void>

开启视频预览。

该方法用于在进入频道前启动本地视频预览。调用该 API 前，必须调用 enableVideo 开启视频功能。

Note
- 本地预览默认开启镜像功能。
- 使用该方法启用了本地视频预览后，如果直接调用 leaveChannel 退出频道，并不会关闭预览。如需关闭预览，请调用 stopPreview。
Returns Promise<void>

startRecording

startRecording(config: MediaRecorderConfiguration): Promise<void>

开启本地音视频流录制。
since
v3.6.2

该方法录制在客户端录制以下内容：
- 本地麦克风采集且经 SDK 编码为 AAC 格式的音频。
- 本地摄像头采集且经 SDK 编码的视频。
只有当检测到可录制的音视频流时，才能成功生成录制文件；当没有可录制的音视频或录制中的音视频流中断超过 5 秒后， SDK 会停止录制，并触发 RecorderStateChanged(-1, 2) 回调。

Note 该方法需要在加入频道后调用。
Parameters
- config: MediaRecorderConfiguration
  
  音视频流录制配置。详见 MediaRecorderConfiguration。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument)：参数无效。请确保：
    - 指定的录制文件保存路径正确且可写
    - 指定的录制文件格式正确。
    - 设置的最大录制时长正确。
  - 4(NotSupported)：RtcEngine 当前状态不支持该操作。可能因为录制正在进行中或录制出错停止。
  - 7(NotInitialized)：SDK 尚未初始化。

startRhythmPlayer

startRhythmPlayer(sound1: string, sound2: string, config: RhythmPlayerConfig): Promise<void>

开启虚拟节拍器。

自从 v3.4.2

在音乐教学、体育教学等场景中，老师通常需要使用节拍器，让学生跟着正确的节拍练习。节拍由强拍和弱拍组成，每小节的第一拍称为强拍，其余称为弱拍。你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

Note
- 开启虚拟节拍器后，SDK 会从头开始播放指定的音频文件，并根据你设置的 beatsPerMinute 控制每个文件的播放时长。例如，将 beatsPerMinute 设为 60，则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长，则 SDK 只播放节拍时长部分的音频。
- 该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
Parameters
- sound1: string
  强拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。
  - Android：例如：/sdcard/emulated/0/audio.mp4。
  - iOS：例如：/var/mobile/Containers/Data/audio.mp4。
- sound2: string
  弱拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。
  - Android：例如：/sdcard/emulated/0/audio.mp4。
  - iOS：例如：/var/mobile/Containers/Data/audio.mp4。
- config: RhythmPlayerConfig
  
  节拍器配置，详见 RhythmPlayerConfig。
Returns Promise<void>

startRtmpStreamWithTranscoding

startRtmpStreamWithTranscoding(url: string, transcoding: LiveTranscoding): Promise<void>

开始 CDN 直播推流并设置转码属性。
since
v3.6.2

调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流，如果你需要向多个地址转码推流，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

Note
- 请确保已开通 CDN 推流服务，详见进阶功能旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 `stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。
Parameters
- url: string
  
  CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding: LiveTranscoding
  
  CDN 直播推流的转码属性，详见 LiveTranscoding。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument)：url 为空或为长度为 0 的字符串。
  - 7(NotInitialized)：调用该方法前，未初始化 SDK。

startRtmpStreamWithoutTranscoding

startRtmpStreamWithoutTranscoding(url: string): Promise<void>

开始非转码推流。
since
v3.6.2

调用该方法，你可以向指定的 CDN 推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流，如果你需要向多个地址推流，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

Note
- 请确保已开通 CDN 推流服务，详见进阶功能旁路推流中的前提条件。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 `stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。
Parameters
- url: string
  
  CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2(InvalidArgument)：url 为空或为长度为 0 的字符串。
  - 7(NotInitialized)：调用该方法前，未初始化 SDK。

startScreenCapture

startScreenCapture(parameters: ScreenCaptureParameters): Promise<void>

开始屏幕共享。
since
v3.7.0

对于 Android 平台，屏幕共享时，请确保：
- 用户已授予应用屏幕采集权限，否则 SDK 会触发 LocalVideoStateChanged 回调并报告 ScreenCapturePermissionDenied(16)。
- Android API 级别不低于 21，否则方法调用失败并返回错误码 2。
- 如需在屏幕共享时采集系统音频，你还需确保 Android API 级别不低于 29，否则方法调用失败并返回错误码 3。
对于 iOS 平台，屏幕共享 Extension 进程开启、结束、异常退出时，SDK 会相应地触发 LocalVideoStateChanged 回调并分别报告 ExtensionCaptureStarted(13)、ExtensionCaptureStoped(14)、ExtensionCaptureDisconnected(15)。

Note
- 请在加入频道后调用该方法。
- 屏幕共享流的计费以 ScreenCaptureParameters 中 dimensions 的值为准：当你未传值时，以 1280 × 720 计费；当你传值时，以你传入的值计费。详细的计费规则请参考实时音视频计费。
- 对于 iOS 平台，你需要注意：
  
  屏幕共享仅适用于 iOS 11 及以上。
  
  该功能对设备性能要求较高，声网推荐你在 iPhone X 及之后机型上使用。
  
  如果你使用音频自采集而非 SDK 采集音频，为避免应用退后台后屏幕共享停止，声网建议你对应用添加保活处理逻辑。
- 对于 Android 平台，你需要注意：
  
  在 Android 9 及之后版本上，为避免应用退后台后被系统杀死，声网建议你在 /app/Manifests/AndroidManifest.xml 文件中添加前台服务权限：android.permission.FOREGROUND_SERVICE。
  
  因性能限制，屏幕共享不支持 Android TV。
  
  因系统限制，使用华为手机进行屏幕共享时，为避免崩溃，请不要在共享过程中调节屏幕共享流的视频编码分辨率。
Parameters
- parameters: ScreenCaptureParameters
  
  屏幕共享的配置。详见 ScreenCaptureParameters。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 2：受系统限制，Android 5（API 级别 21）以下无法采集屏幕。当你在 Android 5 以下调用 startScreenCapture 时，SDK 会报告该错误码。
  - 3：受系统限制，Android 10（API 级别 29）以下无法采集系统音频。当你在 Android 5（API 级别 21）以上且 Android 10（API 级别 29）以下调用 startScreenCapture 并设置 captureAudio 为 true 时，SDK 会报告该错误码。

stopAllEffects

stopAllEffects(): Promise<void>

停止播放所有音效文件。

Returns Promise<void>

stopAudioMixing

stopAudioMixing(): Promise<void>

停止播放音乐文件及混音。

该方法停止播放伴奏。请在频道内调用该方法。

Returns Promise<void>

stopAudioRecording

stopAudioRecording(): Promise<void>

停止客户端录音。

Returns Promise<void>

stopChannelMediaRelay

stopChannelMediaRelay(): Promise<void>

停止跨频道媒体流转发。

一旦停止，主播会退出所有目标频道。

成功调用该方法后，SDK 会触发 ChannelMediaRelayStateChanged 回调。如果报告 Idle(0) 和 None(0)，则表示已停止转发媒体流。

Note

如果该方法调用不成功，SDK 会触发 ChannelMediaRelayStateChanged 回调，并报告错误码 ServerNoResponse(2) 或 ServerConnectionLost(8)。你可以调用 leaveChannel 方法离开频道，跨频道媒体流转发会自动停止。

Returns Promise<void>

stopEchoTest

stopEchoTest(): Promise<void>

停止通话回路测试。

Returns Promise<void>

stopEffect

stopEffect(soundId: number): Promise<void>

停止播放指定音效文件。

Note

如果你已通过 preloadEffect 将音效加载至内存，确保这里的 soundID 与 preloadEffect 设置的 soundID 相同。

Parameters
- soundId: number
  
  音效文件的 ID。每个音效均有唯一的 ID。
Returns Promise<void>

stopLastmileProbeTest

stopLastmileProbeTest(): Promise<void>

停止通话前网络质量探测。

Returns Promise<void>

stopPreview

stopPreview(): Promise<void>

停止视频预览。

Note 请在开启预览后且加入频道前调用该方法。

Returns Promise<void>

stopRecording

stopRecording(): Promise<void>

停止本地音视频流录制。

since

v3.6.2

Note 调用 startRecording 后，如果要停止录制，必须调用 stopRecording；否则，生成的录制文件可能无法正常播放。

Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 7(NotInitialized)：SDK 尚未初始化。

stopRhythmPlayer

stopRhythmPlayer(): Promise<void>

关闭虚拟节拍器。

自从 v3.4.2

调用 startRhythmPlayer 后，你可以调用该方法关闭虚拟节拍器。

Returns Promise<void>

stopRtmpStream

stopRtmpStream(url: string): Promise<void>

结束 CDN 直播推流。

since

v3.6.2

调用该方法，你可以结束指定的 CDN 推流地址上的直播。该方法每次只能结束一个推流地址上的直播。如果你需要结束多个推流地址的直播，则需多次调用该方法。

调用该方法后，SDK 会在本地触发 RtmpStreamingStateChanged 回调，报告推流的状态。

Parameters
- url: string
  
  CDN 推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
Returns Promise<void>

stopScreenCapture

stopScreenCapture(): Promise<void>

结束屏幕共享。

since

v3.7.0

Returns Promise<void>

switchCamera

switchCamera(): Promise<void>

切换前置/后置摄像头。

Returns Promise<void>

switchChannel

switchChannel(token: string | undefined | null, channelName: string, options?: ChannelMediaOptions): Promise<void>

快速切换直播频道。

当直播频道中的观众想从一个频道切换到另一个频道时，可以调用该方法，实现快速切换。

成功调用该方切换频道后，本地会先收到离开原频道的回调 LeaveChannel，再收到成功加入新频道的回调 JoinChannelSuccess。

用户成功加入（切换）频道后，默认订阅频道内所有其他用户的音频流和视频流，因此产生用量并影响计费。如果想取消订阅，可以通过调用相应的 mute 方法实现。

Note

该方法仅适用直播频道中的观众用户。

Parameters
- token: string | undefined | null
  
  在你的服务器上生成的 Token。详见使用 Token 鉴权。
- channelName: string
  标识频道的频道名，最大不超过 64 字节。以下为支持的字符集范围（共 89 个字符）：
  - 26 个小写英文字母 a-z
  - 26 个大写英文字母 A-Z
  - 10 个数字 0-9
  - 空格
  - "!", "#", "$", "%", "&", "(", ")", "+", "-", ":", ";", "<", "=", ".", ">", "?", "@", "[", "]", "^", "_", " {", "}", "|", "~", ","
- Optional options: ChannelMediaOptions
  
  自从 v3.3.1 频道媒体设置选项。详见 ChannelMediaOptions。
Returns Promise<void>
- 方法调用成功时，无返回值。
- 方法调用失败时，返回错误码。可能的错误包括：
  - 1(Failed): 一般性的错误（未明确归类）。
  - 2(InvalidArgument): 参数无效。
  - 5(Refused): 调用被拒绝。可能因为用户角色不是观众。
  - 7(NotInitialized): SDK 尚未初始化，就调用其 API。请确认在调用 API 之前已创建 RtcEngine 对象并完成初始化。
  - 102(InvalidChannelId): 频道名无效。请更换有效的频道名。
  - 113(NotInChannel): 用户不在频道内。

takeSnapshot

takeSnapshot(channel: string, uid: number, filePath: string): Promise<void>

获取视频截图。

自从 v3.5.2

该方法用于对指定用户的视频流进行截图，生成一张 JPG 格式的图片，并保存至指定的路径。

该方法是异步操作，调用返回时 SDK 并没有真正获取截图。成功调用该方法后，SDK 会触发 SnapshotTaken 回调报告截图是否成功和获取截图的详情。

Note
- 该方法需要在加入频道后调用。
- 如果用户的视频经过前处理，例如，添加了水印或美颜，生成的截图会包含前处理效果。
Parameters
- channel: string
  
  频道名。
- uid: number
  
  用户 ID。如果要对本地用户的视频截图，uid 设为 0。
- filePath: string
  截图的本地保存路径，需精确到文件名及格式，确保目录存在且可写。例如：
  - Android：/storage/emulated/0/Android/data/<package name>/files/example.jpg。
  - iOS：/App Sandbox/Library/Caches/example.jpg。
Returns Promise<void>

unloadEffect

unloadEffect(soundId: number): Promise<void>

从内存释放指定的预加载音效文件。

Parameters
- soundId: number
  
  音效文件的 ID。
Returns Promise<void>

unregisterMediaMetadataObserver

unregisterMediaMetadataObserver(): Promise<void>

注销媒体 Metadata 观测器。

Returns Promise<void>

updateChannelMediaRelay

updateChannelMediaRelay(channelMediaRelayConfiguration: ChannelMediaRelayConfiguration): Promise<void>

更新媒体流转发的频道。

成功开始跨频道转发媒体流后，如果你希望将流转发到多个目标频道，或退出当前的转发频道，可以调用该方法。

成功调用该方法后，SDK 会触发 ChannelMediaRelayEvent 回调，并在回调中报告状态码 UpdateDestinationChannel(7)。

Note
- 请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。
- 跨频道媒体流转发最多支持 4 个目标频道。如果直播间里已经有 4 个频道了，你可以在调用该方法之前，调用 ChannelMediaRelayConfiguration 类中的 destInfos 方法移除不需要的频道。
Parameters
- channelMediaRelayConfiguration: ChannelMediaRelayConfiguration
  
  跨频道媒体流转发参数配置。
Returns Promise<void>

updateRtmpTranscoding

updateRtmpTranscoding(transcoding: LiveTranscoding): Promise<void>

更新转码属性。

since

v3.6.2

开启转码推流后，你可以根据场景需求，动态更新转码属性。转码属性更新后，SDK 会触发 TranscodingUpdated 回调。

Parameters
- transcoding: LiveTranscoding
  
  CDN 直播推流的转码属性，详见 LiveTranscoding。
Returns Promise<void>

updateScreenCaptureParameters

updateScreenCaptureParameters(parameters: ScreenCaptureParameters): Promise<void>

更新屏幕共享配置

since

v3.7.0

Note 请在 startScreenCapture 后调用该方法。

Parameters
- parameters: ScreenCaptureParameters
  
  屏幕共享的配置。详见 ScreenCaptureParameters。
Returns Promise<void>

Static create

create(appId: string): Promise<RtcEngine>

创建 RtcEngine 实例。

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 调用该方法和 createWithAreaCode 均能创建 RtcEngine 实例。该方法与 createWithAreaCode 的区别在于，createWithAreaCode 支持在创建 RtcEngine 实例时指定访问区域。
- 目前声网React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
Parameters
- appId: string
  
  声网为 app 开发者签发的 App ID，详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID，必须先调用 destroy 销毁当前 RtcEngine，再调用 create 重新创建 RtcEngine。
Returns Promise<RtcEngine>
- 方法调用成功，则返回一个 RtcEngine 对象。
- 方法调用失败，则返回错误码。
  - 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static createWithAreaCode

createWithAreaCode(appId: string, areaCode: AreaCode): Promise<RtcEngine>

创建 RtcEngine 实例。
deprecated
该方法从 v3.3.1 起废弃，请改用 createWithContext。

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 目前声网 React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
Parameters
- appId: string
  
  声网为 app 开发者签发的 App ID，详见获取 App ID。使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID，必须先调用 destroy 销毁当前 RtcEngine，再调用 create 重新创建 RtcEngine。
- areaCode: AreaCode
  
  服务器的访问区域。该功能为高级设置，适用于有访问安全限制的场景。支持的区域详见 AreaCode。指定访问区域后，集成了声网 SDK 的 app 会连接指定区域内的声网服务器。
Returns Promise<RtcEngine>
- 方法调用成功，则返回一个 RtcEngine 对象。
- 方法调用失败，则返回错误码。可能的错误包括：
  - 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static createWithConfig

createWithConfig(config: RtcEngineConfig): Promise<RtcEngine>

创建 RtcEngine 实例。
deprecated
自 3.4.5 版本废弃。请改用 createWithContext。

自从 v3.3.1

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 目前声网 React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
Parameters
- config: RtcEngineConfig
  RtcEngine 实例的配置，详见 RtcEngineConfig。
  - 方法调用成功，则返回一个 RtcEngine 对象。
  - 方法调用失败，则返回错误码。
    - 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。
Returns Promise<RtcEngine>

Static createWithContext

createWithContext(context: RtcEngineContext): Promise<RtcEngine>

创建 RtcEngine 实例。

自从 v3.4.5

RtcEngine 类的所有接口函数，如无特殊说明，都是异步调用，对接口的调用建议在同一个线程进行。

Note
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 目前声网 React Native SDK 只支持每个 app 创建一个 RtcEngine 实例。
Parameters
- context: RtcEngineContext
  
  RtcEngine 实例的配置，详见 RtcEngineContext。
Returns Promise<RtcEngine>
- 方法调用成功，则返回一个 RtcEngine 对象。
- 方法调用失败，则返回错误码。可能的错误包括：
  - 101(InvalidAppId)：不是有效的 App ID。请更换有效的 App ID 重新初始化。建议你检查 App ID 的格式是否有效。

Static getErrorDescription

getErrorDescription(error: number): Promise<string>

获取错误码或警告码描述。

自从 v3.3.1

Parameters
- error: number
  
  RtcEngineEvents.Warning 或 Error 中的错误码或警告码。
Returns Promise<string>

错误码或警告码的详细描述。

Static getSdkVersion

getSdkVersion(): Promise<string>

查询 SDK 版本号。

自从 v3.3.1

该方法在加入频道前后都能调用。

Returns Promise<string>

当前的 SDK 版本号，格式为字符串，如 2.3.0。

Static instance

instance(): RtcEngine

获取已经创建的 RtcEngine 实例。

Note

请确保你已经创建 RtcEngine 实例。否则，方法调用会失败并返回错误信息。

Returns RtcEngine
- 方法调用成功，则返回一个 RtcEngine 实例。
- 方法调用失败，则返回错误信息。

React Native API Reference

Hierarchy

Implements

Index

Methods

Methods

addListener

Type parameters

EventType: keyof RtcEngineEvents

Parameters

event: EventType

listener: RtcEngineEvents[EventType]

Returns Subscription

addPublishStreamUrl

Parameters

url: string

transcodingEnabled: boolean

Returns Promise<void>

addVideoWatermark

Parameters

watermarkUrl: string

options: WatermarkOptions

Returns Promise<void>

adjustAudioMixingPlayoutVolume

Parameters

volume: number

Returns Promise<void>

adjustAudioMixingPublishVolume

Parameters

volume: number

Returns Promise<void>

adjustAudioMixingVolume

Parameters

volume: number

Returns Promise<void>

adjustPlaybackSignalVolume

Parameters

volume: number

Returns Promise<void>

adjustRecordingSignalVolume

Parameters

volume: number

Returns Promise<void>

adjustUserPlaybackSignalVolume

Parameters

uid: number

volume: number

Returns Promise<void>

clearVideoWatermarks

Returns Promise<void>

complain

Parameters

callId: string

description: string

Returns Promise<void>

configRhythmPlayer

Parameters

config: RhythmPlayerConfig

Returns Promise<void>

createDataStream

Parameters

reliable: boolean

ordered: boolean

Returns Promise<number>

createDataStreamWithConfig

Parameters

config: DataStreamConfig

Returns Promise<number>

destroy

Returns Promise<void>

disableAudio

Returns Promise<void>

disableLastmileTest

Returns Promise<void>

disableVideo

Returns Promise<void>

enableAudio

Returns Promise<void>

enableAudioVolumeIndication

Parameters