IAgoraRtcEngine - 互动直播 (Legacy) - 文档中心

InitEventHandler

添加主回调事件。

public abstract void InitEventHandler(IAgoraRtcEngineEventHandler engineEventHandler);

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

参数

engineEventHandler: 待添加的回调事件。详见 IAgoraRtcEngineEventHandler。

AddPublishStreamUrl

增加旁路推流地址。

public abstract int AddPublishStreamUrl(string url, bool transcodingEnabled);

弃用：: 该方法已废弃。

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

注意：

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

参数

url

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

transcodingEnabled

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

true: 转码。
false: 不转码。

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2: 参数无效，一般是 URL 为空或是长度为 0 的字符串。
- -7: 推流时未初始化引擎。

AddVideoWatermark [1/2]

添加本地视频水印。

public abstract int AddVideoWatermark(RtcImage watermark);

弃用：: 该方法已废弃，请使用 AddVideoWatermark [2/2] 作为替代。

该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上，同一直播频道中的用户，旁路推流观众，甚至采集设备都能看到或采集到该水印图片。如果你仅仅希望在旁路直播推流中添加水印，请参考 SetLiveTranscoding 中描述的用法。

注意：

在本地直播和旁路推流中，URL 的定义不同。本地直播中，URL 指本地直播视频上图片的本地绝对/相对路径；旁路推流中，URL 指旁路推流视频上图片的地址。
待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致，SDK 会对 PNG 图片进行裁剪，以与设置相符。
声网当前只支持在直播视频流中添加一个水印，后添加的水印会替换掉之前添加的水印。

参数

watermark: 待添加在本地直播推流中的水印图片： RtcImage 。

返回值

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

AddVideoWatermark [2/2]

添加本地视频水印。

public abstract int AddVideoWatermark(string watermarkUrl, WatermarkOptions options);

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

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

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

注意：

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

参数

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

返回值

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

AdjustAudioMixingPlayoutVolume

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

public abstract int AdjustAudioMixingPlayoutVolume(int volume);

注意：你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(PLAY) 回调后调用该方法。

参数

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

返回值

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

AdjustAudioMixingPublishVolume

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

public abstract int AdjustAudioMixingPublishVolume(int volume);

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

注意：

你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(PLAY) 回调后调用该方法。

参数

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

返回值

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

AdjustAudioMixingVolume

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

public abstract int AdjustAudioMixingVolume(int volume);

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

注意：

该方法需要在 StartAudioMixing [1/2] 后调用。

参数

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

返回值

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

AdjustLoopbackRecordingSignalVolume

调节声卡采集信号音量。

public abstract int AdjustLoopbackRecordingSignalVolume(int volume);

调用 EnableLoopbackRecording 开启声卡采集后，你可以调用该方法调节声卡采集的信号音量。

参数

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

返回值

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

AdjustPlaybackSignalVolume

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

public abstract int AdjustPlaybackSignalVolume(int volume);

注意：

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

参数

volume

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

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

返回值

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

AdjustRecordingSignalVolume

调节音频采集信号音量。

public abstract int AdjustRecordingSignalVolume(int volume);

注意：

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

参数

volume

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

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

返回值

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

AdjustUserPlaybackSignalVolume

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

public abstract int AdjustUserPlaybackSignalVolume(uint uid, int volume);

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

注意：

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

参数

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

返回值

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

CreateChannel

创建并获取一个 IAgoraRtcChannel 对象。

public abstract IAgoraRtcChannel CreateChannel(string channelId);

你可以多次调用该方法，创建多个 IAgoraRtcChannel 对象，再调用各 IAgoraRtcChannel 对象中的 JoinChannel 方法，实现同时加入多个频道。

加入多个频道后，你可以同时订阅各个频道的音、视频流；但是同一时间只能在一个频道发布一路音、视频流。

参数

channelId

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

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

注意：

参数没有默认值，请确保对参数设值。
请勿将该参数设为空字符 ""，否则 SDK 会返回 ERR_REFUSED(5)。

返回值

方法调用成功，返回 IAgoraRtcChannel 对象。
方法调用失败，返回 NULL。

Complain

投诉通话质量。

public abstract int Complain(string callId, string description);

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

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2(ERR_INVALID_ARGUMENT)。
- -3(ERR_NOT_READY)。

Initialize

public abstract int Initialize(RtcEngineContext context);

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

注意：

SDK 只支持每个 app 创建一个 IAgoraRtcEngine 实例。

参数

context: IAgoraRtcEngine 实例的配置。详见 RtcEngineContext。

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误（未明确归类）。
- -2(ERR_INVALID_ARGUMENT): 设置了无效的参数。
- -7(ERR_NOT_INITIALIZED): SDK 初始化失败。
- -22(ERR_RESOURCE_LIMITED): 资源申请失败。当 app 占用资源过多，或系统资源耗尽时，SDK 分配资源失败，会返回该错误。
- -101(ERR_INVALID_ID): App ID 无效。

CreateAgoraRtcEngine

创建 IAgoraRtcEngine 对象并返回指针。

public static IAgoraRtcEngine CreateAgoraRtcEngine(AgoraEngineType engineType = AgoraEngineType.MainProcess)

SDK 默认使用主进程创建 IAgoraRtcEngine。如果场景中涉及同时发送摄像头和桌面共享两路视频流，可以调用该方法分别创建 MainProcess 和 SubProcess 两个 IAgoraRtcEngine 对象。其中主进程为集成了 IAgoraRtcEngine 的进程，子进程为 AgoraRtcScreenSharing.exe。

参数

engineType: AgoraRtcEngine 的进程类型，详见 AgoraEngineType。

返回值

方法调用成功，返回一个 IAgoraRtcEngine 对象。
方法调用失败，返回错误码。

CreateDataStream [1/2]

创建数据流。

public abstract int CreateDataStream(bool reliable, bool ordered);

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

注意：

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

参数

reliable

该数据流是否可靠：

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

ordered

该数据流是否有序：

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

返回值

创建的数据流的 ID：方法调用成功。
< 0：方法调用失败。你可以参考错误码和警告码进行问题排查。

CreateDataStream [2/2]

创建数据流。

public abstract int CreateDataStream(DataStreamConfig config);

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

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

参数

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

返回值

创建的数据流的 ID：方法调用成功。
< 0：方法调用失败。你可以参考错误码和警告码进行问题排查。

DisableAudio

关闭音频模块。

public abstract int DisableAudio();

注意：

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

返回值

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

DisableVideo

关闭视频模块。

public abstract int DisableVideo();

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

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

注意：

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

返回值

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

EnableAudio

启用音频模块。

public abstract int EnableAudio();

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

注意：

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

返回值

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

EnableAudioVolumeIndication

启用用户音量提示。

public abstract int EnableAudioVolumeIndication(int interval, int smooth, bool reportVad);

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

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

参数

interval

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

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

smooth

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

reportVad

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

返回值

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

EnableContentInspect

开启/关闭视频截图上传

public abstract int EnableContentInspect(bool enabled, ContentInspectConfig config);

自从: v3.5.2

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

参数

enabled

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

true：开启。
false：关闭。

config

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

返回值

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

EnableDeepLearningDenoise

开启或关闭 AI 降噪模式。

public abstract int EnableDeepLearningDenoise(bool enable);

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

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

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

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

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

注意：

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

参数

enable

是否开启 AI 降噪模式:

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -157(ERR_MODULE_NOT_FOUND): 未集成用于 AI 降噪的动态库。

