RtcEngine - 视频通话 (Legacy) - 文档中心

setEventHandler

添加主回调事件。

void setEventHandler(RtcEngineEventHandler handler)

RtcEngineEventHandler 接口类用于 SDK 向 app 发送回调事件通知，app 通过继承该接口类的方法获取 SDK 的事件通知。接口类的所有方法都有缺省（空）实现，app 可以根据需要只继承关心的事件。在回调方法中，app 不应该做耗时或者调用可能会引起阻塞的 API（如 sendStreamMessage），否则可能影响 SDK 的运行。

参数

handler: 待添加的回调事件。详见 RtcEngineEventHandler。

addPublishStreamUrl

增加旁路推流地址。

Future<void> addPublishStreamUrl(String url, bool transcodingEnabled);

弃用：: 该方法已废弃。替代方案请参考发版说明。

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

注意：

该方法需要在加入频道后调用。
请确保已开通旁路推流的功能。详见进阶功能旁路推流中的前提条件。
只有直播场景中角色为主播的用户才能调用该方法。
该方法每次只能增加一路旁路推流地址。若需推送多路流，则需多次调用该方法。
声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

url

旁路推流地址，格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节，不支持中文字符等特殊字符。

transcodingEnabled

是否转码。转码是指在旁路推流时对音视频流进行转码处理后再推送到其他 CDN 服务器。多适用于频道内有多个主播，需要进行混流、合图的场景。

true: 转码。
false: 不转码。

注意：如果该参数设为 true，需先调用 setLiveTranscoding 方法。

addVideoWatermark

添加本地视频水印。

Future<void> addVideoWatermark(String watermarkUrl, WatermarkOptions options);

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

水印坐标和 setVideoEncoderConfiguration 方法中的设置有依赖关系：

如果视频编码方向（VideoOutputOrientationMode）固定为横屏或自适应模式下的横屏，那么水印使用横屏坐标。
如果视频编码方向（VideoOutputOrientationMode）固定为竖屏或自适应模式下的竖屏，那么水印使用竖屏坐标。
设置水印坐标时，水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸，否则超出部分将被裁剪。

注意：

你需要在调用 enableVideo 方法之后再调用该方法。
如果你只是在旁路推流时添加水印，你可以使用该方法或 setLiveTranscoding 方法设置水印。
待添加水印图片必须是 PNG 格式。该方法支持所有像素格式的 PNG 图片：RGBA、RGB、Palette、Gray 和 Alpha_gray。
如果待添加的 PNG 图片的尺寸与你在该方法中设置的尺寸不一致，SDK 会对 PNG 图片进行缩放或裁剪，以与设置相符。
如果你已经使用 startPreview 方法开启本地视频预览，那么该方法的 visibleInPreview 可设置水印在预览时是否可见。
如果你已设置本地视频为镜像模式，那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像，声网建议你不要对本地视频同时使用镜像和水印功能，请在应用层实现本地水印功能。

参数

watermarkUrl: 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
options: 待添加的水印图片的设置选项，详见 WatermarkOptions 。

adjustAudioMixingPlayoutVolume

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

Future<void> adjustAudioMixingPlayoutVolume(int volume);

注意：你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(PLAY) 回调后调用该方法。

参数

volume: 音乐文件音量范围为 [0,100]。100 （默认值）为原始文件音量。

adjustAudioMixingPublishVolume

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

Future<void> adjustAudioMixingPublishVolume(int volume);

该方法调节混音音乐文件在远端的播放音量大小。

注意：

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

参数

volume: 音乐文件音量。范围为 [0,100]。100 （默认值）为原始文件音量。

adjustAudioMixingVolume

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

Future<void> adjustAudioMixingVolume(int volume);

该方法调节混音音乐文件在本端和远端的播放音量大小。

注意：

参数

volume: 音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

adjustPlaybackSignalVolume

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

Future<void> adjustPlaybackSignalVolume(int volume);

注意：

该方法调节的是本地播放的所有远端用户混音后的音量。
从 v2.3.2 开始，静音本地音频需同时调用 adjustPlaybackSignalVolume 和 adjustAudioMixingPlayoutVolume 方法，并将 volume 设置为 0。
该方法在加入频道前后都能调用。

参数

volume

音量，取值范围为 [0,400]。

0: 静音。
100: （默认）原始音量。
400: 原始音量的 4 倍，自带溢出保护。

adjustRecordingSignalVolume

调节音频采集信号音量。

Future<void> adjustRecordingSignalVolume(int volume);

注意：

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

参数

volume

音量，取值范围为 [0,400]。

0: 静音。
100: （默认）原始音量。
400: 原始音量的 4 倍，自带溢出保护。

adjustUserPlaybackSignalVolume

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

Future<void> adjustUserPlaybackSignalVolume(int uid, int volume);

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

注意：

该方法需要在加入频道后调用。
该方法调节的是本地播放的指定远端用户混音后的音量。

参数

uid: 远端用户 ID。
volume: 音乐文件音量范围为 0~100。100 （默认值）为原始文件音量。

clearVideoWatermarks

删除已添加的视频水印。

Future<void> clearVideoWatermarks();

complain

投诉通话质量。

Future<void> complain(String callId, String description);

该方法允许用户就通话质量进行投诉。需要在离开频道后调用。

参数

callId: 通话 ID。你可以通过调用 getCallId 获取该参数。
description: （非必选项）给通话的描述。长度应小于 800 字节。

createWithContext

初始化 RtcEngine。

static Future<RtcEngine> createWithContext(RtcEngineContext config) async {
                return RtcEngineImpl.createWithContext(config);
              }

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

注意：

请确保在调用其他 API 前先调用 create 和 createWithContext 创建并初始化 RtcEngine。
SDK 只支持每个 app 创建一个 RtcEngine 实例。

参数

config: RtcEngine 实例的配置。详见 RtcEngineContext。

createDataStream

创建数据流。

Future<int?> createDataStream(bool reliable, bool ordered);

在 RtcEngine 生命周期内，每个用户最多只能创建 5 个数据流。

注意：

该方法需要在加入频道后调用。
不可将 reliable 设为 true 且将 ordered 设为 true。

参数

reliable

该数据流是否可靠：

true: 接收方 5 秒内会收到发送方所发送的数据，否则会收到 streamMessageError 回调并获得相应报错信息。
false: 接收方不保证收到，就算数据丢失也不会报错。

ordered

该数据流是否有序：

true: 接收方会按照发送方发送的顺序收到数据包。
false: 接收方不保证按照发送方发送的顺序收到数据包。

createDataStreamWithConfig

创建数据流。

Future<int?> createDataStreamWithConfig(DataStreamConfig config);

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

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

参数

config: 数据流设置。详见 DataStreamConfig。

disableAudio

关闭音频模块。

Future<void> disableAudio();

注意：

该方法设置内部引擎为禁用状态，在频道内和频道外均可调用。离开频道后仍然有效。
该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制音频模块：
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。

disableLastmileTest

关闭网络测试。

Future<void> disableLastmileTest();

disableVideo

关闭视频模块。

Future<void> disableVideo();

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

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

注意：

该方法设置的是内部引擎为禁用状态，在离开频道后仍然有效。
该方法重置整个引擎，响应时间较慢，因此声网建议使用如下方法来控制视频模块：
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。

enableAudio

启用音频模块。

Future<void> enableAudio();

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

注意：

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

enableContentInspect

开启/关闭视频截图上传

Future<void> enableContentInspect(bool enabled, ContentInspectConfig config);

自从: v3.5.2

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

注：

调用该方法前，请确保满足以下要求：

调用该方法前，请确保已联系技术支持开通声网视频截图上传服务。
已将如下动态库集成到项目中：
- Android: libagora_ci_extension.so
- iOS: AgoraCIExtension.xcframework
- macOS: AgoraCIExtension.framework
- Windows: libagora_ci_extension.dll

参数

enabled

设置是否开启视频截图上传：

true：开启。
false：关闭。

config

视频截图上传配置。详见 ContentInspectConfig。

返回值

0: 方法调用成功
< 0: 方法调用失败

enableAudioVolumeIndication

启用用户音量提示。

Future<void> enableAudioVolumeIndication(int interval, int smooth, bool report_vad);

该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户（最多 3 位）的音量相关信息。启用该方法后，只要频道内有发流用户， SDK 会在加入频道后按设置的时间间隔触发 audioVolumeIndication 回调。

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

参数

interval

指定音量提示的时间间隔：

≤ 0: 禁用音量提示功能。
> 0: 返回音量提示的间隔，单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒，否则会收不到 audioVolumeIndication 回调。

smooth

平滑系数，指定音量提示的灵敏度。取值范围为 [0,10]，建议值为 3。数字越大，波动越灵敏；数字越小，波动越平滑。

report_vad

true：开启本地人声检测功能。开启后，audioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。
false：（默认）关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外，audioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。

enableDeepLearningDenoise

开启或关闭 AI 降噪模式。

Future<void> enableDeepLearningDenoise(bool enable);

SDK 默认开启传统降噪模式，以消除大部分平稳噪声。如果你还需要消除非平稳噪声，声网推荐你按如下步骤开启 AI 降噪模式：

确保已集成如下动态库：libagora_ai_denoise_extension.dll
调用 enableDeepLearningDenoise(true)。

AI 降噪模式对设备性能有要求。只有在设备性能良好的情况下，SDK 才会成功开启 AI 降噪模式。

如下设备经测试支持开启 AI 降噪模式:

iPhone 6S
MacBook Pro 2015
iPad Pro 第二代
iPad mini 第五代
iPad Air 第三代

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

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

注意：

该方法需要动态加载动态库，所以声网推荐在加入频道前调用该方法。
该方法对人声的处理效果最佳。声网不推荐调用该方法处理含音乐的音频数据。

参数

enable

是否开启 AI 降噪模式:

true:（默认）开启 AI 降噪模式。
false: 关闭 AI 降噪模式。

enableDualStreamMode

开关双流模式。

Future<void> enableDualStreamMode(bool enabled);

