AgoraRtcEngine
Agora Native SDK 的基础接口类,实现实时音视频的主要功能。
AgoraRtcEngine 提供了 app 调用的主要方法。
addInjectStreamUrl
输入在线媒体流。
addInjectStreamUrl(url: string, config: InjectStreamConfig): number
- 请确保已开通旁路推流的功能,详见推流到 CDN 中的前提条件。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 频道内同一时间只允许输入一个在线媒体流。
- 该方法需要在加入频道后调用。
该方法将正在播放的音视频作为音视频源导入到正在进行的直播中。可主要应用于赛事直播、多人看视频互动等直播场景。调用该方法后,SDK 会在本地触发 STREAM_INJECT_STATUS 回调,报告输入在线媒体流的状态;成功输入媒体流后,该音视频流会出现在频道中,频道内所有用户都会收到 USER_JOINED 回调,其中 uid 为 666。
参数
- url
-
添加到直播中的视频流 URL 地址。支持 RTMP、HLS、HTTP-FLV 协议传输。
- 支持的音频编码格式:AAC;
- 支持的视频编码格式:H.264(AVC)。
- config
- 所添加的视频流属性定义,详见: InjectStreamConfig 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
ERR_INVALID_ARGUMENT
(2): 输入的 URL 为空。请重新调用该方法,并确认输入的媒体流的 URL 有效。ERR_NOT_READY
(3): 用户没有加入频道。ERR_NOT_SUPPORTED
(4): 频道非直播场景。请调用 setChannelProfile 并将频道设置为直播场景再调用该方法。ERR_NOT_INITIALIZED
(7): 引擎没有初始化。请确认调用该方法前已创建 AgoraRtcEngine 对象并完成初始化。
addPublishStreamUrl
增加旁路推流地址。
addPublishStreamUrl(url: string, transcodingEnabled: boolean): number
调用该方法后,你可以向 CDN 推送 RTMP 或 RTMPS 协议的媒体流。SDK 会在本地触发 RTMP_STREAMING_STATE_CHANGED 回调,报告增加旁路推流地址的状态。
- 该方法需要在加入频道后调用。
- 请确保已开通旁路推流的功能,详见进阶功能推流到 CDN 中的前提条件。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法每次只能增加一路旁路推流地址。若需推送多路流,则需多次调用该方法。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- url
- CDN 推流地址,格式为 RTMP 或 RTMPS。该字符长度不能超过 1024 字节。url 不支持中文字符等特殊字符。
- transcodingEnabled
-
是否转码。转码是指在旁路推流时对音视频流进行转码处理后再推送到其他 CDN 服务器。多适用于频道内有多个主播,需要进行混流、合图的场景。
true
: 转码。false
: 不转码。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
ERR_INVALID_ARGUMENT
(2): 参数无效,一般是 URL 为空或是长度为 0 的字符串。ERR_NOT_INITIALIZED
(7): 推流时未初始化引擎。
addVideoWatermark
添加本地视频水印。
addVideoWatermark(watermarkUrl: string, options: WatermarkOptions): number
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(ORIENTATION_MODE) 固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(ORIENTATION_MODE) 固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用本方法。
- 如果你只是在旁路直播(推流到 CDN)中添加水印,你可以使用本方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。本方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在本方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview 方法开启本地视频预览,那么本方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。本方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
adjustAudioMixingPlayoutVolume(volume: number): number
参数
- volume
- 音乐文件音量范围为 [0,100]。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
adjustAudioMixingPublishVolume(volume: number): number
该方法调节混音音乐文件在远端的播放音量大小。
参数
- volume
- 音乐文件音量。范围为 [0,100]。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingVolume
调节音乐文件的播放音量。
adjustAudioMixingVolume(volume: number): number
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing 后调用。
- 调用该方法不影响调用 playEffect 播放音效文件的音量。
参数
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
adjustPlaybackSignalVolume(volume: number): number
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 从 v2.3.2 开始,静音本地音频需同时调用
adjustPlaybackSignalVolume
和 adjustAudioMixingPlayoutVolume 方法,并将volume
设置为0
。 - 该方法在加入频道前后都能调用。
参数
- volume
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustRecordingSignalVolume
调节音频采集信号音量。
adjustRecordingSignalVolume(volume: number): number
该方法在加入频道前后都能调用。
参数
- volume
-
麦克风采集信号音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
adjustUserPlaybackSignalVolume(uid: number, volume: number): number
- 自从
- v3.0.0
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
-
播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarks
删除已添加的视频水印。
clearVideoWatermarks(): number
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
complain
投诉通话质量。
complain(callId: string, description: string): number
该方法允许用户就通话质量进行投诉。需要在离开频道后调用。
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- description
- (非必选项)给通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(
ERR_INVALID_ARGUMENT
)。 - -3(
ERR_NOT_READY
)。
- -2(
initializeWithContext
创建并初始化 AgoraRtcEngine。
initializeWithContext(context: RtcEngineContext): number
请确保在调用其他 API 前先调用 initializeWithContext 创建并初始化 AgoraRtcEngine。
参数
- context
-
AgoraRtcEngine 实例的配置。详见 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 无效。
createChannel
创建并获取一个 AgoraRtcChannel 对象。
createChannel(channelId: string): (AgoraRtcChannel | null)
你可以多次调用该方法,创建多个 AgoraRtcChannel 对象,再调用各 AgoraRtcChannel 对象中的 joinChannel 方法,实现同时加入多个频道。
加入多个频道后,你可以同时订阅各个频道的音、视频流;但是同一时间只能在一个频道发布一路音、视频流。
参数
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道 进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
注意:- 参数没有默认值,请确保对参数设值。
- 请勿将该参数设为空字符
""
,否则 SDK 会返回ERR_REFUSED
(5)。
返回值
- 方法调用成功,返回 AgoraRtcChannel 对象。
- 方法调用失败,返回
null
。
createDataStream
创建数据流。
createDataStream(reliable: boolean, ordered: boolean): number
- 弃用:
- 该方法从 v3.3.0 起废弃。请改用 createDataStreamWithConfig。
在 AgoraRtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。
- 该方法需要在加入频道后调用。
- 不可将 reliable 设为
true
且将 ordered 设为true
。
参数
- reliable
- 该数据流是否可靠:
true
: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 STREAM_MESSAGE_ERROR 回调并获得相应报错信息。true
: 接收方不保证收到,就算数据丢失也不会报错。
- ordered
- 该数据流是否有序:
true
: 接收方会按照发送方发送的顺序收到数据包。true
: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 成功创建的数据流 ID:方法调用成功。
- < 0: 创建数据流失败。你可以参考错误码和警告码进行问题排查。
createDataStreamWithConfig
创建数据流。
createDataStreamWithConfig(config: DataStreamConfig): number
该方法用于创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStream,该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- config
- 数据流设置。详见 DataStreamConfig。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。你可以参考错误码和警告码进行问题排查。
destroyRenderer
disableAudio
关闭音频模块。
disableAudio(): number
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。leaveChannel 后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableLastmileTest
关闭网络测试。
disableLastmileTest(): number
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
disableVideo
关闭视频模块。
disableVideo(): number
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 USER_ENABLE_VIDEO (false
) 回调。
- 该方法设置的是内部引擎为禁用状态,在 leaveChannel 后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudio
启用音频模块。
enableAudio(): number
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在 leaveChannel 后仍然有效。
- 该方法开启整个音频模块,响应时间较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudioVolumeIndication
启用用户音量提示。
enableAudioVolumeIndication(interval: number, smooth: number, report_vad: boolean = false): number
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户, SDK 会在加入频道后按设置的时间间隔触发 AUDIO_VOLUME_INDICATION 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒。建议设置到大于 200 毫秒。最小不得少于 10 毫秒,否则会收不到 AUDIO_VOLUME_INDICATION 回调。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- report_vad
-
true
:开启本地人声检测功能。开启后,AUDIO_VOLUME_INDICATION 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,AUDIO_VOLUME_INDICATION 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDeepLearningDenoise
开启或关闭 AI 降噪模式。
enableDeepLearningDenoise(enable: boolean): number
- 自从
- v3.3.0
- 确保已集成如下动态库:
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 不推荐调用该方法处理含音乐的音频数据。
参数
- enabled
- 是否开启 AI 降噪模式:
true
:(默认)开启 AI 降噪模式。false
: 关闭 AI 降噪模式。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -157(
ERR_MODULE_NOT_FOUND
): 未集成用于 AI 降噪的动态库。
- -157(
enableDualStreamMode
开关双流模式。
enableDualStreamMode(enabled: boolean): number
该方法开启或关闭双流模式。发送端开启双流模式后,接收端可以选择接收大流还是小流。其中,大流指高分辨率、高码率的视频流,小流指低分辨率、低码率的视频流。
参数
- enabled
-
true
: 开启双流模式。false
: 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableEncryption
开启或关闭内置加密。
enableEncryption(enabled: boolean, config: EncryptionConfig): number
- 自从
- v3.1.0
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功
-
< 0: 方法调用失败
- -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
- -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 AgoraRtcEngine 对象并完成初始化。
enableLastmileTest
启用网络测试。
enableLastmileTest(): number
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
无论哪种场景,启用该方法均会消耗网络流量,影响通话质量。用户必须在收到 LASTMILE_QUALITY 回调后须调用 disableLastmileTest 停止测试,再加入频道或切换为主播。
- 该方法请勿与 startLastmileProbeTest 同时使用。
- 调用该方法后,在收到 LASTMILE_QUALITY 回调前请勿调用其他方法,否则可能由于 API 操作过于频繁导致回调无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
- 加入频道前调用该方法检测网络质量后,SDK 会占用一路视频的带宽,码率与 setVideoEncoderConfiguration 中设置的码率相同。加入频道后,无论是否调用了 disableLastmileTest,SDK 均会自动停止带宽占用。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalAudio
开关本地音频采集。
enableLocalAudio(enabled: boolean): number
当用户加入频道时,音频功能默认是开启的。该方法可以关闭或重新开启本地音频功能,即停止或重新开始本地音频采集。
该方法不影响接收或播放远端音频流,enableLocalAudio(false
) 适用于只听不发的用户场景。
- 该方法与 muteLocalAudioStream 的区别在于:
- enableLocalVideo: 开启或关闭本地音频采集及处理。使用
enableLocalAudio
关闭或开启本地采集后,本地听远端播放会有短暂中断。 - muteLocalAudioStream: 停止或继续发送本地音频流。
- enableLocalVideo: 开启或关闭本地音频采集及处理。使用
- 该方法在加入频道前后都能调用。
参数
- enabled
true
: 重新开启本地音频功能,即开启本地音频采集(默认);false
: 关闭本地音频功能,即停止本地音频采集。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalVideo
开关本地视频采集。
enableLocalVideo(enabled: boolean): number
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频采集即默认开启。你可以调用 enableLocalVideo(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true
)。
成功禁用或启用本地视频采集后,远端会触发 USER_ENABLE_LOCAL_VIDEO 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在 leaveChannel 后仍然有效。
参数
- enabled
-
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLoopbackRecording
开启声卡采集。
enableLoopbackRecording( enabled = false, deviceName: string | null = null ): number
启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。
- macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 是否开启声卡采集:
true
: 开启声卡采集。false
:(默认)关闭声卡采集。
- deviceName
- 声卡的设备名。默认设为 null,即使用当前声卡采集。 如果用户使用虚拟声卡,如 "Soundflower",可以将虚拟声卡名称 "Soundflower" 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enablePlugin
开启或关闭指定的插件。
enablePlugin(pluginId: string, enabled: boolean): number
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- enabled
- 是否开启插件:
true
:开启插件。false
:关闭插件。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
enableSoundPositionIndication
开启/关闭远端用户的语音立体声。
enableSoundPositionIndication(enabled: boolean)
如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用该方法开启远端用户的语音立体声。
参数
- enabled
- 是否开启远端用户语音立体声:
true
: 开启语音立体声。false
: 关闭语音立体声。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableVideo
启用视频模块。
enableVideo(): number
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。 调用 disableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 REMOTE_VIDEO_STATE_CHANGED 回调。
- 该方法设置的是内部引擎为启用状态,在 leaveChannel 后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableWebSdkInteroperability
打开与 Web SDK 的互通(仅在直播场景适用)。
enableWebSdkInteroperability(enabled: boolean): number
- 弃用:
- 该方法从 v3.0.0 起废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Agora Web SDK 的互通:
true
: 打开互通。false
: (默认) 关闭互通。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAudioPlaybackDevices
getAudioRecordingDevices
getVideoDevices
getAudioMixingCurrentPosition
获取音乐文件的播放进度。
getAudioMixingCurrentPosition(): number
该方法获取当前音乐文件播放进度,单位为毫秒。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功返回音乐文件播放进度。
- < 0: 方法调用失败。
getAudioMixingDuration
获取音乐文件的时长。
getAudioMixingDuration(filePath?: string): number
- 自从
- v3.4.0
参数
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
C:\music\audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Supported Media Formats in Media Foundation。
返回值
- ≥ 0: 方法调用成功返回音乐文件时长(毫秒)。
- < 0: 方法调用失败。
getAudioMixingPlayoutVolume
获取音乐文件的本地播放音量。
getAudioMixingPlayoutVolume(): number
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioMixingPublishVolume
获取音乐文件的远端播放音量。
getAudioMixingPublishVolume(): number
该接口可以方便开发者排查音量相关问题。
PLAY
) 回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getCallId
getConnectionState
获取当前网络连接状态。
getConnectionState(): CONNECTION_STATE_TYPE
- 自从
- v2.3.2
该方法在加入频道前后都能调用。
返回值
当前网络连接的状态。详见 CONNECTION_STATE_TYPE。
getCurrentVideoDevice
getEffectCurrentPosition
获取指定音效文件的播放进度。
getEffectCurrentPosition(soundId: number): number
参数
- sound
- 音效 ID。请确保与 playEffect 中设置的 soundId 一致。
返回值
- ≥ 0:方法调用成功,返回指定音效文件的播放进度(毫秒)。
- < 0:方法调用失败。
getEffectDuration
获取指定音效文件总时长。
getEffectDuration(filePath: string): number
参数
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
C:\music\audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Supported Media Formats in Media Foundation。
返回值
- ≥ 0:方法调用成功,返回指定音效文件时长(毫秒)。
- < 0:方法调用失败。
getEffectsVolume
获取音效文件的播放音量。
getEffectsVolume(): number
音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 音效文件的音量。
- < 0: 方法调用失败
getErrorDescription
获取警告或错误描述。
getErrorDescription(errorCode: number): string
参数
- code
- SDK 报告的错误码或警告码。
返回值
具体的错误或警告描述。你可以参考错误码和警告码进行问题排查。
getCurrentAudioPlaybackDevice
getAudioPlaybackDeviceMute
获取当前播放设备静音状态。
getAudioPlaybackDeviceMute(): boolean
返回值
true
: 播放设备为静音状态。false
: 播放设备为非静音状态。
getAudioPlaybackVolume
获取播放设备音量。
getAudioPlaybackVolume(): number
返回值
播放设备音量。取值范围 [0,255]。
getPluginParameter
获取指定插件的参数。
getPluginParameter(pluginId: string, key: string): string
如果你想在使用插件时将 JSON 字符串数据传递给 C++ 层,你需要调用 getPluginParameter 和 setPluginParameter 获取并设置参数。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- key
- Key 值。
返回值
Key 值对应的 Value 值。
getPlugins
getCurrentAudioRecordingDevice
getAudioRecordingDeviceMute
获取当前音频采集设备静音状态。
getAudioRecordingDeviceMute(): boolean
返回值
true
: 采集设备为静音状态。false
: 采集设备为非静音状态。
getAudioRecordingVolume
获取音频采集设备音量。
getAudioRecordingVolume(): number
返回值
音频采集设备音量。取值范围 [0,255]。
getScreensInfo
获取屏幕信息。
getScreensInfo(): Array<Object>
使用标识屏幕的 Display ID(macOS 系统)或 ScreenRect(Windows 系统)共享屏幕前,你需要调用该方法获取屏幕信息。
返回值
包含屏幕信息的对象。Windows 系统和 macOS 系统中返回的屏幕信息不同。你无需了解该对象的具体内容,直接使用该对象进行屏幕共享。
getUserInfoByUid
通过 UID 获取用户信息。
getUserInfoByUid(uid: number): { errCode: number; userInfo: UserInfo }
- 自从
- v2.8.0
远端用户加入频道后, SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 USER_INFO_UPDATED 回调。
收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- uid
- 用户 ID。该参数为必填。
- userInfo
- 标识用户信息的 UserInfo 对象。详见 UserInfo 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
getUserInfoByUserAccount(userAccount: string): { errCode: number; userInfo: UserInfo }
- 自从
- v2.8.0
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表, 并在本地触发 USER_INFO_UPDATED 回调。
收到这个回调后,你可以调用该方法,通过传入 User Account 获取包含了指定用户 UID 的 UserInfo 对象。
参数
- userAccount
- 用户 User Account。该参数为必填。
- userInfo
- 标识用户信息的 UserInfo 对象。详见 UserInfo 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getVersion
获取 SDK 版本。
getVersion(): string
返回值
当前的 SDK 版本号。格式为字符串,如 3.3.0。
getWindowsInfo
获取窗口信息。
getWindowsInfo(): Array<WindowInfo>
使用标识窗口的 Window ID 共享窗口前,你需要调用该方法获取窗口信息。
返回值
WindowInfo 数组:WindowInfo。
joinChannel
加入频道并设置是否自动订阅音频或视频流。
joinChannel( token: string, info: string, uid: number, options?: ChannelMediaOptions ): number
- 自从
- v3.3.0
该方法让用户加入实时音视频互动频道。在 App ID 一致的前提下,进入同一个频道的用户可以互相通话;多个用户加入同一个频道可以群聊。
- 本地会触发 JOINED_CHANNEL 和 CONNECTION_STATE_CHANGED 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 USER_JOINED 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 REJOIN_CHANNEL_SUCCESS 回调。
参数
- token
-
在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
警告: 请确保用于生成 token 的 App ID、频道名和用户名和 initializeWithContext 方法初始化引擎时用的 App ID,以及该方法中设置的频道名和用户名是一致的。 - channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道 进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- info
-
预留参数。
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。 建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 JOINED_CHANNEL 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -3(ERR_NOT_READY): SDK 初始化失败,请尝试重新初始化 SDK。
- -5(ERR_REFUSED): 调用被拒绝。可能有如下两个原因:
- 已经创建了一个同名的 AgoraRtcChannel 频道。
- 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化,就调用该方法。请确认在调用 API 之前已经创建 AgoraRtcEngine 对象并完成初始化。
joinChannelWithUserAccount
使用 User Account 加入频道,并设置是否自动订阅音频或视频流。
joinChannelWithUserAccount( token: string, channelId: string, userAccount: string, options?: ChannelMediaOptions ): number
- 自从
- v3.3.0
- 本地:LOCAL_USER_REGISTERED、JOINED_CHANNEL 和 CONNECTION_STATE_CHANGED 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 USER_JOINED 和 USER_INFO_UPDATED 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
-
在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
警告: 请确保用于生成 token 的 App ID、频道名和用户名和 initializeWithContext 方法初始化引擎时用的 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): 调用被拒绝。可能有如下两个原因:
- 已经创建了一个同名的 AgoraRtcChannel 频道。
- 已经通过 AgoraRtcChannel 加入了一个频道,并在该 AgoraRtcChannel 频道中发布了音视频流。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化,就调用该方法。请确认在调用 API 之前已经创建 AgoraRtcEngine 对象并完成初始化。
leaveChannel
离开频道。
leaveChannel(): number
该方法会把会话相关的所有资源释放掉。该方法是异步操作,调用返回时并没有真正退出频道。
调用 joinChannel 后,必须调用 leaveChannel 结束通话,否则无法开始下一次通话。
- 本地:LEAVE_CHANNEL 回调。
- 远端:通信场景下的用户和直播场景下的主播离开频道后,远端会触发 USER_OFFLINE 回调。
- 如果你调用了 leaveChannel 后立即调用 release 方法,SDK 将无法触发 LEAVE_CHANNEL 回调。
- 如果你在旁路推流过程中调用了 leaveChannel 方法,SDK 将自动调用 removePublishStreamUrl 方法。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
muteAllRemoteAudioStreams(mute: boolean): number
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见设置订阅状态。
参数
- mute
- 是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
muteAllRemoteVideoStreams(mute: boolean): number
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
muteLocalAudioStream(mute: boolean): number
成功调用该方法后,远端会触发 USER_MUTE_AUDIO 回调。
- 该方法不影响音频采集状态,因为没有禁用音频采集设备。
- 该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法, SDK 会根据你设置的频道场景以及用户角色,重新设置是否取消发布本地音频。因此我们建议在 setChannelProfile 后调用该方法。
参数
- mute
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStream
取消或恢复发布本地视频流。
muteLocalVideoStream(mute: boolean): number
成功调用该方法后,远端会触发 USER_MUTE_VIDEO 回调。
- 相比于 enableLocalVideo(
false
) 用于控制本地视频流发送的方法,该方法响应速度更快。 - 该方法不影响视频采集状态,没有禁用摄像头。
- 该方法在加入频道前后都能调用。如果你在该方法后调用 setChannelProfile 方法,SDK 会根据你设置的频道场景以及用户角色,重新设置是否停止发送本地视频。因此我们建议在 setChannelProfile 后调用该方法。
参数
- mute
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
muteRemoteAudioStream(userId: number, mute: boolean): number
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- userId
- 指定用户的用户 ID。
- mute
是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
muteRemoteVideoStream(userId: number, mute: boolean): number
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- userId
-
指定用户的用户 ID。
- mute
是否取消订阅指定远端用户的视频流。
true
: 取消订阅指定用户的视频流。false
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllEffects
暂停所有音效文件播放。
pauseAllEffects(): number
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseAudioMixing
暂停播放音乐文件。
pauseAudioMixing(): number
请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pauseEffect
暂停音效文件播放。
pauseEffect(soundId: number): number
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
playEffect
播放指定的本地或在线音效文件。
playEffect(soundId: number, filePath: string, loopCount: number, pitch: number, pan: number, gain: number, publish: number, startPos?: number ): number
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
C:\music\audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Supported Media Formats in Media Foundation。- 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:方法调用失败。
preloadEffect
将音效文件加载至内存。
preloadEffect(soundId: number, filePath: string): number
为保证通信畅通,请注意控制预加载音效文件的大小,并在 joinChannel 前就使用该方法完成音效预加载。音频文件支持以下音频格式: mp3、aac、m4a、3gp 和 wav。
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
C:\music\audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Supported Media Formats in Media Foundation。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
rate
给通话评分。
rate(callId: string, rating: number, description: string): number
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- rating
- 给通话的评分,最低 1 分,最高 5 分,如超过这个范围,SDK 会返回 -2(
ERR_INVALID_ARGUMENT
) 错误。 - description
- (非必选项)给通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(
ERR_INVALID_ARGUMENT
)。 - -3(
ERR_NOT_READY
)。
- -2(
registerLocalUserAccount
注册本地用户 User Account。
registerLocalUserAccount(appId: string, userAccount: string): number
- 自从
- v2.8.0
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 LOCAL_USER_REGISTERED 回调,告知本地用户的 UID 和 User Account。
- 先调用 registerLocalUserAccount 方法注册 Account,再调用 joinChannelWithUserAccount 方法加入频道。
- 直接调用 joinChannelWithUserAccount 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount 进入频道的时间。
- userAccount 不能为空,否则该方法不生效。
- 请确保在该方法中设置的 User Account 在频道中的唯一性。
- 为保证通信质量,请确保频道内使用同一类型的数据标识用户身份。即同一频道内需要统一使用 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
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerMediaMetadataObserver
注册媒体 metadata 观测器用于接收或发送 metadata。
registerMediaMetadataObserver(type: METADATA_TYPE = 0): number
- 自从
- v2.4.1
- 请在 joinChannel 前调用该方法。
- 该方法仅适用于直播场景。
参数
- type
- 用户希望在观测器中使用的 METADATA 类型 。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerPlugin
注册插件。
registerPlugin(pluginInfo: PluginInfo): number
注册插件后,你可以在 SDK 中使用插件的功能。举例来说,如果你想使用 FaceUnity 的插件,你可以先将该插件文件集成到 SDK 的项目工程文件中,然后调用该方法注册插件。
- 调用 getPlugins 方法,并通过 Plugin 接口中的 enable、disable、setParameter、getParameter 函数开启插件,关闭插件,设置插件参数,获取插件参数。
- 调用 enablePlugin、setPluginParameter、getPluginParameter 方法,开关插件、设置插件参数、获取插件参数。
参数
- pluginInfo
- 插件信息。详见 PluginInfo。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
release
销毁 AgoraRtcEngine 对象。
release(sync: boolean = false): number
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。
参数
- sync
-
true
: 该方法为同步调用。需要等待 AgoraRtcEngine 资源释放后才能执行其他操作,所以我们建议在子线程中调用该方法,避免主线程阻塞。此外,我们不建议在 SDK 的回调中调用 release,否则由于 SDK 要等待回调返回才能回收相关的对象资源,会造成死锁。SDK 会自动检测这种死锁并转为异步调用,但是检测本身会消耗额外的时间。false
: 该方法为异步调用。不需要等待 AgoraRtcEngine 资源释放后就能执行其他操作。使用异步调用时要注意,不要在该调用后立即卸载 SDK 动态库,否则可能会因为 SDK 的清理线程还没有退出而崩溃。
removeInjectStreamUrl
删除导入的外部媒体流。
removeInjectStreamUrl(url: string): number
成功删除外部视频源 URL 地址后会触发 USER_OFFLINE 回调,uid 为
666
。
参数
- url
- 已导入、待删除的外部视频源 URL 地址。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
removePublishStreamUrl
删除旁路推流地址。
removePublishStreamUrl(url: string): number
调用该方法后,SDK 会在本地触发 RTMP_STREAMING_STATE_CHANGED 回调,报告删除旁路推流地址的状态。
- 调用该方法前,请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 该方法需要在加入频道后调用。
- 该方法每次只能删除一路旁路推流地址。若需删除多路流,则需多次调用该方法。
参数
- url
- 待删除的旁路推流地址,格式为 RTMP。该字符长度不能超过 1024 字节。推流地址不支持中文等特殊字符。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
renewToken
更新 Token。
renewToken(token: string): number
- 发生 TOKEN_PRIVILEGE_WILL_EXPIRE 回调时。
- CONNECTION_STATE_CHANGED 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
- token
- 新的 Token。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
resumeAllEffects
恢复播放所有音效文件。
resumeAllEffects(): number
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeAudioMixing
恢复播放音乐文件。
resumeAudioMixing(): number
该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
resumeEffect
恢复播放指定音效文件。
resumeEffect(soundId: number): number
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
sendCustomReportMessage
发送自定义上报消息。
sendCustomReportMessage(id: string, category: string, event: string, label: string, value: number): number
- 自从
- v3.1.0
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。 如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendMetadata
发送媒体附属信息。
sendMetadata(metadata: Metadata): number
成功调用 registerMediaMetadataObserver 方法后,SDK 会触发 READY_TO_SEND_METADATA 回调,你可以调用该方法发送媒体附属信息。
如果成功发送了媒体附属信息,接收端会收到 METADATA_RECEIVED 回调。
参数
- metadata
- 媒体附属信息。详见 Metadata。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
sendStreamMessage
发送数据流。
sendStreamMessage(streamId: number, data: string): number
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 STREAM_MESSAGE 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 STREAM_MESSAGE_ERROR 回调。
- 请确保在调用该方法前,已调用 createDataStreamWithConfig 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
参数
- streamId
- 数据流 ID。可以通过 createDataStreamWithConfig 获取。
- data
- 待发送的数据。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAddonLogFile
设置 SDK 的 Electron 层的日志文件。
setAddonLogFile(filePath: string): number
参数
- filePath
- SDK 的 Electron 层的日志文件的完整路径。请确保你指定的目录存在且可写。你可以通过该参数修改日志文件名。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioEffectParameters
设置 SDK 预设人声音效的参数。
setAudioEffectParameters(preset: AUDIO_EFFECT_PRESET, param1: number, param2: number): number
详细描述
- 自从
- v3.2.0
- 3D 人声音效:设置 3D 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1) 或 AUDIO_PROFILE_IOT(6),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setAudioEffectParameters 后,Agora 不推荐调用以下方法,否则 setAudioEffectParameters 设置的效果会被覆盖:
参数
- preset
- SDK 预设的音效:
- 3D 人声音效:ROOM_ACOUSTICS_3D_VOICE
- 你需要在使用该枚举前将 setAudioProfile 的 profile 参数设置 为 AUDIO_PROFILE_MUSIC_STANDARD_STEREO(3) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5),否则该枚举设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- 电音音效:PITCH_CORRECTION。为获取更好的人声效果,Agora 建议你在使用该枚举前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO(5)。
- 3D 人声音效:ROOM_ACOUSTICS_3D_VOICE
- 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
: A2
: A#3
: B4
: (Default) C5
: C#6
: D7
: D#8
: E9
: F10
: F#11
: G12
: G#
- 如果 preset 设为 ROOM_ACOUSTICS_3D_VOICE,你需要将 param2 设置为
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioEffectPreset
设置 SDK 预设的人声音效。
setAudioEffectPreset(preset: AUDIO_EFFECT_PRESET): number
详细描述
- 自从
- v3.2.0
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
根据不同的场景,你可以为用户设置不同的音效,各音效的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_SPEECH_STANDARD(1) 或 AUDIO_PROFILE_IOT(6),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 如果调用 setAudioEffectPreset 并设置除 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION 外的枚举,请勿再调用 setAudioEffectParameters,否则 setAudioEffectPreset 设置的效果会被覆盖。
- 调用 setAudioEffectPreset 后,Agora 不推荐调用以下方法,否则 setAudioEffectPreset 设置的效果会被覆盖:
参数
- preset
- 预设的音效选项,详见 AUDIO_EFFECT_PRESET。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPitch
调整本地播放的音乐文件的音调。
setAudioMixingPitch(pitch: number): number
- 自从
- v3.0.1
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
PLAY
) 回调后调用该方法。参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPosition
设置音乐文件的播放位置。
setAudioMixingPosition(pos: number): number
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
PLAY
) 回调后调用该方法。参数
- pos
- 整数。进度条位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile
设置音频编码属性。
setAudioProfile(profile: AUDIO_PROFILE_TYPE, scenario: AUDIO_SCENARIO_TYPE): number
- 该方法需要在 joinChannel 之前设置好, joinChannel 之后设置不生效。
- 通信和直播场景下,音质(码率)会有网络自适应的调整,通过该方法设置的是一个最高码率。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY(4),scenario 设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。
参数
- profile
-
设置采样率,码率,编码模式和声道数,详见AUDIO_PROFILE_TYPE。
- scenario
- 设置音频应用场景,详见 AUDIO_SCENARIO_TYPE 。不同的音频场景下,设备的音量类型是不同的。详见如何区分媒体音量和通话音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setBeautyEffectOptions
设置美颜效果选项。
setBeautyEffectOptions(enabled: boolean, options: BeautyOptions): number
- 自从
- v3.0.0 (Windows), v3.2.0 (macOS)
开启本地美颜功能,并设置美颜效果选项。
该方法需要在 enableVideo 后调用。
参数
- enabled
- 是否开启美颜功能:
true
: 开启。false
:(默认)关闭。
- options
- 美颜选项,详细定义见 BeautyOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraCapturerConfiguration
设置摄像头采集配置。
setCameraCapturerConfiguration(config: CameraCapturerConfiguration): number
- 使用原始音视频数据自采集接口时,如果 SDK 输出的分辨率和帧率高于 setVideoEncoderConfiguration 中指定的参数,在后续处理视频帧的时候, 比如美颜功能时,会需要更高的 CPU 及内存,容易导致性能问题。在这种情况下,我们推荐将摄像头采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1), 避免性能问题。
- 如果没有本地预览功能或者对预览质量没有要求,我们推荐将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PERFORMANCE(1),以优化 CPU 和内存的资源分配。
- 如果用户希望本地预览视频比实际编码发送的视频清晰,可以将采集偏好设置为 CAPTURER_OUTPUT_PREFERENCE_PREVIEW(2)。
- 如果用户需要自定义本地采集的视频宽高,请将采集偏好设为 CAPTURER_OUTPUT_PREFERENCE_MANUAL(3)。
参数
- config
- 摄像头采集配置,详见 CameraCapturerConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setChannelProfile
设置频道场景。
setChannelProfile(profile: CHANNEL_PROFILE_TYPE): number
该方法用于设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannel 前调用和进行设置,进入频道后无法再设置。
参数
- profile
-
频道使用场景。详见 CHANNEL_PROFILE_TYPE。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2 (ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
setClientRole
设置直播场景下的用户角色。
setClientRole(role: CLIENT_ROLE_TYPE): number
在加入频道前和加入频道后均可调用该方法设置用户角色。
- 本地会触发 CLIENT_ROLE_CHANGED 回调。
- 远端会触发 USER_JOINED 或 USER_OFFLINE(USER_OFFLINE_BECOME_AUDIENCE) 回调。
参数
- role
-
直播场景里的用户角色。详见 CLIENT_ROLE_TYPE。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
setClientRoleWithOptions
设置直播场景下的用户角色和级别。
setClientRoleWithOptions(role: CLIENT_ROLE_TYPE, options: ClientRoleOptions): number
- 自从
- v3.2.0
在加入频道前和加入频道后均可调用该方法设置用户角色。
- 本地触发 CLIENT_ROLE_CHANGED 回调。
- 远端触发 USER_JOINED 或 USER_OFFLINE 回调。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以推流到 CDN 等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内,可以操作和享受到的服务级别。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。详见 CLIENT_ROLE_TYPE。
- options
- 用户具体设置,包含用户级别。详见 ClientRoleOptions。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITALIZED): SDK 尚未初始化。
setCloudProxy
设置 Agora 云代理服务。
setCloudProxy(type: CLOUD_PROXY_TYPE): number
- 自从
- 3.3.0
当用户防火墙限制 IP 和端口号时,你需要参考使用云代理开放相应 IP 和端口号,然后调用该方法开启云代理,并将 proxyType 设为 UDP_PROXY (1), 即使用 UDP 协议的云代理。
成功连接云代理后,SDK 会触发 CONNECTION_STATE_CHANGED ( CONNECTION_STATE_CONNECTING , CONNECTION_CHANGED_SETTING_PROXY_SERVER ) 回调。
如果你想关闭已设置的云代理,请调用 setCloudProxy (NONE_PROXY)。
如果你想更改已设置的云代理类型,请先调用 setCloudProxy (NONE_PROXY), 再调用 setCloudProxy 并传入你期望的 proxyType 值。
- Agora 推荐你在频道外调用该方法。
- 使用 UDP 协议的云代理时,推流到 CDN 和跨频道媒体流转发功能不可用。
参数
- proxyType
- 云代理类型,详见 CLOUD_PROXY_TYPE 。该参数为必填参数,如果你不赋值,SDK 会报错。
返回值
- 0: 方法调用成功。
-
< 0: 方法调用失败。
-
-2(
ERR_INVALID_ARGUMENT
): 传入的参数无效。 -
-7(
ERR_NOT_INITIALIZED
): SDK 尚未初始化。
-
-2(
setDefaultMuteAllRemoteAudioStreams
默认取消或恢复订阅远端用户的音频流。
setDefaultMuteAllRemoteAudioStreams(mute: boolean): number
- 弃用:
- 该方法自 v3.3.0 起废弃。
该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。
- 如果需要恢复订阅单个用户的音频流,调用 muteRemoteAudioStream (
false
),并指定你想要订阅的远端用户 ID。 - 如果想恢复订阅多个用户的音频流,则需要多次调用 muteRemoteAudioStream (
false
)。
参数
- mute
- 是否默认取消订阅远端用户的音频流:
true
:默认取消订阅远端用户的音频流。false
:(默认)默认订阅远端用户的音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDefaultMuteAllRemoteVideoStreams
默认取消或恢复订阅远端用户的视频流。
setDefaultMuteAllRemoteVideoStreams(mute: boolean): number
- 弃用:
- 该方法自 v3.3.0 起废弃。
该方法需要在加入频道后调用。调用成功后,本地用户取消或恢复订阅调用时刻之后加入频道的远端用户。
- 如果需要恢复订阅单个用户的视频流,调用 muteRemoteVideoStream(
false
),并指定你想要订阅的远端用户 ID。 - 如果想恢复订阅多个用户的视频流,则需要多次调用 muteRemoteVideoStream(
false
)。
参数
- mute
-
是否默认取消订阅远端用户的视频流:
true
: 默认取消订阅。false
:(默认)默认订阅。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoDevice
通过设备 ID 指定视频采集设备。
setVideoDevice(deviceId: string): number
参数
- deviceId
设备 ID。可通过调用 getVideoDevices 方法获取。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setEffectPosition
设置指定音效文件的播放位置。
setEffectPosition(soundId: number, pos: number): number
成功设置后,本地音效文件会在指定位置开始播放。
参数
- soundId
- 音效 ID。请确保与 playEffect 中设置的 soundId 一致。
- pos
- 音效文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectsVolume
设置音效文件的播放音量。
setEffectsVolume(volume: number): number
参数
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionMode
启用内置的加密方案。
setEncryptionMode(encryptionMode: string): number
- 弃用:
- 该方法自 v3.2.0 起废弃。请改用 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 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-xts
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionSecret
启用内置加密,并设置数据加密密码。
setEncryptionSecret(secret: string): number
- 弃用:
- 该方法自 v3.2.0 起废弃。请改用 enableEncryption 方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setHighQualityAudioParameters
设置音频高音质选项。
setHighQualityAudioParameters(fullband: boolean, stereo: boolean, fullBitrate: boolean): number
- 弃用:
- 该方法已废弃。声网不建议你使用。如果你希望设置音频高音质选项,请改用 setAudioProfile 方法。
参数
- fullband
全频带编解码器(48 kHz 采样率), 不兼容 v1.7.4 以前版本
true
:启用全频带编解码器false
:禁用全频带编解码器
- stereo
立体声编解码器,不兼容 v1.7.4 以前版本
true
:启用立体声编解码器false
:禁用立体声编解码器
- fullBitrate
高码率模式,建议仅在纯音频模式下使用
true
:启用高码率模式false
:禁用高码率模式
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLiveTranscoding
设置直播推流转码。
setLiveTranscoding(transcoding: LiveTranscoding): number
该方法用于旁路推流的视图布局及音频设置等。调用该方法更新转码设置后本地会触发 TRANSCODING_UPDATED 回调。
- 只有直播场景中角色为主播的用户才能调用该方法。
- 请确保已开通旁路推流的功能,详见进阶功能《推流到 CDN》中的前提条件。
- 首次调用该方法更新转码设置时,不会触发 TRANSCODING_UPDATED 回调。
- 该方法需要在加入频道后调用。
- Agora 目前仅支持转码时向 CDN 推送 RTMPS 协议的媒体流。
参数
- transcoding
-
推流转码设置。详见 LiveTranscoding。
返回
- 0:方法调用成功。
- < 0:方法调用失败。
setLocalPublishFallbackOption
设置弱网条件下发布的音视频流回退选项。
setLocalPublishFallbackOption(option: STREAM_FALLBACK_OPTIONS): number
网络不理想的环境下,实时通信音视频的质量都会下降。使用该接口并将 option 设置为 STREAM_FALLBACK_OPTION_AUDIO_ONLY (2) 后,SDK 会在上行弱网且音视频质量严重受影响时,自动关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当本地推流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发本地发布的媒体流已回退为音频流 LOCAL_PUBLISH_FALLBACK_TO_AUDIO_ONLY 回调。
- 旁路推流场景下,设置本地推流回退为 STREAM_FALLBACK_OPTION_AUDIO_ONLY(2) 可能会导致远端的 CDN 用户听到声音的时间有所延迟。因此在有旁路推流的场景下,Agora 建议不开启该功能。
- 该方法需要在加入频道前调用。
参数
- option
- 本地发流回退处理选项:
- STREAM_FALLBACK_OPTION_DISABLED (0):(默认)上行网络较弱时,不对音视频流作回退处理,但不能保证音视频流的质量
- STREAM_FALLBACK_OPTION_AUDIO_ONLY (2):上行网络较弱时只发布音频流
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVideoMirrorMode
设置本地视频镜像。
setLocalVideoMirrorMode(mirrorMode: VIDEO_MIRROR_MODE_TYPE): number
- 弃用:
- 从 v3.0.0 起废弃。
参数
- mode
- 本地视频镜像模式。详见 VIDEO_MIRROR_MODE_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceChanger
设置本地语音变声、美音或语聊美声效果。
setLocalVoiceChanger(voiceChanger: VOICE_CHANGER_PRESET): number
- 弃用:
- 该方法从 v3.2.0 起废弃,请改用以下方法:
- setAudioEffectPreset :音效
- setVoiceBeautifierPreset :美声效果
- setVoiceConversionPreset :变声效果
- 变声效果:枚举值以
VOICE_CHANGER
为前缀。效果包括老男人、小男孩、小女孩、猪八戒、空灵和绿巨人,通常用于语聊场景。 - 美音效果:枚举值以
VOICE_BEAUTY
为前缀。效果包括浑厚、低沉、圆润、假音、饱满、清澈、高亢、嘹亮和空旷,通常用于语聊和唱歌场景。 - 语聊美声效果:枚举值以
GENERAL_BEAUTY_VOICE
为前缀。效果包括磁性(男)、清新(女)和活力(女),通常用于语聊场景。该功能主要细化了男声和女声各自的特点。
- 为达到更好的声音效果,Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法不能与 setLocalVoiceReverbPreset 方法一同使用,否则先调的方法会不生效。更多注意事项,详见进阶功能《变声与混响》。
- 该方法在加入频道前后都能调用。
参数
- voiceChanger
- 预设本地语音变声、美音或语聊美声效果选项,默认值为 VOICE_CHANGER_OFF ,即原声。详见 VOICE_CHANGER_PRESET 。设置语聊美声效果时,Agora 推荐使用 GENERAL_BEAUTY_VOICE_MALE_MAGNETIC 处理男声,使用 GENERAL_BEAUTY_VOICE_FEMALE_FRESH 或 GENERAL_BEAUTY_VOICE_FEMALE_VITALITY 处理女声,否则音频可能会产生失真。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVoiceEqualization
设置本地语音音效均衡。
setLocalVoiceEqualization(bandFrequency: AUDIO_EQUALIZATION_BAND_FREQUENCY, bandGain: number): number
参数
- 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
设置本地语音音调。
setLocalVoicePitch(pitch: number): number
参数
- pitch
- 语音频率可以 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVoiceReverb
设置本地音效混响。
setLocalVoiceReverb(reverbKey: AUDIO_REVERB_TYPE, value: number): number
该方法在加入频道前后都能调用。
参数
- reverbKey
- 混响音效 Key。该方法共有 5 个混响音效 Key: AUDIO_REVERB_TYPE 。
- value
- 各混响音效 Key 所对应的值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceReverbPreset
设置本地语音混响(含虚拟立体声效果)。
setLocalVoiceReverbPreset(reverbPreset: AUDIO_REVERB_PRESET)
- 弃用:
- 该方法从 v3.2.0 起废弃,请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。
通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。
- 当使用以
AUDIO_REVERB_FX
为前缀的枚举值时,请确保在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY (4) 或 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5) ,否则该方法设置无效。 - 当使用 AUDIO_VIRTUAL_STEREO 时,Agora 推荐在调用该方法前将 setAudioProfile 的 profile 参数设置为 AUDIO_PROFILE_MUSIC_HIGH_QUALITY_STEREO (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法不能与 setLocalVoiceChanger 方法一同使用,否则先调的方法会不生效。更多注意事项,详见进阶功能《变声与混响》。
- 该方法在加入频道前后都能调用。
参数
- reverbPreset
本地语音混响选项,默认值为 AUDIO_REVERB_OFF ,即原声。详见 AUDIO_REVERB_PRESET 。
为达到更好的混响效果,Agora 推荐使用以
AUDIO_REVERB_FX
为前缀的枚举值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFile
设置 Agora SDK 输出的日志文件。
setLogFile(filePath: string): number
- 弃用:
- 该方法从 v3.3.0 起废弃。请改用 initializeWithContext 设置日志文件路径。
该方法设置的是 SDK 的 Native 层的日志。
默认情况下,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
。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogFileSize
设置 Agora SDK 输出的单个日志文件大小。
setLogFileSize(fileSizeInKBytes: number): number
- 弃用:
- v3.3.0。请改用 initializeWithContext 中的 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。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogFilter
设置日志输出等级。
setLogFilter(filter: LOG_FILTER_TYPE): number
- 弃用:
- v3.3.0。请改用 initializeWithContext 中的 logConfig。
该方法设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 OFF、CRITICAL、ERROR、WARNING、INFO 和 DEBUG。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 WARNING 级别,就可以看到在 CRITICAL、ERROR 和 WARNING 级别上的所有日志信息。
参数
- filter
- 日志过滤等级。详见 LOG_FILTER_TYPE。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMaxMetadataSize
设置媒体附属信息的最大大小。
setMaxMetadataSize(size: number): number
调用 registerMediaMetadataObserver 后,你可以调用本方法来设置媒体附属信息的最大大小。
参数
- size
- 媒体附属信息的最大大小。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setAudioPlaybackDevice
指定播放设备。
setAudioPlaybackDevice(deviceId: string): number
参数
- deviceId
通过 deviceID 指定播放设备。由 getAudioPlaybackDevices 获取。插拔设备不会影响 deviceId。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioPlaybackDeviceMute
设置播放设备静音。
setAudioPlaybackDeviceMute(mute: boolean): number
参数
- mute
- 是否设置播放设备为静音:
true
: 播放设备设为静音。false
: 播放设备不设为静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioPlaybackVolume
设置播放设备音量。
setAudioPlaybackVolume(volume: number): number
参数
- volume
- 播放设备音量。取值可在 [0,255]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPluginParameter
设置指定插件的参数。
setPluginParameter(pluginId: string, parameter: string): number
调用 getPluginParameter 获取到 Value 值后,你可以调用本方法将包含 Key 和 Value 值的 JSON 字符串数据传递给 C++ 层。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- parameter
- 包含 Key 和 Value 值的 JSON 字符串。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setRecordingAudioFrameParameters
设置采集的原始音频数据格式。
setRecordingAudioFrameParameters( sampleRate: number, channel: 1 | 2, mode: RAW_AUDIO_FRAME_OP_MODE_TYPE, samplesPerCall: number ): number
调用 registerPlugin 注册插件并获取采集的原始音频数据后,你可以调用本方法设置 SDK 返回的该原始数据的采样率、声道数等参数。
- 该方法需要在加入频道前调用。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。
参数
- sampleRate
- SDK 返回数据的采样率 (Hz),可设置为 8000、 16000、 32000、 44100 或 48000。
- channel
- SDK 返回数据的通道数。取值可为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
- SDK 返回数据的使用模式,详见 RAW_AUDIO_FRAME_OP_MODE_TYPE。
- samplesPerCall
- SDK 返回数据的采样点数,如 RTMP/RTMPS 推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setAudioRecordingDevice
指定音频采集设备。
setAudioRecordingDevice(deviceId: string): number
参数
- deviceId
音频采集设备的 Device ID。可通过 getAudioRecordingDevices 获取。插拔设备不会影响 deviceId。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioRecordingDeviceMute
设置当前音频采集设备静音。
setAudioRecordingDeviceMute(mute: boolean): number
参数
- mute
- 是否设置音频采集设备静音:
true
: 采集设备静音。false
: 采集设备为非静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioRecordingVolume
设置音频采集设备音量。
setAudioRecordingVolume(volume: number): number
参数
- volume
- 音频采集设备音量。取值范围 [0,255]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
setRemoteDefaultVideoStreamType(streamType: REMOTE_VIDEO_STREAM_TYPE): number
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode (false
)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流可以接为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 API_CALL_EXECUTED 中返回。
参数
- streamType
- 视频流类型: REMOTE_VIDEO_STREAM_TYPE 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteSubscribeFallbackOption
设置弱网条件下订阅的音视频流的回退选项。
setRemoteSubscribeFallbackOption(option: STREAM_FALLBACK_OPTIONS): number
网络不理想的环境下,直播音视频的质量都会下降。如果你使用本方法并将 option 设置为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1) 或 STREAM_FALLBACK_OPTION_AUDIO_ONLY(2),SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流,或关断视频流,从而保证或提高音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。当远端订阅流回退为音频流时,或由音频流恢复为音视频流时,SDK 会触发 REMOTE_SUBSCRIBE_FALLBACK_TO_AUDIO_ONLY 回调。
参数
- option
- 详见 STREAM_FALLBACK_OPTIONS。默认 option 为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1)。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteUserPriority
设置远端用户媒体流的优先级。
setRemoteUserPriority(uid: number, userPriority: PRIORITY_TYPE)
- 自从
- v2.4.0
设置远端用户的优先级。如果将某个用户的优先级设为高,那么发给这个用户的音视频流的优先级就会高于其他用户。弱网下 SDK 会优先保证高优先级用户收到的流的质量。
- 目前 Agora SDK 仅允许将一名远端用户设为高优先级。
- 该方法需要在加入频道前调用。
参数
- uid
- 远端用户的 ID。
- userPriority
- 远端用户的需求优先级。详见: PRIORITY_TYPE。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoStreamType
设置订阅的视频流类型。
setRemoteVideoStreamType(userId: number, streamType: REMOTE_VIDEO_STREAM_TYPE): number
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode(false) 关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
调用本方法的执行结果将在 API_CALL_EXECUTED 中返回。
参数
- userId
- 用户 ID。
- streamType
- 视频流类型: REMOTE_VIDEO_STREAM_TYPE 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVoicePosition
设置远端用户的语音位置。
setRemoteVoicePosition(uid: number, pan: number, gain: number): number
设置远端用户声音的空间位置和音量,方便本地用户听声辨位。
通过调用该接口设置远端用户声音出现的位置,左右声道的声音差异会产生声音的方位感,从而判断出远端用户的实时位置。在多人在线游戏场景,如吃鸡游戏中,该方法能有效增加游戏角色的方位感,模拟真实场景。
- 使用该方法需要在加入频道前调用 enableSoundPositionIndication 开启远端用户的语音立体声。
- 为获得最佳听觉体验,我们建议使用该方法时使用立体声外放。
- 该方法需要在加入频道后调用。
参数
- uid
- 远端用户的 ID
- pan
- 设置远端用户声音的空间位置,取值范围为 [-1.0,1.0]:
- (默认)0.0: 声音出现在正前方。
- -1.0: 声音出现在左边。
- 1.0: 声音出现在右边。
- gain
- 设置远端用户声音的音量,取值范围为 [0.0,100.0],默认值为 100.0,表示该用户的原始音量。取值越小,则音量越低。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRenderMode
setScreenCaptureContentHint
设置屏幕共享内容类型。
setScreenCaptureContentHint(contentHint: VideoContentHint): number
- 自从
- v2.4.0
Agora SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE,即无指定的内容类型。
参数
- contentHint
- 屏幕共享的内容类型。详见 VideoContentHint。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfiguration
设置视频编码属性。
setVideoEncoderConfiguration(config: VideoEncoderConfiguration): number
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoProfile
设置视频编码配置。
setVideoProfile(profile: VIDEO_PROFILE_TYPE, swapWidthAndHeight: boolean = false): number
- 弃用:
- 该方法自 v2.3 起废弃。请改用 setVideoEncoderConfiguration 方法。
该方法设置视频的编码属性。 该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
参数
- profile
- 视频属性。详见: VIDEO_PROFILE_TYPE 。
- swapWidthAndHeight
SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
true
: 交换宽和高false
: 不交换宽和高(默认)
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoQualityParameters
设置视频优化选项(仅适用于直播)。
- 弃用:
- 该方法从 v2.4.0 起废弃。Agora 建议使用 VideoEncoderConfiguration 类中的 degradationPreference 参数设置视频质量偏好。
参数
- preferFrameRateOverImageQuality
-
画质和流畅度里,是否优先保证流畅度:
true
:优先保证流畅度。false
: (默认)优先保证画质。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoRenderDimension
设置本地视频渲染分辨率(JavaScript 层)。
setVideoRenderDimension( user: User, width: number, height: number, channelId: string = "" )
Agora SDK 会自动控制 JavaScript 层视频渲染,如果你觉得应用显示的视频分辨率过低,你可以调用该方法设置视频渲染分辨率。
- 该方法只影响本地渲染,不影响远端用户所见。
- 为保证视频质量,请在设置视频渲染帧率时,相应地调整视频渲染分辨率。详见 setVideoRenderFPS。
参数
- user
- 视频所属的用户,详见 User。
- width
- 视频的宽度 (px)。
- height
- 视频的高度 (px)。
- channelId
- 标识视频渲染所属的频道的 ID。仅在多频道场景下需要设置该参数。
setVideoRenderFPS
设置本地视频渲染帧率(JavaScript 层)。
setVideoRenderFPS(fps: number)
Agora SDK 会自动控制 JavaScript 层视频渲染,如果你觉得应用显示的视频帧率过低,你可以调用该方法设置视频渲染帧率。
- 该方法只影响本地渲染,不影响远端用户所见。
- 为保证视频质量,请在设置视频渲染分辨率时,相应地调整视频渲染帧率。详见 setVideoRenderDimension。
参数
- fps
- 本地视频渲染帧率 (fps)。不能超过 30 fps。
setView
setVoiceBeautifierParameters
设置预设美声效果的参数。
setVoiceBeautifierParameters(preset: VOICE_BEAUTIFIER_PRESET, param1: number, param2: number): number
- 自从
- v3.3.0
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 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) 或 AUDIO_PROFILE_IOT(6),否则该方法会不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierParameters,Agora 不推荐调用以下方法,否则 setVoiceBeautifierParameters 设置的效果会被覆盖:
参数
- preset
- 预设的音效:
SINGING_BEAUTIFIER
: 歌唱美声。
- param1
- 歌声的性别特征:
1
: 男声。2
: 女声。
- param2
- 歌声的混响效果:
1
: 歌声在小房间的混响效果。2
: 歌声在大房间的混响效果。3
: 歌声在大厅的混响效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceBeautifierPreset
设置预设的美声效果。
setVoiceBeautifierPreset(preset: VOICE_BEAUTIFIER_PRESET): number
- 自从
- v3.2.0
调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果,各美声效果的适用场景可参考《美声与音效》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 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) 或 AUDIO_PROFILE_IOT(6),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierPreset,Agora 不推荐调用以下方法,否则 setVoiceBeautifierPreset 设置的效果会被覆盖:
参数
- preset
- 预设的美声效果选项,详见 VOICE_BEAUTIFIER_PRESET。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceConversionPreset
设置预设的变声效果。
setVoiceConversionPreset(preset: VOICE_CONVERSION_PRESET): number
- 自从
- v3.3.1
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的变声效果,各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 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),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceConversionPreset 后,Agora 不推荐调用以下方法,否则 setVoiceConversionPreset 设置的效果会被覆盖:
参数
- preset
- 预设的变声效果选项: VOICE_CONVERSION_PRESET。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVolumeOfEffect
实时调整音效文件的播放音量。
setVolumeOfEffect(soundId: number, volume: number): number
参数
- soundId
- 指定音效的 ID。每个音效均有唯一的 ID。
- volume
- 播放音量。取值范围为 [0,100]。默认值为 100,表示原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioDeviceLoopbackTest
开始音频设备回路测试。
startAudioDeviceLoopbackTest(indicationInterval: number): number
该方法测试音频采集和播放设备是否能正常工作。一旦测试开始,音频采集设备会采集本地音频,然后使用音频播放设备播放出来。 SDK 会按设置的时间间隔触发两个 AUDIO_VOLUME_INDICATION 回调,分别报告音频采集设备(uid = 0) 和音频播放设置(uid = 1)的音量信息。
- 该方法需要在加入频道前调用。
- 该方法仅在本地进行音频设备测试,不涉及网络连接。
参数
- indicationInterval
SDK 触发 AUDIO_VOLUME_INDICATION 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得少于 10 毫秒,否则会收不到 AUDIO_VOLUME_INDICATION 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startAudioMixing
开始播放音乐文件。
startAudioMixing( filePath: string, loopback: boolean, replace: boolean, cycle: number, startPos?: number, ): number
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 AUDIO_MIXING_STATE_CHANGED (PLAY
) 回调。播放结束后,本地会触发 AUDIO_MIXING_STATE_CHANGED (STOPPED
) 回调。
参数
- filePath
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
C:\music\audio.mp4
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见 Supported Media Formats in Media Foundation。- loopback
- 是否只在本地播放音乐文件:
true
: 只在本地播放音乐文件,只有本地用户能听到音乐。false
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- replace
- 是否用音乐文件替换麦克风采集的音频:
true
: 替换。用户只能听到音乐。false
: 不替换。用户可以听到音乐和麦克风采集的音频。
- cycle
- 音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
- startPos
- 音乐文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording
开始客户端录音。
startAudioRecording(filePath: string, sampleRate: number, quality: AUDIO_RECORDING_QUALITY_TYPE ): number
- 弃用:
- 自 v3.4.0 废弃,请改用 startAudioRecordingWithConfig。
- 自从
- v2.9.1
- .wav: 文件大,音质保真度较高。
- .aac: 文件小,音质保真度较低。
- 请确保你在该方法中指定的路径存在并且可写。
- 该接口需在 joinChannel 之后调用。如果调用 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: 方法调用失败
startAudioRecordingWithConfig
开始客户端录音。
startAudioRecordingWithConfig(config: AudioRecordingConfiguration): number
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 AUDIO_RECORDING_QUALITY_MEDIUM,录音时长为 10 分钟的文件大小约为 2 M。
用户离开频道后,录音会自动停止。
参数
- config
- 录音配置。详见 AudioRecordingConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
startChannelMediaRelay(config: ChannelMediaRelayConfiguration): number
- 如果 CHANNEL_MEDIA_RELAY_STATE 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0),且 CHANNEL_MEDIA_RELAY_EVENT 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 CHANNEL_MEDIA_RELAY_STATE 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要提交工单联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败
startVideoDeviceTest
开启视频采集设备测试。
startVideoDeviceTest(): number
该方法用于测试当前视频采集设备是否工作正常,使用前需保证已调用过 enableVideo,且输入视频的 HWND 有效。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startEchoTest
开始语音通话回路测试。
startEchoTest(): number
- 弃用:
- 该方法自 v2.4.0 起废弃,请改用 startEchoTestWithInterval。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在 10 秒后回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTestWithInterval
开始语音通话回路测试。
startEchoTestWithInterval(intervalInSeconds: number): number
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTestWithInterval 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
- intervalInSeconds
- 设置返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒,默认为 10 秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startLastmileProbeTest
开始通话前网络质量探测。
startLastmileProbeTest(config: LastmileProbeConfig): number
- 自从
- v2.4.0
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- LASTMILE_QUALITY,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- LASTMILE_PROBE_RESULT,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 该方法会消耗一定的网络流量,影响通话质量,因此我们建议不要和 enableLastmileTest 同时使用。
- 调用该方法后,在收到 LASTMILE_QUALITY 和 LASTMILE_PROBE_RESULT 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 LastmileProbeConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioPlaybackDeviceTest
启动音频播放设备测试。
startAudioPlaybackDeviceTest(testAudioFilePath: string): number
该方法测试音频播放设备是否能正常工作。启动测试后,SDK 播放指定的音频文件,测试者如果能听到声音,说明播放设备能正常工作。
调用该方法后,SDK 会每隔 100 ms 触发一次 AUDIO_VOLUME_INDICATION 回调,报告 uid = 1 及播放设备的音量信息。
参数
- testAudioFilePath
- 音频文件的绝对路径,路径字符串使用 UTF-8 编码格式。
- 支持文件格式: wav、mp3、m4a、aac。
- 支持文件采样率: 8000、16000、32000、44100、48000。
返回值
- 0: 方法调用成功。同时你可以听到设置的音频文件的声音。
- < 0: 方法调用失败。
startPreview
开启视频预览。
startPreview(): number
该方法用于在进入频道前启动本地视频预览。调用该 API 前,必须:
- 调用 setView 设置预览窗口及属性。
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 启用了本地视频预览后,如果调用 leaveChannel退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 stopPreview。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startAudioRecordingDeviceTest
启动音频采集设备测试。
startAudioRecordingDeviceTest(indicationInterval: number): number
该方法测试音频采集设备是否能正常工作。调用该方法后,SDK 会按设置的时间间隔触发 AUDIO_VOLUME_INDICATION 回调, 报告 uid = 0 及采集设备的音量信息。
参数
- indicationInterval
- SDK 触发 AUDIO_VOLUME_INDICATION 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。 不得小于 10 毫秒,否则会收不到 AUDIO_VOLUME_INDICATION 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startScreenCaptureByScreen
通过指定区域共享屏幕。
startScreenCaptureByScreen(screenSymbol: ScreenSymbol, regionRect: Rectangle, captureParams: ScreenCaptureParameters ): number
- 自从
- v2.4.0
共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。
参数
- screenSymbol
- 标识屏幕的 Display ID(macOS 系统)或 ScreenRect(Windows 系统)。详见 ScreenSymbol。你可以通过 getScreensInfo 方法获取。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
startScreenCaptureByWindow
通过窗口 ID 共享窗口。
startScreenCaptureByWindow(windowId: number, regionRect: Rectangle, captureParams: ScreenCaptureParameters ): number
- 自从
- v2.4.0
共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。
- 该方法需要在加入频道后调用。
参数
- windowId
- 指定待共享的窗口 ID。
你可以通过 getWindowsInfo 方法获取。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
- captureParams
- 屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopAllEffects
停止播放所有音效文件。
stopAllEffects(): number
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioDeviceLoopbackTest
停止音频设备回路测试。
stopAudioDeviceLoopbackTest(): number
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopAudioMixing
停止播放音乐文件。
stopAudioMixing(): number
该方法停止播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioRecording
停止客户端录音。
stopAudioRecording(): number
如果你调用了 startAudioRecordingWithConfig 开始录音,可以调用该方法停止录音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
stopChannelMediaRelay(): number
- 自从
- v2.9.0
成功调用该方法后,SDK 会触发 CHANNEL_MEDIA_RELAY_STATE 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopVideoDeviceTest
停止视频采集设备测试。
stopVideoDeviceTest(): number
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopEchoTest
停止语音通话回路测试。
stopEchoTest(): number
返回值
- 0: 方法调用成功。
-
< 0: 方法调用失败。
- -5(ERR_REFUSED): 无法启动测试,可能没有成功初始化。
stopEffect
停止播放指定音效文件。
stopEffect(soundId: number): number
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopLastmileProbeTest
停止通话前网络质量探测。
stopLastmileProbeTest(): number
- 自从
- v2.4.0
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioPlaybackDeviceTest
停止播放设备测试。
stopAudioPlaybackDeviceTest(): number
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopPreview
停止视频预览。
stopPreview(): number
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopAudioRecordingDeviceTest
停止音频采集设备测试。
stopAudioRecordingDeviceTest(): number
该方法停止音频采集设备测试。调用 startAudioRecordingDeviceTest 后,必须调用该方法停止测试。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopScreenCapture
停止屏幕共享。
stopScreenCapture(): number
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchChannel
快速切换直播频道,并设置是否自动订阅音频流或视频流。
switchChannel(token: string, channelId: string, options?: ChannelMediaOptions): number
- 自从
- v3.3.0
当直播频道中的观众想从一个频道切换到另一个频道时,可以调用该方法,实现快速切换。
成功调用该方切换频道后,本地会先收到离开原频道的回调 LEAVE_CHANNEL,再收到成功加入新频道的回调 JOINED_CHANNEL。
用户成功切换频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 动态秘钥。
- 安全要求不高: 将值设为 null。
- 安全要求高: 将值设置为从你的服务端生成的 Token。如果你的项目已经启用了 App Certificate, 请务必使用 Token。
警告: 请确保用于生成 token 的 App ID 和 initializeWithContext 方法初始化引擎时用的 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): 用户不在频道内。
unloadEffect
从内存释放某个预加载的音效文件。
unloadEffect(soundId: number): number
参数
- soundId
- 指定音效文件的 ID。每个音效文件均有唯一的 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
unregisterMediaMetadataObserver
取消注册媒体 metadata 观测器。
unregisterMediaMetadataObserver(type: METADATA_TYPE = 0): number
参数
- type
- 观测器使用的 metadata 类型。目前仅支持 VIDEO_METADATA 。详见 METADATA_TYPE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
unregisterPlugin
取消注册指定插件。
unregisterPlugin(pluginId: string): number
调用 registerPlugin 注册插件后,如果你想取消注册插件,请调用本方法。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
updateChannelMediaRelay
更新媒体流转发的频道。
updateChannelMediaRelay(config: ChannelMediaRelayConfiguration): number
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 CHANNEL_MEDIA_RELAY_EVENT 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
参数
- configuration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
updateScreenCaptureParameters
更新屏幕共享的参数配置。
updateScreenCaptureParameters(captureParams: ScreenCaptureParameters): number
- 自从
- v2.4.0
参数
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -3(ERR_NOT_READY): 如果当前没有共享的屏幕,会返回该错误码。
updateScreenCaptureRegion
更新屏幕共享区域。
updateScreenCaptureRegion(regionRect: Rectangle): number
- 自从
- v2.4.0
参数
- regionRect
- 待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见 Rectangle。 如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕或窗口。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -3(ERR_NOT_READY): 如果当前没有共享的屏幕,会返回该错误码。
videoSourceDisableAudio
关闭音频模块。
videoSourceDisableAudio(): number
双实例方法。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceDisableVideo
关闭视频模块。
videoSourceDisableVideo(): number
双实例方法。
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 videoSourceEnableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 VIDEO_SOURCE_USER_ENABLE_VIDEO(false
) 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceEnableAudio
启用音频模块。
videoSourceEnableAudio(): number
双实例方法。
调用该方法启用屏幕共享实例的音频模块(默认为关闭状态)。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceEnableDualStreamMode
对 videoSource
流开启双流模式。
videoSourceEnableDualStreamMode(enabled: boolean): number
双实例方法。
参数
- enabled
-
true
: 开启双流模式。false
: 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
videoSourceEnableEncryption
开启或关闭内置加密。
videoSourceEnableEncryption(enabled: boolean, config: EncryptionConfig): number
双实例方法。
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功
-
< 0: 方法调用失败
- -2(ERR_INVALID_ARGUMENT): 调用了无效的参数。需重新指定参数。
- -4(ERR_NOT_SUPPORTED): 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。需在调用 API 之前已创建 AgoraRtcEngine 对象并完成初始化。
videoSourceEnableLocalAudio
开关本地音频采集。
videoSourceEnableLocalAudio(enabled: boolean): number
双实例方法。
该方法可以关闭或重新开启本地音频功能,即停止或重新开始本地音频采集。
该方法不影响接收或播放远端音频流,videoSourceEnableLocalAudio(false
) 适用于只听不发的用户场景。
参数
- enabled
true
: 重新开启本地音频功能,即开启本地音频采集(默认);false
: 关闭本地音频功能,即停止本地音频采集。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceEnableLocalVideo
开关本地视频采集。
videoSourceEnableLocalVideo(enabled: boolean): number
双实例方法。
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 videoSourceEnableVideo 后,本地视频采集即默认开启。你可以调用 videoSourceEnableLocalVideo(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 videoSourceEnableLocalVideo(true
)。
成功禁用或启用本地视频采集后,远端会触发 VIDEO_SOURCE_USER_ENABLE_LOCAL_VIDEO 回调。
参数
- enabled
-
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceEnableLoopbackRecording
开启声卡采集。
videoSourceEnableLoopbackRecording( enabled = false, deviceName: string | null = null ): number
双实例方法。
启用声卡采集功能后,声卡播放的声音会被合到本地音频流中,从而可以发送到远端。
- macOS 系统默认声卡不支持采集功能,如需开启此功能需要 App 自己启用一个虚拟声卡,并将该虚拟声卡的名字作为 deviceName 传入 SDK。 Agora 测试并推荐 soundflower 作为虚拟声卡。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 是否开启声卡采集:
true
: 开启声卡采集。false
:(默认)关闭声卡采集。
- deviceName
- 声卡的设备名。默认设为 null,即使用当前声卡采集。 如果用户使用虚拟声卡,如 "Soundflower",可以将虚拟声卡名称 "Soundflower" 作为参数,SDK 会找到对应的虚拟声卡设备,并开始采集。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceEnablePlugin
开启或关闭指定的插件。
videoSourceEnablePlugin(pluginId: string, enabled: boolean): number
双实例方法。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- enabled
- 是否开启插件:
true
:开启插件。false
:关闭插件。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
videoSourceEnableVideo
启用视频模块。
videoSourceEnableVideo(): number
双实例方法。
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。 调用 videoSourceDisableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 VIDEO_SOURCE_REMOTE_VIDEO_STATE_CHANGED 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceEnableWebSdkInteroperability
开启 videoSource
与 Web SDK
的互通。
videoSourceEnableWebSdkInteroperability(enabled: boolean): number
- 弃用:
- 该方法从 v3.0.0 起废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Agora Web SDK 的互通:
true
: 打开互通。false
: (默认) 关闭互通。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceGetPluginParameter
获取指定插件的参数。
videoSourceGetPluginParameter(pluginId: string, key: string): string
双实例方法。
如果你想在使用插件时将 JSON 字符串数据传递给 C++ 层,你需要调用 videoSourceGetPluginParameter 和 videoSourceSetPluginParameter 获取并设置参数。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- key
- Key 值。
返回值
Key 值对应的 Value 值。
videoSourceGetPlugins
获取插件。
videoSourceGetPlugins(): Plugin[]
双实例方法。
调用 videoSourceRegisterPlugin 后,你可以调用本方法获取注册的插件。
返回值
Plugin 接口组成的数组。
videoSourceInitializeWithContext
创建并初始化 videoSource
对象。
videoSourceInitializeWithContext(context: RtcEngineContext): number
双实例方法。
videoSource
方法前先调用该方法初始化 videoSource
对象。参数
- context
- videoSource 的配置,详见 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 无效。
videoSourceJoinChannel
videoSource
加入频道。
videoSourceJoinChannel( token: string, channelId: string, info: string, uid: number, options?: ChannelMediaOptions ): number
双实例方法。
参数
- token
-
在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
警告: 请确保用于生成 token 的 App ID、频道名和用户名和 initializeWithContext 方法初始化引擎时用的 App ID,以及该方法中设置的频道名和用户名是一致的。 - channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道 进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- info
-
预留参数。
- uid
videoSource
的用户 ID。一个频道内不能出现相同的用户 ID。请确保videoSource
用户 ID 和 joinChannel 使用的uid
不同。- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
videoSourceLeaveChannel
videoSource
离开频道。
videoSourceLeaveChannel(): number
双实例方法。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
videoSourceMuteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
videoSourceMuteAllRemoteAudioStreams(mute: boolean): number
双实例方法。
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见设置订阅状态。
参数
- mute
- 是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceMuteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
videoSourceMuteAllRemoteVideoStreams(mute: boolean): number
双实例方法。
自 v3.3.0 起,成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 该方法的推荐设置详见《设置订阅状态》。
参数
- mute
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceRegisterPlugin
注册插件。
videoSourceRegisterPlugin(pluginInfo: PluginInfo): number
双实例方法。
注册插件后,你可以在 SDK 中使用插件的功能。举例来说,如果你想使用 FaceUnity 的插件,你可以先将该插件文件集成到 SDK 的项目工程文件中,然后调用该方法注册插件。
- 调用 videoSourceGetPlugins 方法,并通过 Plugin 接口中的 enable、disable、setParameter、getParameter 函数开启插件,关闭插件,设置插件参数,获取插件参数。
- 调用 videoSourceEnablePlugin、videoSourceSetPluginParameter、videoSourceGetPluginParameter 方法,开关插件、设置插件参数、获取插件参数。
参数
- pluginInfo
- 插件信息。详见 PluginInfo。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
videoSourceRelease
释放 videoSource
对象。
videoSourceRelease(): number
双实例方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
videoSourceRenewToken
更新 videoSource
的
Token。
videoSourceRenewToken(token: string): number
双实例方法。
参数
- token
- 新的 Token。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
videoSourceSetAddonLogFile
设置 videoSource
进程的 Electron
层的日志文件。
videoSourceSetAddonLogFile(filePath: string): number
双实例方法。
参数
- filePath
- SDK 的 Electron 层的日志文件的完整路径。请确保你指定的目录存在且可写。你可以通过该参数修改日志文件名。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceSetChannelProfile
设置 videoSource
的频道场景。
videoSourceSetChannelProfile(profile: CHANNEL_PROFILE_TYPE): number
双实例方法。
参数
- profile
-
频道使用场景。详见 CHANNEL_PROFILE_TYPE。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2 (ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
videoSourceSetEncryptionMode
启用内置的加密方案。
videoSourceSetEncryptionMode(encryptionMode: string): number
- 弃用:
- 该方法自 v3.2.0 起废弃。请改用 videoSourceEnableEncryption 方法。
双实例方法。
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 模式; - "": 设置为空字符串时,默认使用加密方式 "
aes-128-xts
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceSetEncryptionSecret
启用内置加密,并设置数据加密密码。
videoSourceSetEncryptionSecret(secret: string): number
- 弃用:
- 该方法自 v3.2.0 起废弃。请改用 videoSourceEnableEncryption 方法。
双实例方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceSetLogFile
设置 SDK Native 层 videoSource
进程的日志。
videoSourceSetLogFile(filePath: string): number
- 弃用:
- 该方法已废弃,建议改用 videoSourceInitializeWithContext 设置日志文件。
双实例方法。
- 如需调用本方法,请在初始化
videoSource
对象后立即调用,否则可能造成输出日志不完整。 videoSource
进程和主进程的默认日志文件路径相同,你需要修改文件路径,避免日志文件被覆盖。
参数
- filePath
-
日志文件的完整路径。默认路径为
C:\Users\<user_name>\AppData\Local\Agora\<process_name>\agorasdk.log
。请确保指定的目录存在而且可写。你可通过该参数修改日志文件名。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceSetPluginParameter
设置指定插件的参数。
videoSourceSetPluginParameter(pluginId: string, parameter: string): number
双实例方法。
调用 videoSourceGetPluginParameter 获取到 Value 值后,你可以调用本方法将包含 Key 和 Value 值的 JSON 字符串数据传递给 C++ 层。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
- parameter
- 包含 Key 和 Value 值的 JSON 字符串。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
videoSourceSetScreenCaptureContentHint
设置屏幕共享内容类型。
videoSourceSetScreenCaptureContentHint(contentHint: VideoContentHint): number
双实例方法。
Agora SDK 会根据不同的内容类型,使用不同的算法对共享效果进行优化。如果不调用该方法,SDK 会将屏幕共享的内容默认为 CONTENT_HINT_NONE,即无指定的内容类型。
参数
- contentHint
- 屏幕共享的内容类型。详见 VideoContentHint。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceSetVideoEncoderConfiguration
设置视频编码属性。
videoSourceSetVideoEncoderConfiguration(config: VideoEncoderConfiguration): number
双实例方法。
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceSetVideoProfile
设置 videoSource
的视频属性。
videoSourceSetVideoProfile( profile: VIDEO_PROFILE_TYPE, swapWidthAndHeight: boolean = false ): number
- 弃用:
- 请改用 videoSourceSetVideoEncoderConfiguration 方法。
双实例方法。
参数
- profile
- 视频属性。详见: VIDEO_PROFILE_TYPE 。
- swapWidthAndHeight
SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
true
: 交换宽和高false
: 不交换宽和高(默认)
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
videoSourceStartPreview
开启视频预览。
videoSourceStartPreview(): number
双实例方法。
该方法用于在进入频道前启动本地视频预览。调用该 API 前,必须:
- 调用 setView 设置预览窗口及属性。
- 调用 videoSourceEnableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 启用了本地视频预览后,如果调用 videoSourceLeaveChannel退出频道,本地预览依然处于启动状态,如需要关闭本地预览,需要调用 videoSourceStopPreview。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
videoSourceStartScreenCaptureByScreen
通过指定区域共享屏幕。
videoSourceStartScreenCaptureByScreen( screenSymbol: ScreenSymbol, regionRect: Rectangle, captureParams: ScreenCaptureParameters ): number
双实例方法。
共享一个屏幕或该屏幕的部分区域。你需要在该方法中指定想要共享的屏幕区域。
参数
- screenSymbol
- 标识屏幕的 Display ID(macOS 系统)或 ScreenRect(Windows 系统)。详见 ScreenSymbol。你可以通过 getScreensInfo 方法获取。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了屏幕的边界,则只共享屏幕内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕。
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceStartScreenCaptureByWindow
通过窗口 ID 共享窗口。
videoSourceStartScreenCaptureByWindow( windowId: number, regionRect: Rectangle, captureParams: ScreenCaptureParameters ): number
双实例方法。
共享一个窗口或该窗口的部分区域。用户需要在该方法中指定想要共享的窗口 ID。
- 该方法需要在加入频道后调用。
参数
- windowId
- 指定待共享的窗口 ID。
你可以通过 getWindowsInfo 方法获取。
- regionRect
- (可选)指定待共享区域相对于整个屏幕的位置。如不填,则表示共享整个屏幕。详见 Rectangle。如果设置的共享区域超出了窗口的边界,则只共享窗口内的内容;如果宽或高为 0,则共享整个窗口。
- captureParams
- 屏幕共享的参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceStopPreview
停止视频预览。
videoSourceStopPreview(): number
双实例方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
videoSourceStopScreenCapture
停止屏幕共享。
videoSourceStopScreenCapture(): number
双实例方法。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
videoSourceUnregisterPlugin
取消注册指定插件。
videoSourceUnregisterPlugin(pluginId: string): number
双实例方法。
调用 videoSourceRegisterPlugin 注册插件后,如果你想取消注册插件,请调用本方法。
参数
- pluginId
- 用于标识插件的 ID,可以从 PluginInfo 中获取。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
videoSourceUpdateScreenCaptureParameters
更新屏幕共享的参数配置。
videoSourceUpdateScreenCaptureParameters(captureParams: ScreenCaptureParameters): number
双实例方法。
参数
- captureParams
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -3(ERR_NOT_READY): 如果当前没有共享的屏幕,会返回该错误码。
videoSourceUpdateScreenCaptureRegion
更新屏幕共享区域。
videoSourceUpdateScreenCaptureRegion(regionRect: Rectangle): number
双实例方法。
参数
- regionRect
- 待共享区域相对于整个屏幕或窗口的位置,如不填,则表示共享整个屏幕或窗口。详见 Rectangle。 如果设置的共享区域超出了屏幕或窗口的边界,则只共享屏幕或窗口内的内容;如果将 width 或 height 设为 0 ,则共享整个屏幕或窗口。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -3(ERR_NOT_READY): 如果当前没有共享的屏幕,会返回该错误码。