EnableDualStreamMode

开关双流模式。

public abstract int EnableDualStreamMode(bool enabled);

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

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

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

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

参数

enabled

是否开启双流模式。

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

返回值

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

EnableEncryption

开启或关闭内置加密。

public abstract int EnableEncryption(bool enabled, EncryptionConfig config);

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

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

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

参数

enabled

是否开启内置加密：

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

config

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

返回值

0: 方法调用成功
< 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 IAgoraRtcEngine 对象并完成初始化。

EnableLastmileTest

启用网络测试。

public abstract int EnableLastmileTest();

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

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

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

注意：

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

返回值

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

EnableLocalAudio

开关本地音频采集。

public abstract int EnableLocalAudio(bool enabled);

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

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

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

注意：

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

参数

enabled

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

返回值

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

EnableLocalVideo

开关本地视频采集。

public abstract int EnableLocalVideo(bool enabled);

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

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

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

注意：

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

参数

enabled

是否开启本地视频采集。

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

返回值

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

EnableLoopbackRecording

开启声卡采集。

public abstract int EnableLoopbackRecording(bool enabled, string deviceName);

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

注意：

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

参数

enabled

是否开启声卡采集:

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

deviceName

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

返回值

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

EnableSoundPositionIndication

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

public abstract int EnableSoundPositionIndication(bool enabled);

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

参数

enabled

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

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

返回值

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

EnableVideo

启用视频模块。

public abstract int EnableVideo();

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

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

注意：

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

返回值

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

EnableVirtualBackground

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

public abstract int EnableVirtualBackground(bool enabled, VirtualBackgroundSource backgroundSource);

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

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

注意：

调用该方法前，请确保你已集成相应的动态库。
该方法需要在 EnableVideo 后调用。
该功能对设备性能要求较高，声网推荐你在搭载如下芯片的设备上使用：
- CPU 为 i5 及更好的设备
声网建议你在满足如下条件的场景中使用该功能：
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中，物件较少，用户的人像为半身人像且基本无遮挡，背景色较单一且与用户着装颜色不同。

参数

enabled

是否开启虚拟背景：

true: 开启。
false: 关闭。

backgroundSource

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

返回值

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

EnableWebSdkInteroperability

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

public abstract int EnableWebSdkInteroperability(bool enabled);

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

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

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

参数

enabled

是否打开与 Web SDK 的互通：

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

返回值

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

EnableWirelessAccelerate

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

public abstract int EnableWirelessAccelerate(bool enabled);

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

当路由器提供加速服务后，SDK 会周期性触发 OnWlAccStats 回调，报告 Wi-Fi 连接优化数据，并在 Wi-Fi 连接质量不佳时触发 OnWlAccMessage 回调，报告 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

获取指定音频文件信息。

public abstract int GetAudioFileInfo(string filePath);

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

注意：

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

参数

filePath

文件路径：

Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.

返回值

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

GetAudioMixingCurrentPosition

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

public abstract int GetAudioMixingCurrentPosition();

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

注意：你需要在调用 StartAudioMixing [1/2] 并收到 OnAudioMixingStateChanged(PLAY) 回调后调用该方法。

返回值

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

GetAudioMixingDuration

获取音乐文件总时长。

public abstract int GetAudioMixingDuration();

弃用：: 自 v3.4.0 起废弃。请改用 GetAudioFileInfo。

该方法获取音乐文件总时长，单位为毫秒。

注意：

你需要在调用 StartAudioMixing [1/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

返回值

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

GetAudioMixingPlayoutVolume

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

public abstract int GetAudioMixingPlayoutVolume();

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

注意：

请在频道内调用该方法。

返回值

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

GetAudioMixingPublishVolume

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

public abstract int GetAudioMixingPublishVolume();

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

返回值

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

GetAudioTrackCount

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

public abstract int GetAudioTrackCount();

注：

你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法支持的音频文件格式见声网 RTC SDK 支持播放哪些格式的音频文件。

返回值

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

GetCallId

获取通话 ID。

public abstract string GetCallId();

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

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

返回值

方法调用成功则返回当前的通话 ID。
方法调用失败则返回空字符串。

GetConnectionState

获取当前网络连接状态。

public abstract CONNECTION_STATE_TYPE GetConnectionState();

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

返回值

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

GetEffectCurrentPosition

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

public abstract int GetEffectCurrentPosition(int soundId);

注意：该方法需要在 PlayEffect [2/2] 后调用。

参数

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

返回值

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

GetEffectDuration

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

public abstract int GetEffectDuration(string filePath);

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

参数

filePath

文件路径：

Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.

返回值

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

GetEffectsVolume

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

public abstract int GetEffectsVolume();

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

注意：该方法需要在 PlayEffect [2/2] 后调用。

返回值

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

GetUserInfoByUid

通过 UID 获取用户信息。

public abstract int GetUserInfoByUid(uint uid, out UserInfo userInfo);

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

参数

uid: 用户 ID。
userInfo: 标识用户的 UserInfo 对象。

返回值

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

GetUserInfoByUserAccount

通过 User Account 获取用户信息。

public abstract int GetUserInfoByUserAccount(string userAccount, out UserInfo userInfo);

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

参数

account: 用户 User Account。
userInfo: 标识用户的 UserInfo 对象。

返回值

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

JoinChannel [1/2]

加入频道。

public abstract int JoinChannel(string token, string channelId, string info = "", uint uid = 0);

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

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

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

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

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

参数

token

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

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

channelId

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

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

info

(非必选项) 预留参数。

uid

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

返回值

0(ERR_OK) 方法调用成功。
< 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
  - 已经创建了一个同名的 IAgoraRtcChannel 频道。
  - 已经通过 IAgoraRtcChannel 加入了一个频道，并在该 IAgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用该方法。请确认在调用 API 之前已经创建 IAgoraRtcEngine 对象并完成初始化。
- -17(ERR_JOIN_CHANNEL_REJECTED): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IAgoraRtcEngine 频道，当已经加入 IAgoraRtcEngine 频道的用户使用有效的频道名再次调用 IAgoraRtcEngine 类中的加入频道方法时，会返回此错误码。

JoinChannel [2/2]

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

public abstract int JoinChannel(string token, string channelId, string info, uint uid,
            ChannelMediaOptions options);

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

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

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

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

参数

token

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

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

channelId

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

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

info

预留参数。

uid

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

options

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

返回值

0(ERR_OK) 方法调用成功。
< 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
  - 已经创建了一个同名的 IAgoraRtcChannel 频道。
  - 已经通过 IAgoraRtcChannel 加入了一个频道，并在该 IAgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用该方法。请确认在调用 API 之前已经创建 IAgoraRtcEngine 对象并完成初始化。
- -17(ERR_JOIN_CHANNEL_REJECTED): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IAgoraRtcEngine 频道，当已经加入 IAgoraRtcEngine 频道的用户使用有效的频道名再次调用 IAgoraRtcEngine 类中的加入频道方法时，会返回此错误码。

JoinChannelWithUserAccount [1/2]

使用 User Account 加入频道。

public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount);

自从: v2.8.0

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

本地：OnLocalUserRegistered、OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
通信场景下的用户和直播场景下的主播加入频道后，远端会依次触发 OnUserJoined 和 OnUserInfoUpdated 回调。

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

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

参数

token

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

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

channelId