该方法设置单流（默认）或者双流模式。你可以在发流端调用该方法开启或关闭双流模式。

双流指视频大流和视频小流：

视频大流：高分辨率、高帧率的视频流。
视频小流：低分辨率、低帧率的视频流。

开启双流模式后，你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。

参数

enabled

是否开启双流模式。

true: 开启双流模式。
false: 关闭双流模式。

enableEncryption

开启或关闭内置加密。

Future<void> enableEncryption(bool enabled, EncryptionConfig config);

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

同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后，SDK 会自动关闭加密。如需重新开启加密，你需要在用户再次加入频道前调用该方法。

注意：如果开启了内置加密，则不能使用旁路推流功能。

参数

enabled

是否开启内置加密：

true: 开启内置加密。
false: 关闭内置加密。

config

配置内置加密模式和密钥。详见 EncryptionConfig。

enableFaceDetection

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

Future<void> enableFaceDetection(bool enable);

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

注意：该方法仅适用于 Android 和 iOS。

开启本地人脸检测后，SDK 会触发 facePositionChanged 回调向你报告人脸检测的信息：

摄像头采集的画面大小
人脸在画面中的位置
人脸距设备屏幕的距离

该方法需要在相机启动（如通过调用 startPreview 或 joinChannel 实现）后调用。

参数

enable

是否开启人脸检测：

true：开启人脸检测。
false：（默认）关闭人脸检测。

enableInEarMonitoring

开启耳返功能。

Future<void> enableInEarMonitoring(bool enabled);

该方法打开或关闭耳返功能。

注意：

该方法仅适用于 Android 和 iOS 平台。
用户必须使用有线耳机才能听到耳返效果。
该方法在加入频道前后都能调用。

参数

enabled

开启/关闭耳返功能:

true: 开启耳返功能。
false: （默认）关闭耳返功能。

enableLastmileTest

启用网络测试。

Future<void> enableLastmileTest();

该方法启用网络连接质量测试，用于检测用户目前的网络接入质量（上行网络质量）。默认该功能为关闭状态。该方法主要用于以下场景:

用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
直播场景下，当用户角色由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

无论哪种场景，启用该方法均会消耗网络流量，影响通话质量。用户必须在收到 lastmileQuality 回调后须调用 disableLastmileTest 停止测试，再加入频道或切换为主播。

注意：

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

enableLocalAudio

开关本地音频采集。

Future<void> enableLocalAudio(bool enabled);

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

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

音频功能关闭或重新开启后，会收到 localAudioStateChanged 回调，并报告 Stopped(0) 或 Recording(1)。

注意：

该方法与 muteLocalAudioStream 的区别在于：
- enableLocalVideo: 开启或关闭本地音频采集及处理。使用 enableLocalAudio 关闭或开启本地采集后，本地听远端播放会有短暂中断。
- muteLocalAudioStream: 停止或继续发送本地音频流。
该方法在加入频道前后都能调用。

参数

enabled

true: 重新开启本地音频功能，即开启本地音频采集（默认）；
false: 关闭本地音频功能，即停止本地音频采集。

enableLocalVideo

开关本地视频采集。

Future<void> enableLocalVideo(bool enabled);

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

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

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

注意：

该方法在加入频道前后都能调用。
该方法设置内部引擎为启用状态，在离开频道后仍然有效。

参数

enabled

是否开启本地视频采集。

true:（默认）开启本地视频采集。
false: 关闭本地视频采集。关闭后，远端用户会接收不到本地用户的视频流；但本地用户依然可以接收远端用户的视频流。设置为 false 时，该方法不需要本地有摄像头。

enableLocalVoicePitchCallback

开启本地语音音调回调。

Future<void> enableLocalVoicePitchCallback(int interval);

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

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

参数

interval

设置 SDK 触发 localVoicePitchInHz 回调的时间间隔：

≤ 0: 关闭 localVoicePitchInHz 回调。
> 0: SDK 触发 localVoicePitchInHz 回调的时间间隔，单位为毫秒。取值需大于等于 10 毫秒，如果小于 10 毫秒，SDK 会自动调整为 10 毫秒。

enableLoopbackRecording

开启声卡采集。

Future<void> enableLoopbackRecording(bool enabled, {String? deviceName})

启用声卡采集功能后，声卡播放的声音会被合到本地音频流中，从而可以发送到远端。

注意：

该方法仅适用于 macOS 和 Windows 平台。
macOS 系统默认声卡不支持采集功能，如果你需要使用该功能，请启用一个虚拟声卡，并将该虚拟声卡的名字传入 deviceName 参数。声网推荐你启用 AgoraALD (Agora Audio Loopback Device) 并向该参数传入 "AgoraALD"。
该方法在加入频道前后都能调用。

参数

enabled

是否开启声卡采集:

true: 开启声卡采集。
false:（默认）关闭声卡采集。

deviceName

声卡的设备名。默认为空，代表使用当前声卡采集。如果你使用虚拟声卡，如 AgoraALD（Agora Audio Loopback Device），你可以将该参数设置为声卡的名称（"AgoraALD"）。

enableRemoteSuperResolution

开启或关闭远端视频超分辨率。

Future<void> enableRemoteSuperResolution(int userId, bool enable);

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

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

警告：

超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗，只可以对一个远端用户开启超分辨率，并且远端用户视频的原始分辨率在 Android 设备上不能超过 640 × 360，在 iOS 设备上不能超过 640 × 480。

当超出限制时，SDK 会触发 warning 回调，并返回相应的警告码：

SuperResolutionStreamOverLimitation: 1610，远端用户的原始视频分辨率超出了可以应用超分辨率的范围。
SuperResolutionUserCountOverLimitation: 1611，已对一个远端用户的视频使用超分辨率。
SuperResolutionDeviceNotSupported: 1612，设备不支持使用超分辨率。

注意：

该方法仅适用于 Android 和 iOS 平台。
调用该方法前，请确保你已经集成相应的动态库：
- Android: libagora_super_resolution_extension.so
- iOS: AgoraSuperResolutionExtension.xcframework
该方法对用户设备具有一定要求，声网推荐你使用如下或更好的设备：
- Android:
  - VIVO：V1821A，NEX S，1914A，1916A，1962A，1824BA，X60，X60 Pro
  - OPPO：PCCM00，Find X3
  - OnePlus：A6000
  - Xiaomi：Mi 8，Mi 9，Mi 10，Mi 11，MIX3，Redmi K20 Pro
  - SAMSUNG：SM-G9600，SM-G9650，SM-N9600，SM-G9708，SM-G960U，SM-G9750，S20，S21
  - HUAWEI：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:
  - 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（第四代）

参数

userId

远端用户 ID。

enable

是否对远端视频开启超分辨率：

true: 开启超分辨率。
false: 关闭超分辨率。

enableSoundPositionIndication

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

Future<void> enableSoundPositionIndication(bool enabled);

如果想调用 setRemoteVoicePosition 实现听声辨位的功能，请确保在加入频道前调用该方法开启远端用户的语音立体声。

参数

enabled

是否开启远端用户语音立体声：

true: 开启语音立体声。
false: 关闭语音立体声。

enableVideo

启用视频模块。

Future<void> enableVideo();

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

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

注意：

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

enableVirtualBackground

开启/关闭虚拟背景（beta 功能）。

Future<void> enableVirtualBackground(
      bool enabled, VirtualBackgroundSource backgroundSource);

虚拟背景功能支持你使用自定义的背景图替代本地用户原来的背景图或者将背景虚化处理。成功开启虚拟背景功能后，频道内所有用户都能看到自定义的背景。

你可以从 virtualBackgroundSourceEnabled 回调了解虚拟背景是否成功开启和相应的出错原因。

注意：

调用该方法前，请确保你已集成相应的动态库。
- Android: libagora_segmentation_extension.so
- iOS: AgoraVideoSegmentationExtension.xcframework
该方法需要在 enableVideo 后调用。
该功能对设备性能要求较高，声网推荐你在搭载如下芯片的设备上使用：
- 骁龙 700 系列 750G 及以上
- 骁龙 800 系列 835 及以上
- 天玑 700 系列 720 及以上
- 麒麟 800 系列 810 及以上
- 麒麟 900 系列 980 及以上
- 搭载 A9 及以上芯片的如下设备：
  - iPhone 6S 及以上
  - iPad Air 第三代及以上
  - iPad 第五代及以上
  - iPad Pro 第一代及以上
  - iPad mini 第五代及以上
声网建议你在满足如下条件的场景中使用该功能：
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。

参数

enabled

是否开启虚拟背景：

true: 开启。
false: 关闭。

backgroundSource

自定义的背景图。详见 VirtualBackgroundSource。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配，SDK 会在保证自定义背景图不变形的前提下，对自定义背景图进行缩放和裁剪。

enableWebSdkInteroperability

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

Future<void> enableWebSdkInteroperability(bool enabled);

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

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

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

参数

enabled

是否打开与 Web SDK 的互通：

true: 打开互通。
false: (默认) 关闭互通。

enableWirelessAccelerate

开启或关闭 Wi-Fi 加速功能。

Future<void> enableWirelessAccelerate(bool enabled);

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

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

注：

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

参数

enabled

设置是否开启 Wi-Fi 加速功能：

true：开启。
false：关闭。

返回值

0: 方法调用成功
< 0: 方法调用失败

getAudioFileInfo

获取指定音频文件信息。

Future<int?> getAudioFileInfo(String filePath);

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

注意：

该方法需要在加入频道后调用。
该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

参数

filePath

文件路径：

Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.
iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4.

返回值

0: 方法调用成功。
< 0: 方法调用失败。

getAudioMixingCurrentPosition

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

Future<int?> getAudioMixingCurrentPosition();

该方法获取当前音乐文件播放进度，单位为毫秒。

注意：你需要在调用并收到 audioMixingStateChanged(PLAY) 回调后调用该方法。

返回值

≥ 0: 方法调用成功返回音乐文件播放进度。
< 0: 方法调用失败。

getAudioMixingDuration

获取音乐文件的时长。

