RtcEngine
Agora Native SDK 的基础接口类,实现实时音视频的主要功能。
RtcEngine 提供了 app 调用的主要方法。
setEventHandler
添加主回调事件。
void setEventHandler(RtcEngineEventHandler handler)
RtcEngineEventHandler 接口类用于 SDK 向 app 发送回调事件通知,app 通过继承该接口类的方法获取 SDK 的事件通知。 接口类的所有方法都有缺省(空)实现,app 可以根据需要只继承关心的事件。在回调方法中,app 不应该做耗时或者调用可能会引起阻塞的 API(如 sendStreamMessage), 否则可能影响 SDK 的运行。
参数
- handler
- 待添加的回调事件,详见 RtcEngineEventHandler。
addInjectStreamUrl
输入在线媒体流。
Future<void> addInjectStreamUrl(String url, LiveInjectStreamConfig config);
- 请确保已开通旁路推流的功能,详见推流到 CDN 中的前提条件。
- 在直播场景中,只有角色为主播的用户才 能调用该方法。
- 频道内同一时间只允许输入一个在线媒体流。
- 该方法需要在加入频道后调用。
该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后,SDK 会在本地触发 streamInjectedStatus 回调,报告输入在线媒体流的状态;成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 userJoined 回调,其中 uid 为 666。
参数
- url
-
添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。
- 支持的音频编码格式:AAC;
- 支持的视频编码格式:H.264(AVC)。
- config
- 所添加的视频流属性定义,详见: LiveInjectStreamConfig 。
addPublishStreamUrl
增加旁路推流地址。
Future<void> addPublishStreamUrl(String url, bool transcodingEnabled);
调用该方法后,你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 rtmpStreamingStateChanged 回调,报告增加旁路推流地址的状态。
- 该方法需要在加入频道后调用。
- 请确保已开通旁路推流的功能。详见进阶功能推流到 CDN 中的前提条件。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- url
- CDN 推流地址,格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节,不支持中文字符等特殊字符。
- transcodingEnabled
-
是否转码。转码是指在旁路推流时对音视频流进行转码处理后再推送到其他 CDN 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景。
true
: 转码。false
: 不转码。
addVideoWatermark
添加本地视频水印。
Future<void> addVideoWatermark(String watermarkUrl, WatermarkOptions options);
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(VideoOutputOrientationMode) 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(VideoOutputOrientationMode) 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 如果你只是在旁路直播(推流到 CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
Future<void> adjustAudioMixingPlayoutVolume(int volume);
参数
- volume
- 音乐文件音量范围为 [0,100]。100 (默认值)为原始文件音量。
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
Future<void> adjustAudioMixingPublishVolume(int volume);
该方法调节混音音乐文件在远端的播放音量大小。
参数
- volume
- 音乐文件音量。范围为 [0,100]。100 (默认值)为原始文件音量。
adjustAudioMixingVolume
调节音乐文件的播放音量。
Future<void> adjustAudioMixingVolume(int volume);
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing 后调用。
- 调用该方法不影响调用 playEffect 播放音效文件的音量。
参数
- 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 { if (_instance != null) return _instance!; _instance = RtcEngine._(false); await _instance!.initialize(config); return _instance!; }
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。
deviceManager
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();
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 该方法开启整个音频模块,响应时间较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
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);
- 确保已集成如下动态库:
libagora_ai_denoise_extension.dll
- 调用 enableDeepLearningDenoise(
true
)。
- iPhone 6S
- MacBook Pro 2015
- iPad Pro 第二代
- iPad mini 第五代
- iPad Air 第三代
成功开启 AI 降噪模式后,如果 SDK 检测到当前设备的性能不足,SDK 会自动关闭 AI 降噪模式,并开启传统降噪模式。
在频道内,如果你调用了 enableDeepLearningDenoise(true
) 或 SDK 自动关闭了 AI 降噪模式,当你需要重新开启 AI 降噪模式时, 你需要先调用
leaveChannel,再调用 enableDeepLearning(true
)。
- 该方法需要动态加载动态库,所以 Agora 推荐在加入频道前调用该方法。
- 该方法对人声的处理效果最佳。Agora 不推荐调用该方法处理含音乐的音频数据。
参数
- enable
- 是否开启 AI 降噪模式:
true
:(默认)开启 AI 降噪模式。false
: 关闭 AI 降噪模式。
enableDualStreamMode
开关双流模式。
Future<void> enableDualStreamMode(bool enabled);
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式。
true
: 开启双流模式。false
: 关闭双流模式。
enableEncryption
开启或关闭内置加密。
Future<void> enableEncryption(bool enabled, EncryptionConfig config);
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
enableFaceDetection
开启/关闭本地人脸检测。
Future<void> enableFaceDetection(bool enable);
该方法在加入频道前后都能调用。
- 摄像头采集的画面大小
- 人脸在画面中的位置
- 人脸距设备屏幕的距离
该方法需要在相机启动(如通过调用 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
) 适用于只听不发的用户场景。
- 该方法与 muteLocalAudioStream 的区别在于:
- enableLocalVideo: 开启或关闭本地音频采集及处理。使用
enableLocalAudio
关闭或开启本地采集后,本地听远端播放会有短暂中断。 - muteLocalAudioStream: 停止或继续发送本地音频流。
- enableLocalVideo: 开启或关闭本地音频采集及处理。使用
- 该方法在加入频道前后都能调用。
参数
- enabled
true
: 重新开启本地音频功能,即开启本地音频采集(默认);false
: 关闭本地音频功能,即停止本地音频采集。
enableLocalVideo
开关本地视频采集。
Future<void> enableLocalVideo(bool enabled);
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频采集即默认开启。你可以调用 enableLocalVideo(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true
)。
成功禁用或启用本地视频采集后,远端会触发 remoteVideoStateChanged 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
- enabled
-
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
enableLoopbackRecording
开启声卡采集。
Future<void> enableLoopbackRecording(bool enabled, {String? deviceName})
启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。
- 该方法仅适用于 macOS 和 Windows 平台。
- macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 是否开启声卡采集:
true
: 开启声卡采集。false
:(默认)关闭声卡采集。
- deviceName
- 声卡的设备名。默认设为 null,即使用当前声卡采集。 如果用户使用虚拟声卡,如 "Soundflower",可以将虚拟声卡名称 "Soundflower" 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。
enableRemoteSuperResolution
开启或关闭远端视频超分辨率。
Future<void> enableRemoteSuperResolution(int userId, bool enable);
该功能可以有效提升本地用户看到的远端视频画面的分辨率。例如远端用户视频的原始分辨率为 a < b,开启该功能后,本地设备会以 2a < 2b 的分辨率 显示该远端视频。
调用该方法后,SDK 会触发 userSuperResolutionEnabled 回调报告超分辨率是否成功开启。
- SuperResolutionStreamOverLimitation: 1610,远端用户的原始视频分辨率超出了可以应用超分辨率的范围。
- SuperResolutionUserCountOverLimitation: 1611,已对一个远端用户的视频使用超分辨率。
- SuperResolutionDeviceNotSupported: 1612,设备不支持使用超分辨率。
- 该方法仅适用于 Android 和 iOS 平台。
- 调用该方法前,请确保你已经集成相应的动态库:
- Android: libagora_super_resolution_extension.so
- iOS: AgoraSuperResolutionExtension.xcframework
- 该方法对用户设备具有一定要求,Agora 推荐你使用如下或更好的设备:
- 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(第四代)
- Android:
参数
- 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 后调用。
- 该功能对设备性能要求较高,Agora 推荐你在搭载如下芯片的设备上使用:
- 骁龙 700 系列 750G 及以上
- 骁龙 800 系列 835 及以上
- 天玑 700 系列 720 及以上
- 麒麟 800 系列 810 及以上
- 麒麟 900 系列 980 及以上
- 搭载 A9 及以上芯片的如下设备:
- iPhone 6S 及以上
- iPad Air 第三代及以上
- iPad 第五代及以上
- iPad Pro 第一代及以上
- iPad mini 第五代及以上
- Agora 建议你在满足如下条件的场景中使用该功能:
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。
- 该功能不支持 Texture 格式或使用 Push 方式自采集的视频数据。
参数
- enabled
- 是否开启虚拟背景:
true
: 开启。false
: 关闭。
- backgroundSource
- 自定义的背景图。详见 VirtualBackgroundSource。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配,SDK 会在保证自定义背景图内容不变形的前提下,对自定义背景图进行缩放和裁剪。
enableWebSdkInteroperability
打开与 Web SDK 的互通(仅在直播场景适用)。
Future<void> enableWebSdkInteroperability(bool enabled);
- 弃用:
- 该方法已废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Agora Web SDK 的互通:
true
: 打开互通。false
: (默认) 关闭互通。
getAudioFileInfo
获取指定音频文件信息。
Future<int?> getAudioFileInfo(String filePath);
成功调用该方法后,SDK 会触发 requestAudioFileInfoCallback 回调,报告指定音频文件的时长等信息。你可以多次调用该方法,获取多个音频文件的信息。
- 该方法需要在加入频道后调用。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 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();
该方法获取当前音乐文件播放进度,单位为毫秒。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功返回音乐文件播放进度。
- < 0: 方法调用失败。
getAudioMixingDuration
获取音乐文件的时长。
Future<int?> getAudioMixingDuration([String? filePath]);
- 该方法需要在加入频道后调用。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 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();
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioMixingPublishVolume
获取音乐文件的远端播放音量。
Future<int?> getAudioMixingPublishVolume();
该接口可以方便开发者排查音量相关问题。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioTrackCount
获取当前音乐文件的音轨索引。
Future<int?> getAudioTrackCount();
- 该方法仅适用于 Android、iOS 和 Windows。
- 你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING) 回调后调用该方法。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
返回值
- ≥ 0: 方法调用成功,返回当前音乐文件的音轨索引。
- < 0: 方法调用失败。
getCameraMaxZoomFactor
获取摄像头支持最大缩放比例。
Future<double?> getCameraMaxZoomFactor();
- 请在启动摄像头之前调用该方法,如 joinChannel、enableVideo 或者 enableLocalVideo 之前。
返回值
设备摄像头支持的最大缩放比例。
getCallId
getConnectionState
获取当前网络连接状态。
Future<ConnectionStateType> getConnectionState();
该方法在加入频道前后都能调用。
返回值
当前网络连接状态。详见 ConnectionStateType。
getEffectCurrentPosition
获取指定音效文件的播放进度。
Future<int?> getEffectCurrentPosition(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- ≥ 0:方法调用成功,返回指定音效文件的播放进度(毫秒)。
- < 0:方法调用失败。
getEffectDuration
获取指定音效文件总时长。
Future<int?> getEffectDuration(String filePath);
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 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 (默认值)为原始文件音量。
返回值
- 音效文件的音量。
- < 0: 方法调用失败
getErrorDescription
获取警告或错误描述。
Future<String?> getErrorDescription(int error)
参数
- error
- SDK 报告的错误码或警告码。
返回值
具体的错误或警告描述。
getScreenShareHelper
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 对象。
- 非空:方法调用成功。
- 空:方法调用失败。
getSdkVersion
获取 SDK 版本。
Future<String?> getSdkVersion()
返回值
当前的 SDK 版本号。格式为字符串。
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();
返回值
true
: 扬声器已开启,语音会输出到扬声器。false
: 扬声器未开启,语音会输出到非扬声器(听筒,耳机等)。
joinChannel
加入频道并设置是否自动订阅音频或视频流。
Future<void> joinChannel( String? token, String channelName, String? optionalInfo, int optionalUid, [ChannelMediaOptions? options]);
该方法让用户加入实时音视频互动频道。在 App ID 一致的前提下,进入同一个频道的用户可以互相通话;多个用户加入同一个频道可以群聊。
- 本地会触发 joinChannelSuccess 和 connectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 userJoined 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;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 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 joinChannelSuccess 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
频道媒体设置选项。详见 ChannelMediaOptions。
joinChannelWithUserAccount
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
Future<void> joinChannelWithUserAccount( String? token, String channelName, String userAccount, [ChannelMediaOptions? options]);
- 本地:localUserRegistered、joinChannelSuccess 和 connectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 userJoined 和 userInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- 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 回调,并在回调中报告是否成功暂停媒体流转发。
pauseAllEffects
暂停所有音效文件播放。
Future<void> pauseAllEffects();
pauseAudioMixing
暂停播放音乐文件。
Future<void> pauseAudioMixing();
请在加入频道后调用该方法。
pauseEffect
暂停音效文件播放。
Future<void> pauseEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
playEffect
播放指定的本地或在线音效文件。
Future<void> playEffect(int soundId, String filePath, int loopCount, double pitch, double pan, int gain, bool publish, [int? startPos]);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 支持的媒体格式。- 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 前就使用该方法完成音效预加载。
- 该方法不支持在线音频文件。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 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。
- 先调用 registerLocalUserAccount 方法注册 Account,再调用 joinChannelWithUserAccount 方法加入频道。
- 直接调用 joinChannelWithUserAccount 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 userAccount 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 UID 或 User Account。 如果有用户通过 Agora Web SDK 加入频道,请确保 Web 加入的用户也是同样类型。
参数
- appId
- 你的项目在 Agora 控制台注册的 App ID。
- userAccount
- 用户 User Account。该参数用于标识实时音视频互动频道中的用户。你需要自行设置和管理用户的 User Account,并确保同一频道中每个用户的 User Account 是唯一的。该参数为必填,最大不超过 255 字节,不可填 null。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a-z
- 26 个大写英文字母 A-Z
- 10 个数字 0-9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
registerMediaMetadataObserver
注册媒体 metadata 观测器用于接收或发送 metadata。
Future<void> registerMediaMetadataObserver();
- 请在 joinChannel 前调用该方法。
- 该方法仅适用于直播场景。
destroy
销毁 RtcEngine 对象。
Future<void> destroy();
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。
removeInjectStreamUrl
删除导入的外部媒体流。
Future<void> removeInjectStreamUrl(String url);
成功删除外部视频源 URL 地址后会触发 userOffline 回调,uid 为
666
。
参数
- url
- 已导入、待删除的外部视频源 URL 地址。
removePublishStreamUrl
删除旁路推流地址。
Future<void> removePublishStreamUrl(String url);
调用该方法后,SDK 会在本地触发 rtmpStreamingStateChanged 回调,报告删除旁路推流地址的状态。
- 调用该方法前,请确保已开通旁路推流的功能。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法需要在加入频道后调用。
- 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
参数
- url
- 待删除的旁路推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。
renewToken
更新 Token。
Future<void> renewToken(String token);
- 发生 tokenPrivilegeWillExpire 回调时。
- connectionStateChanged 回调报告 TokenExpired(9) 时。
参数
- token
- 新的 Token。
resumeAllChannelMediaRelay
恢复向所有目标频道转发媒体流。
Future<void> resumeAllChannelMediaRelay();
调用 pauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
成功调用该方法后,SDK 会触发 channelMediaRelayEvent 回调,并在回调中报告是否成功恢复媒体流转发。
resumeAllEffects
恢复播放所有音效文件。
Future<void> resumeAllEffects();
resumeAudioMixing
恢复播放音乐文件。
Future<void> resumeAudioMixing();
该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。
resumeEffect
恢复播放指定音效文件。
Future<void> resumeEffect(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
selectAudioTrack
指定当前音频文件的播放音轨。
Future<void> selectAudioTrack(int index);
- 自从
- v3.5.1
获取音频文件的音轨索引后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置播放语言。
参数
- index
- 音轨的索引值。
setAudioMixingPlaybackSpeed
设置当前音乐文件的播放速度。
Future<void> setAudioMixingPlaybackSpeed(int speed);
你需要在调用 startAudioMixing 并收到 audioMixingStateChanged(Playing) 回调后调用该方法。
参数
- speed
- 播放速度。推荐取值范围为 [50,400],其中:
- 50: 0.5 倍速。
- 100: 原始速度。
- 400: 4 倍速。
setAudioMixingDualMonoMode
设置当前音频文件的声道模式。
Future<void> setAudioMixingDualMonoMode(AudioMixingDualMonoMode mode);
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 startAudioMixing 并收到 audioMixingStateChanged (Playing) 回调后调用该方法。
- 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AudioMixingDualMonoMode。
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
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - sound2
- 弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
Android: /sdcard/emulated/0/audio.mp4, iOS: /var/mobile/Containers/Data/audio.mp4
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - config
- 节拍器配置。详见 RhythmPlayerConfig。
stopRhythmPlayer
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);
- 频道内每秒最多能发送 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 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setAudioEffectParameters 后,Agora 不推荐调用以下方法,否则 setAudioEffectParameters 设置的效果会被覆盖:
参数
- preset
- SDK 预设的音效,支持以下设置:
- RoomAcoustics3DVoice,3D 人声音效。
- 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置 为 MusicStandardStereo(3) 或 MusicHighQualityStereo(5),否则该枚举设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- PitchCorrection,电音音效。为获取更好的人声效果,Agora 建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。
- RoomAcoustics3DVoice,3D 人声音效。
- 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
: A2
: A#3
: B4
: (Default) C5
: C#6
: D7
: D#8
: E9
: F10
: F#11
: G12
: G#
- 如果 preset 设为 RoomAcoustics3DVoice,你需要将 param2 设置为
setAudioEffectPreset
设置 SDK 预设的人声音效。
Future<void> setAudioEffectPreset(AudioEffectPreset preset);
详细描述
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
根据不同的场景,你可以为用户设置不同的音效,各音效的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 如果调用 setAudioEffectPreset 并设置除 RoomAcoustics3DVoice 或 PitchCorrection 外的枚举,请勿再调用 setAudioEffectParameters,否则 setAudioEffectPreset 设置的效果会被覆盖。
- 调用 setAudioEffectPreset 后,Agora 不推荐调用以下方法,否则 setAudioEffectPreset 设置的效果会被覆盖:
参数
- preset
- 预设的音效选项,详见 AudioEffectPreset。
setAudioMixingPitch
调整本地播放的音乐文件的音调。
Future<void> setAudioMixingPitch(int pitch);
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
setAudioMixingPosition
设置音乐文件的播放位置。
Future<void> setAudioMixingPosition(int pos);
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
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 后调用。
- Agora 从 3.6.0 版起更新了基础美颜算法,能提升基础美颜效果并支持锐度调节功能。如果你想体验优化后的基础美颜效果或设置锐度,请在调用该方法前,将如下动态库集成到项目文件中:
- Android:
libagora_video_process_extension.so
- iOS:
AgoraVideoProcessExtension.xcframework
- macOS:
AgoraVideoProcessExtension.framework
- Windows:
libagora_video_process_extension.dll
- Android:
参数
- enabled
- 是否开启美颜功能:
true
: 开启。false
:(默认)关闭。
- options
- 美颜选项,详细定义见 BeautyOptions。
setCameraAutoFocusFaceModeEnabled
设置是否开启人脸对焦功能。
Future<void> setCameraAutoFocusFaceModeEnabled(bool enabled);
- 请在启动摄像头之前调用该方法,如 joinChannel、enableVideo 或者 enableLocalVideo 之前。
参数
- enabled
- 是否开启人脸对焦:
true
: 开启人脸对焦功能。false
:(默认)关闭人脸对焦功能。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraCapturerConfiguration
设置摄像头采集配置。
Future<void> setCameraCapturerConfiguration( CameraCapturerConfiguration config);
- 使用原始音视频数据自采集接口时,如果 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);
该方法用于设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannel 前调用和进行设置,进入频道后无法再设置。
参数
- profile
-
频道使用场景。详见 ChannelProfile。
setClientRole
设置直播场景下的用户角色和级别。
Future<void> setClientRole(ClientRole role, [ClientRoleOptions? options]);
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 clientRoleChanged 回调。
- 远端触发 userJoined 或 userOffline 回调。
参数
- role
- 直播场景中的用户角色。详见 ClientRole。
- options
- 用户具体设置,包含用户级别。详见 ClientRoleOptions。
setCloudProxy
设置 Agora 云代理服务。
Future<void> setCloudProxy(CloudProxyType proxyType);
当用户防火墙限制 IP 和端口号时,你需要参考使用云代理开放相应 IP 和端口号,然后调用该方法开启云代理,并将 proxyType 设为 UDP (1),即使用 UDP 协议的云代理。
成功连接云代理后,SDK 会触发 connectionStateChanged (Connecting, SettingProxyServer) 回调。
如果你想关闭已设置的云代理,请调用 setCloudProxy (None)。
如果你想更改已设置的云代理类型,请先调用 setCloudProxy (None), 再调用 setCloudProxy 并传入你期望的 proxyType 值。
- Agora 推荐你在频道外调用该方法。
- 使用 UDP 协议的云代理时,推流到 CDN 和跨频道媒体流转发功能不可用。
参数
- proxyType
- 云代理类型,详见 CloudProxyType。该参数为必填参数,如果你不赋值,SDK 会报错。
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);
成功设置后,本地音效文件会在指定位置开始播放。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- pos
- 音效文件的播放位置,单位为毫秒。
setEffectsVolume
设置音效文件的播放音量。
Future<void> setEffectsVolume(int volume);
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
setEnableSpeakerphone
启用/关闭扬声器播放。
Future<void> setEnableSpeakerphone(bool speakerOn);
该方法设置是否将音频路由到扬声器(外放)。调用该方法后,SDK 将返回 audioRouteChanged 回调提示状态已更改。
- 该方法仅适用于 Android 和 iOS 平台。
- 请确保在调用此方法前已经加入频道。
参数
- speakerOn
- 是否切换音频路由到扬声器(外放):
true
: 切换到外放。如果设备连接了耳机或蓝牙,则无法切换到外放。false
: 切换到听筒。如果设备连接了耳机,则音频路由走耳机。
setEncryptionMode
启用内置的加密方案。
Future<void> setEncryptionMode(EncryptionMode encryptionMode);
- 弃用:
- 请改用 enableEncryption 方法。
Agora Video SDK 支持内置加密方案,默认支持 AES-128-XTS。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 secret 才能进行通话。关于这几种加密方式的区别,请参考 AES 加密算法的相关资料。
参数
- 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 回调。
- 该方法需要在加入频道后调用。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- transcoding
-
推流转码设置。详见 LiveTranscoding。
setLocalPublishFallbackOption
设置弱网条件下发布的音视频流回退选项。
Future<void> setLocalPublishFallbackOption(StreamFallbackOptions option);
网络不理想的环境下,实时通信音视频的质量都会下降。使用该接口并将 option 设置为 AudioOnly (2) 后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当本地推流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发本地发布的媒体流已回退为音频流 localPublishFallbackToAudioOnly 回调。
- 旁路推流场景下,设置本地推流回退为 AudioOnly(2) 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下,Agora 建议不开启该功能。
- 该方法需要在加入频道前调用。
参数
- option
- 本地发流回退处理选项。详见 StreamFallbackOptions。
setLocalVoiceChanger
设置本地语音变声、美音或语聊美声效果。
Future<void> setLocalVoiceChanger(AudioVoiceChanger voiceChanger);
- 弃用:
- 该方法从 v3.2.0 起废弃,请改用以下方法:
- setAudioEffectPreset :音效
- setVoiceBeautifierPreset :美声效果
- setVoiceConversionPreset :变声效果
- 变声效果:枚举值以
VOICE_CHANGER
为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人,通常用于语聊场景。 - 美音效果:枚举值以
VOICE_BEAUTY
为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷,通常用于语聊和唱歌场景。 - 语聊美声效果:枚举值以
GENERAL_BEAUTY_VOICE
为前缀。效果包括磁性(男)、清新(女)和活力(女),通常用于语聊场景。该功能主要细化了男声和女声各自的特点。
- 为达到更好的声音效果,Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 MusicHighQuality (4) 或 MusicHighQualityStereo (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法不能与 setLocalVoiceReverbPreset 方法一同使用,否则先调的方法会不生效。更多注意事项,详见进阶功能《变声与混响》。
- 该方法在加入频道前后都能调用。
参数
- voiceChanger
-
预设本地语音变声、美音或语聊美声效果选项,默认值为 Off ,即原声。详见 AudioVoiceChanger 。设置语聊美声效果时,Agora 推荐使用 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 时,Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 MusicHighQualityStereo (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法不能与 setLocalVoiceChanger 方法一同使用,否则先调的方法会不生效。更多注意事项,详见进阶功能《变声与混响》。
- 该方法在加入频道前后都能调用。
参数
- preset
本地语音混响选项,默认值为 Off ,即原声。详见 AudioReverbPreset 。为达到更好的混响效果,Agora 推荐使用以
AUDIO_REVERB_FX
为前缀的枚举值。
setLogFile
设置 Agora 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 写入最新的日志。
参数
- filePath
-
日志文件的完整路径。默认路径为
C:\Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log
。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。
setLogFileSize
设置 Agora 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 写入最新的日志。
参数
- fileSizeInKBytes
- 单个日志文件的大小,单位为 KB。默认值为 1024 KB。如果你将 fileSizeInKByte 设为 1024 KB,SDK 会最多输出 5 MB 的日志文件。 如果你将 fileSizeInKByte 设为小于 1024 KB,单个日志文件最大仍为 1024 KB。
setLogFilter
设置日志输出等级。
Future<void> setLogFilter(LogFilter filter);
- 弃用:
- 请改用 createWithContext 中的 logConfig。
该方法设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 WARNING 级别,就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。
参数
- filter
- 日志过滤等级。详见 LogFilter。
setMaxMetadataSize
设置媒体附属信息的最大大小。
Future<void> setMaxMetadataSize(int size);
调用 registerMediaMetadataObserver 后,你可以调用本方法来设置媒体附属信息的最大大小。
参数
- size
- 媒体附属信息的最大大小。
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false
) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 apiCallExecuted 中返回。
参数
- userId
- 用户 ID。
- streamType
-
默认订阅的视频流类型: VideoStreamType 。
setRemoteSubscribeFallbackOption
设置弱网条件下订阅的音视频流的回退选项。
Future<void> setRemoteSubscribeFallbackOption(StreamFallbackOptions option);
网络不理想的环境下,直播音视频的质量都会下降。如果你使用本方法并将 option 设置为 VideoStreamLow(1) 或 AudioOnly(2),SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 remoteSubscribeFallbackToAudioOnly 回调。
参数
- option
- 详见 StreamFallbackOptions。默认 option 为 VideoStreamLow(1)。
setRemoteUserPriority
设置远端用户媒体流的优先级。
Future<void> setRemoteUserPriority(int uid, UserPriority userPriority);
设置远端用户的优先级。如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。弱网下 SDK 会优先保证高优先级用户收到的流的质量。
- 目前 Agora SDK 仅允许将一名远端用户设为高优先级。
- 该方法需要在加入频道前调用。
参数
- uid
- 远端用户的 ID。
- userPriority
- 远端用户的需求优先级。详见: UserPriority。
setRemoteVideoStreamType
设置订阅的视频流类型。
Future<void> setRemoteVideoStreamType(int userId, VideoStreamType streamType);
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(false) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 apiCallExecuted 中返回。
参数
- 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);
Agora SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 None,即无指定的内容类型。
参数
- contentHint
- 屏幕共享的内容类型。详见 VideoContentHint。
setVideoEncoderConfiguration
设置视频编码属性。
Future<void> setVideoEncoderConfiguration(VideoEncoderConfiguration config);
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
setVoiceBeautifierParameters
设置预设美声效果的参数。
Future<void> setAudioEffectParameters( AudioEffectPreset preset, int param1, int param2);
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3),并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierParameters,Agora 不推荐调用以下方法,否则 setVoiceBeautifierParameters 设置的效果会被覆盖:
参数
- preset
- 预设的音效:
SINGING_BEAUTIFIER
: 歌唱美声。
- param1
- 歌声的性别特征:
1
: 男声。2
: 女声。
- param2
- 歌声的混响效果:
1
: 歌声在小房间的混响效果。2
: 歌声在大房间的混响效果。3
: 歌声在大厅的混响效果。
setVoiceBeautifierPreset
设置预设的美声效果。
Future<void> setVoiceBeautifierPreset(VoiceBeautifierPreset preset);
调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 GameStreaming(3),并将 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierPreset,Agora 不推荐调用以下方法,否则 setVoiceBeautifierPreset 设置的效果会被覆盖:
参数
- preset
-
预设的美声效果选项,详见 VoiceBeautifierPreset。
setVoiceConversionPreset
设置预设的变声效果。
Future<void> setVoiceConversionPreset(VoiceConversionPreset preset);
- 自从
- v3.3.1
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的变声效果,各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 profile 设为 MusicHighQuality(4) 或 MusicHighQualityStereo(5),并将 scenario 设为 GameStreaming(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 SpeechStandard(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceConversionPreset 后,Agora 不推荐调用以下方法,否则 setVoiceConversionPreset 设置的效果会被覆盖:
参数
- preset
预设的变声效果选项: VoiceConversionPreset。
setVolumeOfEffect
实时调整音效文件的播放音量。
Future<void> setVolumeOfEffect(int soundId, int volume);
参数
- 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)。 - 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以 /assets/ 开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 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。
- .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);
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 Medium,录音时长为 10 分钟的文件大小约为 2 M。
用户离开频道后,录音会自动停止。
参数
- config
- 录音配置。详见 AudioRecordingConfiguration。
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
Future<void> startChannelMediaRelay( ChannelMediaRelayConfiguration channelMediaRelayConfiguration);
- 如果 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);
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- lastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- lastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 enableLastmileTest 同时使用。
- 调用该方法后,在收到 lastmileQuality 和 lastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 LastmileProbeConfig。
startPreview
开启视频预览。
Future<void> startPreview();
该方法用于在进入频道前启动本地视频预览。调用该 API 前,必须:
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 启用了本地视频预览后,如果调用 leaveChannel退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 stopPreview。
startScreenCapture
开始屏幕共享。
Future<void> startScreenCapture(int windowId, [int captureFreq, Rect? rect, int bitrate]);
- 弃用:
- 请使用以下方法作为替代:
- 共享整个屏幕:将 windowId 设为 0,且将 rect 设为 null。
- 共享指定窗口:将 windowId 设为非 0,每个窗口都有一个非 0 的 windowId。
- 共享指定区域:将 windowId 设为 0,且将 rect 设为非 null。在这个情况下,你可以共享指定区域,例如你可以拖动鼠标选中要共享的区域,但这个逻辑你由你自己实现的。这里的共享指定区域指的是共享整个屏幕里的某个区域。目前暂不支持共享指定窗口里的指定区域。
参数
- windowId
- 共享屏幕区域。
- captureFreq
- 共享屏幕的帧率,必须设置,范围是 1 到 15 fps。
- rect
- 屏幕共享区域,详见 Rect 当 windowId 设为 0 时该参数有效;当你将 rect 设为 null 时,整个屏幕被共享。
- bitrate
- 共享屏幕的码率。
startScreenCaptureByDisplayId
通过屏幕 ID 共享屏幕。
Future<void> startScreenCaptureByDisplayId(int displayId, [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);
共享一个屏幕或该屏幕的部分区域。用户需要在该方法中指定想要共享的屏幕 ID。
- 该方法仅适用于 macOS。
- 该方法需要在加入频道后调用。
参数
- displayId
- 指定待共享的屏幕 ID。开发者需要通过该参数指定你要共享的那个屏幕。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界,则只共享屏幕视窗内的内容;如果宽或高为 0,则共享整个屏幕。
- captureParams
- 屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
startScreenCaptureByScreenRect
通过指定区域共享屏幕。
Future<void> startScreenCaptureByScreenRect(Rectangle screenRect, [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);
共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。
参数
- screenRect
- 指定待共享的屏幕相对于虚拟屏的位置。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
startScreenCaptureByWindowId
通过窗口 ID 共享窗口。
Future<void> startScreenCaptureByWindowId(int windowId, [Rectangle? regionRect, ScreenCaptureParameters? captureParams]);
共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。
参数
- windowId
- 指定待共享的窗口 ID。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
- captureParams
- 屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
stopAllEffects
停止播放所有音效文件。
Future<void> stopAllEffects();
stopAudioMixing
停止播放音乐文件。
Future<void> stopAudioMixing();
该方法停止播放音乐文件。请在频道内调用该方法。
stopAudioRecording
停止客户端录音。
Future<void> stopAudioRecording();
如果你调用了 startAudioRecordingWithConfig 开始录音,可以调用该方法停止录音。
stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
Future<void> stopChannelMediaRelay();
成功调用该方法后,SDK 会触发 channelMediaRelayStateChanged 回调。如果报告 Idle (0) 和 None (0),则表示已停止转发媒体流。
stopEchoTest
停止语音通话回路测试。
Future<void> stopEchoTest();
stopEffect
停止播放指定音效文件。
Future<void> stopEffect(int soundId);
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
stopLastmileProbeTest
停止通话前网络质量探测。
Future<void> stopLastmileProbeTest();
stopPreview
停止视频预览。
Future<void> stopPreview();
stopScreenCapture
停止屏幕共享。
Future<void> stopScreenCapture();
switchCamera
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 格式的图片,并保存至指定的路径。
- 该方法需要在加入频道后调用。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- 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)。
参数
- channelMediaRelayConfiguration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
updateScreenCaptureParameters
更新屏幕共享的参数配置。
Future<void> updateScreenCaptureParameters( ScreenCaptureParameters captureParams);
参数
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
updateScreenCaptureRegion
更新屏幕共享区域。
Future<void> updateScreenCaptureRegion(Rectangle regionRect);
参数
- regionRect
- 待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见 Rectangle。 如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕或窗口。
uploadLogFile
上传所有本地的 SDK 日志文件。
Future<String?> uploadLogFile();
- 自从
- v3.3.0
将客户端的所有日志文件上传至 Agora 服务器。成功调用该方法后,SDK 会触发 uploadLogResult 回调报告日志文件是否成功上传至 Agora 服务器。
为了方便排查问题,Agora 推荐你将 uploadLogFile 方法与应用的 UI 元素绑定,在出现质量问题时提示用户上传日志。
返回值
- 方法调用成功: 返回请求 ID。该请求 ID 与 uploadLogResult 回调中的 requestId 一致。你可以通过 requestId 将特定的上传和回调对应起来。
- 方法调用失败: 返回 null。可能是因为调用频率超出限制。