频道名。该参数标识用户进行实时音视频互动的频道。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
空格
"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。
- -17(ERR_JOIN_CHANNEL_REJECTED): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IAgoraRtcEngine 频道，当已经加入 IAgoraRtcEngine 频道的用户使用有效的频道名再次调用 IAgoraRtcEngine 类中的加入频道方法时，会返回此错误码。

JoinChannelWithUserAccount [2/2]

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

public abstract int JoinChannelWithUserAccount(string token, string channelId, string userAccount,
            ChannelMediaOptions options);

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

本地：OnLocalUserRegistered、OnJoinChannelSuccess 和 OnConnectionStateChanged 回调。
远端：通信场景下的用户和直播场景下的主播加入频道后，远端会分别触发 OnUserJoined 和 OnUserInfoUpdated 回调。

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

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

参数

token

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

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

channelId

频道名。该参数标识用户进行实时音视频互动的频道。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 。

返回值

0(ERR_OK) 方法调用成功。
< 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败，请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因：
  - 已经创建了一个同名的 IAgoraRtcChannel 频道。
  - 已经通过 IAgoraRtcChannel 加入了一个频道，并在该 IAgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化，就调用该方法。请确认在调用 API 之前已经创建 IAgoraRtcEngine 对象并完成初始化。
- -17(ERR_JOIN_CHANNEL_REJECTED): 加入频道被拒绝。由于 SDK 仅支持用户同一时间加入一个 IAgoraRtcEngine 频道，当已经加入 IAgoraRtcEngine 频道的用户使用有效的频道名再次调用 IAgoraRtcEngine 类中的加入频道方法时，会返回此错误码。

LeaveChannel

离开频道。

public abstract int LeaveChannel();

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

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

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

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

注意：

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

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误（未明确归类）。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

MuteAllRemoteAudioStreams

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

public abstract int MuteAllRemoteAudioStreams(bool mute);

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

注意：

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

参数

mute

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

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

返回值

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

MuteAllRemoteVideoStreams

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

public abstract int MuteAllRemoteVideoStreams(bool mute);

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

注意：

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

参数

mute

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

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

返回值

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

MuteLocalAudioStream

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

public abstract int MuteLocalAudioStream(bool mute);

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

注意：

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

参数

mute

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

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

返回值

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

MuteLocalVideoStream

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

public abstract int MuteLocalVideoStream(bool mute);

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

注意：

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

参数

mute

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

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

返回值

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

MuteRemoteAudioStream

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

public abstract int MuteRemoteAudioStream(uint userId, bool mute);

注意：

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

参数

userId

指定用户的用户 ID。

mute

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

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

返回值

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

MuteRemoteVideoStream

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

public abstract int MuteRemoteVideoStream(uint userId, bool mute);

注意：

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

参数

userId

指定用户的用户 ID。

mute

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

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

返回值

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

PauseAllChannelMediaRelay

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

public abstract int PauseAllChannelMediaRelay();

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

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

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

返回值

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

PauseEffect

暂停音效文件播放。

public abstract int PauseEffect(int soundId);

参数

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

返回值

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

PlayEffect [1/2]

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

public abstract int PlayEffect(int soundId, string filePath, int loopCount, double pitch = 1.0,
            double pan = 0.0, int gain = 100, bool publish = false);

弃用：: 自 v3.4.0 废弃，请改用 PlayEffect [2/2] 方法。

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

注意：

该方法需要在加入频道后调用。
支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP等。详见支持的媒体格式。

参数

soundId

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

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

filePath

注意：如果你已通过 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: 不将音效发布至远端。只有本地用户能听到音效。

返回值

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

PlayEffect [2/2]

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

public abstract int PlayEffect(int soundId, string filePath, int loopCount, int startPos,
    double pitch = 1.0, double pan = 0.0, int gain = 100, bool publish = false);

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

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

参数

soundId

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

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

filePath

播放文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如 C:\music\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

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

返回值

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

PullAudioFrame

拉取远端音频数据。

public abstract int PullAudioFrame(AudioFrame frame);

使用该方法前，你需要调用 SetExternalAudioSink 通知 app 开启并设置外部渲染。

调用该方法后，app 会采取主动拉取的方式获取远端已解码和混音后的音频数据，用于音频播放。

注意：

该方法需要在加入频道后调用。
开启外部音频渲染后，app 将无法从 OnPlaybackAudioFrame 回调中获得数据。
该方法和 OnPlaybackAudioFrame 回调相比，区别在于：
- SDK 通过 OnPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时，可能会导致音频播放抖动。
- 调用该方法后 app 会主动拉取音频数据。通过设置音频数据，SDK 可以调整缓存，帮助 app 处理延时，从而有效避免音频播放抖动。

参数

frame: 指向 AudioFrame 的指针。

返回值

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

PushAudioFrame

推送外部音频帧。

public abstract int PushAudioFrame(MEDIA_SOURCE_TYPE type, AudioFrame frame, bool wrap);

参数

type

音频采集设备类型。详见 MEDIA_SOURCE_TYPE。

frame

外部音频帧。详见 AudioFrame。

wrap

设置是否占位使用。声网建议用户使用默认值。

true: 占位使用；
false:（默认）不占位使用。

返回值

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

PushVideoFrame

推送外部原始视频帧到 SDK。

public abstract int PushVideoFrame(ExternalVideoFrame frame);

调用 SetExternalVideoSource 方法，设置 enabled 参数为 true、encodedFrame 参数为 false 后，你可以调用本方法将未编码的外部视频帧推送到 SDK。

注意：通信场景下，不支持 Texture 格式的视频数据。

参数

frame: 待推送的视频帧。详见 ExternalVideoFrame。

返回值

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

PreloadEffect

将音效文件加载至内存。

public abstract int PreloadEffect(int soundId, string filePath);

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

注意：

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

参数

soundId

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

filePath

文件路径：

Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.

返回值

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

Rate

给通话评分。

public abstract int Rate(string callId, int rating, string description = "");

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

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2(ERR_INVALID_ARGUMENT)。
- -3(ERR_NOT_READY)。

RegisterAudioFrameObserver

注册语音观测器对象。

public abstract void RegisterAudioFrameObserver(IAgoraRtcAudioFrameObserver audioFrameObserver);

该方法用于注册语音观测器对象，即注册回调。当需要 SDK 给出 OnRecordAudioFrame 或 OnPlaybackAudioFrame 回调时，需要使用该方法注册回调。

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

参数

audioFrameObserver: 接口对象实例。详见 IAgoraRtcAudioFrameObserver。如果传入 NULL，则表示取消注册，声网建议在收到 OnLeaveChannel 后调用，来释放语音观测器对象。

返回值

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

RegisterLocalUserAccount

注册本地用户 User Account。

public abstract int RegisterLocalUserAccount(string appId, string userAccount);

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

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

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

先调用 RegisterLocalUserAccount 方法注册 Account，再调用 JoinChannelWithUserAccount [2/2] 方法加入频道。
直接调用 JoinChannelWithUserAccount [2/2] 方法加入频道。

两种方式的区别在于，提前调用 RegisterLocalUserAccount，可以缩短使用 JoinChannelWithUserAccount [2/2] 进入频道的时间。

注意：

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
空格
"!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","

返回值

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

RegisterMediaMetadataObserver

注册媒体 metadata 观测器用于接收或发送 metadata。

public abstract int RegisterMediaMetadataObserver(METADATA_TYPE type);

注意：

请在 JoinChannel [2/2] 前调用该方法。
该方法仅适用于直播场景。

参数

type: 用户希望在观测器中使用的 METADATA 类型。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。