Future<int?> getAudioMixingDuration([String? filePath]);

注意：

该方法需要在加入频道后调用。
该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

参数

filePath

文件路径：

Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.
iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4.

返回值

≥ 0: 方法调用成功返回音乐文件时长（毫秒）。
< 0: 方法调用失败。

getAudioMixingPlayoutVolume

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

Future<int?> getAudioMixingPlayoutVolume();

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

注意：

返回值

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

getAudioMixingPublishVolume

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

Future<int?> getAudioMixingPublishVolume();

该接口可以方便开发者排查音量相关问题。

返回值

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

getAudioTrackCount

获取当前音乐文件的音轨索引。

Future<int?> getAudioTrackCount();

注：

该方法仅适用于 Android、iOS 和 Windows。
你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

返回值

≥ 0: 方法调用成功，返回当前音乐文件的音轨索引。
< 0: 方法调用失败。

getCameraMaxZoomFactor

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

Future<double?> getCameraMaxZoomFactor();

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

返回值

设备摄像头支持的最大缩放比例。

getCallId

获取通话 ID。

Future<String?> getCallId();

客户端在每次加入频道后会生成一个对应的 callId，标识该客户端的此次通话。有些方法，如 rate、complain 等，需要在通话结束后调用，向 SDK 提交反馈。这些方法中需要填入指定的 callId 参数。

注意：该方法需要在加入频道后调用。

返回值

通话 ID。

getConnectionState

获取当前网络连接状态。

Future<ConnectionStateType> getConnectionState();

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

返回值

当前网络连接状态。详见 ConnectionStateType。

getEffectCurrentPosition

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

Future<int?> getEffectCurrentPosition(int soundId);

注意：该方法需要在 playEffect 后调用。

参数

soundId: 音效的 ID。每个音效的 ID 具有唯一性。

返回值

≥ 0：方法调用成功，返回指定音效文件的播放进度（毫秒）。
< 0：方法调用失败。

getEffectDuration

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

Future<int?> getEffectDuration(String filePath);

注意：该方法需要在加入频道后调用。

参数

filePath

文件路径：

Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.
iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4.

返回值

≥ 0：方法调用成功，返回指定音效文件时长（毫秒）。
< 0：方法调用失败。

getEffectsVolume

获取音效文件的播放音量。

Future<double?> getEffectsVolume();

音量范围为 0~100。100 （默认值）为原始文件音量。

注意：该方法需要在 playEffect 后调用。

返回值

音效文件的音量。
< 0: 方法调用失败

getScreenShareHelper

获取一个子进程对象。

Future<RtcEngine> getScreenShareHelper({String? appGroup})

参数

appGroup: App group。

返回值

一个子进程对象，可用于屏幕共享场景。

getUserInfoByUid

通过 UID 获取用户信息。

Future<UserInfo> getUserInfoByUid(int uid);

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

参数

uid: 用户 ID。

返回值

包含用户信息的 UserInfo 对象。

非空：方法调用成功。
空：方法调用失败。

getUserInfoByUserAccount

通过 User Account 获取用户信息。

Future<UserInfo> getUserInfoByUserAccount(String userAccount);

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

参数

userAccount: 用户 User Account。

返回值

包含用户信息的 UserInfo 对象。

非空：方法调用成功。
空：方法调用失败。

isCameraZoomSupported

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

Future<bool?> isCameraZoomSupported();

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

返回值

true: 设备支持相机缩放功能。
false: 设备不支持相机缩放功能。

isCameraTorchSupported

检测设备是否支持闪光灯常开。

Future<bool?> isCameraTorchSupported();

该方法需要在相机启动（如通过调用 startPreview 或 joinChannel 实现）后调用。

注意：

一般情况下，App 默认开启前置摄像头，因此如果你的前置摄像头不支持闪光灯常开，直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯常开，需要先使用 switchCamera 切换摄像头，再使用该方法。

返回值

true: 设备支持闪光灯常开。
false: 设备不支持闪光灯常开。

isCameraFocusSupported

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

Future<bool?> isCameraFocusSupported();

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

返回值

true: 设备支持手动对焦功能。
false: 设备不支持手动对焦功能。

isCameraExposurePositionSupported

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

Future<bool?> isCameraExposurePositionSupported();

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

返回值

true: 设备支持手动曝光功能。
false: 设备不支持手动曝光功能。

isCameraAutoFocusFaceModeSupported

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

Future<bool?> isCameraAutoFocusFaceModeSupported();

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

返回值

true: 设备支持人脸对焦功能。
false: 设备不支持人脸对焦功能。

isSpeakerphoneEnabled

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

Future<bool?> isSpeakerphoneEnabled();

注：

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

返回值

true: 扬声器已开启，语音会输出到扬声器。
false: 扬声器未开启，语音会输出到非扬声器（听筒，耳机等）。

joinChannel

加入频道并设置是否自动订阅音频或视频流。

Future<void> joinChannel(
      String? token, String channelName, String? optionalInfo, int optionalUid,
      [ChannelMediaOptions? options]);

该方法让用户加入实时音视频互动频道。在 App ID 一致的前提下，进入同一个频道的用户可以互相通话；多个用户加入同一个频道可以群聊。

成功调用该方法加入频道后会触发以下回调：

本地会触发 joinChannelSuccess 和 connectionStateChanged 回调。
通信场景下的用户和直播场景下的主播加入频道后，远端会触发 userJoined 回调。

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

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

警告：请确保用于生成 token 的 App ID、频道名和用户名和 createWithContext 方法初始化引擎时用的 App ID，以及该方法中设置的频道名和用户名是一致的。

channelName

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

optionalInfo

预留参数。

optionalUid

用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID，并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。建议设置范围：1 到 2 ³² -1。如果不指定（即设为 0），SDK 会自动分配一个，并在 joinChannelSuccess 回调中返回，应用层必须记住该返回值并维护，SDK 不对该返回值进行维护。

options

频道媒体设置选项。详见 ChannelMediaOptions 。

joinChannelWithUserAccount

使用 User Account 加入频道，并设置是否自动订阅音频或视频流。

Future<void> joinChannelWithUserAccount(
      String? token, String channelName, String userAccount,
      [ChannelMediaOptions? options]);

该方法允许本地用户使用 User Account 加入频道。成功加入频道后，会触发以下回调：

本地：localUserRegistered、joinChannelSuccess 和 connectionStateChanged 回调。
远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发 userJoined 和 userInfoUpdated 回调。

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

注意：为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

参数

token

在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。

警告：请确保用于生成 token 的 App ID、频道名和用户名和 createWithContext 方法初始化引擎时用的 App ID，以及该方法中设置的频道名和用户名是一致的。

channelName

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填，最大不超过 255 字节，不可填 null。以下为支持的字符集范围（共 89 个字符）：

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

options

频道媒体设置选项。详见 ChannelMediaOptions 。

leaveChannel

离开频道。

Future<void> leaveChannel();

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

成功加入频道后，必须调用本方法结束通话，否则无法开始下一次通话。

成功调用该方法离开频道后会触发以下回调：

本地：leaveChannel 回调。
远端：通信场景下的用户和直播场景下的主播离开频道后，远端会触发 userOffline 回调。

注意：

如果你调用了本方法后立即调用 destroy 方法，SDK 将无法触发 leaveChannel 回调。
如果你在旁路推流过程中调用了本方法离开频道，SDK 将自动调用 removePublishStreamUrl 方法。

muteAllRemoteAudioStreams

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

Future<void> muteAllRemoteAudioStreams(bool muted);

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

注意：

该方法需要在加入频道后调用。

参数

muted

是否取消订阅所有远端用户的音频流：

true: 取消订阅所有远端用户的音频流。
false:（默认）订阅所有远端用户的音频流。

muteAllRemoteVideoStreams

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

Future<void> muteAllRemoteVideoStreams(bool muted);

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

注意：

该方法需要在加入频道后调用。
该方法的推荐设置详见设置订阅状态。

参数

muted

是否取消订阅所有远端用户的视频流。

true: 取消订阅所有用户的视频流。
false:（默认）订阅所有用户的视频流。

muteLocalAudioStream

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

Future<void> muteLocalAudioStream(bool muted);

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

注意：

该方法不影响音频采集状态，因为没有禁用音频采集设备。
该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法， SDK 会根据你设置的频道场景以及用户角色，重新设置是否取消发布本地音频。因此我们建议在 setChannelProfile 后调用该方法。

参数

muted

是否取消发布本地音频流。

true: 取消发布。
false:（默认）发布。

muteLocalVideoStream

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

Future<void> muteLocalVideoStream(bool muted);

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

注意：

相比于 enableLocalVideo(false) 用于控制本地视频流发送的方法，该方法响应速度更快。
该方法不影响视频采集状态，没有禁用摄像头。
该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法，SDK 会根据你设置的频道场景以及用户角色，重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。

参数

muted

是否取消发送本地视频流。

true: 取消发送本地视频流。
false: （默认）发送本地视频流。

muteRemoteAudioStream

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

Future<void> muteRemoteAudioStream(int uid, bool muted);

注意：

该方法需要在加入频道后调用。
该方法的推荐设置详见《设置订阅状态》。

参数

uid

指定用户的用户 ID。

muted

是否取消订阅指定远端用户的音频流。

true: 取消订阅指定用户的音频流。
false:（默认）订阅指定用户的音频流。

muteRemoteVideoStream

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

Future<void> muteRemoteVideoStream(int userId, bool muted);

注意：

该方法需要在加入频道后调用。
该方法的推荐设置详见《设置订阅状态》。

参数

userId

指定用户的用户 ID。

muted

是否取消订阅指定远端用户的视频流。

true: 取消订阅指定用户的视频流。
false: （默认）订阅指定用户的视频流。

pauseAllChannelMediaRelay

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

Future<void> pauseAllChannelMediaRelay();

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

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

注意：该方法需要在 startChannelMediaRelay 后调用。

pauseAllEffects

暂停所有音效文件播放。

Future<void> pauseAllEffects();

playEffect

