RtcEngine
Agora RTC SDK 的基础接口类,实现实时音视频的主要功能。
RtcEngine 提供了 app 调用的主要方法。
addHandler
添加主回调事件。
public void addHandler(IRtcEngineEventHandler handler) { mInstance.addHandler(handler); }
IRtcEngineEventHandler 接口类用于 SDK 向 app 发送回调事件通知,app 通过继承该接口类的方法获取 SDK 的事件通知。 接口类的所有方法都有缺省(空)实现,app 可以根据需要只继承关心的事件。在回调方法中,app 不应该做耗时或者调用可能会引起阻塞的 API(如 sendStreamMessage), 否则可能影响 SDK 的运行。
参数
- handler
- 待添加的回调事件,详见 IRtcEngineEventHandler。
addVideoWatermark [1/2]
添加本地视频水印。
public abstract int addVideoWatermark(AgoraImage watermark);
- 弃用:
- 该方法已废弃,请使用 addVideoWatermark [2/2] 作为替代。
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户,旁路推流观众,甚至采集设备都能看到或采集到该水印图片。如果你仅仅希望在旁路直播推流中添加水印,请参考 setLiveTranscoding中描述的用法。
- 在本地直播和旁路推流中,URL 的定义不同。本地直播中,URL 指本地直播视频上图片的本地绝对/相对路径;旁路推流中,URL 指旁路推流视频上图片的地址。
- 待添加图片的源文件格式必须是 PNG。如果待添加的 PNG 图片的尺寸与你该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行裁剪,以与设置相符。
- 声网当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
参数
- watermark
- 待添加在本地直播推流中的水印图片:AgoraImage。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
addVideoWatermark [2/2]
添加本地视频水印。
public abstract int addVideoWatermark(String watermarkUrl, WatermarkOptions options);
该方法将一张 PNG 图片作为水印添加到本地发布的直播视频流上,同一直播频道中的用户、旁路直播观众和采集设备都能看到或采集到该水印图片。 Agora 当前只支持在直播视频流中添加一个水印,后添加的水印会替换掉之前添加的水印。
- 如果视频编码方向(ORIENTATION_MODE)固定为横屏或自适应模式下的横屏,那么水印使用横屏坐标。
- 如果视频编码方向(ORIENTATION_MODE)固定为竖屏或自适应模式下的竖屏,那么水印使用竖屏坐标。
- 设置水印坐标时,水印的图像区域不能超出 setVideoEncoderConfiguration 方法中设置的视频尺寸,否则超出部分将被裁剪。
- 你需要在调用 enableVideo 方法之后再调用该方法。
- 如果你只是在旁路推流时添加水印,你可以使用该方法或 setLiveTranscoding 方法设置水印。
- 待添加水印图片必须是 PNG 格式。该方法支持所有像素格式的 PNG 图片:RGBA、RGB、Palette、Gray 和 Alpha_gray。
- 如果待添加的 PNG 图片的尺寸与你在该方法中设置的尺寸不一致,SDK 会对 PNG 图片进行缩放或裁剪,以与设置相符。
- 如果你已经使用 startPreview [1/2] 方法开启本地视频预览,那么该方法的
visibleInPreview
可设置水印在预览时是否可见。 - 如果你已设置本地视频为镜像模式,那么此处的本地水印也为镜像。为避免本地用户看本地视频时的水印也被镜像,Agora 建议你不要对本地视频同时使用镜像和水印功能,请在应用层实现本地水印功能。
参数
- watermarkUrl
- 待添加的水印图片的本地路径。该方法支持从本地绝对/相对路径添加水印图片。
- options
- 待添加的水印图片的设置选项,详见 WatermarkOptions 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPlayoutVolume
调节音乐文件在本地播放的音量。
public abstract int adjustAudioMixingPlayoutVolume(int volume);
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
public abstract int adjustAudioMixingPublishVolume(int volume);
该方法调节混音音乐文件在远端的播放音量大小。
你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustAudioMixingPublishVolume
调节音乐文件远端播放音量。
public abstract int adjustAudioMixingPublishVolume(int volume);
该方法调节混音音乐文件在远端的播放音量大小。
你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
参数
- volume
- 音乐文件音量。取值范围为 [0,100],100 (默认值)为原始音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustCustomAudioPublishVolume
调节自定义采集的外部音频源在远端播放的音量。
public abstract int adjustCustomAudioPublishVolume(int sourceId, int volume);
调用该方法设置音频在远端播放的音量后,如果你想重新调整音量,你可以再次调用该方法。
参数
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
- volume
- 自定义采集音频的播放音量,取值范围为 [0,100]。0 表示静音,100 表示原始音量。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
adjustAudioMixingVolume
调节音乐文件的播放音量。
public abstract int adjustAudioMixingVolume(int volume);
该方法调节混音音乐文件在本端和远端的播放音量大小。
- 该方法需要在 startAudioMixing [2/2] 后调用。
- 调用该方法不影响调用 playEffect [2/2] 播放音效文件的音量。
参数
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustPlaybackSignalVolume
调节本地播放的所有远端用户信号音量。
public abstract int adjustPlaybackSignalVolume(int volume);
- 该方法调节的是本地播放的所有远端用户混音后的音量。
- 该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustRecordingSignalVolume
调节音频采集信号音量。
public abstract int adjustRecordingSignalVolume(int volume);
该方法在加入频道前后都能调用。
参数
- volume
-
音量,取值范围为 [0,400]。
- 0: 静音。
- 100: (默认)原始音量。
- 400: 原始音量的 4 倍,自带溢出保护。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
adjustUserPlaybackSignalVolume
调节本地播放的指定远端用户信号音量。
public abstract int adjustUserPlaybackSignalVolume(int uid, int volume);
你可以在通话中调用该方法调节指定远端用户在本地播放的音量。如需调节多个用户在本地播放的音量,则需多次调用该方法。
- 该方法需要在加入频道后调用。
- 该方法调节的是本地播放的指定远端用户混音后的音量。
参数
- uid
- 远端用户 ID。
- volume
- 音乐文件音量范围为 0~100。100 (默认值)为原始文件音量。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
clearVideoWatermarks
删除已添加的视频水印。
public abstract int clearVideoWatermarks();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
complain
投诉通话质量。
public abstract int complain(String callId, String description);
该方法允许用户就通话质量进行投诉。需要在离开频道后调用。
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- description
- (非必选项)通话的描述。长度应小于 800 字节。
返回值
configRhythmPlayer
配置虚拟节拍器。
public abstract int configRhythmPlayer(AgoraRhythmPlayerConfig config);
调用 startRhythmPlayer 后,你可以调用该方法重新配置虚拟节拍器。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
false
。
参数
- config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
create [1/2]
创建并初始化 RtcEngine。
public static synchronized RtcEngine create( Context context, String appId, IRtcEngineEventHandler handler) throws Exception {}
RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 调用该方法和 create [2/2] 均能创建 RtcEngine 实例。该方法与 create [2/2] 的区别在于,create [2/2] 支持在创建 RtcEngine 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
- context
-
安卓活动上下文。
- appId
- Agora 为 app 开发者签发的 App ID。 使用同一个 App ID 的 app 才能进入同一个频道进行通话或直播。一个 App ID 只能用于创建一个 RtcEngine。如需更换 App ID,必须先调用 destroy 销毁当前 RtcEngine 再重新创建。
- handler
- RtcEngine 的事件句柄,详见 IRtcEngineEventHandler。
返回值
- 方法调用成功,返回一个 RtcEngine 对象。
- 方法调用失败,返回错误码。
异常
- Exception
- 调用该方法时可能会发生的异常说明。
create [2/2]
创建并初始化 RtcEngine。
public static synchronized RtcEngine create(RtcEngineConfig config) throws Exception {}
RtcEngine 类的所有接口函数,如无特殊说明,都是异步调用,对接口的调用建议在同一个线程进行。
- 请确保在调用其他 API 前先调用该方法创建并初始化 RtcEngine。
- 调用该方法和 create [1/2] 均能创建 RtcEngine 实例。该方法与 create [1/2] 的 区别在于,该方法支持在创建 RtcEngine 实例时进行更多配置,如指定访问区域、设置日志文件等。
- SDK 只支持每个 app 创建一个 RtcEngine 实例。
参数
- config
-
RtcEngine 实例的配置。详见 RtcEngineConfig。
返回值
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 设置了无效的参数。
- -7: SDK 初始化失败。
- -22: 资源申请失败。当 app 占用资源过多,或系统资源耗尽时,SDK 分配资源失败,会返回该错误。
- -101: App ID 无效。
返回值
- 方法调用成功,返回一个 RtcEngine 对象。
- 方法调用失败,返回错误码。
异常
- Exception
- 调用该方法时可能会发生的异常说明。
createDataStream [1/2]
创建数据流。
public abstract int createDataStream(boolean reliable, boolean ordered);
在 RtcEngine 生命周期内,每个用户最多只能创建 5 个数据流。
- 该方法需要在加入频道后调用。
- 不可将 reliable 设为
true
且将 ordered 设为true
。
参数
- reliable
-
该数据流是否可靠:
true
: 接收方 5 秒内会收到发送方所发送的数据,否则会收到 onStreamMessageError 回调并获得相应报错信息。false
: 接收方不保证收到,就算数据丢失也不会报错。
- ordered
-
该数据流是否有序:
true
: 接收方会按照发送方发送的顺序收到数据包。false
: 接收方不保证按照发送方发送的顺序收到数据包。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。
createDataStream [2/2]
创建数据流。
public abstract int createDataStream(DataStreamConfig config);
该方法用于创建数据流。每个用户在每个频道中最多只能创建 5 个数据流。
相比 createDataStream [1/2],该方法不支持数据可靠。接收方会丢弃超出发送时间 5 秒后的数据包。
参数
- config
- 数据流设置。详见 DataStreamConfig。
返回值
- 创建的数据流的 ID:方法调用成功。
- < 0:方法调用失败。
createMediaPlayer
创建媒体播放器。
public abstract IMediaPlayer createMediaPlayer();
返回值
- 方法调用成功:返回 IMediaPlayer 对象。
- 方法调用失败:返回空指针。
CreateRendererView
创建 RendererView。
public static SurfaceView CreateRendererView(Context context) { return new SurfaceView(context);
- 弃用:
- 此方法已废弃。请使用 Android 原生的 SurfaceView。
该方法创建视频 RendererView,返回 SurfaceView 的类型。 View 的操作和布局由 app 管理, Agora SDK 在 app 提供的 View 上进行渲染。 显示视频视图必须调用该方法,而不是直接调用 SurfaceView。
参数
- context
- 安卓活动 (Android Activity) 的上下文。
返回值
SurfaceView
CreateTextureView
创建 TextureView。
public static TextureView CreateTextureView(Context context) { return new TextureView(context);
- 弃用:
- 此方法已废弃。请使用 Android 原生的 TextureView。
该方法创建 TextureView,适用于需要对视频画面进行缩放、旋转和平移的场景,如屏幕共享。View 的操作和布局由 app 管理,SDK 仅在 app 提供的 View 上进行渲染。
参数
- context
- 安卓活动 (Android Activity) 的上下文。
返回值
TextureView
createCustomVideoTrack
创建一个自定义的视频轨道。
public abstract int createCustomVideoTrack();
- 调用该方法创建视频轨道并获得视频轨道 ID。
- 在每个频道的 ChannelMediaOptions 中,将 customVideoTrackId 参数设置为你想要发布的视频轨道 ID,并将 publishCustomVideoTrack 设置为
true
。 - 调用 pushExternalVideoFrameEx [2/2] 将 videoTrackId 指定为步骤 2 中指定的视频轨道 ID,即可实现在多个频道中发布对应的自定义视频源。
返回值
- 方法调用成功,返回视频轨道 ID 作为该视频轨道的唯一标识。
- 方法调用失败,返回负值。
destroyCustomVideoTrack
销毁指定的视频轨道。
public abstract int destroyCustomVideoTrack(int video_track_id);
参数
- video_track_id
- 调用 createCustomVideoTrack 方法返回的视频轨道 ID。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
destroy
销毁 RtcEngine 对象。
public static synchronized void destroy() { if (mInstance == null) return; mInstance.doDestroy(); mInstance = null; System.gc(); }
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。
调用该方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须依次重新调用 create [2/2] 方法创建一个新的 RtcEngine 对象。
disableAudio
关闭音频模块。
public abstract int disableAudio();
- 该方法设置内部引擎为禁用状态,在频道内和频道外均可调用。离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableAudioSpectrumMonitor
关闭音频频谱监测。
public abstract int disableAudioSpectrumMonitor();
调用 enableAudioSpectrumMonitor 后,如果你想关闭音频频谱监测,请调用该方法。
该方法在加入频道前后均可调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
disableVideo
关闭视频模块。
public abstract int disableVideo();
该方法用于关闭视频模块,可以在加入频道前或者通话中调用,在加入频道前调用,则自动开启纯音频模式,在通话中调用则由视频模式切换为纯音频模式。 调用 enableVideo 方法可开启视频模式。
成功调用该方法后,远端会触发 onUserEnableVideo (false
) 回调。
- 该方法设置的是内部引擎为禁用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudio
启用音频模块。
public abstract int enableAudio();
启用音频模块(默认为开启状态)。
- 该方法设置音频模块为启用状态,在频道内和频道外均可调用。在离开频道后仍然有效。
- 该方法开启整个音频模块,响应时间较慢,因此 Agora 建议使用如下方法来控制音频模块:
- enableLocalAudio: 是否启动麦克风采集并创建本地音频流。
- muteLocalAudioStream: 是否发布本地音频流。
- muteRemoteAudioStream: 是否接收并播放远端音频流。
- muteAllRemoteAudioStreams: 是否接收并播放所有远端音频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudioQualityIndication
启用音频质量通知回调。
public abstract int enableAudioQualityIndication(boolean enabled);
- 弃用:
- 从 v2.4.1 起废弃。
参数
- enabled
- 是否启用音频质量通知回调。
true
: 启用。false
: (默认)禁用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableAudioSpectrumMonitor
开启音频频谱监测。
public abstract int enableAudioSpectrumMonitor(int intervalInMS);
如果你想获取本地或远端用户的音频频谱数据,请注册音频频谱观测器并开启音频频谱监测。
该方法在加入频道前后均可调用。
参数
- intervalInMS
-
SDK 触发 onLocalAudioSpectrum 和 onRemoteAudioSpectrum 回调的时间间隔(毫秒)。 默认值为 100 毫秒。取值不得少于 10 毫秒,否则该方法会调用失败。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 参数设置错误。
enableAudioVolumeIndication
启用用户音量提示。
public abstract int enableAudioVolumeIndication(int interval, int smooth, boolean reportVad);
该方法允许 SDK 定期向 app 报告本地发流用户和瞬时音量最高的远端用户(最多 3 位)的音量相关信息。启用该方法后,只要频道内有发流用户, SDK 会在加入频道后按设置的时间间隔触发 onAudioVolumeIndication 回调。
参数
- interval
- 指定音量提示的时间间隔:
- ≤ 0: 禁用音量提示功能。
- > 0: 返回音量提示的间隔,单位为毫秒。该参数需要设为 200 的整数倍。如果取值低于 200,SDK 会自动调整为 200。
- smooth
- 平滑系数,指定音量提示的灵敏度。取值范围为 [0,10],建议值为 3。数字越大,波动越灵敏;数字越小,波动越平滑。
- reportVad
-
true
:开启本地人声检测功能。开启后,onAudioVolumeIndication 回调的 vad 参数会报告是否在本地检测到人声。false
:(默认)关闭本地人声检测功能。除引擎自动进行本地人声检测的场景外,onAudioVolumeIndication 回调的 vad 参数不会报告是否在本地检测到人声。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableContentInspect
开启/关闭视频截图上传。
public abstract int enableContentInspect(boolean enabled, ContentInspectConfig config);
开启视频截图上传后,SDK 会根据你在 ContentInspectConfig 中设置的模块类型和频率对本地用户发送的视频进行截图和上传。截图完成后,Agora 服务器会以 HTTPS 请求的形式,向你的服务器发送回调通知,并将所有截图发送至你指定的第三方云存储。
- 调用该方法前,请确保已联系技术支持开通 Agora 视频截图上传服务。
- 该方法依赖于视频内容审核动态库
libagora_ci_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 设置是否开启视频截图上传:
true
:开启视频截图上传。false
:关闭视频截图上传。
- config
- 视频截图上传配置。详见 ContentInspectConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableDualStreamMode [1/2]
在发送端开启或关闭双流模式。
public abstract int enableDualStreamMode(boolean enabled);
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式。
true
: 开启双流模式。false
: (默认) 关闭双流模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableDualStreamMode [2/2]
在发送端开启或关闭双流模式并设置视频小流。
public abstract int enableDualStreamMode(boolean enabled, SimulcastStreamConfig streamConfig);
- 视频大流:高分辨率、高帧率的视频流。
- 视频小流:低分辨率、低帧率的视频流。
开启双流模式后,你可以在收流端调用 setRemoteVideoStreamType 选择接收视频大流或视频小流。
- 该方法适用于发送端发送的所有类型的流,包括且不限于来自摄像头采集的视频流、屏幕共享流、自定义采集的视频流。
- 如果需要在多频道场景下开启视频双流,可以调用 enableDualStreamModeEx 方法。
- 该方法可以在加入频道前后调用。
参数
- enabled
-
是否开启双流模式:
true
: 开启双流模式。false
: (默认) 关闭双流模式。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableEncryption
开启或关闭内置加密。
public abstract int enableEncryption(boolean enabled, EncryptionConfig config);
在安全要求较高的场景下,Agora 建议你在加入频道前,调用本方法开启内置加密。
同一频道内所有用户必须使用相同的加密模式和密钥。用户离开频道后,SDK 会自动关闭加密。如需重新开启加密,你需要在用户再次加入频道前调用该方法。
参数
- enabled
-
是否开启内置加密:
- true: 开启内置加密。
- false: 关闭内置加密。
- config
- 配置内置加密模式和密钥。详见 EncryptionConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -2: 调用了无效的参数。需重新指定参数。
- -4: 设置的加密模式不正确或加载外部加密库失败。需检查枚举值是否正确或重新加载外部加密库。
- -7: SDK 尚未初始化。需在调用 API 之前已创建 RtcEngine 对象并完成初始化。
enableExtension
启用/禁用插件。
public abstract int enableExtension(String provider, String extension, boolean enable);
该方法需要在加入频道前调用。
- 如果要开启多个插件,需要多次调用该方法。
- 不同插件在 SDK 中处理数据的顺序由插件的开通顺序决定。即先开启的插件会先处理数据。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- enable
-
是否启用插件:
true
: 启用插件。false
: 禁用插件。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableFaceDetection
开启/关闭本地人脸检测。
public abstract int enableFaceDetection(boolean enabled);
该方法在加入频道前后都能调用。
- 摄像头采集的画面大小
- 人脸在 view 中的位置
- 人脸距设备屏幕的距离
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannel [2/2] 实现)后调用。
参数
- enable
- 是否开启人脸检测:
true
:开启人脸检测。false
:(默认)关闭人脸检测。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableInEarMonitoring [1/2]
开启耳返功能。
public abstract int enableInEarMonitoring(boolean enabled);
该方法打开或关闭耳返功能。
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 开启/关闭耳返功能:
true
: 开启耳返功能。false
: (默认)关闭耳返功能。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableInEarMonitoring [2/2]
开启耳返功能。
public abstract int enableInEarMonitoring(boolean enabled, int includeAudioFilters);
该方法打开或关闭耳返功能。
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- enabled
- 开启/关闭耳返功能:
true
: 开启耳返功能。false
: (默认)关闭耳返功能。
- includeAudioFilters
- 耳返 audio filter 类型:
- EAR_MONITORING_FILTER_NONE (1 << 0):不在耳返中添加 audio filter。
- EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS (1 << 1): 在耳返中添加人声效果 audio filter。如果你实现了美声、音效等功能,用户可以在耳返中听到添加效果后的声音。
- EAR_MONITORING_FILTER_NOISE_SUPPRESSION (1 <<2):在耳返中添加降噪 audio filter。
可使用按位或运算符 (|) 添加多个 audio filter。注意: 如果你将 enabled 参数设为
false
,则无需设置 includeAudioFilters 参数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableLocalAudio
开关本地音频采集。
public abstract int enableLocalAudio(boolean enabled);
当用户加入频道时,音频功能默认是开启的。该方法可以关闭或重新开启本地音频功能,即停止或重新开始本地音频采集。
该方法不影响接收远端音频流,enableLocalAudio(false)
适用于只听不发的用户场景。
- 该方法与 muteLocalAudioStream 的区别在于:
- enableLocalAudio: 开启或关闭本地音频采集及处理。使用 enableLocalAudio 关闭或开启本地采集后,本地听远端播放会有短暂中断。
- muteLocalAudioStream: 停止或继续发送本地音频流。
- 该方法在加入频道前后均可调用。在加入频道前调用只能设置设备状态,在加入频道后才会立即生效。
参数
- enabled
-
true
: 重新开启本地音频功能,即开启本地音频采集(默认);false
: 关闭本地音频功能,即停止本地音频采集。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableLocalVideo
开关本地视频采集。
public abstract int enableLocalVideo(boolean enabled);
该方法禁用或重新启用本地视频采集,不影响接收远端视频。
调用 enableVideo 后,本地视频采集即默认开启。你可以调用 enableLocalVideo(false
) 关闭本地视频采集。关闭后如果想要重新开启,则可调用 enableLocalVideo(true
)。
成功禁用或启用本地视频采集后,远端会触发 onRemoteVideoStateChanged 回调。
- 该方法在加入频道前后都能调用。
- 该方法设置内部引擎为启用状态,在离开频道后仍然有效。
参数
- enabled
-
是否开启本地视频采集。
true
:(默认)开启本地视频采集。false
: 关闭本地视频采集。关闭后,远端用户会接收不到本地用户的视频流;但本地用户依然可以接收远端用户的视频流。设置为false
时,该方法不需要本地有摄像头。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableRemoteSuperResolution
开启或关闭远端视频超分辨率。
public abstract int enableRemoteSuperResolution(int uid, boolean enable);
该功能可以有效提升本地用户看到的远端视频画面的分辨率,即:将接收到的指定远端用户的视频宽和高(像素)均扩大为 2 倍。
- 如果参数 superResolutionType >0:超分辨率已开启。
- 如果参数 superResolutionType =0:超分辨率未开启。
超分辨率功能会额外耗费系统资源。为平衡视觉体验和系统消耗,只可以对一个远端用户开启超分辨率,并且远端用户视频的原始分辨率在设备上不能超过 640 × 360。
- 该方法依赖于超分辨率动态库
libagora_super_resolution_extension.so
,如果删除该动态库会导致无法正常开启该功能。 - 该方法对用户设备具有一定要求,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
- Android:
参数
- uid
- 远端用户 ID。
- enable
- 是否对远端视频开启超分辨率:
true
: 开启超分辨率。false
: 关闭超分辨率。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableSoundPositionIndication
开启/关闭远端用户的语音立体声。
public abstract int enableSoundPositionIndication(boolean enabled);
如果想调用 setRemoteVoicePosition 实现听声辨位的功能,请确保在加入频道前调用该方法开启远端用户的语音立体声。
参数
- enabled
- 是否开启远端用户语音立体声:
true
: 开启语音立体声。false
: 关闭语音立体声。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
enableVideo
启用视频模块。
public abstract int enableVideo();
该方法可以在加入频道前或者通话中调用,在加入频道前调用则自动开启视频模块;在通话中调用则由音频模式切换为视频模式。调用 disableVideo 方法可关闭视频模式。
成功调用该方法后,远端会触发 onRemoteVideoStateChanged 回调。
- 该方法设置的是内部引擎为启用状态,在离开频道后仍然有效。
- 该方法重置整个引擎,响应时间较慢,因此声网建议使用如下方法来控制视频模块:
- enableLocalVideo: 是否启动摄像头采集并创建本地视频流。
- muteLocalVideoStream: 是否发布本地视频流。
- muteRemoteVideoStream: 是否接收并播放远端视频流。
- muteAllRemoteVideoStreams: 是否接收并播放所有远端视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
enableVideoImageSource
设置是否开启垫片推流功能。
public abstract int enableVideoImageSource(boolean enabled, ImageTrackOptions options);
在发布视频流时,你可以调用该方法使用自定义图片来替代当前发布的视频流画面进行推流。
开启该功能后,你可以通过 ImageTrackOptions 参数自定义垫片图片;在你关闭垫片功能之后,远端用户看到的依旧是当前你发布的视频流画面。
参数
- enable
- 是否开启垫片推流:
true
:开启垫片推流。false
:(默认)关闭垫片推流。
- options
- 垫片图片设置,详见 ImageTrackOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
enableVirtualBackground
开启/关闭虚拟背景。
public abstract int enableVirtualBackground( boolean enabled, VirtualBackgroundSource backgroundSource);
虚拟背景功能支持你使用自定义的背景图替代本地用户原来的背景图或者将背景虚化处理。成功开启虚拟背景功能后,频道内所有用户都能看到自定义的背景。
请在 enableVideo 或 startPreview [1/2] 之后调用该方法。
- 该功能对设备性能要求较高,Agora 推荐你在搭载如下芯片的设备上使用:
- 骁龙 700 系列 750G 及以上
- 骁龙 800 系列 835 及以上
- 天玑 700 系列 720 及以上
- 麒麟 800 系列 810 及以上
- 麒麟 900 系列 980 及以上
- Agora 建议你在满足如下条件的场景中使用该功能:
- 使用高清摄像设备、摄像环境光照均匀。
- 摄像画面中,物件较少,用户的人像为半身人像且基本无遮挡,背景色较单一且与用户着装颜色不同。
参数
- enabled
- 是否开启虚拟背景:
true
: 开启虚拟背景。false
: 关闭虚拟背景。
- backgroundSource
- 自定义的背景图。详见 VirtualBackgroundSource。为将自定义背景图的分辨率与 SDK 的视频采集分辨率适配,SDK 会在保证自定义背景图不变形的前提下,对自定义背景图进行缩放和裁剪。
- segproperty
- 背景图像的处理属性。详见 SegmentationProperty。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1:自定义的背景图不存在。请检查 VirtualBackgroundSource 中 source 的值。
- -2:自定义的背景图颜色格式出错。请检查 VirtualBackgroundSource 中 color 的值。
- -3:设备不支持使用虚拟背景。
enableWebSdkInteroperability
打开与 Web SDK 的互通(仅在直播场景适用)。
public abstract int enableWebSdkInteroperability(boolean enabled);
- 弃用:
- 该方法已废弃,SDK 自动开启与 Web SDK 的互通,无需调用该方法开启。
该方法打开或关闭与 Agora Web SDK 的互通。如果有用户通过 Web SDK 加入频道,请确保调用该方法,否则 Web 端用户看 Native 端的画面会是黑屏。
该方法仅在直播场景下适用,通信场景下默认互通是打开的。
参数
- enabled
- 是否打开与 Agora Web SDK 的互通:
true
: 打开互通。false
: (默认) 关闭互通。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getAudioDeviceInfo
获取音频设备信息。
public abstract DeviceInfo getAudioDeviceInfo();
调用该方法后,你可以获取音频设备是否支持极低延时采集和播放。
- 该方法在加入频道前后均可调用。
返回值
- 非空:方法调用成功。
- 空:方法调用失败。
getAudioEffectManager
获取 IAudioEffectManager 类,以管理音效文件。
public abstract IAudioEffectManager getAudioEffectManager();
返回值
IAudioEffectManager
getAudioMixingCurrentPosition
获取音乐文件的播放进度。
public abstract int getAudioMixingCurrentPosition();
该方法获取当前音乐文件播放进度,单位为毫秒。
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。 - 如需多次调用 getAudioMixingCurrentPosition,请确保调用间隔大于 500 ms。
返回值
- ≥ 0: 方法调用成功,返回当前音乐文件播放进度(ms)。0 表示当前音乐文件未开始播放。
- < 0: 方法调用失败。
getAudioMixingDuration
获取音乐文件总时长。
public abstract int getAudioMixingDuration();
该方法获取音乐文件总时长,单位为毫秒。
你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功返回音乐文件时长。
- < 0: 方法调用失败。
getAudioMixingPlayoutVolume
获取音乐文件的本地播放音量。
public abstract int getAudioMixingPlayoutVolume();
该方法获取混音的音乐文件本地播放音量,方便排查音量相关问题。
你需要在调用 startAudioMixing [2/2] 并收到 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioMixingPublishVolume
获取音乐文件的远端播放音量。
public abstract int getAudioMixingPublishVolume();
该接口可以方便开发者排查音量相关问题。
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。返回值
- ≥ 0: 方法调用成功则返回音量值,范围为 [0,100]。
- < 0: 方法调用失败。
getAudioTrackCount
获取当前音乐文件的音轨索引。
public abstract int getAudioTrackCount();
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
返回值
- 方法调用成功时,返回当前音乐文件的音轨索引。
- < 0: 方法调用失败。
getCallId
getCameraMaxZoomFactor
获取摄像头支持最大缩放比例。
public abstract float getCameraMaxZoomFactor();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
返回值
设备摄像头支持的最大缩放比例。
getConnectionState
获取当前网络连接状态。
public abstract RtcConnection.CONNECTION_STATE_TYPE getConnectionState();
该方法在加入频道前后都能调用。
返回值
当前网络连接状态。
getEffectCurrentPosition
获取指定音效文件的播放进度。
public int getEffectCurrentPosition(int soundId);
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
返回值
- 方法调用成功,返回指定音效文件的播放进度(毫秒)。
- < 0:方法调用失败。
getEffectDuration
获取指定音效文件总时长。
public abstract int getEffectDuration(String filePath);
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
/assets/
开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 URI 地址访问本地文件。例如content://com.android.providers.media.documents/document/audio%3A14441
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
返回值
- 方法调用成功,返回指定音效文件时长(毫秒)。
- < 0:方法调用失败。
getErrorDescription
获取警告或错误描述。
public static String getErrorDescription(int error)
参数
- error
- SDK 报告的错误码或警告码。
返回值
具体的错误或警告描述。
getExtensionProperty [1/2]
获取插件的详细信息。
public abstract String getExtensionProperty(String provider, String extension, String key);
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
返回值
- 方法调用成功,则返回插件信息。
- 方法调用失败,则返回空字符串。
getExtensionProperty [2/2]
获取插件的详细信息。
public abstract String getExtensionProperty( String provider, String extension, String key, Constants.MediaSourceType sourceType);
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
- sourceType
- 插件的媒体源类型。详见 MediaSourceType。
返回值
- 方法调用成功,则返回插件信息。
- 方法调用失败,则返回空字符串。
getMediaPlayerCacheManager
获取 IMediaPlayerCacheManager 实例。
public abstract IMediaPlayerCacheManager getMediaPlayerCacheManager();
请在初始化 RtcEngine 后调用该方法。
返回值
getNativeHandle
获取 Native SDK 的 C++ 句柄。
public abstract long getNativeHandle();
该方法获取 Native SDK engine 的 C++ 句柄,用于包括注册音视频帧观测器在内的特殊场景。
返回值
SDK 引擎的 Native 句柄。
getNetworkType
获取本地网络连接类型。
public abstract int getNetworkType();
- 自从
- v4.0.1
你可以在任何阶段通过该方法获取正在使用的网络类型。
返回值
- ≥ 0: 方法调用成功,返回本地网络连接类型。
- 0:网络连接已断开。
- 1:网络类型为 LAN。
- 2:网络类型为 Wi-Fi(包含热点)。
- 3:网络类型为 2G 移动网络。
- 4:网络类型为 3G 移动网络。
- 5:网络类型为 4G 移动网络。
- 6:网络类型为 5G 移动网络。
- < 0: 方法调用失败,返回错误码。
- -1:网络连接类型未知。
getUserInfoByUid
通过 UID 获取用户信息。
public abstract int getUserInfoByUid(int uid, UserInfo userInfo);
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- uid
- 用户 ID。
- userInfo
- 输入和输出参数。标识用户的 UserInfo 对象:
- 输入值:一个 UserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getUserInfoByUserAccount
通过 User Account 获取用户信息。
public abstract int getUserInfoByUserAccount(String userAccount, UserInfo userInfo);
远端用户加入频道后,SDK 会获取到该远端用户的 UID 和 User Account,然后缓存一个包含了远端用户 UID 和 User Account 的 Mapping 表,并在本地触发 onUserInfoUpdated 回调。收到这个回调后,你可以调用该方法,通过传入 UID 获取包含了指定用户 User Account 的 UserInfo 对象。
参数
- userAccount
- 用户 User Account。
- userInfo
- 输入和输出参数。标识用户的 UserInfo 对象:
- 输入值:一个 UserInfo 对象
- 输出值:一个包含了用户 User Account 和 UID 的 UserInfo 对象
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
getSdkVersion
获取 SDK 版本。
public static String getSdkVersion()
参数
返回值
当前的 SDK 版本号。格式为字符串。
isCameraAutoFocusFaceModeSupported
检测设备是否支持人脸对焦功能。
public abstract boolean isCameraAutoFocusFaceModeSupported();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
返回值
true
: 设备支持人脸对焦功能。false
: 设备不支持人脸对焦功能。
isCameraExposurePositionSupported
检测设备是否支持手动曝光功能。
public abstract boolean isCameraExposurePositionSupported();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
返回值
true
: 设备支持手动曝光功能。false
: 设备不支持手动曝光功能。
isCameraFaceDetectSupported
检查设备摄像头是否支持人脸检测。
public abstract boolean isCameraFaceDetectSupported();
返回值
true
: 设备摄像头支持人脸检测。false
: 设备摄像头不支持人脸检测。
isCameraFocusSupported
检测设备是否支持手动对焦功能。
public abstract boolean isCameraFocusSupported();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
返回值
true
: 设备支持手动对焦功能。false
: 设备不支持手动对焦功能。
isCameraTorchSupported
检测设备是否支持闪光灯常开。
public abstract boolean isCameraTorchSupported();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
- 一般情况下,app 默认开启前置摄像头,因此如果你的前置摄像头不支持闪光灯常开,直接使用该方法会返回 false。如果需要检查后置摄像头是否支持闪光灯常开,需要先使用 switchCamera 切换摄像头,再使用该方法。
返回值
true
: 设备支持闪光灯常开。false
: 设备不支持闪光灯常开。
isCameraZoomSupported
检测设备是否支持摄像头缩放功能。
public abstract boolean isCameraZoomSupported();
- 请在启动摄像头之后调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
返回值
true
: 设备支持相机缩放功能。false
: 设备不支持相机缩放功能。
isSpeakerphoneEnabled
检查扬声器状态启用状态。
public abstract boolean isSpeakerphoneEnabled();
返回值
true
: 扬声器已开启,语音会输出到扬声器。false
: 扬声器未开启,语音会输出到非扬声器(听筒,耳机等)。
isTextureEncodeSupported
检查视频是否支持 Texture 编码。
public abstract boolean isTextureEncodeSupported();
返回值
true
:支持 Texture 编码。false
:不支持 Texture 编码。
joinChannel [1/2]
加入频道。
public abstract int joinChannel( String token, String channelName, String optionalInfo, int optionalUid);
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- optionalInfo
- (非必选项) 预留参数。
- optionalUid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。 建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回, 应用层必须记住该返回值并维护,SDK 不对该返回值进行维护。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [2/2] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannel [2/2]
设置媒体选项并加入频道。
public abstract int joinChannel( String token, String channelId, int uid, ChannelMediaOptions options);
该方法让用户加入通话频道,在同一个频道内的用户可以互相通话,多个用户加入同一个频道,可以群聊。 使用不同 App ID 的 app 不能互通。
- 本地会触发 onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会触发 onUserJoined 回调。
在网络状况不理想的情况下,客户端可能会与 Agora 服务器失去连接;SDK 会自动尝试重连,重连成功后,本地会触发 onRejoinChannelSuccess 回调。
相比 joinChannel [1/2],该方法增加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
- 该方法允许用户一次加入仅一个频道。
- 请务必确保用于生成 Token 的 App ID 和 create [2/2] 方法初始化引擎时用的是同一个 App ID,否则使用 Token 加入频道失败。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- channelId
-
频道名。该参数标识用户进行实时音视频互动的频道。App ID 一致的前提下,填入相同频道名的用户会进入同一个频道进行音视频互动。该参数为长度在 64 字节以内的字符串。以下为支持的字符集范围(共 89 个字符):
- 26 个小写英文字母 a~z
- 26 个大写英文字母 A~Z
- 10 个数字 0~9
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
- uid
- 用户 ID。该参数用于标识在实时音视频互动频道中的用户。你需要自行设置和管理用户 ID,并确保同一频道内的每个用户 ID 是唯一的。该参数为 32 位无符号整数。 建议设置范围:1 到 232-1。如果不指定(即设为 0),SDK 会自动分配一个,并在 onJoinChannelSuccess 回调中返回, app 层必须记住该返回值并维护,SDK 不对该返回值进行维护。
- options
- 频道媒体设置选项。详见 ChannelMediaOptions。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [2/2] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
joinChannelWithUserAccount [1/2]
使用 User Account 和 Token 加入频道。
public abstract int joinChannelWithUserAccount( String token, String channelName, String userAccount);
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 通信场景下的用户和直播场景下的主播加入频道后,远端会依次触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- 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
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
joinChannelWithUserAccount [2/2]
使用 User Account 和 Token 加入频道,并设置是否自动订阅音频或视频流。
public abstract int joinChannelWithUserAccount( String token, String channelName, String userAccount, ChannelMediaOptions options);
- 本地:onLocalUserRegistered、onJoinChannelSuccess 和 onConnectionStateChanged 回调。
- 远端:通信场景下的用户和直播场景下的主播加入频道后,远端会分别触发 onUserJoined 和 onUserInfoUpdated 回调。
用户成功加入频道后,默认订阅频道内所有其他用户的音频流和视频流,因此产生用量并影响计费。如果想取消订阅,可以通过调用相应的 mute 方法实现。
相比 joinChannelWithUserAccount [1/2],该方法加了 options 参数,用于配置用户加入频道时是否自动订阅频道内所有远端音视频流。默认情况下,用户订阅频道内所有其他用户的音频流和视频流,因此会产生用量并影响计费。如果想取消订阅,可以通过设置 options 参数或相应的 mute 方法实现。
参数
- token
- 在服务端生成的用于鉴权的动态密钥。详见使用 Token 鉴权。
- 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。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token,uid 参数未设置为整型,ChannelMediaOptions 结构体成员值不合法。你需要填入有效的参数,重新加入频道。
- -3:RtcEngine 对象初始化失败。你需要重新初始化 RtcEngine 对象。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是:调用 startEchoTest [2/2] 开始通话回路测试后,未调用 stopEchoTest 停止测试就调用该方法加入频道。你需要在该方法前调用 stopEchoTest。
- -17:加入频道被拒绝。可能的原因是用户已经在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。除收到 CONNECTION_STATE_DISCONNECTED(1) 状态外,不要再次调用该方法加入频道。
- -102:频道名无效。你需要在 channelId 中填入有效的频道名,重新加入频道。
- -121:用户 ID 无效。你需要在 uid 中填入有效的用户 ID,重新加入频道。
leaveChannel [1/2]
离开频道。
public abstract int leaveChannel();
该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。
成功加入频道后,必须调用本方法或者 leaveChannel [2/2] 结束通话,否则无法开始下一次通话。
- 本地:onLeaveChannel 回调。
- 远端:通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 onLeaveChannel 回调。
返回值
- 0(ERR_OK): 方法调用成功。
- < 0: 方法调用失败。
- -1(ERR_FAILED): 一般性的错误(未明确归类)。
- -2(ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
leaveChannel [2/2]
离开频道。
public abstract int leaveChannel(LeaveChannelOptions options);
离开频道,即挂断或退出通话。
加入频道后,必须调用本方法或 leaveChannel [1/2] 结束通话,才能开始下一次通话。
不管当前是否在通话中,都可以调用该方法,没有副作用。该方法会把会话相关的所有资源释放掉。
该方法是异步操作,调用返回时并没有真正退出频道。在真正退出频道后,SDK 会触发 onLeaveChannel 回调。
成功调用该方法离开频道后,本地会触发onLeaveChannel 回调;通信场景下的用户和直播场景下的主播离开频道后,远端会触发 onUserOffline 回调。
- 如果你调用了本方法后立即调用 destroy 方法,SDK 将无法触发 onLeaveChannel 回调。
参数
- options
- 离开频道的选项,详见 LeaveChannelOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteAllRemoteAudioStreams
取消或恢复订阅所有远端用户的音频流。
public abstract int muteAllRemoteAudioStreams(boolean muted);
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的音频流,包括在调用该方法后加入频道的用户的音频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户音频流,可以在调用 joinChannel [2/2] 加入频道时设置 autoSubscribeAudio 为
false
。 - 该方法的推荐设置详见设置订阅状态。
参数
- muted
-
是否取消订阅所有远端用户的音频流:
true
: 取消订阅所有远端用户的音频流。false
:(默认)订阅所有远端用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteAllRemoteVideoStreams
取消或恢复订阅所有远端用户的视频流。
public abstract int muteAllRemoteVideoStreams(boolean muted);
成功调用该方法后,本地用户会取消或恢复订阅所有远端用户的视频流,包括在调用该方法后加入频道的用户的视频流。
- 该方法需要在加入频道后调用。
- 如果需要在加入频道前设置默认不订阅远端用户视频流,可以在调用 joinChannel [2/2] 加入频道时设置 autoSubscribeVideo 为
false
。
参数
- muted
-
是否取消订阅所有远端用户的视频流。
true
: 取消订阅所有用户的视频流。false
:(默认)订阅所有用户的视频流。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteLocalAudioStream
取消或恢复发布本地音频流。
public abstract int muteLocalAudioStream(boolean muted);
参数
- muted
-
是否取消发布本地音频流。
true
: 取消发布。false
:(默认)发布。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteLocalVideoStream
取消或恢复发布本地视频流。
public abstract int muteLocalVideoStream(boolean muted);
成功调用该方法后,远端会触发 onUserMuteVideo 回调。
- 相比于 enableLocalVideo(
false
) 用于控制本地视频流发送的方法,该方法响应速度更快。 - 该方法不影响视频采集状态,没有禁用摄像头。
参数
- muted
-
是否取消发送本地视频流。
true
: 取消发送本地视频流。false
: (默认)发送本地视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRecordingSignal
是否将录音信号静音。
public abstract int muteRecordingSignal(boolean muted);
参数
- muted
-
true
: 静音。false
:(默认)不静音。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
muteRemoteAudioStream
取消或恢复订阅指定远端用户的音频流。
public abstract int muteRemoteAudioStream(int uid, boolean muted);
- 该方法需要在加入频道后调用。
参数
- uid
- 指定用户的用户 ID。
- muted
-
是否取消订阅指定远端用户的音频流。
true
: 取消订阅指定用户的音频流。false
:(默认)订阅指定用户的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
muteRemoteVideoStream
取消或恢复订阅指定远端用户的视频流。
public abstract int muteRemoteVideoStream(int userId, boolean muted);
- 该方法需要在加入频道后调用。
参数
- userId
- 指定用户的用户 ID。
- muted
-
是否取消订阅指定远端用户的视频流。
true
: 取消订阅指定用户的视频流。false
: (默认)订阅指定用户的视频流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pauseAllChannelMediaRelay
暂停向所有目标频道转发媒体流。
public abstract int pauseAllChannelMediaRelay();
开始跨频道转发媒体流后,如果你需要暂停向所有频道转发媒体流,可以调用该方法;暂停后,如果要恢复跨频道媒体流转发,可以调用 resumeAllChannelMediaRelay 方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调,并在回调中报告是否成功暂停媒体流转发。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
pauseAudioMixing
暂停播放音乐文件。
public abstract int pauseAudioMixing();
请在加入频道后调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
pullPlaybackAudioFrame [1/2]
拉取远端音频数据。
public abstract int pullPlaybackAudioFrame(byte[] data, int lengthInByte);
使用该方法前,你需要调用 setExternalAudioSink 通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法仅支持拉取自采集的数据。如果你需要拉取 SDK 采集的数据,请不要调用该方法。
- 该方法需要在加入频道后调用。
- 开启外部音频渲染后,app 将无法从 onPlaybackAudioFrame 回调中获得数据。
- 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
- SDK 通过 onPlaybackAudioFrame 回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
- 调用该方法后 app 会主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
- data
- 待拉取的远端音频数据,数据类型为
byte[]
。 - lengthInByte
- 音频数据长度,单位为字节。该参数的值由音频数据时长、setExternalAudioSink 的
sampleRate
和channels
参数确定。lengthInByte
=sampleRate
/1000 × 2 ×channels
× 音频数据时长 (ms)。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pullPlaybackAudioFrame [2/2]
拉取远端音频数据。
public abstract int pullPlaybackAudioFrame(ByteBuffer data, int lengthInByte);
使用该方法前,你需要调用 setExternalAudioSink(enabled: true)
通知 app 开启并设置外部渲染。
调用该方法后,app 会采取主动拉取的方式获取远端已解码和混音后的音频数据,用于音频播放。
- 该方法需要在加入频道后调用。
- 该方法和 onPlaybackAudioFrame 回调相比,区别在于:
- onPlaybackAudioFrame:SDK 通过该回调将音频数据传输给 app。如果 app 处理延时,可能会导致音频播放抖动。
- pullPlaybackAudioFrame [1/2]:App 主动拉取音频数据。通过设置音频数据,SDK 可以调整缓存,帮助 app 处理延时,从而有效避免音频播放抖动。
参数
- data
- 待拉取的远端音频数据,数据类型为
ByteBuffer
。 - lengthInByte
- 远端音频数据长度,单位为字节。 该参数的值由音频数据时长、setExternalAudioSink 的 sampleRate 和 channels 参数确定。lengthInByte = sampleRate/1000 × 2 × channels × 音频数据时长 (ms)。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalAudioFrame [1/2]
推送外部音频帧。
public abstract int pushExternalAudioFrame(byte[] data, long timestamp);
参数
- data
- 外部音频数据。
- timestamp
- 外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalAudioFrame [2/2]
推送外部音频数据。
public abstract int pushExternalAudioFrame(ByteBuffer data, long timestamp, int sourceId);
调用该方法前,请将 ChannelMediaOptions 中的 publishCustomAudioTrack 设为 true
。
参数
- data
- 外部音频数据。
- timestamp
- 外部音频帧的时间戳(毫秒)。该参数为必填。你可以使用该时间戳还原音频帧顺序;在有视频的场景中(包含使用外部视频源的场景),该参数可以帮助实现音视频同步。
- sourceId
- 外部音频源的 ID。如果你要发布自定义的外部音频源,则将该参数设置为你想要发布的自定义音频轨道 ID。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
pushExternalVideoFrame [1/2]
推送外部原始视频帧到 SDK。
public abstract boolean pushExternalVideoFrame(AgoraVideoFrame frame);
- 弃用:
- 如果你需要推送 I422 格式的视频帧,请使用该方法。其他情况下,请改用 pushExternalVideoFrame [2/2]。
调用 setExternalVideoSource 方法,设置 enabled 参数为 true
、encodedFrame 参数为 false
后,你可以调用本方法将未编码的外部视频帧推送到 SDK。
调用该方法或 pushExternalVideoFrame [2/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrame [1/2] 方法不支持 texture 格式的视频数据。
参数
- frame
-
待推送的视频帧。详见 AgoraVideoFrame。
返回值
true
:推送成功。false
:推送失败。
pushExternalVideoFrame [2/2]
推送外部视频帧。
public abstract boolean pushExternalVideoFrame(VideoFrame frame);
该方法主动将视频帧数据用 VideoFrame 类封装后传递给 SDK。请确保在你调用本方法前已调用 setExternalVideoSource, 并将参数 enable 设置为 true
,不然调用本方法后会一直报错。
调用该方法或 pushExternalVideoFrame [1/2] 均能将视频帧数据传递给SDK。区别为 pushExternalVideoFrame [2/2] 方法支持 texture 格式的视频数据。
参数
- frame
- 待推送的外部原始视频帧。详见 VideoFrame。
返回值
true
:推送成功。false
:推送失败。
rate
给通话评分。
public abstract int rate(String callId, int rating, String description);
参数
- callId
- 通话 ID。你可以通过调用 getCallId 获取该参数。
- rating
- 给通话的评分,最低 1 分,最高 5 分,如超过这个范围,SDK 会返回 -2(
ERR_INVALID_ARGUMENT
) 错误。 - description
- (非必选项)给通话的描述。长度应小于 800 字节。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2(
ERR_INVALID_ARGUMENT
)。 - -3(
ERR_NOT_READY
)。
- -2(
registerAudioEncodedFrameObserver
注册音频编码数据观测器。
public abstract int registerAudioEncodedFrameObserver( AudioEncodedFrameObserverConfig config, IAudioEncodedFrameObserver observer);
- 请在加入频道后调用该方法。
- 由于该方法和 startAudioRecording [2/2] 都会设置音频内容和音质,Agora 不推荐该方法和 startAudioRecording [2/2] 一起使用。否则,只有后调用的方法会生效。
参数
- config
- 编码后音频的观测器设置。详见 AudioEncodedFrameObserverConfig。
- observer
- 编码后音频的观测器。详见 IAudioEncodedFrameObserver。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
registerAudioFrameObserver
注册音频观测器对象。
public abstract int registerAudioFrameObserver(IAudioFrameObserver observer);
该方法用于注册音频观测器对象,即注册回调。当需要 SDK 给出 onMixedAudioFrame、onRecordAudioFrame、onPlaybackAudioFrame 或 onEarMonitoringAudioFrame 等回调时,需要使用该方法注册回调。
参数
- observer
-
接口对象实例。详见 IAudioFrameObserver。如果传入 NULL,则表示取消注册。Agora 建议在收到 onLeaveChannel 后调用,来释放音频观测器对象。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerAudioSpectrumObserver
注册音频频谱观测器。
public abstract int registerAudioSpectrumObserver(IAudioSpectrumObserver observer);
成功注册音频频谱观测器并调用 enableAudioSpectrumMonitor 开启音频频谱监测后,SDK 会按照你设置的时间间隔报告你在 IAudioSpectrumObserver 类中实现的回调。
参数
- observer
-
音频频谱观测器。详见 IAudioSpectrumObserver。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
registerLocalUserAccount
注册本地用户 User Account。
public abstract int registerLocalUserAccount(String appId, String userAccount);
该方法为本地用户注册一个 User Account。注册成功后,该 User Account 即可标识该本地用户的身份,用户可以使用它加入频道。
成功注册 User Account 后,本地会触发 onLocalUserRegistered 回调,告知本地用户的 UID 和 User Account。
- 先调用 registerLocalUserAccount 方法注册 Account,再调用 joinChannelWithUserAccount [2/2] 方法加入频道。
- 直接调用 joinChannelWithUserAccount [2/2] 方法加入频道。
两种方式的区别在于,提前调用 registerLocalUserAccount,可以缩短使用 joinChannelWithUserAccount [2/2] 进入频道的时间。
- 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
- 空格
- "!"、"#"、"$"、"%"、"&"、"("、")"、"+"、"-"、":"、";"、"<"、"="、"."、">"、"?"、"@"、"["、"]"、"^"、"_"、"{"、"}"、"|"、"~"、","
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
registerMediaMetadataObserver
注册媒体 metadata 观测器用于接收或发送 metadata。
public abstract int registerMediaMetadataObserver(IMetadataObserver observer, int type);
你需要自行实现 IMetadataObserver 类并在本方法中指定 metadata 类型。本方法允许你为视频流添加同步的 metadata,用于多样化的直播互动,如发送购物链接、电子优惠券和在线测试。
调用该方法成功后,SDK 会触发 getMaxMetadataSize 回调。
参数
- observer
- metadata 观测器。详见 IMetadataObserver。
- type
-
metadata 类型。目前仅支持 VIDEO_METADATA。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
registerVideoEncodedFrameObserver
为编码后的视频图像注册视频帧接收观测器。
public abstract int registerVideoEncodedFrameObserver(IVideoEncodedFrameObserver receiver);
- 请在加入频道后调用该方法。
- 如果你调用该方法注册了 IVideoEncodedFrameObserver 对象,则不能再注册 IVideoFrameObserver 对象。
参数
- receiver
- 视频帧接收观测器,详见 IVideoEncodedFrameObserver。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
registerVideoFrameObserver
注册视频观测器对象。
public abstract int registerVideoFrameObserver(IVideoFrameObserver observer);
你需要在该方法中实现一个 IVideoFrameObserver 类,并根据场景需要,注册该类的回调。 成功注册视频观测器后,SDK 会在捕捉到每个视频帧时,触发你所注册的上述回调。
- 在处理回调时,你需要考虑视频帧中 width 和 height 参数的变化,因为观测得到的视频帧可能会随以下情况变化:
- 当网络状况差时,分辨率会阶梯式下降。
- 当用户自行调整分辨率时,回调中报告的分辨率也会变化。
- 该方法需要在加入频道前调用。
参数
- observer
- 接口对象实例。详见 IVideoFrameObserver。如果传入 NULL,则取消注册。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
destroy
销毁 RtcEngine 对象。
public static synchronized void destroy() { if (mInstance == null) return; mInstance.doDestroy(); mInstance = null; System.gc(); }
该方法释放 Agora SDK 使用的所有资源。有些 app 只在用户需要时才进行实时音视频通信,不需要时则将资源释放出来用于其他操作, 该方法适用于此类情况。
调用该方法后,你将无法再使用 SDK 的其它方法和回调。如需再次使用实时音视频通信功能,你必须依次重新调用 create [2/2] 方法创建一个新的 RtcEngine 对象。
removeHandler
删除指定的回调句柄。
public void removeHandler(IRtcEngineEventHandler handler) { mInstance.removeHandler((IAgoraEventHandler) handler); }
该方法删除指定的回调句柄。对于某些注册的回调句柄,如果你在收到相应回调事件后无需再次接收回调消息,可以调用该方法移除回调句柄。
参数
- handler
- 待删除的回调句柄。详见 IRtcEngineEventHandler。
renewToken
更新 Token。
public abstract int renewToken(String token);
- 发生 onTokenPrivilegeWillExpire 回调时。
- onConnectionStateChanged 回调报告 CONNECTION_CHANGED_TOKEN_EXPIRED(9) 时。
参数
- token
- 新的 Token。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:传入的参数无效。例如,使用了不合法的 Token。你需要填入有效的参数。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
resumeAllChannelMediaRelay
恢复向所有目标频道转发媒体流。
public abstract int resumeAllChannelMediaRelay();
调用 pauseAllChannelMediaRelay 方法后,如果你需要恢复向所有目标频道转发媒体流,可以调用该方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调,并在回调中报告是否成功恢复媒体流转发。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
resumeAudioMixing
恢复播放音乐文件。
public abstract int resumeAudioMixing();
该方法恢复混音,继续播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
selectAudioTrack
指定当前音乐文件的播放音轨。
public abstract int selectAudioTrack(int audioIndex);
获取音乐文件的音轨数量后,你可以调用该方法指定任一音轨进行播放。例如,如果一个多音轨文件的不同音轨存放了不同语言的歌曲,则你可以调用该方法设置音乐文件的播放语言。
- 该方法支持的音频文件格式见 https://docs.agora.io/cn/faq/audio_format。
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。
参数
- audioIndex
- 指定的播放音轨。取值范围为 [0, getAudioTrackCount()]。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
sendCustomReportMessage
发送自定义上报消息。
public abstract int sendCustomReportMessage( String id, String category, String event, String label, int value);
声网提供自定义数据上报和分析服务。该服务当前处于免费内测期。内测期提供的能力为 6 秒内最多上报 10 条数据,每条自定义数据不能超过 256 字节,每个字符串不能超过 100 字节。如需试用该服务,请联系 sales@agora.io 开通并商定自定义数据格式。
sendStreamMessage
发送数据流。
public abstract int sendStreamMessage(int streamId, byte[] message);
- 频道内每秒最多能发送 30 个包,且每个包最大为 1 KB。
- 每个客户端每秒最多能发送 6 KB 数据。
- 频道内每人最多能同时有 5 个数据通道。
成功调用该方法后,远端会触发 onStreamMessage 回调,远端用户可以在该回调中获取接收到的流消息; 若调用失败,远端会触发 onStreamMessageError 回调。
- 请确保在调用该方法前,已调用 createDataStream [2/2] 创建了数据通道。
- 直播场景下,该方法仅适用于主播用户。
参数
- streamId
- 数据流 ID。可以通过 createDataStream [2/2] 获取。
- message
- 待发送的数据。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAdvancedAudioOptions
设置音频的高级选项。
public abstract int SetAdvancedAudioOptions(AdvancedAudioOptions options);
如果你对音频处理有进阶需求,例如需要采集和发送立体声,可以调用该方法设置音频的高级选项。
- 你需要在 joinChannel [2/2]、enableAudio 和 enableLocalAudio 前调用该方法。
参数
- options
- 音频的高级选项。详见 AdvancedAudioOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAudioEffectParameters
设置 SDK 预设人声音效的参数。
public abstract int setAudioEffectParameters(int preset, int param1, int param2);
- 3D 人声音效:设置 3D 人声音效的环绕周期。
- 电音音效:设置电音音效的基础调式和主音音高。为方便用户自行调节电音音效,Agora 推荐你将基础调式和主音音高配置选项与应用的 UI 元素绑定。
设置后,频道内所有用户都能听到该效果。
- 该方法在加入频道前后都能调用。
- 为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setAudioEffectParameters 后,Agora 不推荐调用以下方法,否则 setAudioEffectParameters 设置的效果会被覆盖:
参数
- preset
- SDK 预设的音效,支持以下设置:
- ROOM_ACOUSTICS_3D_VOICE,3D 人声音效。
- 你需要在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置 为 MUSIC_STANDARD_STEREO(3) 或 MUSIC_HIGH_QUALITY_STEREO(5),否则该枚举设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- PITCH_CORRECTION,电音音效。为获取更好的人声效果,Agora 建议你在使用该枚举前将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- ROOM_ACOUSTICS_3D_VOICE,3D 人声音效。
- 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 预设的人声音效。
public abstract int setAudioEffectPreset(int preset);
调用该方法可以为本地发流用户设置 SDK 预设的人声音效,且不会改变原声的性别特征。设置音效后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 如果调用 setAudioEffectPreset 并设置除 ROOM_ACOUSTICS_3D_VOICE 或 PITCH_CORRECTION 外的枚举,请勿再调用 setAudioEffectParameters,否则 setAudioEffectPreset 设置的效果会被覆盖。
- 调用 setAudioEffectPreset 后,Agora 不推荐调用以下方法,否则 setAudioEffectPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
- 预设的音效选项。
- AUDIO_EFFECT_OFF: 原声,即关闭人声音效。
- ROOM_ACOUSTICS_KTV: KTV。
- ROOM_ACOUSTICS_VOCAL_CONCERT: 演唱会。
- ROOM_ACOUSTICS_STUDIO: 录音棚。
- ROOM_ACOUSTICS_PHONOGRAPH: 留声机。
- ROOM_ACOUSTICS_VIRTUAL_STEREO: 虚拟立体声,即 SDK 将单声道的音频渲染出双声道的音效。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- ROOM_ACOUSTICS_SPACIAL: 空旷。
- ROOM_ACOUSTICS_ETHEREAL: 空灵。
- ROOM_ACOUSTICS_3D_VOICE: 3D 人声,即 SDK 将音频渲染出在用户周围环绕的效果。环绕周期默认为 10 秒。设置该音效后,你还可以调用 setAudioEffectParameters 修改环绕周期。
- 使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_STANDARD_STEREO 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- 启用 3D 人声后,用户需要使用支持双声道的音频播放设备才能听到预期效果。
- VOICE_CHANGER_EFFECT_UNCLE: 大叔。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_OLDMAN: 老年男性。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_BOY: 男孩。建议用于处理男声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_SISTER: 少女。建议用于处理女声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_GIRL: 女孩。建议用于处理女声,否则无法达到预期效果。
- VOICE_CHANGER_EFFECT_PIGKING: 猪八戒。
- VOICE_CHANGER_EFFECT_HULK: 绿巨人。
- STYLE_TRANSFORMATION_RNB: R&B。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- STYLE_TRANSFORMATION_POPULAR: 流行。使用该预设音效前,你需要将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY 或 MUSIC_HIGH_QUALITY_STEREO,否则该预设音效的设置无效。
- PITCH_CORRECTION: 电音,即 SDK 以主音音高为 C 的自然大调为基础修正音频的实际音高。设置该音效后,你还可以调用 setAudioEffectParameters 调整修音的基础调式和主音音高。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingDualMonoMode
设置当前音频文件的声道模式。
public abstract int setAudioMixingDualMonoMode(Constants.AudioMixingDualMonoMode mode);
在双声道音频文件中,左声道和右声道可以存储不同的音频数据。根据实际需要,你可以设置声道模式为原始模式、左声道模式、右声道模式或混合模式。例如,在 KTV 场景中,音频文件的左声道存储了伴奏,右声道存储了原唱的歌声。如果你只需听伴奏,调用该方法设置音频文件的声道模式为左声道模式;如果你需要同时听伴奏和原唱,调用该方法设置声道模式为混合模式。
- 你需要在调用 startAudioMixing [2/2] 并收到
onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。 - 该方法仅适用于双声道的音频文件。
参数
- mode
- 声道模式。详见 AudioMixingDualMonoMode。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPitch
调整本地播放的音乐文件的音调。
public abstract int setAudioMixingPitch(int pitch);
本地人声和播放的音乐文件混音时,调用该方法可以仅调节音乐文件的音调。
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。参数
- pitch
- 按半音音阶调整本地播放的音乐文件的音调,默认值为 0,即不调整音调。取值范围为 [-12,12],每相邻两个值的音高距离相差半音。取值的绝对值越大,音调升高或降低得越多。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioMixingPosition
设置音乐文件的播放位置。
public abstract int setAudioMixingPosition(int pos);
该方法可以设置音频文件的播放位置,这样你可以根据实际情况播放文件,而非从头到尾播放整个文件。
onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调后调用该方法。参数
- pos
- 整数。进度条位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [1/2]
设置音频编码属性和音频场景。
public abstract int setAudioProfile(int profile, int scenario);
- 弃用:
- 此方法已废弃,如需设置音频编码属性,请改用 setAudioProfile [2/2];如需设置音频场景,请改用 setAudioScenario。
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将 profile 设置为
MUSIC_HIGH_QUALITY(4)
,scenario 设置为AUDIO_SCENARIO_GAME_STREAMING(3)
。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。
- DEFAULT (0):默认值
- 直播场景下:48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- 通信场景下:32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- SPEECH_STANDARD (1):指定 32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- MUSIC_STANDARD (2):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- MUSIC_STANDARD_STEREO (3):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 80 Kbps。
- MUSIC_HIGH_QUALITY (4):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 96 Kbps。
- MUSIC_HIGH_QUALITY_STEREO (5):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 128 Kbps。
- DEFAULT (0):默认值
- scenario
- 音频场景。不同的音频场景下,设备的音量类型是不同的。
- AUDIO_SCENARIO_DEFAULT (0): (默认)自动场景,根据用户角色和音频路由自动匹配合适的音质。
- AUDIO_SCENARIO_GAME_STREAMING (3): 高音质场景,适用于音乐为主的场景。
- AUDIO_SCENARIO_CHATROOM (5): 聊天室场景,适用于用户需要频繁上下麦的场景。该场景下,观众会收到申请麦克风权限的弹窗提示。
- AUDIO_SCENARIO_CHORUS (7): 合唱场景。适用于网络条件良好,要求极低延时的实时合唱场景。
注意: 使用该枚举前,你需要调用 getAudioDeviceInfo 获取音频设备是否支持极低延时采集和播放。只有在支持极低延时(isLowLatencyAudioSupported =
true
)的音频设备上,才能够体验到极低延时。 - AUDIO_SCENARIO_MEETING (8): 会议场景,适用于人声为主的多人会议。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioProfile [2/2]
设置音频编码属性。
public synchronized int setAudioProfile(int profile)
- 该方法在加入频道前后均可调用。
- 在有高音质需求的场景(例如音乐教学场景)中,建议将
profile
设置为MUSIC_HIGH_QUALITY (4)
。 - 如果你想设置音频应用场景,请调用 create [2/2] 并设置 RtcEngineConfig 结构体中的 mAudioScenario。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。
- DEFAULT (0):默认值
- 直播场景下:48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- 通信场景下:32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- SPEECH_STANDARD (1):指定 32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- MUSIC_STANDARD (2):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- MUSIC_STANDARD_STEREO (3):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 80 Kbps。
- MUSIC_HIGH_QUALITY (4):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 96 Kbps。
- MUSIC_HIGH_QUALITY_STEREO (5):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 128 Kbps。
- DEFAULT (0):默认值
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setAudioScenario
设置音频场景。
public abstract int setAudioScenario(int scenario);
参数
- scenario
- 音频场景。详见 AudioScenario。不同的音频场景下,设备的音量类型是不同的。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setAVSyncSource
设置发流端音画同步。
public abstract int setAVSyncSource(String channelId, int uid);
同一用户可能使用两个设备分别发送音频流和视频流,为保证接收端听到和看到的音频和视频的时间同步性,你可以在视频发送端调用该方法,并传入音频发送端的频道名、用户 ID。 SDK 会以发送的音频流的时间戳为基准进行自动调节发送的视频流,以保证即使在两个发送端的上行网络情况不一致(如分别使用 Wi-Fi 和 4G 网络)的情况下,也能让接收到的音视频具有时间同步性。
参数
- channelId
- 标识音频发送端所在频道的频道名。
- uid
- 音频发送端的用户 ID。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setBeautyEffectOptions
设置美颜效果选项。
public abstract int setBeautyEffectOptions(boolean enabled, BeautyOptions options);
开启本地美颜功能,并设置美颜效果选项。
- 请在 enableVideo 或 startPreview [1/2] 之后调用该方法。
- 该方法仅适用于 Android 5.0 及以上版本。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启美颜功能:
true
: 开启美颜功能。false
:(默认)关闭美颜功能。
- options
- 美颜选项,详细定义见 BeautyOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- ERR_NOT_SUPPORTED(4):当前设备版本低于 Android 5.0,不支持该操作。
setCameraAutoFocusFaceModeEnabled
设置是否开启人脸对焦功能。
public abstract int setCameraAutoFocusFaceModeEnabled(boolean enabled);
SDK 默认关闭人脸自动对焦。如需自行设置人脸自动对焦,请调用该方法。
- 该方法需在摄像头启动后调用,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之后。
参数
- enabled
-
是否开启人脸对焦:
true
: 开启人脸对焦功能。false
: 关闭人脸对焦功能。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraCapturerConfiguration
设置摄像头采集配置。
public abstract int setCameraCapturerConfiguration(CameraCapturerConfiguration config);
- 请在启动摄像头之前调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之前。
参数
- config
- 摄像头采集配置,详见 CameraCapturerConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraExposurePosition
设置手动曝光位置。
public abstract int setCameraExposurePosition(float positionXinView, float positionYinView);
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannel [2/2] 实现)后调用。
成功调用该方法后,本地会触发 onCameraExposureAreaChanged 回调。
参数
- positionXinView
- 触摸点相对于视图的横坐标。
- positionYinView
- 触摸点相对于视图的纵坐标。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraFocusPositionInPreview
设置手动对焦位置,并触发对焦。
public abstract int setCameraFocusPositionInPreview(float positionX, float positionY);
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannel [2/2] 实现)后调用。 成功调用该方法后,本地会触发 onCameraFocusAreaChanged 回调。
参数
- positionX
- 触摸点相对于视图的横坐标。
- positionY
- 触摸点相对于视图的纵坐标。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraTorchOn
设置是否打开闪光灯。
public abstract int setCameraTorchOn(boolean isOn);
- 请在启动摄像头之前调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之前。
参数
- isOn
-
是否打开闪光灯:
true
: 打开闪光灯。false
:(默认)关闭闪光灯。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setCameraZoomFactor
设置摄像头缩放比例。
public abstract int setCameraZoomFactor(float factor);
- 请在启动摄像头之前调用该方法,如 joinChannel [2/2]、enableVideo 或者 enableLocalVideo 之前。
参数
- factor
- 相机缩放比例,有效范围从 1.0 到最大缩放比例。你可以通过 getCameraMaxZoomFactor 方法获取设备支持的最大缩放比例。
返回值
- 方法调用成功: 返回设置的 factor 值。
- 方法调用失败: 返回值 < 0。
setChannelProfile
设置频道场景。
public abstract int setChannelProfile(int profile);
SDK 初始化后默认的频道场景为直播场景。你可以调用该方法设置 Agora 频道的使用场景。Agora SDK 会针对不同的使用场景采用不同的优化策略,如通信场景偏好流畅,直播场景偏好画质。
- 为保证实时音视频质量,相同频道内的用户必须使用同一种频道场景。
- 该方法必须在 joinChannel [2/2] 前调用和进行设置,进入频道后无法再设置。
- 不同的频道场景下,SDK 的默认音频路由和默认视频编码码率是不同的,详见 setDefaultAudioRouteToSpeakerphone 和 setVideoEncoderConfiguration 中的说明。
参数
- profile
-
频道使用场景。
- CHANNEL_PROFILE_COMMUNICATION (0):通信。当频道中只有两个用户时,建议使用该场景。
- CHANNEL_PROFILE_LIVE_BROADCASTING (1):直播。当频道中超过两个用户时,建议使用该场景。
- CHANNEL_PROFILE_GAME (2):该属性已废弃。
- CHANNEL_PROFILE_CLOUD_GAMING (3):互动。该场景对延时进行了优化。如果你的场景中有用户需要频道互动, 建议使用该场景。
返回值
- 0(ERR_OK) 方法调用成功。
- < 0 方法调用失败。
- -2 (ERR_INVALID_ARGUMENT): 参数无效。
- -7(ERR_NOT_INITIALIZED): SDK 尚未初始化。
setClientRole [1/2]
设置用户角色。
public abstract int setClientRole(int role);
在加入频道前和加入频道后均可调用该方法设置用户角色。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 本地会触发 onClientRoleChanged 回调。
- 远端会触发 onUserJoined 或
onUserOffline(USER_OFFLINE_BECOME_AUDIENCE)
回调。
参数
- role
-
用户的角色:
- CLIENT_ROLE_BROADCASTER (1):主播。
- CLIENT_ROLE_AUDIENCE (2):观众。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -7: SDK 尚未初始化。
setClientRole [2/2]
设置直播场景下的用户角色和级别。
public abstract int setClientRole(int role, ClientRoleOptions options);
直播场景下,SDK 会默认设置用户角色为观众,你可以调用该方法设置用户角色为主播。
该方法在加入频道前后均可调用。
如果你在加入频道前调用该方法设置用户角色为主播、并且通过 setupLocalVideo 方法设置了本地视频属性,则用户加入频道时会自动开启本地视频预览。
- 调用 muteLocalAudioStream 和 muteLocalVideoStream 修改发布状态。
- 本地触发 onClientRoleChanged 回调。
- 远端触发 onUserJoined 或 onUserOffline 回调。
- 用户角色(role)确定用户在 SDK 层的权限,包含是否可以发送流、是否可以接收流、是否可以旁路推流等。
- 用户级别(level)需要与角色结合使用,确定用户在其权限范围内可以享受到的服务。例如对于观众,选择接收低延时还是超低延时的视频流。不同的级别会影响计费。
参数
- role
- 直播场景中的用户角色。
- CLIENT_ROLE_BROADCASTER (1): 主播。主播可以发流也可以收流。
- CLIENT_ROLE_AUDIENCE (2):(默认)观众。观众只能收流不能发流。
- options
- 用户具体设置,包含用户级别。详见 ClientRoleOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -1: 一般性的错误(未明确归类)。
- -2: 参数无效。
- -5: 调用被拒绝。
- -7: SDK 尚未初始化。
setCloudProxy
设置 Agora 云代理服务。
public abstract int setCloudProxy(int proxyType);
当用户的网络访问受到防火墙限制时,你需要将 Agora 提供的 IP 和端口号添加到防火墙白名单,然后调用该方法开启云代理,并通过 proxyType 参数设置云代理类型。
成功连接云代理后,SDK 会触发 onConnectionStateChanged (CONNECTION_STATE_CONNECTING, CONNECTION_CHANGED_SETTING_PROXY_SERVER) 回调。
如果你想关闭已设置的 Force UDP 或 Force TCP 云代理,请调用 setCloudProxy (TRANSPORT_TYPE_NONE_PROXY)
。
如果你想更改已设置的云代理类型,请先调用 setCloudProxy (TRANSPORT_TYPE_NONE_PROXY)
,再调用 setCloudProxy 并传入你期望的 proxyType 值。
- Agora 推荐你在频道外调用该方法。
- 如果用户处于内网防火墙环境下,使用 Force UDP 云代理时,旁路推流和跨频道媒体流转发功能不可用。
- 使用 Force UDP 云代理时,调用 startAudioMixing [2/2] 方法时无法播放 HTTP 协议的在线音频文件。旁路推流和跨频道媒体流转发功能会使用 TCP 协议的云代理。
参数
- proxyType
-
云代理类型。
- TRANSPORT_TYPE_NONE_PROXY(0):自动模式。SDK 默认开启该模式。在该模式下,SDK 优先连接 SD-RTN™,如果连接失败,自动切换到 TLS 443。
- TRANSPORT_TYPE_UDP_PROXY(1):UDP 协议的云代理,即 Force UDP 云代理模式。在该模式下,SDK 始终通过 UDP 协议传输数据。
- TRANSPORT_TYPE_TCP_PROXY(2):TCP(加密)协议的云代理,即 Force TCP 云代理模式。在该模式下,SDK 始终通过 TLS 443 传输数据。
该参数为必填参数,如果你不赋值,SDK 会报错。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2: 传入的参数无效。
- -7: SDK 尚未初始化。
setColorEnhanceOptions
设置色彩增强功能。
public abstract int setColorEnhanceOptions(boolean enabled, ColorEnhanceOptions options);
摄像头采集到的视频画面可能存在色彩失真的现象。色彩增强功能可以通过智能调节饱和度和对比度等视频特性,提升视频色彩丰富度和色彩还原度,最终使视频画面更生动。
你可以调用该方法开启色彩增强功能并设置色彩增强的效果。
- 请在 enableVideo 后调用该方法。
- 色彩增强对设备性能有一定要求。开启色彩增强后,如果设备出现严重发烫等问题,Agora 推荐你将色彩增强等级修改为消耗性能较少的等级或关闭色彩增强功能。
- 该方法和 setExtensionProperty 均可开启色彩增强功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启色彩增强功能:
true
:开启色彩增强功能。false
:(默认)关闭色彩增强功能。
- options
- 色彩增强选项,用于设置色彩增强的效果。详见 ColorEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setDefaultAudioRouteToSpeakerphone
设置默认的音频路由。
public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeaker);
手机设备一般有两个音频路由,一个是位于顶部的听筒,播放声音偏小;一个是位于底部的扬声器,播放声音偏大。设置默认的音频路由,就是在没有外接设备的前提下,设置系统使用听筒还是扬声器播放音频。
- 语音通话:听筒
- 语音直播:扬声器
- 视频通话:扬声器
- 视频直播:扬声器
调用该 API 可以改变上述默认音频路由。成功改变音频路由后,SDK 会触发 onAudioRouteChanged 回调。
当手机插入外接设备,如蓝牙设备或耳机时,系统的音频路由会发生改变。详细的路由变化规律请参考 音频路由。
参数
- defaultToSpeaker
- 是否使用扬声器作为默认的音频路由:
true
: 设置默认音频路由为扬声器。false
: 设置默认音频路由为听筒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDirectCdnStreamingAudioConfiguration
设置主播端直接向 CDN 推流时的音频编码属性。
public abstract int setDirectCdnStreamingAudioConfiguration(int profile);
该方法仅对麦克风采集或自采集的音频有效,即对在 DirectCdnStreamingMediaOptions 中设置 publishMicrophoneTrack 或 publishCustomAudioTrack 为 true
时所采集的音频有效。
参数
- profile
-
音频编码属性,包含采样率、码率、编码模式和声道数。
- DEFAULT (0):默认值
- 直播场景下:48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- 通信场景下:32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- SPEECH_STANDARD (1):指定 32 kHz 采样率,语音编码,单声道,编码码率最大值为 18 Kbps。
- MUSIC_STANDARD (2):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 64 Kbps。
- MUSIC_STANDARD_STEREO (3):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 80 Kbps。
- MUSIC_HIGH_QUALITY (4):指定 48 kHz 采样率,音乐编码,单声道,编码码率最大值为 96 Kbps。
- MUSIC_HIGH_QUALITY_STEREO (5):指定 48 kHz 采样率,音乐编码,双声道,编码码率最大值为 128 Kbps。
- DEFAULT (0):默认值
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDirectCdnStreamingVideoConfiguration
设置主播端直接向 CDN 推流时的视频编码属性。
public abstract int setDirectCdnStreamingVideoConfiguration(VideoEncoderConfiguration config);
该方法仅对摄像头采集、屏幕共享或自采集的视频有效。即对在 DirectCdnStreamingMediaOptions 中设置 publishCameraTrack 或 publishCustomVideoTrack 为 true
时所采集的视频有效。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setDualStreamMode [1/2]
在发送端设置双流模式。
public abstract int setDualStreamMode(Constants.SimulcastStreamMode mode);
- 自从
- v4.0.1
SDK 默认在发送端开启小流 auto 模式,效果等同于调用该方法并将 mode 设置为 AUTO_SIMULCAST_STREAM。如果你想修改此行为,可以调用该方法并修改 mode 为 DISABLE_SIMULCAST_STREAM(始终不发送小流)或 ENABLE_SIMULCAST_STREAM(始终发送小流)。
- 调用该方法并设置 mode 为 DISABLE_SIMULCAST_STREAM 时,跟
enableDualStreamMode [1/2](false)
的效果相同。 - 调用该方法并设置 mode 为 ENABLE_SIMULCAST_STREAM 时,跟
enableDualStreamMode [1/2](true)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SIMULCAST_STREAM_MODE。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setDualStreamMode [2/2]
在发送端设置双流模式并设置视频小流。
public abstract int setDualStreamMode( Constants.SimulcastStreamMode mode, SimulcastStreamConfig streamConfig);
- 自从
- v4.0.1
SDK 默认在发送端开启小流 auto 模式,效果等同于调用该方法并将 mode 设置为 AUTO_SIMULCAST_STREAM。如果你想修改此行为,可以调用该方法并修改 mode 为 DISABLE_SIMULCAST_STREAM(始终不发送小流)或 ENABLE_SIMULCAST_STREAM(始终发送小流)。
该方法跟 setDualStreamMode [1/2] 的区别在于,该方法还可以进行视频小流的配置,SDK 会根据 streamConfig 中的配置发送小流。
- 调用该方法并设置 mode 为 DISABLE_SIMULCAST_STREAM 时,跟
enableDualStreamMode [1/2](false)
的效果相同。 - 调用该方法并设置 mode 为 ENABLE_SIMULCAST_STREAM 时,跟
enableDualStreamMode [1/2](true)
的效果相同。 - 两种方法均可在加入频道前后调用,若同时使用,则以后调用的方法中的设置为准。
参数
- mode
- 发送视频流的模式。详见 SIMULCAST_STREAM_MODE。
- streamConfig
-
视频小流的配置。详见 SimulcastStreamConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEffectPosition
设置指定音效文件的播放位置。
public abstract int setEffectPosition(int soundId, int pos);
成功设置后,本地音效文件会在指定位置开始播放。
参数
- soundId
- 音效的 ID。每个音效的 ID 具有唯一性。
- pos
- 音效文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEarMonitoringAudioFrameParameters
设置耳返的音频数据格式。
public abstract int setEarMonitoringAudioFrameParameters( int sampleRate, int channel, int mode, int samplesPerCall);
该方法用于设置 onEarMonitoringAudioFrame 回调的耳返音频数据格式。
- 调用该方法前,你需要先调用 enableInEarMonitoring [2/2],将 includeAudioFilters 设置为 EAR_MONITORING_FILTER_BUILT_IN_AUDIO_FILTERS 或 EAR_MONITORING_FILTER_NOISE_SUPPRESSION。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onEarMonitoringAudioFrame 回调。
参数
- sampleRate
- onEarMonitoringAudioFrame 中报告音频的采样率 (Hz),可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onEarMonitoringAudioFrame 中报告音频的声道数,可设置为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
-
音频帧的使用模式:
- RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): 只读模式。例如: 若用户通过 Agora SDK 采集数据,自己进行 RTMP 推流,则可以选择该模式。
- RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): 读写模式。例如:若用户自己有音效处理模块,且想要根据实际需要对数据进行前处理 (例如变声),则可以选择该模式。
- samplesPerCall
- onEarMonitoringAudioFrame 中报告的音频的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setEnableSpeakerphone
开启或关闭扬声器播放。
public abstract int setEnableSpeakerphone(boolean enabled);
如果 SDK 默认的音频路由(见音频路由)或 setDefaultAudioRouteToSpeakerphone 的设置无法满足你的需求,你可以调用 setEnableSpeakerphone 切换当前的音频路由。成功改变音频路由后,SDK 会触发 onAudioRouteChanged 回调。
该方法只设置用户在当前频道内使用的音频路由,不会影响 SDK 默认的音频路由。如果用户离开当前频道并加入新的频道,则用户还是会使用 SDK 默认的音频路由。
- 该方法需要在加入频道后调用。
- 如果用户使用了蓝牙耳机、有线耳机等外接音频播放设备,则该方法的设置无效,音频只会通过外接设备播放。当有多个外接设备时,音频会通过最后一个接入的设备播放。
参数
- enabled
-
设置是否开启扬声器播放:
true
: 开启。音频路由为扬声器。false
: 关闭。音频路由为听筒。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setEncryptionMode
启用内置的加密方案。
public abstract int setEncryptionMode(String encryptionMode);
- 弃用:
- 请改用 enableEncryption 方法。
Agora Video SDK 支持内置加密方案,默认支持 AES-128-GCM。如需采用其他加密方案,可以调用本方法。同一频道内的所有用户必须设置相同的加密方式和 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-gcm
"。
- "
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setEncryptionSecret
启用内置加密,并设置数据加密密码。
public abstract int setEncryptionSecret(String secret);
- 弃用:
- 请改用 enableEncryption 方法。
在加入频道之前, app 需调用该方法指定 secret 来启用内置的加密功能,同一频道内的所有用户应设置相同的 secret。 当用户离开频道时,该频道的 secret 会自动清除。如果未指定 secret 或将 secret 设置为空,则无法激活加密功能。
- 请不要在旁路推流时调用此方法。
- 为保证最佳传输效果,请确保加密后的数据大小不超过原始数据大小 + 16 字节。16 字节是 AES 通用加密模式下最大填充块大小。
参数
- secret
- 加密密码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionProperty
设置插件的属性。
public abstract int setExtensionProperty( String provider, String extension, String key, String value);
开启插件后,你可以调用该方法设置插件的属性。
参数
- provider
- 提供插件的服务商名称。
- extension
- 插件的名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExtensionProviderProperty
设置插件服务商的属性。
public abstract int setExtensionProviderProperty(String provider, String key, String value);
你可以调用该方法设置插件服务商的属性,并根据服务商的类型初始化相关参数。
该方法需要在 enableExtension 之后、且启用音频(enableAudio/enableLocalAudio)或启用视频(enableVideo/enableLocalVideo)之前调用。
参数
- provider
- 提供插件的服务商名称。
- key
- 插件属性的 Key。
- value
- 插件属性 Key 对应的值。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExternalAudioSink
设置外部音频渲染。
public abstract int setExternalAudioSink(boolean enabled, int sampleRate, int channels);
该方法适用于需要自行渲染音频的场景。开启外部音频渲染后,你可以调用 pullPlaybackAudioFrame [1/2] 拉取远端音频数据。App 可以对拉取到的原始音频数据进行处理后再渲染,获取想要的音频效果。
参数
- enabled
-
设置是否开启外部音频渲染:
true
:开启外部音频渲染。false
:(默认)关闭外部音频渲染。
- sampleRate
-
外部音频渲染的采样率 (Hz),可设置为 16000,32000,44100 或 48000。
- channels
- 外部音频渲染的声道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setExternalAudioSource [1/2]
设置外部音频采集参数。
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels);
请在 joinChannel [1/2] 和 startPreview [1/2] 前调用该方法。
参数
- enabled
-
true
: 开启使用外部音频源的功能。false
: (默认)关闭使用外部音频源的功能。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为 8000,16000,32000,44100 或 48000。
- channels
-
外部音频源的通道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setExternalAudioSource [2/2]
设置外部音频采集参数。
public abstract int setExternalAudioSource(boolean enabled, int sampleRate, int channels, int sourceNumber, boolean localPlayback, boolean publish);
参数
- enabled
-
是否开启使用外部音频源的功能:
true
:开启外部音频源。false
:(默认)关闭外部音频源。
- sampleRate
- 外部音频源的采样率 (Hz),可设置为
8000
,16000
,32000
,44100
或48000
。 - channels
- 外部音频源的声道数,可设置为
1
(单声道)或2
(双声道)。 - sourceNumber
- 外部音频源的数量,取值为正整数。SDK 会根据该参数值创建对应数量的自采集音频轨道,并从 0 开始为音频轨道命名。你可以在 ChannelMediaOptions 中,设置 publishCustomAudioSourceId 为你想要发布的音频轨道 ID。
- localPlayback
-
是否在本地播放外部音频源:
true
:在本地播放。false
:(默认)不在本地播放。
- publish
-
是否将音频发布到远端:
true
:(默认)发布到远端。false
:不发布到远端。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setExternalVideoSource
设置外部视频源。
public abstract int setExternalVideoSource( boolean enable, boolean useTexture, Constants.ExternalVideoSourceType sourceType);
参数
- enable
- 是否启用外部视频源:
true
: 启用外部视频源。SDK 准备接收外部视频帧。false
:(默认)不启用外部视频源。
- useTexture
- 是否使用 texture 格式的外部视频帧:
true
: 使用 texture 格式的外部视频帧。false
: 不使用 texture 格式的外部视频帧。
- sourceType
- 是否对外部视频帧编码,详见 ExternalVideoSourceType。
返回值
- 0:方法调用成功。
- < 0: 方法调用失败。
setHeadphoneEQPreset
设置预设的耳机均衡效果。
public abstract int setHeadphoneEQPreset(int preset);
- 自从
- v4.0.1
该方法主要应用于空间音效场景下,你可以选择预设的耳机均衡器收听音频,以达到预期的音频体验。
参数
- preset
- 预设的耳机均衡效果。详见 HEADPHONE_EQUALIZER_PRESET。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -1:一般性的错误(未明确归类)。
setInEarMonitoringVolume
设置耳返音量。
public abstract int setInEarMonitoringVolume(int volume);
- 用户必须使用有线耳机才能听到耳返效果。
- 该方法在加入频道前后都能调用。
参数
- volume
- 设置耳返音量,取值范围在 [0,100]。默认值为 100。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalAccessPoint
配置与声网私有媒体服务器 Native 接入模块的连接。
public abstract int setLocalAccessPoint(LocalAccessPointConfiguration config);
成功部署声网私有媒体服务器并在内网终端集成 Agora Native SDK v4.0.0 后,你可以调用该方法指定 Local Access Point,给 SDK 分配 Native 接入模块。
- 该方法仅在部署声网混合云方案后生效。你可以联系 sales@agora.io 了解和部署声网混合云。
- 该方法需要在加入频道前调用。
参数
- config
- Local Access Point 配置。详见 LocalAccessPointConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalRenderMode [1/2]
设置本地视图显示模式。
- 弃用:
- 该方法已废弃,请使用 setLocalRenderMode [2/2] 作为替代。
该方法设置本地视图显示模式。 App 可以多次调用此方法更改显示模式。
参数
- renderMode
-
本地视图显示模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalRenderMode [2/2]
更新本地视图显示模式。
public abstract int setLocalRenderMode(int renderMode, int mirrorMode);
初始化本地用户视图后,你可以调用该方法更新本地用户视图的渲染和镜像模式。该方法只影响本地用户看到的视频画面,不影响本地发布视频。
- 请在调用 setupLocalVideo 方法初始化本地视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新本地用户视图的显示模式。
参数
- renderMode
-
本地视图显示模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
- mirrorMode
-
本地视图的镜像模式。
- MIRROR_MODE_AUTO (0):默认的镜像模式(SDK 决定镜像模式)。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- MIRROR_MODE_ENABLED (1):开启镜像模式。
- MIRROR_MODE_DISABLED (2):关闭镜像模式。
注意: 如果你使用前置摄像头,默认启动本地用户视图镜像模式;如果你使用后置摄像头,默认关闭本地视图镜像模式。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVideoMirrorMode
设置本地视频镜像。
public abstract int setLocalVideoMirrorMode(int mode);
- 弃用:
- 该方法已废弃。
参数
- mode
-
- MIRROR_MODE_AUTO (0):默认的镜像模式(SDK 决定镜像模式)。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- MIRROR_MODE_ENABLED (1):开启镜像模式。
- MIRROR_MODE_DISABLED (2):关闭镜像模式。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceEqualization
设置本地语音音效均衡。
public abstract int setLocalVoiceEqualization( Constants.AUDIO_EQUALIZATION_BAND_FREQUENCY bandFrequency, int bandGain);
参数
- bandFrequency
- 频谱子带索引。取值范围是 [0,9],分别代表音效的 10 个频带。对应的中心频率为 [31,62,125,250,500,1k,2k,4k,8k,16k] Hz。详见 AUDIO_EQUALIZATION_BAND_FREQUENCY 。
- bandGain
- 每个 band 的增益,单位是 dB,每一个值的范围是 [-15,15],默认值为 0。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoicePitch
设置本地语音音调。
public abstract int setLocalVoicePitch(double pitch);
参数
- pitch
- 语音频率。可以 [0.5,2.0] 范围内设置。取值越小,则音调越低。默认值为 1.0,表示不需要修改音调。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLocalVoiceReverb
设置本地音效混响。
public abstract int setLocalVoiceReverb(Constants.AUDIO_REVERB_TYPE reverbKey, int value);
SDK 提供一个使用更为简便的方法 setAudioEffectPreset,直接实现流行、R&B、KTV 等预置的混响效果。
参数
- reverbKey
- 混响音效 Key。该方法共有 5 个混响音效 Key,详见 AUDIO_REVERB_TYPE。
- value
- 各混响音效 Key 所对应的值。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLocalVoiceReverbPreset
设置本地语音混响(含虚拟立体声效果)。
public abstract int setLocalVoiceReverbPreset(int reverbPreset);
- 弃用:
- 请改用 setAudioEffectPreset 或 setVoiceBeautifierPreset。
通信场景下的用户或直播场景下的主播均可调用该方法设置本地语音混响。成功设置以后,频道内的所有用户均可听到声音效果。
- 当使用以
AUDIO_REVERB_FX
为前缀的枚举值时,请确保在调用该方法前将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY (4) 或 MUSIC_HIGH_QUALITY_STEREO (5) ,否则该方法设置无效。 - 当使用 AUDIO_VIRTUAL_STEREO 时,Agora 推荐在调用该方法前将 setAudioProfile [1/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY_STEREO (5)。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含人声和音乐的音频数据。
- 该方法在加入频道前后都能调用。
参数
- reverbPreset
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFile
设置日志文件
public abstract int setLogFile(String filePath);
- 弃用:
- 此方法已废弃,请改用 create [2/2] 中的
logConfig
参数设置日志文件路径 。
设置 SDK 的输出 log 文件。SDK 运行时产生的所有 log 将写入该文件。App 必须保证指定的目录存在而且可写。
如需调用本方法,请在调用 create [2/2] 方法初始化 RtcEngine 对象后立即调用,否则输出日志可能不完整。
参数
- filePath
- 日志文件的完整路径。该日志文件为 UTF-8 编码。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setLogFileSize
设置 SDK 输出的日志文件的大小。
public abstract int setLogFileSize(long fileSizeInKBytes);
- 弃用:
- 该方法已废弃,请改用 create [2/2] 中的
logConfig
参数设置日志文件大小。
默认情况下,SDK 会生成 5 个 SDK 日志文件和 5 个 API 调用日志文件,规则如下:
- SDK 日志文件的名称分别为:
agorasdk.log
、agorasdk.1.log
、agorasdk.2.log
、agorasdk.3.log
、agorasdk.4.log
。 - API 调用日志文件的名称分别为:
agoraapi.log
、agoraapi.1.log
、agoraapi.2.log
、agoraapi.3.log
、agoraapi.4.log
。 - 每个 SDK 日志文件的默认大小为 1,024 KB;API 调用日志文件的默认大小为 2,048 KB。日志文件均为 UTF-8 编码。
- 最新的日志永远写在
agorasdk.log
和agoraapi.log
中。 - 当
agorasdk.log
写满后,SDK 会按照以下顺序对日志文件进行操作:- 删除
agorasdk.4.log
文件(如有)。 - 将
agorasdk.3.log
重命名为agorasdk.4.log
。 - 将
agorasdk.2.log
重命名为agorasdk.3.log
。 - 将
agorasdk.1.log
重命名为agorasdk.2.log
。 - 新建
agorasdk.log
文件。
- 删除
agoraapi.log
文件的覆盖规则与agorasdk.log
相同。
该方法仅用于设置 agorasdk.log
文件的大小,对agoraapi.log
不生效。
参数
- fileSizeInKBytes
-
单个
agorasdk.log
日志文件的大小,单位为 KB,取值范围为 [128,20480],默认值为 1,024 KB。 如果你将fileSizeInKByte
设为小于 128 KB,SDK 会自动调整到 128 KB;如果你将fileSizeInKByte
设为大于 20,480 KB,SDK 会自动调整到 20,480 KB。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogFilter
设置日志输出等级。
public abstract int setLogFilter(int filter);
- 弃用:
- 请改用 create [2/2] 中的 logConfig。
该方法设置 Agora SDK 的输出日志输出等级。不同的输出等级可以单独或组合使用。日志级别顺序依次为 LOG_FILTER_OFF、LOG_FILTER_CRITICAL、LOG_FILTER_ERROR、LOG_FILTER_WARN、LOG_FILTER_INFO 和 LOG_FILTER_DEBUG。 选择一个级别,你就可以看到在该级别之前所有级别的日志信息。
例如,你选择 LOG_FILTER_WARN 级别,就可以看到在 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR 和 LOG_FILTER_WARN 级别的日志信息。
参数
- filter
-
日志过滤等级。
- LOG_FILTER_OFF (0):不输出日志信息。
- LOG_FILTER_DEBUG (0x80f):输出所有 API 日志信息。如果你想获取最完整的日志,可以将日志级别设为该等级。
- LOG_FILTER_INFO (0x0f):输出 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR、LOG_FILTER_WARN 和 LOG_FILTER_INFO 级别的日志信息。我们推荐你将日志级别设为该等级。
- LOG_FILTER_WARN (0x0e):输出 LOG_FILTER_CRITICAL、LOG_FILTER_ERROR 和 LOG_FILTER_WARN 级别的日志信息。
- LOG_FILTER_ERROR (0x0c):输出 LOG_FILTER_CRITICAL 和 LOG_FILTER_ERROR 级别的日志信息。
- LOG_FILTER_CRITICAL (0x08):输出 LOG_FILTER_CRITICAL 级别的日志信息。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLogLevel
设置 SDK 的日志输出级别。
public abstract int setLogLevel(int level);
- 弃用:
- 该方法已经废弃。请改用 RtcEngineConfig 设置日志输出级别。
选择一个级别,你就可以看到该级别的日志信息。
参数
- level
- 日志级别: LogLevel。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setLowlightEnhanceOptions
设置暗光增强功能。
public abstract int setLowlightEnhanceOptions(boolean enabled, LowLightEnhanceOptions options);
暗光增强功能可以在光线亮度偏低(如背光、阴天、暗场景)和亮度不均匀的环境下自适应调整视频画面的亮度值,恢复或凸显图像的细节信息,最终提升视频图像的整体视觉效果。
你可以调用该方法开启暗光增强功能并设置暗光增强的效果。
- 请在 enableVideo 后调用该方法。
- 暗光增强对设备性能有一定要求。开启暗光增强后,如果设备出现严重发烫等问题,Agora 推荐你将暗光增强等级修改为消耗性能较少的等级或关闭暗光增强功能。
- 该方法和 setExtensionProperty 均可开启暗光增强功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启暗光增强功能:
true
: 开启暗光增强功能。false
:(默认)关闭暗光增强功能。
- options
- 暗光增强选项,用于设置暗光增强的效果。详见 LowlightEnhanceOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setMixedAudioFrameParameters
设置 onMixedAudioFrame 报告的音频数据格式。
public abstract int setMixedAudioFrameParameters(int sampleRate, int channel, int samplesPerCall);
参数
- sampleRate
-
音频数据采样率 (Hz),可设置为
8000
、16000
、32000
、44100
或48000
。
- channel
-
音频数据声道数,可设置为
1
(单声道) 或2
(双声道)。
- samplesPerCall
-
音频数据采样点数。旁路推流场景下通常设为
1024
。
SDK 会根据该方法设置的采样间隔(秒)定期触发 onMixedAudioFrame 回调。 采样间隔 = samplesPerCall
/(sampleRate
x channel
)。请确保你的取值能满足采样间隔大于或等于 0.01 秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setParameters
通过 JSON 配置 SDK 提供技术预览或特别定制功能。
public abstract int setParameters(String parameters);
请联系技术支持获取 JSON 配置方式。
参数
- parameters
- JSON 字符串形式的参数。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setPlaybackAudioFrameBeforeMixingParameters
设置 onPlaybackAudioFrameBeforeMixing 报告的音频数据格式。
public abstract int setPlaybackAudioFrameBeforeMixingParameters(int sampleRate, int channel);
参数
- sampleRate
-
音频数据采样率 (Hz),可设置为
8000
、16000
、32000
、44100
或48000
。
- channel
-
音频数据声道数,可设置为
1
(单声道) 或2
(双声道) 。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setPlaybackAudioFrameParameters
设置播放的音频格式。
public abstract int setPlaybackAudioFrameParameters( int sampleRate, int channel, int mode, int samplesPerCall);
该方法设置 onPlaybackAudioFrame 回调数据的格式。
- 该方法需要在加入频道前调用。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onPlaybackAudioFrame 回调。
参数
- sampleRate
- onPlaybackAudioFrame 中返回数据的采样率,可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onPlaybackAudioFrame 中返回数据的通道数,可设置为 1 或 2:
- 1: 单声道
- 2: 双声道
- mode
-
音频帧的使用模式:
- RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): 只读模式。例如: 若用户通过 Agora SDK 采集数据,自己进行 RTMP 推流,则可以选择该模式。
- RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): 读写模式。例如:若用户自己有音效处理模块,且想要根据实际需要对数据进行前处理 (例如变声),则可以选择该模式。
- samplesPerCall
- onPlaybackAudioFrame 中返回数据的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRecordingAudioFrameParameters
设置采集的原始音频数据格式。
public abstract int setRecordingAudioFrameParameters( int sampleRate, int channel, int mode, int samplesPerCall);
该方法设置 onRecordAudioFrame 回调的采集音频格式。
- 该方法需要在加入频道前调用。
- SDK 会通过该方法中的 samplesPerCall、sampleRate 和 channel 参数计算出采样间隔,计算公式为采样间隔 = samplesPerCall/(sampleRate × channel)。请确保采样间隔不小于 0.01 秒。SDK 会根据该采样间隔触发 onRecordAudioFrame 回调。
参数
- sampleRate
- onRecordAudioFrame 中返回数据的采样率,可设置为 8000、 16000、 32000、44100 或 48000。
- channel
-
onRecordAudioFrame 中返回数据的通道数,可设置为 1 或 2:
- 1: 单声道。
- 2: 双声道。
- mode
-
音频帧的使用模式:
- RAW_AUDIO_FRAME_OP_MODE_READ_ONLY (0): 只读模式。例如: 若用户通过 Agora SDK 采集数据,自己进行 RTMP 推流,则可以选择该模式。
- RAW_AUDIO_FRAME_OP_MODE_READ_WRITE (2): 读写模式。例如:若用户自己有音效处理模块,且想要根据实际需要对数据进行前处理 (例如变声),则可以选择该模式。
- samplesPerCall
- onRecordAudioFrame 中返回数据的采样点数,如旁路推流应用中通常为 1024。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteDefaultVideoStreamType
设置默认订阅的视频流类型。
public abstract int setRemoteDefaultVideoStreamType(int streamType);
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [2/2] (false)
关闭双流模式,接收端可以选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需默认接收所有用户的视频小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),接收端主播可以调用本方法在接收端发起小流申请,发送端收到申请后自动切换为小流模式。
调用本方法的执行结果将在 onApiCallExecuted 中返回。
- 该方法只能在加入频道前调用。Agora 不支持你在加入频道后修改默认订阅的视频流类型。
- 如果你既调用了该方法,也调用了 setRemoteVideoStreamType,则 SDK 以 setRemoteVideoStreamType 中的设置为准。
参数
- streamType
-
默认订阅的视频流类型:
- VIDEO_STREAM_HIGH (0):视频大流,即高分辨率、高码率视频流。
- VIDEO_STREAM_LOW (1):视频小流,即低分辨率、低码率视频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteRenderMode [1/2]
设置远端视图显示模式。
public abstract int setRemoteRenderMode(int userId, int renderMode);
- 弃用:
- 该方法已废弃,请使用 setRemoteRenderMode [2/2]。
该方法设置远端视图显示模式。App 可以多次调用此方法更改显示模式。
参数
- userId
- 远端用户 ID。
- renderMode
-
远端用户视图的渲染模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteRenderMode [2/2]
更新远端视图显示模式。
public abstract int setRemoteRenderMode(int userId, int renderMode, int mirrorMode);
初始化远端用户视图后,你可以调用该方法更新远端用户视图在本地显示时的渲染和镜像模式。该方法只影响本地用户看到的视频画面。
- 请在调用 setupRemoteVideo 方法初始化远端视图后,调用该方法。
- 你可以在通话中多次调用该方法,多次更新远端用户视图的显示模式。
参数
- userId
- 远端用户 ID。
- renderMode
-
远端用户视图的渲染模式。
- RENDER_MODE_HIDDEN (1):优先保证视窗被填满。视频尺寸等比缩放,直至整个视窗被视频填满。如果视频长宽与显示窗口不同,多出的视频将被截掉。
- RENDER_MODE_FIT (2):优先保证视频内容全部显示。视频尺寸等比缩放,直至视频窗口的一边与视窗边框对齐。如果视频长宽与显示窗口不同,视窗上未被填满的区域将被涂黑。
- RENDER_MODE_ADAPTIVE (3): 该模式已废弃,不推荐使用。
- mirrorMode
-
远端用户视图的镜像模式。
- MIRROR_MODE_AUTO (0):默认的镜像模式(SDK 决定镜像模式)。如果你使用前置摄像头,默认启动本地视图镜像模式;如果你启用后置摄像头,默认关闭本地视图镜像模式。
- MIRROR_MODE_ENABLED (1):开启镜像模式。
- MIRROR_MODE_DISABLED (2):关闭镜像模式。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setRemoteSubscribeFallbackOption
设置弱网条件下订阅的音视频流的回退选项。
public abstract int setRemoteSubscribeFallbackOption(int option);
当网络不理想时,直播音视频的质量都会下降。你可以调用该方法并将 option 设置为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW 或 STREAM_FALLBACK_OPTION_AUDIO_ONLY,SDK 会在下行弱网且音视频质量严重受影响时,将视频流切换为小流或关断视频流,从而保证音频质量。同时 SDK 会持续监控网络质量,并在网络质量改善时恢复音视频流。
当远端订阅流回退为音频流或由音频流恢复为音视频流时,SDK 会触发 onRemoteSubscribeFallbackToAudioOnly 回调。
参数
- option
- 订阅音视频流的回退选项。默认值为 STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW(1)。
- STREAM_FALLBACK_OPTION_DISABLED (0): 上行/下行网络较弱时,不对音视频流作回退处理,但不能保证音视频流的质量。
- STREAM_FALLBACK_OPTION_VIDEO_STREAM_LOW (1): 在下行网络条件较差时只接收视频小流(低分辨率、低码率视频流)。该选项只对 setRemoteSubscribeFallbackOption 有效。
- STREAM_FALLBACK_OPTION_AUDIO_ONLY (2): 上行/下行网络较弱时,先尝试只接收视频小流(低分辨率、低码率视频流);如果网络环境无法显示视频,则再回退到只接收远端订阅的音频流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVideoStreamType
设置订阅的视频流类型。
public abstract int setRemoteVideoStreamType(int uid, int streamType);
在网络条件受限的情况下,如果发送端没有调用 enableDualStreamMode [2/2](false)
关闭双流模式,接收端可以调用该方法选择接收大流还是小流。其中,大流为高分辨率高码率的视频流,小流则是低分辨率低码率的视频流。
正常情况下,用户默认接收大流。如需接收小流,可以调用本方法进行切换。SDK 会根据视频窗口的大小动态调整对应视频流的大小,以节约带宽和计算资源。视频小流默认的宽高比和视频大流的宽高比一致。根据当前大流的宽高比,系统会自动分配小流的分辨率、帧率及码率。
SDK 默认在发送端开启小流 auto 模式(不主动发送小流),接收端主播可以调用本方法在接收端发起小流申请,发送端收到申请后自动切换为小流模式。
调用本方法的执行结果将在 onApiCallExecuted 中返回。
参数
- uid
- 用户 ID。
- streamType
-
视频流类型:
- 0:视频大流。
- 1:视频小流。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setRemoteVoicePosition
设置远端用户声音的 2D 位置,即水平面位置。
public abstract int 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,表示该用户的原始音量。取值越小,则音量越低。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setSubscribeAudioBlacklist
设置音频订阅黑名单。
public abstract int setSubscribeAudioBlacklist(int[] uidList);
你可以调用该方法指定不订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅黑名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeAudioBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeAudioWhitelist
设置音频订阅白名单。
public abstract int setSubscribeAudioWhitelist(int[] uidList);
你可以调用该方法指定想要订阅的音频流。
- 该方法在加入频道前后均可调用。
- 音频订阅白名单不受 muteRemoteAudioStream、muteAllRemoteAudioStreams 以及 ChannelMediaOptions 中的 autoSubscribeAudio 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
音频订阅白名单的用户 ID 列表。
如果你想指定订阅某一发流用户的音频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeAudioWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoBlacklist
设置视频订阅黑名单。
public abstract int setSubscribeVideoBlacklist(int[] uidList);
你可以调用该方法指定不订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅黑名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅黑名单后,如果离开当前频道后再重新加入频道,黑名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅黑名单的用户 ID 列表。
如果你想指定不订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅黑名单中移除,需要重新调用 setSubscribeVideoBlacklist 方法更新订阅黑名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setSubscribeVideoWhitelist
设置视频订阅白名单。
public abstract int setSubscribeVideoWhitelist(int[] uidList);
你可以调用该方法指定想要订阅的视频流。
- 该方法在加入频道前后均可调用。
- 视频订阅白名单不受 muteRemoteVideoStream、muteAllRemoteVideoStreams 以及 ChannelMediaOptions 中的 autoSubscribeVideo 的影响。
- 设置订阅白名单后,如果离开当前频道后再重新加入频道,白名单依然生效。
- 如果某个用户同时在音频订阅黑名单和白名单中,仅订阅黑名单生效。
参数
- uidList
-
视频订阅白名单的用户 ID 列表。
如果你想指定仅订阅某一发流用户的视频流,将该用户的 ID 加入此列表中。如果你想要将某一用户从订阅白名单中移除,需要重新调用 setSubscribeVideoWhitelist 方法更新音频订阅白名单的用户 ID 列表,使其不包含你想移除的用户的 uid。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setupLocalVideo
初始化本地视图。
public abstract int setupLocalVideo(VideoCanvas local);
该方法初始化本地视图并设置本地用户视频显示属性,只影响本地用户看到的视频画面,不影响本地发布视频。调用该方法绑定本地视频流的显示视窗(view),并设置本地用户视图的渲染模式和镜像模式。
在 App 开发中,通常在初始化后调用该方法进行本地视频设置,然后再加入频道。退出频道后,绑定仍然有效,如果需要解除绑定,可以调用该方法将参数 view 设为 NULL。
- 该方法在加入频道前后都能调用。
- 如果你希望在通话中更新本地用户视图的渲染或镜像模式,请使用 setLocalRenderMode [2/2] 方法。
参数
- local
- 本地视频显示属性。详见 VideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setupRemoteVideo
初始化远端用户视图。
public abstract int setupRemoteVideo(VideoCanvas remote);
该方法绑定远端用户和显示视图,并设置远端用户视图在本地显示时的渲染模式和镜像模式,只影响本地用户看到的视频画面。
调用该方法时需要指定远端视频的用户 ID,一般可以在进频道前提前设置好。如果无法在加入频道前得到远端用户的 ID,可以在收到 onUserJoined 回调时调用该方法。
如需解除某个远端用户的绑定视图,可以调用该方法并将 view 设置为空。
离开频道后,SDK 会清除远端用户视图的绑定关系。
- 如果你希望在通话中更新远端用户视图的渲染或镜像模式,请使用 setRemoteRenderMode [2/2] 方法。
- 如果你使用了 Agora 录制服务,录制服务会作为一个哑客户端加入频道,因此也会触发 onUserJoined 回调。由于录制服务不会发送视频流,app 无需为它绑定视图。如果 app 无法识别哑客户端,可以在收到 onFirstRemoteVideoDecoded 回调时再绑定远端用户视图。
参数
- remote
-
远端视频显示属性。详见 VideoCanvas。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
setVideoDenoiserOptions
设置视频降噪功能。
public abstract int setVideoDenoiserOptions(boolean enabled, VideoDenoiserOptions options);
采光不足的环境和低端视频采集设备会使视频图像含有明显的噪声,影响视频画质。在实时互动场景下,视频噪声还会在编码过程中占用码流资源并降低编码效率。
你可以调用该方法开启视频降噪功能并设置视频降噪的效果。
- 请在 enableVideo 后调用该方法。
- 视频降噪对设备性能有一定要求。开启视频降噪后,如果设备出现严重发烫等问题,Agora 推荐你将视频降噪等级修改为消耗性能较少的等级或关闭视频降噪功能。
- 该方法和 setExtensionProperty 均可开启视频降噪功能:
- 当你使用 SDK 采集视频时,Agora 推荐使用该方法(该方法只可对 SDK 采集的视频起作用)。
- 当你使用外部的视频源实现自定义视频采集,或者将外部视频源发送给 SDK 时,Agora 推荐使用 setExtensionProperty 方法。
- 该方法依赖于视频增强动态库
libagora_clear_vision_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- enabled
- 是否开启视频降噪功能:
true
: 开启视频降噪功能。false
:(默认)关闭视频降噪功能。
- options
- 视频降噪选项,用于设置视频降噪的效果。详见 VideoDenoiserOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoEncoderConfiguration
设置视频编码属性。
public abstract int setVideoEncoderConfiguration(VideoEncoderConfiguration config);
设置本地视频的编码属性。
参数
- config
- 视频编码参数配置。详见 VideoEncoderConfiguration。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVideoProfile
设置视频编码配置。
public abstract int setVideoProfile(int profile, boolean swapWidthAndHeight);
- 弃用:
- 该方法已废弃。请改用 setVideoEncoderConfiguration 方法。
该方法设置视频的编码属性。 该方法在加入频道前后都能调用。 如果用户加入频道后不需要重新设置视频编码属性,则 Agora 建议在 enableVideo 前调用该方法,可以加快首帧出图的时间。
参数
- profile
-
视频属性。
- swapWidthAndHeight
-
SDK 会按照你选择的视频属性 (profile) 输出固定宽高的视频。该参数设置是否交换宽和高:
true
: 交换宽和高false
: 不交换宽和高(默认)
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVideoQualityParameters
设置视频优化选项(仅适用于直播)。
public abstract int setVideoQualityParameters(boolean preferFrameRateOverImageQuality);
- 弃用:
- 该方法已废弃。Agora 建议使用 VideoEncoderConfiguration 类中的 degradationPreference 参数设置视频质量偏好。
参数
- preferFrameRateOverImageQuality
-
画质和流畅度里,是否优先保证流畅度:
true
:优先保证流畅度。false
: (默认)优先保证画质。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
setVoiceBeautifierParameters
设置预设美声效果的参数。
public abstract int setVoiceBeautifierParameters(int preset, int param1, int param2);
调用该方法可以设置歌唱美声效果的性别特征和混响效果。该方法对本地发流用户进行设置。设置后,频道内所有用户都能听到该效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3),并将 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierParameters,Agora 不推荐调用以下方法,否则 setVoiceBeautifierParameters 设置的效果会被覆盖:
参数
- preset
- 预设的音效:
SINGING_BEAUTIFIER
: 歌唱美声。
- param1
- 歌声的性别特征:
1
: 男声。2
: 女声。
- param2
- 歌声的混响效果:
1
: 歌声在小房间的混响效果。2
: 歌声在大房间的混响效果。3
: 歌声在大厅的混响效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceBeautifierPreset
设置预设的美声效果。
public abstract int setVoiceBeautifierPreset(int preset);
调用该方法可以为本地发流用户设置预设的人声美化效果。设置美声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的美声效果。各美声效果的适用场景可参考设置人声效果。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3),并将 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceBeautifierPreset,Agora 不推荐调用以下方法,否则 setVoiceBeautifierPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
-
预设的美声效果选项:
- VOICE_BEAUTIFIER_OFF: 原声,即关闭美声效果。
- CHAT_BEAUTIFIER_MAGNETIC: 磁性(男)。
- CHAT_BEAUTIFIER_FRESH: 清新(女)。
- CHAT_BEAUTIFIER_VITALITY: 活力(女)。
- SINGING_BEAUTIFIER: 歌唱美声。
- 如果调用 setVoiceBeautifierPreset(SINGING_BEAUTIFIER),你可以美化男声并添加歌声在小房间的混响效果。请勿用于设置女声,否则音频会失真。
- 如果调用 setVoiceBeautifierParameters(SINGING_BEAUTIFIER, param1, param2),你可以美化男声或女声并添加混响效果。
- TIMBRE_TRANSFORMATION_VIGOROUS: 浑厚。
- TIMBRE_TRANSFORMATION_DEEP: 低沉。
- TIMBRE_TRANSFORMATION_MELLOW: 圆润。
- TIMBRE_TRANSFORMATION_FALSETTO: 假音。
- TIMBRE_TRANSFORMATION_FULL: 饱满。
- TIMBRE_TRANSFORMATION_CLEAR: 清澈。
- TIMBRE_TRANSFORMATION_RESOUNDING: 高亢。
- TIMBRE_TRANSFORMATION_RINGING: 嘹亮。
- ULTRA_HIGH_QUALITY_VOICE: 超高音质,即让音频更清晰、细节更丰富。
- 为达到更好的效果,我们推荐在调用该方法前将 setAudioProfile [2/2] 的 profile 参数设置为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5),且 scenario 参数设置为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 如果用户的音频采集设备可以高度还原音频细节,Agora 建议你不要开启超高音质,否则 SDK 会过度还原音频细节,达不到预期效果。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
setVoiceConversionPreset
设置预设的变声效果。
public abstract int setVoiceConversionPreset(int preset);
调用该方法可以为本地发流用户设置 SDK 预设的变声效果。设置变声效果后,频道内所有用户都能听到该效果。根据不同的场景,你可以为用户设置不同的变声效果。各变声效果的适用场景可参考《设置人声效果》。
为获取更好的人声效果,Agora 推荐你在调用该方法前将 setAudioProfile [1/2] 的 profile 设为 MUSIC_HIGH_QUALITY(4) 或 MUSIC_HIGH_QUALITY_STEREO(5),并将 scenario 设为 AUDIO_SCENARIO_GAME_STREAMING(3)。
- 该方法在加入频道前后都能调用。
- 请勿将 setAudioProfile [1/2] 的 profile 参数设置为 SPEECH_STANDARD(1),否则该方法不生效。
- 该方法对人声的处理效果最佳,Agora 不推荐调用该方法处理含音乐的音频数据。
- 调用 setVoiceConversionPreset 后,Agora 不推荐调用以下方法,否则 setVoiceConversionPreset 设置的效果会被覆盖:
- 该方法依赖于美声动态库
libagora_audio_beauty_extension.so
,如果删除该动态库会导致无法正常开启该功能。
参数
- preset
-
预设的变声效果选项:
- VOICE_CONVERSION_OFF: 原声,即关闭变声效果。
- VOICE_CHANGER_NEUTRAL: 中性。为避免音频失真,请确保仅对女声设置该效果。
- VOICE_CHANGER_SWEET: 甜美。为避免音频失真,请确保仅对女声设置该效果。
- VOICE_CHANGER_SOLID: 稳重。为避免音频失真,请确保仅对男声设置该效果。
- VOICE_CHANGER_BASS: 低沉。为避免音频失真,请确保仅对男声设置该效果。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startAudioMixing [1/2]
开始播放音乐文件。
public abstract int startAudioMixing( String filePath, boolean loopback, boolean replace, int cycle);
- 弃用:
- 请改用 startAudioMixing [2/2]。
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 onAudioMixingStateChanged (AUDIO_MIXING_STATE_PLAYING) 回调。播放结束后,本地会触发 onAudioMixingStateChanged (AUDIO_MIXING_STATE_STOPPED) 回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [1/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
- 在 Android 平台上调用该方法时,请注意如下事项:
- 请确保使用 Android 4.2 或以上设备,且 API Level 不低于 16。
- 如果播放的是在线音乐文件,Agora 建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
- 如果在模拟器上调用该方法,则请确保音乐文件在
/sdcard/
目录下,且格式为 MP3。
参数
- filePath
-
播放文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
content://com.android.providers.media.documents/document/audio%203A14441
。支持的音频格式包括 MP3、AAC、M4A、MP4、WAV、3GP。详见支持的媒体格式。 - loopback
-
是否只在本地播放音乐文件:
true
: 只在本地播放音乐文件,只有本地用户能听到音乐。false
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioMixing [2/2]
开始播放音乐文件。
public abstract int startAudioMixing(String filePath, boolean loopback, int cycle, int startPos);
该方法支持将本地或在线音乐文件和麦克风采集的音频进行混音或替换。成功播放音乐文件后,本地会触发 onAudioMixingStateChanged(AUDIO_MIXING_STATE_PLAYING)
回调。播放结束后,本地会触发 onAudioMixingStateChanged(AUDIO_MIXING_STATE_STOPPED)
回调。
- 该方法在加入频道前后均可调用。如需多次调用 startAudioMixing [2/2],请确保调用间隔大于 500 ms。
- 如果本地音乐文件不存在、文件格式不支持或无法访问在线音乐文件 URL,则 SDK 会报告警告码 701。
- 该方法支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。
- 在 Android 平台上调用该方法时,请注意如下事项:
- 请确保使用 Android 4.2 或以上设备,且 API Level 不低于 16。
- 如果播放的是在线音乐文件,Agora 建议不要使用重定向地址。重定向地址在某些机型上可能无法打开。
- 如果在模拟器上调用该方法,则请确保音乐文件在
/sdcard/
目录下,且格式为 MP3。
参数
- filePath
- 文件路径:
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
/assets/
开头的路径。 通过绝对路径访问本地文件可能会遇到权限问题,Agora 推荐使用 URI 地址访问本地文件。例如content://com.android.providers.media.documents/document/audio%3A14441
。
- Android: 文件路径,需精确到文件名及后缀。支持在线文件的 URL 地址,本地文件的 URI 地址、绝对路径或以
- loopback
-
是否只在本地播放音乐文件:
true
: 只在本地播放音乐文件,只有本地用户能听到音乐。false
: 将本地播放的音乐文件发布至远端,本地用户和远端用户都能听到音乐。
- cycle
-
音乐文件的播放次数。
- ≥ 0: 播放次数。例如,0 表示不播放;1 表示播放 1 次。
- -1: 无限循环播放。
- startPos
- 音乐文件的播放位置,单位为毫秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording [1/2]
开始客户端录音。
public abstract int startAudioRecording(String filePath, int quality);
- 弃用:
- 该方法已废弃,其默认录音采样率为 32 kHz,不可修改。请改用新的 startAudioRecording [2/2] 方法。
.wav
: 文件大,音质保真度高;.aac
: 文件小,有一定的音质保真度损失。
请确保 App 里指定的目录存在且可写。该接口需在 joinChannel [1/2] 之后调用。如果调用 leaveChannel [1/2] 时还在录音,录音会自动停止。
参数
- filePath
- 录音文件在本地保存的绝对路径,需精确到文件名及格式。例如:
content://com.android.providers.media.documents/document/audio%203A14441
。注意:请确保你指定的路径存在并且可写。
- quality
- 录音质量。
- 0: 低音质。采样率为 32 kHz,录制 10 分钟的文件大小为 1.2 M 左右。
- 1: 中音质。采样率为 32 kHz,录制 10 分钟的文件大小为 2 M 左右。
- 2: 高音质。采样率为 32 kHz,录制 10 分钟的文件大小为 3.75 M 左右。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startAudioRecording [2/2]
开始客户端录音。
public abstract int startAudioRecording(AudioFileRecordingConfig config);
- WAV: 音质保真度较高,文件较大。例如,采样率为 32000 Hz,录音时长为 10 分钟的文件大小约为 73 M。
- AAC: 音质保真度较低,文件较小。例如,采样率为 32000 Hz,录音音质为 AUDIO_RECORDING_QUALITY_MEDIUM,录音时长为 10 分钟的文件大小约为 2 M。
用户离开频道后,录音会自动停止。
参数
- config
- 录音配置。详见 AudioRecordingConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startChannelMediaRelay
开始跨频道媒体流转发。该方法可用于实现跨频道连麦等场景。
public abstract int startChannelMediaRelay( ChannelMediaRelayConfiguration channelMediaRelayConfiguration);
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_RUNNING (2) 和 RELAY_OK (0),且 onChannelMediaRelayEvent 回调报告 RELAY_EVENT_PACKET_SENT_TO_DEST_CHANNEL (4), 则表示 SDK 开始在源频道和目标频道之间转发媒体流。
- 如果 onChannelMediaRelayStateChanged 回调报告 RELAY_STATE_FAILURE (3), 则表示跨频道媒体流转发出现异常。
- 请在成功加入频道后调用该方法。
- 在直播场景中,只有角色为主播的用户才能调用该方法。
- 成功调用该方法后,若你想再次调用该方法,必须先调用 stopChannelMediaRelay 方法退出当前的转发状态。
- 跨频道媒体流转发功能需要联系技术支持开通。
- 该功能不支持 String 型 UID。
参数
- channelMediaRelayConfiguration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration。
返回值
- 0:方法调用成功
- < 0:方法调用失败
startDirectCdnStreaming
设置主播端开始直接向 CDN 推流。
public abstract int startDirectCdnStreaming(IDirectCdnStreamingEventHandler eventHandler, String publishUrl, DirectCdnStreamingMediaOptions options);
Agora 不支持同一时间向同一个 URL 重复推流。
媒体选项说明
Agora 不支持 publishCameraTrack 和 publishCustomVideoTrack 同时为 true
,也不支持 publishMicrophoneTrack 和 publishCustomAudioTrack 同时为 true
。你可以根据场景需求设置媒体选项 (DirectCdnStreamingMediaOptions)。示例如下:
如果你想推送主播端采集的音视频流,请将媒体选项进行如下设置:
- publishCustomAudioTrack 设为
true
并调用 pushExternalAudioFrame [2/2] - publishCustomVideoTrack 设为
true
并调用 pushExternalVideoFrame [1/2] - 确保 publishCameraTrack 为
false
(默认值) - 确保 publishMicrophoneTrack 为
false
(默认值)
参数
- eventHandler
- 详见 onDirectCdnStreamingStateChanged 及 onDirectCdnStreamingStats。
- publishUrl
- CDN 推流 URL。
- options
- 主播端的媒体选项。详见 DirectCdnStreamingMediaOptions。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest [1/2]
开始语音通话回路测试。
public abstract int startEchoTest();
- 弃用:
- 该方法已废弃,请改用 startEchoTest [2/2]。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在 10 秒后回放出来。如果 10 秒后用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest [1/2] 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest [2/2]
开始语音通话回路测试。
public abstract int startEchoTest(int intervalInSeconds);
- 弃用:
- 该方法自 v4.0.1 废弃,请改用 startEchoTest [3/3]。
该方法启动语音通话测试,目的是测试系统的音频设备(耳麦、扬声器等)和网络连接是否正常。在测试过程中,用户先说一段话,声音会在设置的时间间隔(单位为秒)后回放出来。如果用户能正常听到自己刚才说的话,就表示系统音频设备和网络连接都是正常的。
- 请在加入频道前调用该方法。
- 调用 startEchoTest [2/2] 后必须调用 stopEchoTest 以结束测试,否则不能进行下一次回声测试,也无法加入频道。
- 直播场景下,该方法仅能由用户角色为主播的用户调用。
参数
- intervalInSeconds
- 设置返回语音通话回路测试结果的时间间隔,取值范围为 [2,10],单位为秒,默认为 10 秒。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startEchoTest [3/3]
开始音视频通话回路测试。
public abstract int startEchoTest(EchoTestConfiguration config);
加入频道前,为测试用户本地发流、收流是否正常,你可以调用该方法进行音视频通话回路测试,即测试系统的音视频设备和用户的上下行网络是否正常。
- 请在加入频道前调用该方法。
- 调用该方法后,必须调用 stopEchoTest 结束测试,否则该用户无法进行下一次音视频通话回路测试, 也无法加入频道。
- 直播场景下,该方法仅能由主播调用。
参数
- config
- 音视频通话回路测试的配置。详见 EchoTestConfiguration。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startLastmileProbeTest
开始通话前网络质量探测。
public abstract int startLastmileProbeTest(LastmileProbeConfig config);
开始通话前网络质量探测,向用户反馈上下行网络的带宽、丢包、网络抖动和往返时延数据。
- onLastmileQuality,视网络情况约 2 秒内返回。该回调通过打分反馈上下行网络质量,更贴近用户的主观感受。
- onLastmileProbeResult,视网络情况约 30 秒内返回。该回调通过具体数据反馈上下行网络质量,更加客观。
- 用户加入频道前,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 直播场景下,当用户角色想由观众切换为主播时,可以调用该方法判断和预测目前的上行网络质量是否足够好。
- 调用该方法后,在收到 onLastmileQuality 和 onLastmileProbeResult 回调之前请不要调用其他方法,否则可能会由于 API 操作过于频繁导致此方法无法执行。
- 在直播场景中,如果本地用户为主播,请勿加入频道后调用该方法。
参数
- config
- Last mile 网络探测配置,详见 LastmileProbeConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
startPreview [1/2]
开启视频预览。
public abstract int startPreview();
- 调用 setupLocalVideo 设置预览窗口及属性。
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 如果调用 leaveChannel [1/2]退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用 stopPreview [1/2]。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startPreview [2/2]
开启视频预览并指定预览的视频源。
public abstract int startPreview(Constants.VideoSourceType sourceType);
- 调用 setupLocalVideo 设置预览窗口及属性。
- 调用 enableVideo 开启视频功能。
- 本地预览默认开启镜像功能。
- 如果调用 leaveChannel [1/2] 退出频道,本地预览依然处于开启状态,如需要关闭本地预览,需要调用 stopPreview [2/2]。
- 该方法中设置的视频源类型需要跟 setupLocalVideo 中 VideoCanvas 的视频源类型一致。
参数
- sourceType
- 视频源的类型,详见 VideoSourceType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
startRhythmPlayer
开启虚拟节拍器。
public abstract int startRhythmPlayer( String sound1, String sound2, AgoraRhythmPlayerConfig config);
在音乐教学、体育教学等场景中,老师通常需要使用节拍器,让学生跟着正确的节拍练习。 节拍由强拍和弱拍组成,每小节的第一拍称为强拍,其余称为弱拍。
你需要在该方法中设置强拍和弱拍的文件路径、每小节的拍数、节拍速度以及是否将节拍器的声音发送至远端。
- 开启虚拟节拍器后,SDK 会从头开始播放指定的音频文件,并根据你在 AgoraRhythmPlayerConfig 中设置的 beatsPerMinute 控制每个文件的播放时长。例如,将 beatsPerMinute 设为
60
,则 SDK 会 1 秒播放 1 个节拍。如果文件时长超过了节拍时长,则 SDK 只播放节拍时长部分的音频。 - 虚拟节拍器的声音默认会发布至远端,如果你不希望远端用户听到虚拟节拍器的声音,你可以将 ChannelMediaOptions 中的 publishRhythmPlayerTrack 设为
false
。
参数
- sound1
- 强拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
content://com.android.providers.media.documents/document/audio%203A14441
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - sound2
- 弱拍文件的绝对路径或 URL 地址,需精确到文件名及后缀。例如
content://com.android.providers.media.documents/document/audio%203A14441
。支持的音频文件格式见 Agora RTC SDK 支持播放哪些格式的音频文件。 - config
- 节拍器配置。详见 AgoraRhythmPlayerConfig。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -22: 无法找到音频文件。请填写正确的 sound1 和 sound2。
startRtmpStreamWithoutTranscoding
开始非转码推流。
public abstract int startRtmpStreamWithoutTranscoding(String url);
调用该方法,你可以向指定的旁路推流地址推送直播音视频流。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
startRtmpStreamWithTranscoding
开始旁路推流并设置转码属性。
public abstract int startRtmpStreamWithTranscoding(String url, LiveTranscoding transcoding);
调用该方法,你可以向指定的旁路推流地址推送直播音视频流并设置转码属性。该方法每次只能向一个地址推送媒体流,如果你需要向多个地址转码推流,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
- 请确保已开通旁路推流服务。
- 请在加入频道后调用该方法。
- 只有直播场景下的主播才能调用该方法。
- 调用该方法推流失败后,如果你想要重新推流,那么请你务必先调用 stopRtmpStream,再调用该方法重推,否则 SDK 会返回与上次推流失败时一样的错误码。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:url 为空或为长度为 0 的字符串。
- -7:调用该方法前,未初始化 SDK。
startScreenCapture
开始屏幕共享。
public abstract int startScreenCapture(ScreenCaptureParameters screenCaptureParameters);
- 在加入频道前调用该方法,然后调用 joinChannel [2/2] 加入频道并设置 publishScreenCaptureVideo 为
true
,即可开始屏幕共享。 - 在加入频道后调用该方法,然后调用 updateChannelMediaOptions 设置 publishScreenCaptureVideo 为
true
,即可开始屏幕共享。
参数
- screenCaptureParameters
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2,073,600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
- -2: 参数为空。
startRecordingDeviceTest
启动音频采集设备测试。
public abstract int startRecordingDeviceTest(int indicationInterval);
该方法测试音频采集设备是否能正常工作。调用该方法后,SDK 会按设置的时间间隔触发 onAudioVolumeIndication 回调,报告 uid = 0 及采集设备的音量信息。
参数
- indicationInterval
- SDK 触发 onAudioVolumeIndication 回调的时间间隔,单位为毫秒。建议设置到大于 200 毫秒。不得小于 10 毫秒,否则会收不到 onAudioVolumeIndication 回调。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopAudioMixing
停止播放音乐文件。
public abstract int stopAudioMixing();
该方法停止播放音乐文件。请在频道内调用该方法。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopAudioRecording
停止客户端录音。
public abstract int stopAudioRecording();
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopChannelMediaRelay
停止跨频道媒体流转发。一旦停止,主播会退出所有目标频道。
public abstract int stopChannelMediaRelay();
成功调用该方法后,SDK 会触发 onChannelMediaRelayStateChanged 回调。如果报告 RELAY_STATE_IDLE (0) 和 RELAY_OK (0),则表示已停止转发媒体流。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopDirectCdnStreaming
设置主播端停止直接向 CDN 推流。
public abstract int stopDirectCdnStreaming();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopEchoTest
停止语音通话回路测试。
public abstract int stopEchoTest();
返回值
- 0: 方法调用成功。
-
< 0: 方法调用失败。
- -5(ERR_REFUSED): 无法启动测试,可能没有成功初始化。
stopLastmileProbeTest
停止通话前网络质量探测。
public abstract int stopLastmileProbeTest();
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopRecordingDeviceTest
停止音频采集设备测试。
该方法停止音频采集设备测试。调用 startRecordingDeviceTest 后,必须调用该方法停止测试。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopPreview [1/2]
停止视频预览。
public abstract int stopPreview();
调用 startPreview [1/2] 开启预览后,如果你想关闭本地视频预览,请调用该方法。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopPreview [2/2]
停止视频预览。
public abstract int stopPreview(Constants.VideoSourceType sourceType);
调用 startPreview [2/2] 开启预览后,如果你想关闭本地视频预览,请调用该方法。
参数
- sourceType
- 视频源的类型,详见 VideoSourceType。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
stopRhythmPlayer
关闭虚拟节拍器。
public abstract int stopRhythmPlayer();
调用 startRhythmPlayer 后,你可以调用该方法关闭虚拟节拍器。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
stopRtmpStream
结束旁路推流。
public abstract int stopRtmpStream(String url);
调用该方法,你可以结束指定的旁路推流地址上的直播。该方法每次只能结束一个推流地址上的直播,如果你需要结束多个推流地址的直播,则需多次调用该方法。
调用该方法后,SDK 会在本地触发 onRtmpStreamingStateChanged 回调,报告推流的状态。
参数
- url
- 旁路推流地址。格式为 RTMP 或 RTMPS。字符长度不能超过 1024 字节。不支持中文字符等特殊字符。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
stopScreenCapture
停止屏幕共享。
public abstract int stopScreenCapture();
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
switchCamera
切换前置/后置摄像头。
public abstract int switchCamera();
该方法需要在相机启动(如通过调用 startPreview [1/2] 或 joinChannel [2/2] 实现)后调用。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
takeSnapshot
获取视频截图。
public abstract int takeSnapshot(int uid, String filePath);
该方法用于对指定用户的视频流进行截图,生成一张 JPG 格式的图片,并保存至指定的路径。
该方法是异步操作,调用返回时 SDK 并没有真正获取截图。成功调用该方法后,SDK 会触发 onSnapshotTaken 回调报告截图是否成功和获取截图的详情。
- 该方法需要在加入频道后调用。
- 该方法对 ChannelMediaOptions 中指定发布的视频流进行截图。
- 如果用户的视频经过前处理,例如,添加了水印或美颜,生成的截图会包含前处理效果。
参数
- uid
- 用户 ID。如果要对本地用户的视频截图,则设为 0。
- filePath
-
截图的本地保存路径,需精确到文件名及格式, 例如:
- Android:
/storage/emulated/0/Android/data/<package name>/files/example.jpg
- Android:
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
unregisterAudioSpectrumObserver
取消注册音频频谱观测器。
public abstract int unRegisterAudioSpectrumObserver(IAudioSpectrumObserver observer);
调用 registerAudioSpectrumObserver 后,如果你想取消注册音频频谱观测器,请调用该方法。
参数
- observer
- 音频频谱观测器。详见 IAudioSpectrumObserver。
返回值
- 0: 方法调用成功
- < 0: 方法调用失败
unregisterMediaMetadataObserver
取消注册媒体 metadata 观测器。
public abstract int unregisterMediaMetadataObserver(IMetadataObserver observer, int type);
参数
- observer
- metadata 观测器,详见 IMetadataObserver。
- type
-
metadata 类型。目前仅支持 VIDEO_METADATA。
返回值
- 0:方法调用成功。
- < 0:方法调用失败。
updateChannelMediaOptions
加入频道后更新频道媒体选项。
public abstract int updateChannelMediaOptions(ChannelMediaOptions options);
参数
- options
- 频道媒体选项,详见 ChannelMediaOptions。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
- -2:ChannelMediaOptions 结构体成员值设置无效。例如,使用了不合法的 Token,设置了无效的用户角色。你需要填入有效的参数。
- -7:RtcEngine 对象尚未初始化。你需要在调用该方法前成功初始化 RtcEngine 对象。
- -8:RtcEngine 对象内部状态错误。可能的原因是用户不在频道中。Agora 推荐通过 onConnectionStateChanged 回调判断用户是否在频道中。如果收到 CONNECTION_STATE_DISCONNECTED(1) 或 CONNECTION_STATE_FAILED(5),则表示用户不在频道中。你需要在调用该方法前调用 joinChannel [2/2] 加入频道。
updateChannelMediaRelay
更新媒体流转发的频道。
public abstract int updateChannelMediaRelay( ChannelMediaRelayConfiguration channelMediaRelayConfiguration);
成功开始跨频道转发媒体流后,如果你希望将流转发到多个目标频道,或退出当前的转发频道,可以调用该方法。
成功调用该方法后,SDK 会触发 onChannelMediaRelayEvent 回调, 并在回调中报告状态码 RELAY_EVENT_PACKET_UPDATE_DEST_CHANNEL (7)。
onChannelMediaRelayStateChanged(RELAY_STATE_RUNNING, RELAY_OK)
后调用该方法;否则,方法调用会失败。参数
- channelMediaRelayConfiguration
- 跨频道媒体流转发参数配置。详见 ChannelMediaRelayConfiguration 。
返回值
- 0:方法调用成功
- < 0:方法调用失败
updateRtmpTranscoding
更新旁路推流转码属性。
public abstract int updateRtmpTranscoding(LiveTranscoding transcoding);
开启转码推流后,你可以根据场景需求,动态更新转码属性。转码属性更新后,SDK 会触发 onTranscodingUpdated 回调。
参数
- transcoding
-
旁路推流的转码属性,详见 LiveTranscoding 类。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。
updateScreenCaptureParameters
更新屏幕共享的参数配置。
public abstract int updateScreenCaptureParameters( ScreenCaptureParameters screenCaptureParameters);
- 请在开启屏幕共享或窗口共享后调用该方法。
参数
- screenCaptureParameters
- 屏幕共享的编码参数配置。默认的分辨率为 1920 x 1080,即 2073600 像素。该像素值为计费标准。详见 ScreenCaptureParameters。
返回值
- 0: 方法调用成功。
- < 0: 方法调用失败。