返回值

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

RegisterPacketObserver

注册数据包观测器。

public abstract int RegisterPacketObserver(IPacketObserver observer);

该方法注册数据包观测器 (Packet Observer)。在声网 SDK 发送/接收（语音、视频）网络包时，会回调 IPacketObserver 定义的接口，App 可用此接口对数据做处理，例如加解密。

注意：

处理后发送到网络的包大小不应超过 1200 字节，否则有可能发送失败。
若需调用此方法，需确保接收端和发送端都调用此方法，否则会出现未定义行为（例如音频无声或视频黑屏）。
若在直播场景下使用旁路推流、录制或储存，声网不建议调用此方法。
你需要在加入频道前调用该方法。

参数

observer: IPacketObserver 。

返回值

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

RegisterVideoFrameObserver

注册视频观测器对象。

public abstract void RegisterVideoFrameObserver(IAgoraRtcVideoFrameObserver videoFrameObserver);

你需要在该方法中实现一个 IAgoraRtcVideoFrameObserver 类，并根据场景需要，注册该类的回调。成功注册视频观测器后，SDK 会在捕捉到每个视频帧时，触发你所注册的上述回调。

注意：

在处理回调时，你需要考虑视频帧中 width 和 height 参数的变化，因为观测得到的视频帧可能会随以下情况变化：
- 当网络状况差时，分辨率会阶梯式下降。
- 当用户自行调整分辨率时，回调中报告的分辨率也会变化。
该方法需要在加入频道前调用。

参数

videoFrameObserver: 接口对象实例。如果传入 NULL，则取消注册。详见 IAgoraRtcVideoFrameObserver。

返回值

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

Dispose

销毁 IAgoraRtcEngine、IAgoraRtcAudioPlaybackDeviceManager、 IAgoraRtcAudioRecordingDeviceManager 和 IAgoraRtcVideoDeviceManager 对象。

public abstract void Dispose(bool sync = false);

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

调用该方法后，你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能，你必须依次重新调用 CreateAgoraRtcEngine 和 Initialize 方法创建一个新的 IAgoraRtcEngine 对象。

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

参数

sync

true: 该方法为同步调用。需要等待 IAgoraRtcEngine 资源释放后才能执行其他操作，所以我们建议在子线程中调用该方法，避免主线程阻塞。此外，我们不建议在 SDK 的回调中调用 Dispose，否则由于 SDK 要等待回调返回才能回收相关的对象资源，会造成死锁。SDK 会自动检测这种死锁并转为异步调用，但是检测本身会消耗额外的时间。
false: 该方法为异步调用。不需要等待 IAgoraRtcEngine 资源释放后就能执行其他操作。使用异步调用时要注意，不要在该调用后立即卸载 SDK 动态库，否则可能会因为 SDK 的清理线程还没有退出而崩溃。

RemovePublishStreamUrl

删除旁路推流地址。

public abstract int RemovePublishStreamUrl(string url);

弃用：: 该方法已废弃。

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

注意：

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

参数

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

返回值

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

RenewToken

更新 Token。

public abstract int RenewToken(string token);

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

发生 OnTokenPrivilegeWillExpire 回调时。
OnConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。

参数

token: 新的 Token。

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误（未明确归类）。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

ResumeAllChannelMediaRelay

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

public abstract int ResumeAllChannelMediaRelay();

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

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

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

返回值

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

ResumeAudioMixing

恢复播放音乐文件。

public abstract int ResumeAudioMixing();

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

返回值

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

ResumeEffect

恢复播放指定音效文件。

public abstract int ResumeEffect(int soundId);

参数

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

返回值

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

SendCustomReportMessage

发送自定义上报消息。

public abstract int SendCustomReportMessage(string id, string category, string events, string label, int value);

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

SendMetadata

发送媒体附属信息。

public abstract int SendMetadata(Metadata metadata);

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

参数

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

返回值

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

SendStreamMessage

发送数据流。

public abstract int SendStreamMessage(int streamId, byte[] data);

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

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

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

注意：

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

参数

streamId: 数据流 ID。可以通过 CreateDataStream [2/2] 获取。
data: 待发送的数据。

返回值

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

SelectAudioTrack

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

public abstract int SelectAudioTrack(int index);

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

注：

你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法仅适用于 Android、iOS 和 Windows。
该方法支持的音频文件格式见 Audio Formats。

参数

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

返回值

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

SetAudioEffectParameters

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

public abstract int SetAudioEffectParameters(AUDIO_EFFECT_PRESET preset, int param1, int param2);

详细描述

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

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

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

注意：

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

参数

preset

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

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

param1

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

param2

如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE，你需要将 param2 设置为 0。
如果 preset 设为 PITCH_CORRECTION，则 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#

返回值

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

SetAudioEffectPreset

设置 SDK 预设的人声音效。

public abstract int SetAudioEffectPreset(AUDIO_EFFECT_PRESET preset);

详细描述

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

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

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

注意：

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

参数

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

返回值

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

SetAudioMixingDualMonoMode

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

public abstract int SetAudioMixingDualMonoMode(AUDIO_MIXING_DUAL_MONO_MODE mode);

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

注：

你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
该方法仅适用于双声道的音乐文件。

参数

mode: 声道详情。详见AUDIO_MIXING_DUAL_MONO_MODE。

返回值

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

SetAudioMixingPitch

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

public abstract int SetAudioMixingPitch(int pitch);

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

注意：你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

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

返回值

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

setAudioMixingPlaybackSpeed

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

public abstract int SetAudioMixingPlaybackSpeed(int speed);

你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。

参数

speed

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

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

返回值

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

SetAudioMixingPosition

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

public abstract int SetAudioMixingPosition(int pos);

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

注意：你需要在调用 StartAudioMixing [2/2] 并收到 OnAudioMixingStateChanged(PLAY) 回调后调用该方法。

参数

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

返回值

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

SetAudioProfile

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

public abstract int SetAudioProfile(AUDIO_PROFILE_TYPE profile, AUDIO_SCENARIO_TYPE scenario);

注意：

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

参数

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

返回值

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

SetAVSyncSource

设置发流端音画同步。

public abstract int SetAVSyncSource(string channelId, uint uid);

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

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

参数

channelId: 标识音频发送端所在频道的频道名。
uid: 音频发送端的用户 ID。

SetBeautyEffectOptions

设置美颜效果选项。

public abstract int SetBeautyEffectOptions(bool enabled, BeautyOptions options);

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

注意：

该方法需要在 EnableVideo 后调用。

参数

enabled

是否开启美颜功能：

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

options

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

返回值

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

SetCameraCapturerConfiguration

设置摄像头采集配置。

public abstract int SetCameraCapturerConfiguration(CameraCapturerConfiguration config);

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

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

注意：

请在启动摄像头之前调用该方法，如 JoinChannel [2/2]、EnableVideo 或者 EnableLocalVideo 之前。

参数

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

返回值

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

setCameraTorchOn

设置是否打开闪光灯。

public abstract int SetCameraTorchOn(bool isOn);

注意：

请在启动摄像头之前调用该方法，如 JoinChannel [2/2]、EnableVideo 或者 EnableLocalVideo 之前。

参数

isOn

是否打开闪光灯：

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

返回值

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

SetChannelProfile

设置频道场景。

public abstract int SetChannelProfile(CHANNEL_PROFILE_TYPE profile);

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

注意：

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

参数

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

返回值