播放指定的本地或在线音效文件。

Future<void> playEffect(int soundId, String filePath, int loopCount,
      double pitch, double pan, int gain, bool publish,
      [int? startPos]);

你可以多次调用该方法，传入不同的 soundID 和 filePath，同时播放多个音效文件。为获得最佳用户体验，声网推荐同时播放的音效文件不超过 3 个。音效文件播放结束后，SDK 会触发 audioEffectFinished 回调。

注意：该方法需要在加入频道后调用。

参数

soundId

音效的 ID。每个音效的 ID 具有唯一性。

注意：如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 soundId 相同。

filePath

播放文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。

注意：如果你已通过 preloadEffect 将音效加载至内存，请确保该参数与 preloadEffect 中设置的 filePath 相同。

loopCount

音效循环播放的次数。

≥ 0: 循环播放次数。例如，1 表示循环播放 1 次，即总计播放 2 次。
-1: 无限循环播放。

pitch

音效的音调，取值范围为 [0.5,2.0]。默认值为 1.0，表示原始音调。取值越小，则音调越低。

pan

音效的空间位置。取值范围为 [-1.0,1.0]，例如：

-1.0：音效出现在左边
0.0：音效出现在正前方
1.0：音效出现在右边

gain

音效的音量。取值范围为 [0.0,100.0]。默认值为 100.0，表示原始音量。取值越小，则音量越低。

publish

是否将音效发布至远端：

true: 将音效发布至远端。本地用户和远端用户都能听到音效。
false: 不将音效发布至远端。只有本地用户能听到音效。

startPos

音效文件的播放位置，单位为毫秒。

preloadEffect

将音效文件加载至内存。

Future<void> preloadEffect(int soundId, String filePath);

为保证通信畅通，请注意控制预加载音效文件的大小，并在 joinChannel 前就使用该方法完成音效预加载。

注意：

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

参数

soundId

音效的 ID。每个音效的 ID 具有唯一性。

filePath

文件路径：

Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.
iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4.

rate

给通话评分。

Future<void> rate(String callId, int rating, {String? description});

注意：该方法需要在用户离开频道后调用。

参数

callId: 通话 ID。你可以通过调用 getCallId 获取该参数。
rating: 给通话的评分，最低 1 分，最高 5 分，如超过这个范围，SDK 会返回 -2(ERR_INVALID_ARGUMENT) 错误。
description: （非必选项）给通话的描述。长度应小于 800 字节。

registerLocalUserAccount

注册本地用户 User Account。

Future<void> registerLocalUserAccount(String appId, String userAccount);

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

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

该方法为可选。如果你希望用户使用 User Account 加入频道，可以选用以下两种方式：

先调用 registerLocalUserAccount 方法注册 Account，再调用 joinChannelWithUserAccount 方法加入频道。
直接调用 joinChannelWithUserAccount 方法加入频道。

两种方式的区别在于，提前调用 registerLocalUserAccount，可以缩短使用 joinChannelWithUserAccount 进入频道的时间。

注意：

userAccount 不能为空，否则该方法不生效。
请确保在该方法中设置的 userAccount 在频道中的唯一性。
为保证通信质量，请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。如果有用户通过 Web SDK 加入频道，请确保 Web 加入的用户也是同样类型。

参数

appId

你的项目在声网控制台注册的 App ID。

userAccount

用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account，并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填，最大不超过 255 字节，不可填 null。以下为支持的字符集范围（共 89 个字符）：

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

destroy

销毁 RtcEngine 对象。

Future<void> destroy();

该方法释放声网 SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信，不需要时则将资源释放出来用于其他操作，该方法适用于此类情况。

注意：如需在销毁后再次创建 RtcEngine 对象，需要等待 destroy 方法执行结束后再创建实例。

removePublishStreamUrl

删除旁路推流地址。

Future<void> removePublishStreamUrl(String url);

弃用：: 该方法已废弃。替代方案请参考发版说明

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

注意：

调用该方法前，请确保已开通旁路推流的功能。
只有直播场景中角色为主播的用户才能调用该方法。
该方法需要在加入频道后调用。
该方法每次只能删除一路旁路推流地址。若需删除多路流，则需多次调用该方法。

参数

url: 待删除的旁路推流地址，格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。

renewToken

更新 Token。

Future<void> renewToken(String token);

该方法用于更新 Token。Token 会在一定时间后失效。在以下两种情况下，app 应重新获取 Token, 然后调用该方法传入新的 Token，否则 SDK 无法和服务器建立连接：

发生 tokenPrivilegeWillExpire 回调时。
connectionStateChanged 回调报告 TokenExpired(9) 时。

参数

token: 新的 Token。

resumeAllChannelMediaRelay

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

Future<void> resumeAllChannelMediaRelay();

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

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

注意：该方法需要在 pauseAllChannelMediaRelay 后调用。

resumeAllEffects

恢复播放所有音效文件。

Future<void> resumeAllEffects();

selectAudioTrack

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

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

注：

你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(Playing) 回调后调用该方法。
该方法仅适用于 Android、iOS 和 Windows。
该方法支持的音频文件格式见 https://docs.agora.io/cn/Video/faq/audio_format。

参数

index: 指定的播放音轨。取值范围为 [0, getAudioTrackCount()]。

返回值

0: 方法调用成功。
< 0: 方法调用失败。

setAudioMixingPlaybackSpeed

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

Future<void> setAudioMixingPlaybackSpeed(int speed);

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

参数

speed

播放速度。推荐取值范围为 [50,400]，其中：

50: 0.5 倍速。
100: 原始速度。
400: 4 倍速。

setAudioMixingDualMonoMode

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

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

注：

你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(Playing) 回调后调用该方法。
该方法仅适用于双声道的音乐文件。

参数

mode: 声道详情。详见AudioMixingDualMonoMode。

返回值

0: 方法调用成功。
< 0: 方法调用失败。

startRhythmPlayer

开启虚拟节拍器。

Future<void> startRhythmPlayer(
      String sound1, String sound2, RhythmPlayerConfig config);

在音乐教学、体育教学等场景中，老师通常需要使用节拍器，让学生跟着正确的节拍练习。节拍由强拍和弱拍组成，每小节的第一拍称为强拍，其余称为弱拍。

你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。

注意：

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

参数

sound1: 强拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4。支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
sound2: 弱拍文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4。支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。
config: 节拍器配置。详见 RhythmPlayerConfig。

configRhythmPlayer

配置虚拟节拍器。

Future<void> configRhythmPlayer(RhythmPlayerConfig config);

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

注意：

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

参数

config: 节拍器配置。详见 RhythmPlayerConfig。

sendCustomReportMessage

发送自定义上报消息。

Future<void> sendCustomReportMessage(
      String id, String category, String event, String label, int value);

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

sendMetadata

发送媒体附属信息。

Future<void> sendMetadata(Uint8List metadata);

如果成功发送了媒体附属信息，接收端会收到 metadataReceived 回调。

参数

metadata: 媒体附属信息。详见 Metadata。

sendStreamMessage

发送数据流。

Future<void> sendStreamMessage(int streamId, Uint8List message);

该方法发送数据流消息到频道内所有用户。SDK 对该方法的实现进行了如下限制：

频道内每秒最多能发送 30 个包，且每个包最大为 1 KB。
每个客户端每秒最多能发送 6 KB 数据。
频道内每人最多能同时有 5 个数据通道。

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

注意：

请确保在调用该方法前，已调用 createDataStreamWithConfig 创建了数据通道。
直播场景下，该方法仅适用于主播用户。

参数

streamId: 数据流 ID。可以通过 createDataStreamWithConfig 获取。
message: 待发送的数据。

setAudioEffectParameters

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

Future<void> setAudioEffectParameters(
      AudioEffectPreset preset, int param1, int param2);

详细描述

调用该方法可以对本地发流用户进行如下设置：

3D 人声音效：设置 3D 人声音效的环绕周期。
电音音效：设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效，声网推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。

设置后，频道内所有用户都能听到该效果。

注意：

该方法在加入频道前后都能调用。
为获取更好的人声效果，声网推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。
请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
调用 setAudioEffectParameters 后，声网不推荐调用以下方法，否则 setAudioEffectParameters 设置的效果会被覆盖：

参数

preset

SDK 预设的音效，支持以下设置：

RoomAcoustics3DVoice，3D 人声音效。
- 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicStandardStereo(3) 或 MusicHighQualityStereo(5)，否则该枚举设置无效。
- 启用 3D 人声后，用户需要使用支持双声道的音频播放设备才能听到预期效果。
PitchCorrection，电音音效。为获取更好的人声效果，声网建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。

param1

如果 preset 设为 RoomAcoustics3DVoice ，则 param1 表示 3D 人声音效的环绕周期。取值范围为 [1,60]，单位为秒。默认值为 10，表示人声会 10 秒环绕 360 度。
如果 preset 设为 PitchCorrection，则 param1 表示电音音效的基础调式：
- 1: （默认）自然大调。
- 2: 自然小调。
- 3: 和风小调。

param2

如果 preset 设为 RoomAcoustics3DVoice，你需要将 param2 设置为 0。
如果 preset 设为 PitchCorrection，则 param2 表示电音音效的主音音高：
- 1: A
- 2: A#
- 3: B
- 4: (Default) C
- 5: C#
- 6: D
- 7: D#
- 8: E
- 9: F
- 10: F#
- 11: G
- 12: G#

setAudioEffectPreset

设置 SDK 预设的人声音效。

Future<void> setAudioEffectPreset(AudioEffectPreset preset);

详细描述

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

根据不同的场景，你可以为用户设置不同的音效，各音效的适用场景可参考《设置人声效果》。

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

注意：

该方法在加入频道前后都能调用。
请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
如果调用 setAudioEffectPreset 并设置除 RoomAcoustics3DVoice 或 PitchCorrection 外的枚举，请勿再调用 setAudioEffectParameters，否则 setAudioEffectPreset 设置的效果会被覆盖。
调用 setAudioEffectPreset 后，声网不推荐调用以下方法，否则 setAudioEffectPreset 设置的效果会被覆盖：