0(ERR_OK) 方法调用成功。
< 0 方法调用失败。
- -2 (ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。

SetClientRole [1/2]

设置用户角色。

public abstract int SetClientRole(CLIENT_ROLE_TYPE role);

在加入频道前和加入频道后均可调用该方法设置用户角色。

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

调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布状态。
远端会触发 OnUserJoined 或 OnUserOffline(USER_OFFLINE_BECOME_AUDIENCE) 回调。

注意：该方法仅在频道场景为直播（SetChannelProfile 中 profile 设为 CHANNEL_PROFILE_LIVE_BROADCASTING）时生效。

参数

role: 用户角色。详见 CLIENT_ROLE_TYPE。

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -7: SDK 尚未初始化。

SetClientRole [2/2]

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

public abstract int SetClientRole(CLIENT_ROLE_TYPE role, ClientRoleOptions options);

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

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

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

调用 MuteLocalAudioStream 和 MuteLocalVideoStream 修改发布状态。
本地触发 OnClientRoleChanged 回调。
远端触发 OnUserJoined 或 OnUserOffline 回调。

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

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。

SetCloudProxy

设置声网云代理服务。

public abstract int SetCloudProxy(CLOUD_PROXY_TYPE proxyType);

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

成功连接云代理后，SDK 会触发 OnConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) 回调。

As of v3.6.2, when a user calls this method and then joins a channel successfully, the SDK triggers the OnProxyConnected callback to report the user ID, the proxy type connected, and the time calculated from when the user calling the JoinChannel [1/2] method to the callback is triggered.

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

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

注意：

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

参数

proxyType

云代理类型，详见 CLOUD_PROXY_TYPE。

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -2: 传入的参数无效。
- -7: SDK 尚未初始化。

SetColorEnhanceOptions

设置色彩增强功能。

public abstract int SetColorEnhanceOptions(bool enabled, ColorEnhanceOptions options);

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

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

注意：

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

参数

enabled

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

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

options

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

SetDefaultMuteAllRemoteAudioStreams

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

public abstract int SetDefaultMuteAllRemoteAudioStreams(bool mute);

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

注意：

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

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

参数

mute

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

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

返回值

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

SetDefaultMuteAllRemoteVideoStreams

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

public abstract int SetDefaultMuteAllRemoteVideoStreams(bool mute);

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

注意：

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

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

参数

mute

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

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

返回值

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

SetEffectPosition

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

public abstract int SetEffectPosition(int soundId, int pos);

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

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

参数

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

返回值

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

SetEffectsVolume

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

public abstract int SetEffectsVolume(int volume);

注意：该方法需要在 PlayEffect [2/2] 后调用。

参数

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

返回值

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

SetEncryptionMode

启用内置的加密方案。

public abstract int SetEncryptionMode(string 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"。

返回值

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

SetEncryptionSecret

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

public abstract int SetEncryptionSecret(string secret);

弃用：: 请改用 EnableEncryption 方法。

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

注意：

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

参数

secret: 加密密码。

返回值

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

SetExternalAudioSink

设置外部音频渲染。

public abstract int SetExternalAudioSink(bool enabled, int sampleRate, int channels);

该方法适用于需要自行渲染音频的场景。开启外部音频渲染后，你可以通过调用 PullAudioFrame 方法拉取远端音频数据。 App 可以对拉取到的原始音频数据进行处理后再渲染，获取想要的音频效果。

注意：

开启外部音频渲染后，App 会无法从 OnPlaybackAudioFrame 回调中获得数据。
该方法需要在加入频道前调用。

参数

enabled

true: 开启外部音频渲染。
false: （默认）关闭外部音频渲染。

sampleRate

外部音频渲染的采样率 (Hz)，可设置为 16000，32000，44100 或 48000。

channels

外部音频渲染的通道数，可设置为 1 或 2:

1: 单声道
2: 双声道

返回值

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

SetExternalAudioSourceVolume

设置指定位置的外部音频帧音量。

public abstract int SetExternalAudioSourceVolume(int sourcePos, int volume);

你可以多次调用该方法，设置不同位置的外部音频帧音量。音量设置对被推送到指定位置的所有外部音频帧都有效。

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

参数

sourcePos

外部音频帧的推送位置：

0: 本地播放之前的位置。如果你需要在本地播放外部音频帧，请设置该位置。
1: 音频采集之后、前处理之前的位置。如果你需要 SDK 的音频模块处理外部音频帧，请设置该位置。
2: 音频前处理之后、编码之前的位置。如果你无需 SDK 的音频模块处理外部音频帧，请设置该位置。

volume

外部音频帧的音量。取值范围为 [0,100]。默认值为 100，表示原始音量。

返回值

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

SetExternalAudioSource

设置外部音频采集参数。

public abstract int SetExternalAudioSource(bool enabled, int sampleRate, int channels);

请在 JoinChannel [1/2] 和 StartPreview 前调用该方法。

参数

enabled

true: 开启使用外部音频源的功能。
false: （默认）关闭使用外部音频源的功能。

sampleRate

外部音频源的采样率 (Hz)，可设置为 8000，16000，32000，44100 或 48000。

channels

外部音频源的通道数，可设置为 1 或 2:

1: 单声道
2: 双声道

返回值

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

SetExternalVideoSource

配置外部视频源。

public abstract int SetExternalVideoSource(bool enable, bool useTexture = false);

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

参数

enable

是否使用外部视频源：

true：使用外部视频源。
false：（默认）不使用外部视频源。

useTexture

是否使用 Texture 作为输入：

true：使用 texture 作为输入。
false：（默认）不使用 texture 作为输入。

返回值

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

SetHighQualityAudioParameters

设置音频高音质选项。

public abstract int SetHighQualityAudioParameters(bool fullband, bool stereo, bool fullBitrate);

弃用：: 该方法已废弃。声网不建议你使用。如果你希望设置音频高音质选项，请改用 SetAudioProfile 方法。

参数

fullband

全频带编解码器（48 kHz 采样率）, 不兼容 v1.7.4 以前版本。

true：启用全频带编解码器。
false：禁用全频带编解码器。

stereo

立体声编解码器，不兼容 v1.7.4 以前版本。

true：启用立体声编解码器。
false：禁用立体声编解码器。

fullBitrate

高码率模式，建议仅在纯音频模式下使用。

true：启用高码率模式。
false：禁用高码率模式。

返回值

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

SetLiveTranscoding

设置直播推流转码。

public abstract int SetLiveTranscoding(LiveTranscoding transcoding);

弃用：: 该方法已废弃。

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

注意：

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

参数

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

返回

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

SetLocalPublishFallbackOption

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

public abstract int SetLocalPublishFallbackOption(STREAM_FALLBACK_OPTIONS option);

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

注意：

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

参数

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

返回值

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

SetLocalRenderMode [1/2]

设置本地视图显示模式。

public abstract int SetLocalRenderMode(RENDER_MODE_TYPE renderMode);

弃用：: 该方法已废弃，请使用 SetLocalRenderMode [2/2] 作为替代。

该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。

参数

renderMode: 本地视图显示模式。详见 RENDER_MODE_TYPE。

返回值

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

SetLocalRenderMode [2/2]

更新本地视图显示模式。

public abstract int SetLocalRenderMode(RENDER_MODE_TYPE renderMode, VIDEO_MIRROR_MODE_TYPE mirrorMode);

自从: v3.3.0

初始化本地用户视图后，你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面，不影响本地发布视频。

注意：

请在调用 SetupLocalVideo 方法初始化本地视图后，调用该方法。
你可以在通话中多次调用该方法，多次更新本地用户视图的显示模式。

参数

renderMode: 本地视图显示模式。详见 RENDER_MODE_TYPE。
mirrorMode: 本地视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE。

注意：如果你使用前置摄像头，默认启动本地用户视图镜像模式；如果你使用后置摄像头，默认关闭本地视图镜像模式。

返回值

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

SetLocalVideoMirrorMode

设置本地视频镜像。

public abstract int SetLocalVideoMirrorMode(VIDEO_MIRROR_MODE_TYPE mirrorMode);

弃用:: 从 v3.0.0 起废弃。

参数

mirrorMode: 本地视频镜像模式。详见 VIDEO_MIRROR_MODE_TYPE。

返回值

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

SetLocalVoiceChanger

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

public abstract int SetLocalVoiceChanger(VOICE_CHANGER_PRESET voiceChanger);

弃用：

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

SetAudioEffectPreset ：音效
SetVoiceBeautifierPreset ：美声效果
SetVoiceConversionPreset ：变声效果

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

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

注意：

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

参数

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

返回值

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

SetLocalVoiceEqualization

设置本地语音音效均衡。

public abstract int SetLocalVoiceEqualization(AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);

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

参数

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

返回值

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

SetLocalVoicePitch

设置本地语音音调。

public abstract int SetLocalVoicePitch(double pitch);

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

参数

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

返回值

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

SetLocalVoiceReverb

设置本地音效混响。

public abstract int SetLocalVoiceReverb(AUDIO_REVERB_TYPE reverbKey, int value);

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

参数

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

返回值

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

SetLocalVoiceReverbPreset

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

public abstract int SetLocalVoiceReverbPreset(AUDIO_REVERB_PRESET reverbPreset);

弃用：: 请改用 SetAudioEffectPreset 或 SetVoiceBeautifierPreset。

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

注意：

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

参数

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

返回值

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

SetLogFile

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

public abstract int SetLogFile(string filePath);

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

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

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

参数

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

返回值

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

SetLogFileSize

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

public abstract int SetLogFileSize(uint fileSizeInKBytes);

弃用：: 请改用 Initialize 中的 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。

返回值

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

SetLogFilter

设置日志输出等级。

public abstract int SetLogFilter(uint filter);

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

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

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

参数

filter: 日志过滤等级。

返回值

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

SetLowlightEnhanceOptions

设置暗光增强功能。

public abstract int SetLowlightEnhanceOptions(bool enabled, LowLightEnhanceOptions options);

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

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

注意：

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

参数

enabled

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

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

options

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

SetMaxMetadataSize

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

public abstract int SetMaxMetadataSize(int size);

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

参数

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

返回值

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

SetMixedAudioFrameParameters

设置录制和播放声音混音后的数据格式。

public abstract int SetMixedAudioFrameParameters(int sampleRate, int samplesPerCall);

该方法设置 OnMixedAudioFrame 回调数据的格式。

注意：

该方法需要在加入频道前调用。
SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 OnMixedAudioFrame 回调。

参数

sampleRate: OnMixedAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、44100 或 48000。
samplesPerCall: OnMixedAudioFrame 中返回数据的采样点数，如旁路推流应用中通常为 1024。

返回值

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

SetPlaybackAudioFrameParameters

设置播放的音频格式。

public abstract int SetPlaybackAudioFrameParameters(int sampleRate, int channel,
            RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall);

该方法设置 OnPlaybackAudioFrame 回调数据的格式。

注意：

该方法需要在加入频道前调用。
SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 OnPlaybackAudioFrame 回调。

参数

sampleRate

OnPlaybackAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、44100 或 48000。

channel

OnPlaybackAudioFrame 中返回数据的通道数，可设置为 1 或 2:

1: 单声道
2: 双声道

mode

音频帧的使用模式，详见 RAW_AUDIO_FRAME_OP_MODE_TYPE。

samplesPerCall

OnPlaybackAudioFrame 中返回数据的采样点数，如旁路推流应用中通常为 1024。

返回值

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

SetRecordingAudioFrameParameters

设置采集的原始音频数据格式。

public abstract int SetRecordingAudioFrameParameters(int sampleRate, int channel,
            RAW_AUDIO_FRAME_OP_MODE_TYPE mode, int samplesPerCall);

该方法设置 OnRecordAudioFrame 回调的采集音频格式。

注意：

该方法需要在加入频道前调用。
SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔，计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 OnRecordAudioFrame 回调。

参数

sampleRate

OnRecordAudioFrame 中返回数据的采样率，可设置为 8000、 16000、 32000、44100 或 48000。

channel

OnRecordAudioFrame 中返回数据的通道数，可设置为 1 或 2:

1: 单声道。
2: 双声道。

mode

音频帧的使用模式，详见 RAW_AUDIO_FRAME_OP_MODE_TYPE。

samplesPerCall

OnRecordAudioFrame 中返回数据的采样点数，如旁路推流应用中通常为 1024。

返回值

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

SetRemoteDefaultVideoStreamType

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

public abstract int SetRemoteDefaultVideoStreamType(REMOTE_VIDEO_STREAM_TYPE streamType);

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

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

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

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

参数

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

返回值

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

SetRemoteRenderMode [1/2]

设置远端视图显示模式。

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode);

弃用：: 该方法已废弃，请使用 SetRemoteRenderMode [2/2]。

该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。

参数

userId: 远端用户 ID。
renderMode: 远端用户视图的渲染模式，详见 RENDER_MODE_TYPE。

返回值

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

SetRemoteRenderMode [2/2]

更新远端视图显示模式。

public abstract int SetRemoteRenderMode(uint userId, RENDER_MODE_TYPE renderMode,
            VIDEO_MIRROR_MODE_TYPE mirrorMode);

自从: v3.0.0

初始化远端用户视图后，你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。

注意：

请在调用 SetupRemoteVideo 方法初始化远端视图后，调用该方法。
你可以在通话中多次调用该方法，多次更新远端用户视图的显示模式。

参数

userId: 远端用户 ID。
renderMode: 远端用户视图的渲染模式，详见 RENDER_MODE_TYPE。
mirrorMode: 远端用户视图的镜像模式，详见 VIDEO_MIRROR_MODE_TYPE。

返回值

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

SetRemoteSubscribeFallbackOption

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

public abstract int SetRemoteSubscribeFallbackOption(STREAM_FALLBACK_OPTIONS option);

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

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

参数

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

返回值

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

SetRemoteUserPriority

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

public abstract int SetRemoteUserPriority(uint uid, PRIORITY_TYPE userPriority);

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

注意：

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

参数

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

返回值

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

SetRemoteVideoStreamType

设置订阅的视频流类型。

public abstract int SetRemoteVideoStreamType(uint userId, REMOTE_VIDEO_STREAM_TYPE streamType);

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

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

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

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

参数

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

返回值

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

SetRemoteVoicePosition

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

public abstract int SetRemoteVoicePosition(uint 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，表示该用户的原始音量。取值越小，则音量越低。

返回值

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

SetScreenCaptureContentHint

设置屏幕共享内容类型。

public abstract int SetScreenCaptureContentHint(VideoContentHint contentHint);

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

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

参数

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

返回值

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

SetupLocalVideo

初始化本地视图。

public abstract int SetupLocalVideo(VideoCanvas canvas);

该方法初始化本地视图并设置本地用户视频显示属性，只影响本地用户看到的视频画面，不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view)，并设置本地用户视图的渲染模式和镜像模式。