参数

preset: 预设的音效选项，详见 AudioEffectPreset。

setAudioMixingPitch

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

Future<void> setAudioMixingPitch(int pitch);

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

注意：你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(Playing) 回调后调用该方法。

参数

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

setAudioMixingPosition

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

Future<void> setAudioMixingPosition(int pos);

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

注意：你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(PLAY) 回调后调用该方法。

参数

pos: 整数。进度条位置，单位为毫秒。

setAudioProfile

设置音频编码属性和音频场景。

Future<void> setAudioProfile(AudioProfile profile, AudioScenario scenario);

注意：

该方法需要在加入频道前调用。
在有高音质需求的场景（例如音乐教学场景）中，建议将 profile 设置为 MusicHighQuality(4)，scenario 设置为 GameStreaming(3)。

参数

profile: 音频编码属性，包含采样率、码率、编码模式和声道数。详见 AudioProfile。
scenario: 音频场景。详见 AudioScenario 。不同的音频场景下，设备的音量类型是不同的。

setAudioSessionOperationRestriction

设置 SDK 对 Audio Session 的操作权限。

Future<void> setAudioSessionOperationRestriction(
      AudioSessionOperationRestriction restriction);

默认情况下，SDK 和 app 对 Audio Session 都有操作权限。如果你只需使用 app 对 Audio Session 进行操作，你可以调用该方法限制 SDK 对 Audio Session 的操作权限。

该方法在加入频道前后都能调用。一旦调用该方法限制了 SDK 对 Audio Session 的操作权限，该限制会在 SDK 需要更改 Audio Session 时生效。

注意：

该方法仅适用于 iOS 平台。
该方法不会限制 app 对 Audio Session 的操作权限。

参数

restriction: SDK 对 Audio Session 的操作权限，详见 AudioSessionOperationRestriction。该参数为 Bit Mask，每个 Bit 对应一个权限。

setBeautyEffectOptions

设置美颜效果选项。

Future<void> setBeautyEffectOptions(bool enabled, BeautyOptions options);

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

注意：

该方法需要在 enableVideo 后调用。

参数

enabled

是否开启美颜功能：

true: 开启。
false:（默认）关闭。

options

美颜选项，详细定义见 BeautyOptions。

setCameraAutoFocusFaceModeEnabled

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

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

参数

是否开启人脸对焦：

true: 开启人脸对焦功能。
false:（默认）关闭人脸对焦功能。

返回值

0: 方法调用成功。
< 0: 方法调用失败。

setCameraCapturerConfiguration

设置摄像头采集配置。

Future<void> setCameraCapturerConfiguration(
      CameraCapturerConfiguration config);

一般的视频通话或直播中，默认由 SDK 自动控制摄像头的输出参数。在如下特殊场景中，默认的参数无法满足需求或可能引起设备性能问题，我们推荐调用该方法设置摄像头的采集偏好:

使用原始音视频数据自采集接口时，如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数，在后续处理视频帧的时候，比如美颜功能时，会需要更高的 CPU 及内存，容易导致性能问题。在这种情况下，我们推荐将摄像头采集偏好设置为 Performance(1)，避免性能问题。
如果没有本地预览功能或者对预览质量没有要求，我们推荐将采集偏好设置为 Performance(1)，以优化 CPU 和内存的资源分配。
如果用户希望本地预览视频比实际编码发送的视频清晰，可以将采集偏好设置为 Preview(2)。
如果用户需要自定义本地采集的视频宽高，请将采集偏好设为 Manual(3)。

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

参数

config: 摄像头采集配置，详见 CameraCapturerConfiguration。

setCameraExposurePosition

设置手动曝光位置。

Future<void> setCameraExposurePosition(
      double positionXinView, double positionYinView);

该方法需要在相机启动（如通过调用 startPreview 或 joinChannel 实现）后调用。

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

参数

positionXinView: 触摸点相对于视图的横坐标。
positionYinView: 触摸点相对于视图的纵坐标。

setCameraFocusPositionInPreview

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

Future<void> setCameraFocusPositionInPreview(
      double positionX, double positionY);

该方法需要在相机启动（如通过调用 startPreview 或 joinChannel 实现）后调用。成功调用该方法后，本地会触发 cameraFocusAreaChanged 回调。

参数

positionX: 触摸点相对于视图的横坐标。
positionY: 触摸点相对于视图的纵坐标。

setCameraTorchOn

设置是否打开闪光灯。

Future<void> setCameraTorchOn(bool isOn);

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

参数

isOn

是否打开闪光灯：

true: 打开闪光灯。
false:（默认）关闭闪光灯。

返回值

0: 方法调用成功。
< 0: 方法调用失败。

setCameraZoomFactor

设置摄像头缩放比例。

Future<void> setCameraZoomFactor(double factor);

注意：

请在启动摄像头之前调用该方法，如 joinChannel、enableVideo 或者 enableLocalVideo 之前。

参数

factor: 相机缩放比例，有效范围从 1.0 到最大缩放比例。你可以通过 getCameraMaxZoomFactor 方法获取设备支持的最大缩放比例。

setChannelProfile

设置频道场景。

Future<void> setChannelProfile(ChannelProfile profile);

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

注意：

为保证实时音视频质量，相同频道内的用户必须使用同一种频道场景。
该方法必须在 joinChannel 前调用和进行设置，进入频道后无法再设置。

参数

profile: 频道使用场景。详见 ChannelProfile。

setClientRole

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

Future<void> setClientRole(ClientRole role, [ClientRoleOptions? options]);

直播场景下，SDK 会默认设置用户角色为观众，你可以调用该方法设置用户角色为主播。

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

如果你在加入频道后调用该方法切换用户角色，调用成功后，SDK 会自动进行如下操作：

调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
本地触发 clientRoleChanged 回调。
远端触发 userJoined 或 userOffline 回调。

注意：该方法仅适用于直播场景（setChannelProfile 中 profile 设为 LiveBroadcasting）。

参数

role: 直播场景中的用户角色。详见 ClientRole。
options: 用户具体设置，包含用户级别。详见 ClientRoleOptions。

setCloudProxy

设置声网云代理服务。

Future<void> setCloudProxy(CloudProxyType proxyType);

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

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

As of v3.6.2, when a user calls this method and then joins a channel successfully, the SDK triggers the proxyConnected callback to report the user ID, the proxy type connected, and the time calculated from when the user calling the joinChannel method to the callback is triggered.

如果你想关闭已设置的 Force UDP 或 Force TCP 云代理，请调用 setCloudProxy (None)。

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

注意：

声网推荐你在频道外调用该方法。
对 3.3.x 版 SDK，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。对 3.4.0 及之后版 SDK，如果用户处于内网防火墙环境下，使用 Force UDP 云代理时，旁路推流和跨频道媒体流转发功能不可用。
使用 Force UDP 云代理时，调用 startAudioMixing 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。

参数

proxyType

云代理类型，详见 CloudProxyType。

该参数为必填参数，如果你不赋值，SDK 会报错。

setColorEnhanceOptions

设置色彩增强功能。

Future<void> setColorEnhanceOptions(bool enabled, ColorEnhanceOptions option);

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

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

注意：

请在 enableVideo 后调用该方法。
色彩增强对设备性能有一定要求。开启色彩增强后，如果设备出现严重发烫等问题，声网推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。

参数

是否开启色彩增强功能：：

true : 开启。
false :（默认）关闭。

option

色彩增强选项，用于设置色彩增强的效果。详见 ColorEnhanceOptions 。

setDefaultAudioRouteToSpeakerphone

设置默认的音频路由。

Future<void> setDefaultAudioRouteToSpeakerphone(bool defaultToSpeaker);

该方法设置接收到的音频从听筒或扬声器出声。如果用户不调用本方法，音频默认从听筒出声。

各频道场景下默认的音频路由：

通信场景：
- 语音通话，默认从听筒出声。
- 视频通话，默认从扬声器出声。如果有用户在频道中使用 disableVideo 、muteLocalVideoStream 或 muteAllRemoteVideoStreams 方法关闭视频，则语音路由会自动切换回听筒。
直播场景：扬声器。

注意：

该方法仅适用于 Android 和 iOS 平台。
该方法需要在加入频道前设置，否则不生效。

参数

defaultToSpeaker

设置默认的音频路由:

true: 音频路由为外放（扬声器）。如果设备连接了耳机或蓝牙，则无法切换到外放。
false:（默认）音频路由为听筒。

setDefaultMuteAllRemoteAudioStreams

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

Future<void> setDefaultMuteAllRemoteAudioStreams(bool muted);

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

注意：

取消订阅音频流后，如果需要恢复订阅频道内的远端，可以进行如下操作：

如果需要恢复订阅单个用户的音频流，调用 muteRemoteAudioStream (false)，并指定你想要订阅的远端用户 ID。
如果想恢复订阅多个用户的音频流，则需要多次调用 muteRemoteAudioStream (false)。

参数

muted

是否默认取消订阅远端用户的音频流：

true：默认取消订阅远端用户的音频流。
false：（默认）默认订阅远端用户的音频流。

setDefaultMuteAllRemoteVideoStreams

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

Future<void> setDefaultMuteAllRemoteVideoStreams(bool muted);

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

注意：

取消订阅视频流后，如果需要恢复订阅频道内的远端用户，可以进行如下操作：

如果需要恢复订阅单个用户的视频流，调用 muteRemoteVideoStream(false)，并指定你想要订阅的远端用户 ID。
如果想恢复订阅多个用户的视频流，则需要多次调用 muteRemoteVideoStream(false)。

参数

muted

是否默认取消订阅远端用户的视频流：

true: 默认取消订阅。
false:（默认）默认订阅。

setEffectPosition

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

Future<void> setEffectPosition(int soundId, int pos);

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

注意：该方法需要在 playEffect 后调用。

参数

soundId: 音效的 ID。每个音效的 ID 具有唯一性。
pos: 音效文件的播放位置，单位为毫秒。

setEffectsVolume

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