在 App 开发中，通常在初始化后调用该方法进行本地视频设置，然后再加入频道。退出频道后，绑定仍然有效，如果需要解除绑定，可以调用该方法将参数 view 设为 NULL。

注意：

该方法在加入频道前后都能调用。
如果你希望在通话中更新本地用户视图的渲染或镜像模式，请使用 SetLocalRenderMode [2/2] 方法。

参数

canvas: 本地视频显示属性。详见 VideoCanvas。

返回值

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

SetupRemoteVideo

初始化远端用户视图。

public abstract int SetupRemoteVideo(VideoCanvas canvas);

该方法绑定远端用户和显示视图，并设置远端用户视图在本地显示时的渲染模式和镜像模式，只影响本地用户看到的视频画面。

调用该方法时需要指定远端视频的用户 ID，一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID，可以在收到 OnUserJoined 回调时调用该方法。

如需解除某个远端用户的绑定视图，可以调用该方法并将 view 设置为空。

离开频道后，SDK 会清除远端用户视图的绑定关系。

注意：

如果你希望在通话中更新远端用户视图的渲染或镜像模式，请使用 SetRemoteRenderMode [2/2] 方法。
如果你使用了声网录制服务，录制服务会作为一个哑客户端加入频道，因此也会触发 OnUserJoined 回调。由于录制服务不会发送视频流，app 无需为它绑定视图。如果 app 无法识别哑客户端，可以在收到 OnFirstRemoteVideoDecoded 回调时再绑定远端用户视图。

参数

canvas: 远端视频显示属性。详见 VideoCanvas。

返回值

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

SetVideoDenoiserOptions

设置视频降噪功能。

public abstract int SetVideoDenoiserOptions(bool enabled, VideoDenoiserOptions options);

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

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

注意：

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

参数

enabled

是否开启视频降噪功能：

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

options

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

SetVideoEncoderConfiguration

设置视频编码属性。

public abstract int SetVideoEncoderConfiguration(VideoEncoderConfiguration config);

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

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

参数

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

返回值

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

SetVideoProfile

设置视频编码配置。

public abstract int SetVideoProfile(VIDEO_PROFILE_TYPE profile, bool swapWidthAndHeight = false);

弃用：: 该方法自 v2.3 起废弃。请改用 SetVideoEncoderConfiguration 方法。

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

参数

profile

视频属性。详见: VIDEO_PROFILE_TYPE 。

swapWidthAndHeight

SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高：

true: 交换宽和高
false: 不交换宽和高（默认）

返回值

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

SetVideoQualityParameters

设置视频优化选项（仅适用于直播）。

public abstract int SetVideoQualityParameters(bool preferFrameRateOverImageQuality);

弃用：: 该方法从 v2.4.0 起废弃。声网建议使用 VideoEncoderConfiguration 类中的 degradationPreference 参数设置视频质量偏好。

参数

preferFrameRateOverImageQuality

画质和流畅度里，是否优先保证流畅度：

true：优先保证流畅度。
false： (默认)优先保证画质。

返回值

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

SetVoiceBeautifierParameters

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

public abstract int SetVoiceBeautifierParameters(VOICE_BEAUTIFIER_PRESET preset, int param1, int param2);

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

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

注意：

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

参数

preset

预设的音效：

SINGING_BEAUTIFIER: 歌唱美声。

param1

歌声的性别特征：

1: 男声。
2: 女声。

param2

歌声的混响效果：

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

返回值

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

SetVoiceBeautifierPreset

设置预设的美声效果。

public abstract int SetVoiceBeautifierPreset(VOICE_BEAUTIFIER_PRESET preset);

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

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

注意：

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

参数

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

返回值

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

SetVoiceConversionPreset

设置预设的变声效果。

public abstract int SetVoiceConversionPreset(VOICE_CONVERSION_PRESET preset);

自从: v3.3.1

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

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

注意：

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

参数

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

返回值

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

SetVolumeOfEffect

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

public abstract int SetVolumeOfEffect(int soundId, int volume);

注意：该方法需要在 PlayEffect [2/2] 后调用。

参数

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

返回值

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

StartAudioMixing [1/2]

开始播放音乐文件。

public abstract int StartAudioMixing(string filePath, bool loopback, bool replace, int cycle);

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

注意：

该方法需要在加入频道后调用。如需多次调用 StartAudioMixing [1/2]，请确保调用间隔大于 500 ms。
如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL，则 SDK 会报告 WARN_AUDIO_MIXING_OPEN_ERROR (701)。

参数

filePath

文件路径：

Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.

loopback

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

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

replace

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

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

cycle

音乐文件的播放次数。

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

返回值

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

StartAudioMixing [2/2]

开始播放音乐文件。

public abstract int StartAudioMixing(string filePath, bool loopback, bool replace, int cycle, int startPos);

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

注意：

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

参数

filePath

文件路径：

Windows: 音频文件的绝对路径或 URL 地址，需精确到文件名及后缀。例如： C:\music\audio.mp4.

loopback

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

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

replace

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

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

cycle

音乐文件的播放次数。

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

startPos

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

返回值

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

StartAudioRecording [1/3]

开始客户端录音。

public abstract int StartAudioRecording(string filePath, AUDIO_RECORDING_QUALITY_TYPE quality);

弃用：: 该方法从 v2.9.1 起废弃，其默认录音采样率为 32 kHz，不可修改。请改用新的 StartAudioRecording [3/3] 方法。

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

.wav: 文件大，音质保真度高；
.aac: 文件小，有一定的音质保真度损失。

请确保 App 里指定的目录存在且可写。该接口需在 JoinChannel [1/2] 之后调用。如果调用 LeaveChannel 时还在录音，录音会自动停止。

参数

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

注意：请确保你指定的路径存在并且可写。
quality: 录音质量。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回值

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

StartAudioRecording [2/3]

开始客户端录音。

public abstract int StartAudioRecording(string filePath, int sampleRate, AUDIO_RECORDING_QUALITY_TYPE quality);

弃用：: 请改用 StartAudioRecording [3/3]。

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

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

注意：

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

参数

filePath

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

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

sampleRate

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

16000
32000（默认）
44100
48000

quality

录音音质。详见 AUDIO_RECORDING_QUALITY_TYPE 。

返回值

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

StartAudioRecording [3/3]

开始客户端录音。

public abstract int StartAudioRecording(AudioRecordingConfiguration config);

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

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

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

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

参数

config: 录音配置。详见 AudioRecordingConfiguration。

返回值

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

StartChannelMediaRelay

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

public abstract int StartChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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

如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0)，且 OnChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4)，则表示 SDK 开始在源频道和目标频道之间转发媒体流。
如果 OnChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3)，则表示跨频道媒体流转发出现异常。

注意：

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

参数

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

返回值

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

StartEchoTest [1/3]

开始语音通话回路测试。

public abstract int StartEchoTest();

弃用：: 该方法自 v2.4.0 起废弃，请改用 StartEchoTest [2/3]。

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

注意：

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

返回值

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

StartEchoTest [2/3]

开始语音通话回路测试。

public abstract int StartEchoTest(int intervalInSeconds);

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

注意：

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

参数

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

返回值

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

StartEchoTest [3/3]

开始音视频通话回路测试。

public abstract int StartEchoTest(EchoTestConfiguration config);

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

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

注：

请在加入频道前调用该方法。
调用该方法后，必须调用 StopEchoTest 结束测试，否则该用户无法进行下一次音视频通话回路测试，也无法加入频道。
直播场景下，该方法仅能由主播调用。

参数

config: 音视频通话回路测试的配置。详见 EchoTestConfiguration。

返回值

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

StartLastmileProbeTest

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

public abstract int StartLastmileProbeTest(LastmileProbeConfig config);

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

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

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

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

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

注意：

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

参数

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

返回值

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

StartPreview

开启视频预览。

public abstract int StartPreview();

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

调用 EnableVideo 开启视频功能。

注意：

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

返回值

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

StartRecording

开启本地音视频流录制。

public abstract int StartRecording(MediaRecorderConfiguration config);

该方法录制的是本地麦克风采集的、编码为 AAC 格式的音频或本地摄像头采集的、编码后的视频。只有当检测到可录制的音视频流时，才能成功生成录制文件；当没有可录制的音视频或录制中的音视频流中断超过 5 秒后，SDK 会停止录制，并触发 OnRecorderStateChanged(RECORDER_STATE_ERROR, RECORDER_ERROR_NO_STREAM) 回调。

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

参数

config: 音视频流录制配置。详见 MediaRecorderConfiguration。

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。
- -2（ERR_INVALID_ARGUMENT）: 参数无效。请确保：
  - 指定的录制文件保存路径正确且可写。
  - 指定的录制文件格式正确。
  - 设置的最大录制时长正确。
- -4（ERR_NOT_SUPPORTED）: IAgoraRtcEngine 当前状态不支持该操作。可能因为录制正在进行中或录制出错停止。
- -7（ERR_NOT_INITIALZIED）: IAgoraRtcEngine 尚未初始化就调用方法。。

StartRtmpStreamWithTranscoding

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

public abstract int StartRtmpStreamWithTranscoding(string url, LiveTranscoding transcoding);

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

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

注意：

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

参数

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

返回值

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

StartRtmpStreamWithoutTranscoding

开始非转码推流。

public abstract int StartRtmpStreamWithoutTranscoding(string url);

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

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

注意：

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

参数

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

返回值

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

StartScreenCaptureByDisplayId

通过屏幕 ID 共享屏幕。

public abstract int StartScreenCaptureByDisplayId(uint displayId, Rectangle regionRect,
                ScreenCaptureParameters captureParams);

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

注意：

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

参数

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

返回值

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

StartScreenCaptureByScreenRect

通过指定区域共享屏幕。

public abstract int StartScreenCaptureByScreenRect(Rectangle screenRect, Rectangle regionRect,
            ScreenCaptureParameters captureParams);

弃用：: 该方法已废弃。

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

注意：

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

参数

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

返回值

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

StartScreenCaptureByWindowId

通过窗口 ID 共享窗口。

public abstract int StartScreenCaptureByWindowId(view_t windowId, Rectangle regionRect,
            ScreenCaptureParameters captureParams);

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

注意：

参数

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

返回值

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

StopAllEffects

停止播放所有音效文件。

public abstract int StopAllEffects();

返回值

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

StopAudioMixing

停止播放音乐文件。

public abstract int StopAudioMixing();

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

返回值

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

StopAudioRecording

停止客户端录音。

public abstract int StopAudioRecording();

如果你调用了 StartAudioRecording [3/3] 开始录音，可以调用该方法停止录音。

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

返回值

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

StopChannelMediaRelay

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

public abstract int StopChannelMediaRelay();

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

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

返回值

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

StopEchoTest

停止语音通话回路测试。

public abstract int StopEchoTest();

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -5(ERR_REFUSED): 无法启动测试，可能没有成功初始化。

StopEffect

停止播放指定音效文件。

public abstract int StopEffect(int soundId);

参数

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

返回值

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

StopLastmileProbeTest

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

public abstract int StopLastmileProbeTest();

返回值

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

StopPreview

停止视频预览。

public abstract int StopPreview();

返回值

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

StopRecording

停止本地音视频流录制。

public abstract int StopRecording();

注意：调用 StartRecording 后，如果要停止录制，必须调用该方法停止录制；否则，生成的录制文件可能无法正常播放。

返回值

0(ERR_OK): 方法调用成功
< 0: 方法调用失败：
- -7(ERR_NOT_INITIALIZED): IAgoraRtcEngine 尚未初始化就调用方法。

StopRtmpStream

结束旁路推流。

public abstract int StopRtmpStream(string url);

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

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

参数

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

返回值

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

StopScreenCapture

停止屏幕共享。

public abstract int StopScreenCapture();

返回值

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

SwitchChannel [1/2]

快速切换直播频道。

public abstract int SwitchChannel(string token, string channelId);

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

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

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

参数

token

动态秘钥。

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

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

channelId

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

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -1: 一般性的错误（未明确归类）。
- -2: 参数无效。
- -5: 调用被拒绝。可能因为用户角色不是观众。
- -7: SDK 尚未初始化。
- -102: 频道名无效。请更换有效的频道名。
- -113: 用户不在频道内。

SwitchChannel [2/2]

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

public abstract int SwitchChannel(string token, string channelId, ChannelMediaOptions options);

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

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

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

参数

token

动态秘钥。

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

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

channelId

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

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

options

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

返回值

0(ERR_OK): 方法调用成功。
< 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误（未明确归类）。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -5(ERR_REFUSED): 调用被拒绝。可能因为用户角色不是观众。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
- -102(ERR_INVALID CHANNEL_NAME): 频道名无效。请更换有效的频道名。
- -113(ERR_NOT_IN_CHANNEL): 用户不在频道内。

TakeSnapshot

获取视频截图。

public abstract int TakeSnapshot(string channel, uint uid, string filePath);

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

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

注意：

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

参数

channel

频道名。

uid

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

filePath

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

Windows: C:\Users\<user_name>\AppData\Local\Agora\<process_name>\example.jpg

请确保目录存在且可写。

返回值

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

UpdateRtmpTranscoding

更新旁路推流转码属性。

public abstract int UpdateRtmpTranscoding(LiveTranscoding transcoding);

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

参数

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

返回值

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

UploadLogFile

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

public abstract string UploadLogFile();

自从: v3.3.0

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

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

UnloadEffect

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

public abstract int UnloadEffect(int soundId);

参数

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

返回值

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

UnRegisterAudioFrameObserver

取消注册音频帧观测器。

public abstract void UnRegisterAudioFrameObserver();

返回值

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

UnRegisterMediaMetadataObserver

取消注册媒体 metadata 观测器。

public abstract int UnRegisterMediaMetadataObserver(METADATA_TYPE type);

参数

type: 观测器使用的 metadata 类型。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。

返回值

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

UnRegisterVideoFrameObserver

取消注册视频帧观测器。

public abstract void UnRegisterVideoFrameObserver();

返回值

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

UpdateChannelMediaRelay

更新媒体流转发的频道。

public abstract int UpdateChannelMediaRelay(ChannelMediaRelayConfiguration configuration);

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

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

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

参数

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

返回值

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

UpdateScreenCaptureParameters

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

public abstract int UpdateScreenCaptureParameters(ScreenCaptureParameters captureParams);

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -3: 如果当前没有共享的屏幕，会返回该错误码。

updateScreenCaptureRegion

更新屏幕共享区域。

public abstract int UpdateScreenCaptureRegion(Rectangle regionRect);

参数

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

返回值

0: 方法调用成功。
< 0: 方法调用失败。
- -3: 如果当前没有共享的屏幕，会返回该错误码。