Future<void> setEffectsVolume(int volume);

注意：该方法需要在 playEffect 后调用。

参数

volume: 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

setEnableSpeakerphone

启用/关闭扬声器播放。

Future<void> setEnableSpeakerphone(bool speakerOn);

该方法设置是否将音频路由到扬声器（外放）。调用该方法后，SDK 将返回 audioRouteChanged 回调提示状态已更改。

注意：

该方法仅适用于 Android 和 iOS 平台。
请确保在调用此方法前已经加入频道。

参数

speakerOn

是否切换音频路由到扬声器（外放）：

true: 切换到外放。如果设备连接了耳机或蓝牙，则无法切换到外放。
false: 切换到听筒。如果设备连接了耳机，则音频路由走耳机。

setEncryptionMode

启用内置的加密方案。

Future<void> setEncryptionMode(EncryptionMode encryptionMode);

弃用：: 请改用 enableEncryption 方法。

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

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

参数

encryptionMode

加密模式：

"aes-128-xts": 128 位 AES 加密，XTS 模式；
"aes-128-ecb": 128 位 AES 加密，ECB 模式；
"aes-256-xts": 256 位 AES 加密，XTS 模式；
"sm4-128-ecb": 128 位 SM4 加密，ECB 模式；
"aes-128-gcm": 128 位 AES 加密，GCM 模式；
"aes-256-gcm": 256 位 AES 加密，GCM 模式；
"": 设置为空字符串时，默认使用加密方式 "aes-128-xts"。

setEncryptionSecret

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

Future<void> setEncryptionSecret(String secret);

弃用：: 请改用 enableEncryption 方法。

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

注意：

请不要在旁路推流时调用此方法。
为保证最佳传输效果，请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。

参数

secret: 加密密码。

setInEarMonitoringVolume

设置耳返音量。

Future<void> setInEarMonitoringVolume(int volume);

注意：

该方法仅适用于 Android 和 iOS 平台。
用户必须使用有线耳机才能听到耳返效果。
该方法在加入频道前后都能调用。

参数

volume: 设置耳返音量，取值范围在 [0,100]。默认值为 100。

setLiveTranscoding

设置直播推流转码。

Future<void> setLiveTranscoding(LiveTranscoding transcoding);

弃用：: 该方法已废弃。替代方案请参考发版说明。

该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 transcodingUpdated 回调。

注意：

只有直播场景中角色为主播的用户才能调用该方法。
请确保已开通旁路推流的功能，详见进阶功能《推流到 CDN》中的前提条件。
首次调用该方法更新转码设置时，不会触发 transcodingUpdated 回调。
该方法需要在加入频道后调用。
声网目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。

参数

transcoding: 推流转码设置。详见 LiveTranscoding。

setLocalPublishFallbackOption

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

Future<void> setLocalPublishFallbackOption(StreamFallbackOptions option);

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

注意：

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

参数

option: 本地发流回退处理选项。详见 StreamFallbackOptions。

setLocalVoiceChanger

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

Future<void> setLocalVoiceChanger(AudioVoiceChanger voiceChanger);

弃用：

该方法从 v3.2.0 起废弃，请改用以下方法：

setAudioEffectPreset ：音效
setVoiceBeautifierPreset ：美声效果
setVoiceConversionPreset ：变声效果

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

变声效果：枚举值以 VOICE_CHANGER 为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人，通常用于语聊场景。
美音效果：枚举值以 VOICE_BEAUTY 为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷，通常用于语聊和唱歌场景。
语聊美声效果：枚举值以 GENERAL_BEAUTY_VOICE 为前缀。效果包括磁性（男）、清新（女）和活力（女），通常用于语聊场景。该功能主要细化了男声和女声各自的特点。

注意：

为达到更好的声音效果，声网推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality (4) 或 MusicHighQualityStereo (5)。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含人声和音乐的音频数据。
该方法不能与 setLocalVoiceReverbPreset 方法一同使用，否则先调的方法会不生效。更多注意事项，详见进阶功能《变声与混响》。
该方法在加入频道前后都能调用。

参数

voiceChanger: 预设本地语音变声、美音或语聊美声效果选项，默认值为 Off ，即原声。详见 AudioVoiceChanger 。设置语聊美声效果时，声网推荐使用 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC 处理男声，使用 GENERAL_BEAUTY_VOICE_FEMALE_FRESH 或 GENERAL_BEAUTY_VOICE_FEMALE_VITALITY 处理女声，否则音频可能会产生失真。

setLocalVoiceEqualization

设置本地语音音效均衡。

Future<void> setLocalVoiceEqualization(
      AudioEqualizationBandFrequency bandFrequency, int bandGain);

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

参数

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

setLocalVoicePitch

设置本地语音音调。

Future<void> setLocalVoicePitch(double pitch);

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

参数

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

setLocalVoiceReverb

设置本地音效混响。

Future<void> setLocalVoiceReverb(AudioReverbType reverbKey, int value);

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

参数

reverbKey: 混响音效 Key。该方法共有 5 个混响音效 Key: AudioReverbType 。
value: 各混响音效 Key 所对应的值。

setLocalVoiceReverbPreset

设置本地语音混响（含虚拟立体声效果）。

Future<void> setLocalVoiceReverbPreset(AudioReverbPreset preset);

弃用：: 请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。

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

注意：

当使用以 AUDIO_REVERB_FX 为前缀的枚举值时，请确保在调用该方法前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality (4) 或 MusicHighQualityStereo (5) ，否则该方法设置无效。
当使用 VIRTUAL_STEREO 时，声网推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 MusicHighQualityStereo (5)。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含人声和音乐的音频数据。
该方法不能与 setLocalVoiceChanger 方法一同使用，否则先调的方法会不生效。更多注意事项，详见进阶功能《变声与混响》。
该方法在加入频道前后都能调用。

参数

preset: 本地语音混响选项，默认值为 Off ，即原声。详见 AudioReverbPreset 。为达到更好的混响效果，声网推荐使用以 AUDIO_REVERB_FX 为前缀的枚举值。

setLogFile

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

Future<void> setLogFile(String filePath);

弃用:: 请改用 createWithContext 设置日志文件路径。

默认情况下，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 写入最新的日志。

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

参数

filePath: 日志文件的完整路径。默认路径为 C:\Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。

setLogFileSize

设置声网 SDK 输出的单个日志文件大小。

Future<void> setLogFileSize(int fileSizeInKBytes);

弃用：: 请改用 createWithContext 中的 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 写入最新的日志。

注意：如果想要设置日志文件的大小，则需要在 setLogFile 前调用该方法，否则日志会被清空。

参数

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

setLogFilter

设置日志输出等级。

Future<void> setLogFilter(LogFilter filter);

弃用：: 请改用 createWithContext 中的 logConfig。

该方法设置声网 SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。选择一个级别，你就可以看到在该级别之前所有级别的日志信息。

例如，你选择 WARNING 级别，就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。

参数

filter: 日志过滤等级。

setLowlightEnhanceOptions

设置暗光增强功能。

Future<void> setLowlightEnhanceOptions(
                bool enabled, LowLightEnhanceOptions option);

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

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

注意：

请在 enableVideo 后调用该方法。
暗光增强对设备性能有一定要求。开启暗光增强后，如果设备出现严重发烫等问题，声网推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。

参数

是否开启暗光增强功能：：

true : 开启。
false :（默认）关闭。

option

暗光增强选项，用于设置暗光增强的效果。详见 LowLightEnhanceOptions 。

setMaxMetadataSize

设置媒体附属信息的最大大小。

Future<void> setMaxMetadataSize(int size);

调用 registerMediaMetadataObserver 后，你可以调用本方法来设置媒体附属信息的最大大小。

参数

size: 媒体附属信息的最大大小。

setParameters

通过 JSON 配置 SDK 提供技术预览或特别定制功能。

Future<void> setParameters(String parameters);

JSON 选项默认不公开。声网工程师正在努力寻求以标准化方式公开 JSON 选项。

参数

parameters: JSON 字符串形式的参数。

setRemoteDefaultVideoStreamType

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

Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);

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

正常情况下，用户默认接收大流。如需默认接收所有用户的视频小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

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

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

参数

streamType: 默认订阅的视频流类型: VideoStreamType 。

setRemoteSubscribeFallbackOption

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

Future<void> setRemoteSubscribeFallbackOption(StreamFallbackOptions option);

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

注意：该方法需要在加入频道前调用。

参数

option: 订阅音视频流的回退选项。默认值为 VideoStreamLow(1)。详见 StreamFallbackOptions。

setRemoteUserPriority

设置远端用户媒体流的优先级。

Future<void> setRemoteUserPriority(int uid, UserPriority userPriority);

设置远端用户的优先级。如果将某个用户的优先级设为高，那么发给这个用户的音视频流的优先级就会高于其他用户。弱网下 SDK 会优先保证高优先级用户收到的流的质量。

注意：

目前声网 SDK 仅允许将一名远端用户设为高优先级。
该方法需要在加入频道前调用。

参数

uid: 远端用户的 ID。
userPriority: 远端用户的需求优先级。详见: UserPriority。

setRemoteVideoStreamType

设置订阅的视频流类型。

Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);

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

正常情况下，用户默认接收大流。如需接收小流，可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小，以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比，系统会自动分配小流的分辨率、帧率及码率。

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

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

参数

userId: 用户 ID。
streamType: 视频流类型: VideoStreamType 。

setRemoteVoicePosition

设置远端用户声音的 2D 位置，即水平面位置。

Future<void> setRemoteVoicePosition(int uid, double pan, double gain);

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

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

注意：

使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
为获得最佳听觉体验，我们建议使用该方法时使用有线耳机。
该方法需要在加入频道后调用。

参数

uid

远端用户的 ID

pan

设置远端用户声音的 2D 位置，取值范围为 [-1.0,1.0]:

(默认）0.0: 声音出现在正前方。
-1.0: 声音出现在左边。
1.0: 声音出现在右边。

gain

设置远端用户声音的音量，取值范围为 [0.0,100.0]，默认值为 100.0，表示该用户的原始音量。取值越小，则音量越低。

setScreenCaptureContentHint

设置屏幕共享内容类型。

Future<void> setScreenCaptureContentHint(VideoContentHint contentHint);

声网 SDK 会根据不同的内容类型，使用不同的算法对共享效果进行优化。如果不调用该方法，SDK 会将屏幕共享的内容默认为 None，即无指定的内容类型。

注意：该方法在开始屏幕共享前后都能调用。

参数

contentHint: 屏幕共享的内容类型。详见 VideoContentHint。

setScreenCaptureScenario

设置屏幕共享的场景。

Future<void> setScreenCaptureScenario(ScreenScenarioType screenScenario);

开启屏幕共享或窗口共享时，你可以调用该方法设置屏幕共享的场景，SDK 会根据你设置的场景调整共享画质和体验。

参数

screenScenario: 屏幕共享的场景，详见 ScreenScenarioType。

setVideoDenoiserOptions

设置视频降噪功能。

Future<void> setVideoDenoiserOptions(
                bool enabled, VideoDenoiserOptions option);

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

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

注意：

请在 enableVideo 后调用该方法。
视频降噪对设备性能有一定要求。开启视频降噪后，如果设备出现严重发烫等问题，声网推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。

参数

enabled

是否开启视频降噪功能：

true : 开启。
false :（默认）关闭。

options

视频降噪选项，用于设置视频降噪的效果。详见 VideoDenoiserOptions 。

setVideoEncoderConfiguration

设置视频编码属性。

Future<void> setVideoEncoderConfiguration(VideoEncoderConfiguration config);

设置本地视频的编码属性。

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

参数

config: 视频编码参数配置。详见 VideoEncoderConfiguration。

setVoiceBeautifierParameters

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

Future<void> setAudioEffectParameters(
      AudioEffectPreset preset, int param1, int param2);

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

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

注意：

该方法在加入频道前后都能调用。
请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
调用 setVoiceBeautifierParameters，声网不推荐调用以下方法，否则 setVoiceBeautifierParameters 设置的效果会被覆盖：

参数

preset

预设的音效：

SINGING_BEAUTIFIER: 歌唱美声。

param1

歌声的性别特征：

1: 男声。
2: 女声。

param2

歌声的混响效果：

1: 歌声在小房间的混响效果。
2: 歌声在大房间的混响效果。
3: 歌声在大厅的混响效果。

setVoiceBeautifierPreset

设置预设的美声效果。

Future<void> setVoiceBeautifierPreset(VoiceBeautifierPreset preset);

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

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

注意：

该方法在加入频道前后都能调用。
请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
调用 setVoiceBeautifierPreset，声网不推荐调用以下方法，否则 setVoiceBeautifierPreset 设置的效果会被覆盖：

参数

preset: 预设的美声效果选项，详见 VoiceBeautifierPreset。

setVoiceConversionPreset

设置预设的变声效果。

Future<void> setVoiceConversionPreset(VoiceConversionPreset preset);

自从: v3.3.1

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

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

注意：

该方法在加入频道前后都能调用。
请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1)，否则该方法不生效。
该方法对人声的处理效果最佳，声网不推荐调用该方法处理含音乐的音频数据。
调用 setVoiceConversionPreset 后，声网不推荐调用以下方法，否则 setVoiceConversionPreset 设置的效果会被覆盖：

参数

preset: 预设的变声效果选项: VoiceConversionPreset。

setVolumeOfEffect

实时调整音效文件的播放音量。

Future<void> setVolumeOfEffect(int soundId, int volume);

注意：该方法需要在 playEffect 后调用。

参数

soundId: 指定音效的 ID。每个音效均有唯一的 ID。
volume: 播放音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

startAudioMixing

开始播放音乐文件。

Future<void> startAudioMixing(
      String filePath, bool loopback, bool replace, int cycle,
      [int? startPos]);

该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后，本地会触发 audioMixingStateChanged (PLAY) 回调。播放结束后，本地会触发 audioMixingStateChanged (STOPPED) 回调。

注意：

该方法需要在加入频道后调用。如需多次调用 startAudioMixing，请确保调用间隔大于 500 ms。
如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR (701)。
该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

参数

filePath

文件路径：

Android: 文件路径，需精确到文件名及后缀。支持在线文件的 URL 地址，本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。通过绝对路径访问本地文件可能会遇到权限问题，声网推荐使用 URI 地址访问本地文件。例如：content://com.android.providers.media.documents/document/audio%3A14441。
Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.
iOS 或 macOS: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如：/var/mobile/Containers/Data/audio.mp4.

loopback

是否只在本地播放音乐文件：

true: 只在本地播放音乐文件，只有本地用户能听到音乐。
false: 将本地播放的音乐文件发布至远端，本地用户和远端用户都能听到音乐。

replace

是否用音乐文件替换麦克风采集的音频：

true: 替换。用户只能听到音乐。
false: 不替换。用户可以听到音乐和麦克风采集的音频。

cycle

音乐文件的播放次数。

≥ 0: 播放次数。例如，0 表示不播放；1 表示播放 1 次。
-1: 无限循环播放。

startPos

音乐文件的播放位置，单位为毫秒。

startAudioRecording

开始客户端录音。

Future<void> startAudioRecording(String filePath,
      AudioSampleRateType sampleRate, AudioRecordingQuality quality);

弃用：: 请改用 startAudioRecordingWithConfig。

声网 SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内所有用户的音频，并得到一个包含所有用户声音的录音文件。录音文件格式可以为:

.wav: 文件大，音质保真度较高。
.aac: 文件小，音质保真度较低。

注意：

请确保你在该方法中指定的路径存在并且可写。
该接口需在 joinChannel 之后调用。如果调用 leaveChannel 时还在录音，录音会自动停止。
为保证录音效果，当 sampleRate 设为 44.1 kHz 或 48 kHz 时，建议将 quality 设为 Medium 或 High 。

参数

filePath

录音文件在本地保存的绝对路径，需精确到文件名及格式。例如：C:\music\audio.aac。

注意：请确保你指定的路径存在并且可写。

sampleRate

录音采样率（Hz），可以设为以下值：

16000
32000（默认）
44100
48000

quality

录音音质。详见 AudioRecordingQuality 。

startAudioRecordingWithConfig

开始客户端录音。

Future<void> startAudioRecordingWithConfig(
      AudioRecordingConfiguration config);

声网 SDK 支持通话过程中在客户端进行录音。调用该方法后，你可以录制频道内用户的音频，并得到一个录音文件。录音文件格式可以为:

WAV: 音质保真度较高，文件较大。例如，采样率为 32000 Hz，录音时长为 10 分钟的文件大小约为 73 M。
AAC: 音质保真度较低，文件较小。例如，采样率为 32000 Hz，录音音质为 Medium，录音时长为 10 分钟的文件大小约为 2 M。

用户离开频道后，录音会自动停止。

注意：该方法需要在加入频道后调用。

参数

config: 录音配置。详见 AudioRecordingConfiguration。

startChannelMediaRelay

开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。

Future<void> startChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);

成功调用该方法后，SDK 会触发 channelMediaRelayStateChanged 和 channelMediaRelayEvent 回调，并在回调中报告当前的跨频道媒体流转发状态和事件。

如果 channelMediaRelayStateChanged 回调报告 Running (2) 和 None (0)，且 channelMediaRelayEvent 回调报告 SentToDestinationChannel (4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
如果 channelMediaRelayStateChanged 回调报告 Failure (3)，则表示跨频道媒体流转发出现异常。

注意：

请在成功加入频道后调用该方法。
在直播场景中，只有角色为主播的用户才能调用该方法。
成功调用该方法后，若你想再次调用该方法，必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
跨频道媒体流转发功能需要联系技术支持开通。
该功能不支持 String 型 UID。

参数

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

startEchoTest

开始语音通话回路测试。

  Future<void> startEchoTest(
      {int? intervalInSeconds, EchoTestConfiguration? config});

该方法启动语音通话测试，目的是测试系统的音频设备（耳麦、扬声器等）和网络连接是否正常。在测试过程中，用户先说一段话，声音会在设置的时间间隔（单位为秒）后回放出来。如果用户能正常听到自己刚才说的话，就表示系统音频设备和网络连接都是正常的。

注意：

请在加入频道前调用该方法。
调用 startEchoTest 后必须调用 stopEchoTest 以结束测试，否则不能进行下一次回声测试，也无法加入频道。
直播场景下，该方法仅能由用户角色为主播的用户调用。

参数

intervalInSeconds: 设置返回语音通话回路测试结果的时间间隔，取值范围为 [2,10]，单位为秒，默认为 10 秒。

startLastmileProbeTest

开始通话前网络质量探测。

Future<void> startLastmileProbeTest(LastmileProbeConfig config);

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

启用该方法后，SDK 会依次返回如下 2 个回调：

lastmileQuality，视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量，更贴近用户的主观感受。
lastmileProbeResult，视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量，更加客观。

该方法主要用于以下两种场景：

用户加入频道前，可以调用该方法判断和预测目前的上行网络质量是否足够好。
直播场景下，当用户角色想由观众切换为主播时，可以调用该方法判断和预测目前的上行网络质量是否足够好。

注意：

该方法会消耗一定的网络流量，影响通话质量，因此我们建议不要和 enableLastmileTest 同时使用。
调用该方法后，在收到 lastmileQuality 和 lastmileProbeResult 回调之前请不要调用其他方法，否则可能会由于 API 操作过于频繁导致此方法无法执行。
在直播场景中，如果本地用户为主播，请勿加入频道后调用该方法。

参数

config: Last mile 网络探测配置，详见 LastmileProbeConfig。

startPreview

开启视频预览。

Future<void> startPreview();

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

调用 enableVideo 开启视频功能。

注意：

本地预览默认开启镜像功能。
启用了本地视频预览后，如果调用 leaveChannel退出频道，本地预览依然处于启动状态，如需要关闭本地预览，需要调用 stopPreview。

startScreenCaptureMobile

开始屏幕共享（仅支持 Android 和 iOS）。

Future<void> startScreenCaptureMobile(ScreenCaptureParameters2 parameters);

对于 Android 平台，屏幕共享时，请确保：

用户已授予应用屏幕采集权限，否则 SDK 会触发 localVideoStateChanged 回调并报告错误码 ScreenCapturePermissionDenied(16)。
Android API 级别不低于 21，否则方法调用失败并返回错误码 ScreenCaptureSystemNotSupported(2)。
如需在屏幕共享时采集系统音频，你还需确保 Android API 级别不低于 29，否则 SDK 会报告错误码 ScreenCaptureSystemAudioNotSupported(3)。

对于 iOS 平台，屏幕共享 Extension 进程开启、结束、异常退出时，SDK 会相应地触发 localVideoStateChanged 回调并分别报告 ExtensionCaptureStarted(13)、ExtensionCaptureStoped(14)、ExtensionCaptureDisconnected(15)。

注意：

请在加入频道后调用该方法。
屏幕共享流的计费以 ScreenVideoParameters 中 dimensions 的值为准：当你未传值时，以 1280 × 720 计费；当你传值时，以你传入的值计费。详细的计费规则请参考实时音视频计费。
对于 Android 平台，你需要注意：
- 在 Android 9 及之后版本上，为避免应用退后台后被系统杀死，声网建议你在 /app/Manifests/AndroidManifest.xml 文件中添加前台服务权限：android.permission.FOREGROUND_SERVICE。
- 因性能限制，屏幕共享不支持 Android TV。
- 因系统限制，使用华为手机进行屏幕共享时，为避免崩溃，请不要在共享过程中调节屏幕共享流的视频编码分辨率。
对于 iOS 平台，你需要注意：
- 屏幕共享仅适用于 iOS 11 及以上。
- 该功能对设备性能要求较高，声网推荐你在 iPhone X 及之后机型上使用。
- 如果你使用音频自采集而非 SDK 采集音频，为避免应用退后台后屏幕共享停止，声网建议你对应用添加保活处理逻辑。

参数

parameters: 屏幕共享的配置。详见 ScreenCaptureParameters2。

startScreenCaptureByDisplayId

通过屏幕 ID 共享屏幕。

Future<void> startScreenCaptureByDisplayId(int displayId,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。

注意：

该方法仅适用于 macOS 和 Windows。
该方法需要在加入频道后调用。

参数

displayId: 指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。
regionRect: （可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界，则只共享屏幕视窗内的内容；如果宽或高为 0，则共享整个屏幕。
captureParams: 屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

startScreenCaptureByScreenRect

通过指定区域共享屏幕。

Future<void> startScreenCaptureByScreenRect(Rectangle screenRect,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

弃用：: 该方法已废弃。请改用 startScreenCaptureByDisplayId。如果你需要在设备外接其他显示屏的情况下开启屏幕共享，声网强烈建议你使用 startScreenCaptureByDisplayId。

共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。

注意：

该方法仅适用于 Windows 平台。
该方法需要在加入频道后调用。

参数

screenRect: 指定待共享的屏幕相对于虚拟屏的位置。
regionRect: （可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界，则只共享屏幕内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕。
captureParams: 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

startScreenCaptureByWindowId

通过窗口 ID 共享窗口。

Future<void> startScreenCaptureByWindowId(int windowId,
      [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);

共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。

注意：

该方法需要在加入频道后调用。
该方法仅适用于 macOS 和 Windows 平台。

参数

windowId: 指定待共享的窗口 ID。
regionRect: （可选）指定待共享区域相对于整个屏幕的位置。如不填，则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了窗口的边界，则只共享窗口内的内容；如果宽或高为 0，则共享整个窗口。
captureParams: 屏幕共享的参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

startRtmpStreamWithoutTranscoding

开始非转码推流。

Future<void> startRtmpStreamWithoutTranscoding(String url);

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

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

注意：

请确保已开通旁路推流服务，详见进阶功能旁路推流中的前提条件。
请在加入频道后调用该方法。
只有直播场景下的主播才能调用该方法。
调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

参数

url: 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

startRtmpStreamWithTranscoding

开始旁路推流并设置转码属性。

Future<void> startRtmpStreamWithTranscoding(LiveTranscoding transcoding);

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

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

注意：

请确保已开通旁路推流服务，详见进阶功能旁路推流中的前提条件。
请在加入频道后调用该方法。
只有直播场景下的主播才能调用该方法。
调用该方法推流失败后，如果你想要重新推流，那么请你务必先调用 stopRtmpStream，再调用该方法重推，否则 SDK 会返回与上次推流失败时一样的错误码。

参数

url: 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
transcoding: 旁路推流的转码属性，详见 LiveTranscoding 类。

stopAllEffects

停止播放所有音效文件。

Future<void> stopAllEffects();

stopAudioMixing

停止播放音乐文件。

Future<void> stopAudioMixing();

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

stopAudioRecording

停止客户端录音。

Future<void> stopAudioRecording();

如果你调用了 startAudioRecordingWithConfig 开始录音，可以调用该方法停止录音。

注：离开频道时录音会自动停止。

stopChannelMediaRelay

停止跨频道媒体流转发。一旦停止，主播会退出所有目标频道。

Future<void> stopChannelMediaRelay();

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

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

stopEchoTest

停止语音通话回路测试。

Future<void> stopEchoTest();

stopEffect

停止播放指定音效文件。

Future<void> stopEffect(int soundId);

参数

soundId: 指定音效文件的 ID。每个音效文件均有唯一的 ID。

stopLastmileProbeTest

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

Future<void> stopLastmileProbeTest();

stopPreview

停止视频预览。

Future<void> stopPreview();

stopRtmpStream

结束旁路推流。

Future<void> stopRtmpStream(String url);

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

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

参数

url: 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。

stopScreenCapture

停止屏幕共享。

Future<void> stopScreenCapture();

switchCamera

切换前置/后置摄像头。

Future<void> switchCamera();

该方法需要在相机启动（如通过调用 startPreview 或 joinChannel 实现）后调用。

switchChannel

快速切换直播频道，并设置是否自动订阅音频流或视频流。

Future<void> switchChannel(String? token, String channelName,
      [ChannelMediaOptions? options]);

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

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

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

参数

token

动态秘钥。

安全要求不高: 将值设为 null。
安全要求高: 将值设置为从你的服务端生成的 Token。如果你的项目已经启用了 App Certificate, 请务必使用 Token。

警告：请确保用于生成 token 的 App ID 和 createWithContext 方法初始化引擎时用的 App ID，以及该方法中设置的频道名和用户名是一致的。

channelName

频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下，填入相同 channelId 的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围（共 89 个字符）:

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

options

频道媒体设置选项。详见 ChannelMediaOptions。

takeSnapshot

获取视频截图。

Future<void> takeSnapshot(String channel, int uid, String filePath);

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

该方法是异步操作，调用返回时 SDK 并没有真正获取截图。

注意：

该方法需要在加入频道后调用。
如果用户的视频经过前处理，例如，添加了水印或美颜，生成的截图会包含前处理效果。

参数

channel

频道名。

uid

用户 ID。如果要对本地用户的视频截图，uid 设为 0。

filePath

截图的本地保存路径，需精确到文件名及格式，例如：

Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg
iOS: /App Sandbox/Library/Caches/example.jpg
macOS: ～/Library/Logs/example.jpg
Android: /storage/emulated/0/Android/data/<package name>/files/example.jpg

请确保目录存在且可写。

unloadEffect

从内存释放某个预加载的音效文件。

Future<void> unloadEffect(int soundId);

参数

soundId: 指定音效文件的 ID。每个音效文件均有唯一的 ID。

unregisterMediaMetadataObserver

取消注册媒体 metadata 观测器。

Future<void> unregisterMediaMetadataObserver();

updateChannelMediaRelay

更新媒体流转发的频道。

Future<void> updateChannelMediaRelay(
      ChannelMediaRelayConfiguration channelMediaRelayConfiguration);

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

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

注意：请在 startChannelMediaRelay 方法后调用该方法，更新媒体流转发的频道。

参数

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

updateRtmpTranscoding

更新旁路推流转码属性。

Future<void> updateRtmpTranscoding(LiveTranscoding transcoding);

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

参数

transcoding: 旁路推流的转码属性，详见 LiveTranscoding 类。

updateScreenCaptureParameters

更新屏幕共享的参数配置。

Future<void> updateScreenCaptureParameters(
      ScreenCaptureParameters captureParams);

参数

captureParams: 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080，即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。

updateScreenCaptureParametersMobile

更新屏幕共享的参数配置（仅支持 Android 和 iOS）。

  Future<void> updateScreenCaptureParametersMobile(
      ScreenCaptureParameters2 parameters);

参数

parameters: 屏幕共享的编码参数配置。详见 ScreenCaptureParameters2。

updateScreenCaptureRegion

更新屏幕共享区域。

Future<void> updateScreenCaptureRegion(Rectangle regionRect);

参数

regionRect: 待共享区域相对于整个屏幕或窗口的位置，如不填，则表示共享整个屏幕或窗口。详见 Rectangle。如果设置的共享区域超出了屏幕或窗口的边界，则只共享屏幕或窗口内的内容；如果将 width 或 height 设为 0 ，则共享整个屏幕或窗口。

uploadLogFile

上传所有本地的 SDK 日志文件。

Future<String?> uploadLogFile();

自从: v3.3.0

将客户端的所有日志文件上传至声网服务器。成功调用该方法后，SDK 会触发 uploadLogResult 回调报告日志文件是否成功上传至声网服务器。

为了方便排查问题，声网推荐你将 uploadLogFile 方法与应用的 UI 元素绑定，在出现质量问题时提示用户上传日志。

返回值

方法调用成功: 返回请求 ID。该请求 ID 与 uploadLogResult 回调中的 requestId 一致。你可以通过 requestId 将特定的上传和回调对应起来。
方法调用失败: 返回 null。可能是因为调用频率超出限制。