通过阅读本文,您可以了解实时音视频Android SDK接口详情。
目录
基础接口
API | 功能描述 |
创建AliRtcEngine实例(单例模式)。 | |
创建AliRtcEngine实例(单例模式)。 | |
销毁AliRtcEngine 对象。 | |
销毁AliRtcEngine 对象。 | |
设置H5兼容模式。 | |
检查当前是否兼容H5。 | |
设置本地用户行为的回调事件的监听。 | |
设置远端用户行为的通知事件的监听。 | |
查询SDK当前版本。 |
频道相关接口
API | 功能描述 |
设置频道模式。 | |
设置音频编码模式及场景模式。 | |
查询当前是否为纯音频模式。 | |
设置为纯音频模式还是音视频模式。 | |
加入频道。 | |
加入频道。 | |
加入频道。 | |
离开频道。 | |
检查当前是否在频道中 | |
设置用户角色。 | |
获取用户角色。 | |
刷新鉴权信息。 | |
刷新鉴权信息。 |
发布及订阅相关接口
API | 功能描述 |
停止或恢复发布本地视频流,默认会发布。 | |
查询当前是否推音频流。 | |
设置是否默认接收音频流,默认会订阅所有远端音频流;此接口建议入会前调用。 | |
停止或恢复特定远端用户的音频流拉取。 | |
停止或恢复接收所有远端音频流。 | |
是否推送本地视频流,SDK 默认推送。 | |
查询当前是否发布视频流。 | |
设置是否默认接收视频流,默认会订阅所有远端视频流;此接口建议加入频道前调用。 | |
停止或恢复订阅指定的远端视频流。 | |
停止或恢复接收所有远端视频流。 | |
停止或恢复特定远端用户的媒体流;建议在音视频都存在且要控制时使用此接口。 | |
停止或恢复特定远端用户的媒体流;建议在音视频都存在且要控制时使用此接口。 | |
停止或恢复跨频道特定远端用户的媒体流。 | |
停止或恢复订阅跨频道所有用户的流。 | |
调节拉流的播放音量。 |
音频设备管理相关接口
API | 功能描述 |
设置是否停止发布本地音频。 | |
设置是否停止播放远端音频流。 | |
停止或恢复远端所有的音频播放。 | |
开启音频采集。 | |
开启音频采集 | |
关闭音频采集。 | |
设置默认音频输出设备。 | |
设置音频输出为听筒还是扬声器。 | |
获取当前音频输出为听筒还是扬声器。 | |
开启音量检测功能。 | |
启用耳返。 | |
设置耳返音量。 | |
打开音频播放设备。 | |
关闭音频播放设备。 | |
设置本地播放音量。 | |
设置录音音量。 | |
播放音频文件。 | |
停止播放音频文件。 | |
通话前开启音频采集设备检测。 | |
关闭音频采集检测。 |
音频变声与混响
API | 功能描述 |
设置变声音效模式。 | |
设置变调参数。 | |
设置混响音效模式。 | |
设置混响音效类型和具体参数。 |
自定义音频输入
API | 功能描述 |
增加外部音频流。 | |
输入外部音频流数据。 | |
设置推流音量。 | |
获取推流音量。 | |
设置外部音频流播放音量。 | |
获取外部音频流播放音量。 | |
删除外部音频流。 |
音乐伴奏
API | 功能描述 |
获取音频文件信息。 | |
开始伴奏混音。 | |
停止伴奏混音。 | |
设置伴奏音量,包含伴奏的本地播放音量和推流音量。 | |
设置伴奏推流音量。 | |
获取伴奏推流音量。 | |
设置伴奏本地播放音量。 | |
获取伴奏本地播放音量。 | |
暂停伴奏混音。 | |
重新开始伴奏混音。 | |
获取伴奏文件时长, 单位为毫秒。 | |
获取伴奏文件播放进度,单位为毫秒。 | |
设置伴奏文件的播放位置。 |
音效文件
API | 功能描述 |
预加载音效文件 | |
删除预加载的音效文件 | |
开始播放音效 | |
停止播放音效 | |
停止播放所有音效 | |
暂停音效 | |
暂停所有音效 | |
恢复指定音效文件 | |
恢复所有音效文件 | |
设置音效推流混音音量 | |
获取音效推流混音音量 | |
设置所有音效推流混音音量 | |
设置音效本地播放音量 | |
获取音效本地播放音量 | |
设置所有音效本地播音量 |
视频设备管理相关接口
API | 功能描述 |
创建SurfaceView渲染视图。 | |
为本地预览设置渲染窗口以及绘制参数。 | |
为远端的视频设置渲染窗口以及绘制参数。 | |
设置摄像头采集偏好。 | |
禁用或重新启用本地视频采集。 | |
设置是否停止发布本地视频流。 | |
检查摄像头是否打开。 | |
设置视频编码属性。 | |
设置视频解码属性 | |
切换前后摄像头(默认为前置摄像头)。 | |
获取当前摄像头方向。 | |
开始本地预览。 | |
停止本地预览。 | |
设置摄像头缩放比例。 | |
获取摄像头支持最大缩放(变焦)比例。 | |
获取当前摄像头缩放比例设置。 | |
设置摄像头曝光度。 | |
获取摄像头曝光度。 | |
获取摄像头支持的最小曝光度。 | |
获取摄像头支持的最大曝光度。 | |
设置摄像头闪光灯开关。 | |
当前设备是否支持手动聚焦。 | |
设置摄像头手动聚焦点。 | |
是否支持设置摄像头曝光点。 | |
设置摄像头曝光点。 | |
是否支持摄像头自动人脸聚焦。 | |
设置摄像头人脸聚焦。 | |
设置预览和推流视频镜像能力。 | |
设置视频采集缩放时机。 |
配置视频数据回调
API | 功能描述 |
注册视频数据输出对象。 | |
取消注册视频数据输出对象。 | |
注册本地相机流视频OpenGL纹理数据观测器。 | |
取消注册本地相机流视频OpenGL纹理数据观测器。 | |
视频截图功能。 |
配置音频数据回调
API | 功能描述 |
注册音量数据输出对象。 | |
取消音量数据输出对象注册。 | |
设置音频回调参数。 | |
注册音频数据回调。 |
自定义视频输入
API | 功能描述 |
启用外部视频输入源。 | |
输入视频数据。 |
桌面共享接口
API | 功能描述 |
开启共享屏幕推流。 | |
开始共享屏幕和音频流。 说明 此接口即将废弃。 | |
开始屏幕共享。 说明 此接口即将废弃。 | |
停止共享屏幕推流。 | |
设置共享音频流音量。 | |
查询是否设置推送屏幕分享。 | |
设置屏幕流视频编码属性。 |
直播旁路接口
API | 功能描述 |
开启旁路直播。 | |
更新旁路直播相关参数。 | |
停止旁路直播。 | |
获取旁路直播状态。 |
网络质量探测接口
API | 功能描述 |
开启网络质量探测 | |
停止网络质量探测 |
SEI
API | 功能描述 |
推送SEI流。 | |
推送SEI流(扩展)。 |
其他接口
API | 功能描述 |
设置自定义参数 | |
获取自定义参数 | |
设置SDK日志文件保存路径。 | |
设置日志等级。 | |
设置设备方向。 | |
请求音频焦点。 | |
放弃音频焦点。 | |
获取当前的网络时间。 | |
发送 data channel 自定义消息。 |
回调事件
AliRtcEngineEventListener
API | 功能描述 |
网络链接状态回调;客户需要关心此回调。 | |
本地设备异常回调;客户需要关心此回调。 | |
加入频道结果回调。 | |
离开频道结果回调。 | |
音频推流变更回调。 | |
音频订阅情况变更回调。 | |
视频推流变更回调。 | |
相机流订阅情况变更回调。 | |
旁路推流状态改变回调。 | |
旁路任务状态改变回调。 | |
网络质量变化回调。 | |
网络质量探测的回调,开始探测3s左右提供该回调。 | |
网络质量探测的结果回调,探测30s左右提供该回调。 | |
截图结果回调接口。 | |
屏幕分享推流变更回调。 | |
屏幕分享流订阅情况变更回调。 | |
错误通知。 | |
本地音频设备状态回调。 |
AliRtcEngineNotify
API | 功能描述 |
用户鉴权信息即将过期通知,收到后30秒鉴权过期;客户需要关心此回调。 | |
用户调用需要鉴权的接口,服务端返回信息过期。 | |
远端用户下线通知 | |
远端用户上线通知。 | |
远端推流信息通知。 | |
被服务器踢出/会议结束频道的消息。 | |
远端用户静音通知。 | |
音频设备打断开始通知。 | |
音频设备打断结束通知。 | |
对端用户发送视频黑帧数据发送通知。 | |
对端用户关闭相机流采集发送通知。 | |
远端用户应用退到后台。 | |
远端用户应用返回前台。 | |
本地音效播放结束回调 | |
音频文件信息回调。 | |
收到媒体扩展信息回调。 | |
远端用户的第一帧视频帧显示时触发这个消息。 | |
预览开始显示第一帧视频帧时触发这个消息。 | |
收到远端用户视频首帧的回调。 | |
视频首包发送回调。 | |
音频首包发送回调。 | |
视频首包接收回调。 | |
音频首包接收回调。 | |
已解码远端音频首帧回调。 | |
本地伴奏播放状态回调。 | |
远端用户伴奏播放开始回调。 | |
远端用户伴奏播放结束回调。 | |
实时数据回调(2s触发一次)。 | |
发布本地视频流的数据统计(2s触发一次)。 | |
订阅远端视频流的数据统计(2s触发一次)。 | |
订阅远端音频流的数据统计(2s触发一次)。 | |
发布本地音频流数据统计(2s触发一次)。 | |
音频焦点变化回调(仅适用于Android平台)。 | |
音频路由发生变化回调(仅适用于Android、iOS平台)。 | |
可以开始发送data channel消息回调。 | |
data channel自定义消息接收回调。 |
AliRtcAudioVolumeObserver
API | 功能描述 |
用户音量提示回调。 | |
语音激励,监测到活跃用户回调 | |
通话前检测,音量信息回调。 |
AliRtcAudioFrameObserver
API | 功能描述 |
音频采集裸数据回调。 | |
3A后音频数据回调。 | |
推流音频数据回调。 | |
播放数据回调。 | |
远端拉流数据回调。 |
AliRtcDestroyCompletionObserver
API | 功能描述 |
引擎销毁完成回调。 |
AliRtcTextureObserver
API | 功能描述 |
OpenGL上下文创建回调。 | |
OpenGL纹理更新回调。 | |
OpenGL上下文销毁回调。 |
AliRtcVideoObserver
API | 功能描述 |
订阅的本地采集视频数据回调。 | |
订阅的本地编码前视频数据回调。 | |
订阅的远端视频数据回调。 | |
视频数据输出格式 | |
视频数据输出内容。 |
接口详情
getInstance[1/2]
获取AliRtcEngine实例(单例模式)。
public static AliRtcEngineImpl getInstance(Context context);
该方法和getInstance[2/2]均能创建 AliRtcEngine 实例,区别在于
getInstance[2/2]
支持在创建实例的同时进行更多配置。
调用时机
请确保在调用 ARTC SDK 其他 API 前调用该方法创建 AliRtcEngine 实例。
调用限制
对于每个 App,SDK 仅支持创建一个 AliRtcEngine 实例。
参数说明
参数 | 类型 | 描述 |
context | Context | 安卓(Android Activity)的上下文。 |
返回说明
对于每个 App,SDK 仅支持创建一个 AliRtcEngine 实例。
getInstance[2/2]
获取AliRtcEngine实例(单例模式)。
public static AliRtcEngineImpl getInstance(Context context, String extras);
该方法和
getInstance[1/2]
均能创建 AliRtcEngine 实例,区别在于本接口支持在创建实例的同时进行更多配置。
调用时机
请确保在调用 ARTC SDK 其他 API 前调用该方法创建 AliRtcEngine 实例。
调用限制
对于每个 App,SDK 仅支持创建一个 AliRtcEngine 实例。
参数说明
参数 | 类型 | 描述 |
context | Context | 安卓(Android Activity)的上下文。 |
extras | String | 用于接收来自客户灰度下发的参数,通过JSON配置SDK的特别功能,可以是空字符串。 |
返回说明
返回一个 AliRtcEngineImpl 类的单例实例,其中 AliRtcEngineImpl 类为 AliRtcEngine 类的子类。
destroy[1/2]
销毁AliRtcEngine对象。
public abstract void destroy();
销毁AliRtcEngine 单例对象,调用该方法后将会释放所有内部使用的资源,您将不能再使用AliRtcEngine的其他方法和任何回调,如果需要再次使用必须重新调用getInstance
创建新的实例。
该方法和
destroy[2/2]
均能销毁引擎实例,区别在于 destroy[2/2] 允许传入销毁完成的监测器对象。如果需要在销毁后再次创建 AliRtcEngine实例,请确保在本方法执行完毕后再创建。
调用时机
当音视频通信结束后(即不再需要使用 AliRtcEngine 功能时),建议调用此方法释放实例,减少不必要的资源占用。
调用限制
为避免死锁,不建议在任何SDK的回调中调用本方法。
调用此方法后请把引擎对象置空,示例如下:
mAliRtcEngine.destroy(); mAliRtcEngine = null;
destroy[2/2]
销毁AliRtcEngine 对象。
public abstract void destroy(AliRtcDestroyCompletionObserver observer);
销毁AliRtcEngine 单例对象,调用该方法后将会释放所有内部使用的资源,你将不能再使用AliRtcEngine的其他方法和任何回调,如需要再次使用需要重新调用getInstance 创建新的实例。
该方法为异步调用,提供observer供开发者关注destroy完成时机,用户只有在OnDestroyCompletion完成后才能进行下一次创建,observer回调前不能完成销毁。
调用时机
当完成音视频通信之后都建议调用该方法释放实例。
调用限制
为避免死锁,不建议在任何SDK的回调中调用本方法。
相关回调
sdk引擎对象销毁完成后触发OnDestroyCompletion 回调,表明可以进行新一次的创建。
参数说明
参数 | 类型 | 描述 |
observer | 销毁引擎完成的通知回调,可监听此回调以确保资源释放完成。 |
setH5CompatibleMode
设置是否兼容H5。
public static int setH5CompatibleMode(int enable);
参数说明
参数 | 类型 | 描述 |
enable | int | 设置是否兼容H5,取值:
|
当前版本不支持在创建AliRtcEngine实例之后更改H5兼容模式,必须在创建实例之前就调用此接口。
getH5CompatibleMode
检查当前是否兼容H5。
public static int getH5CompatibleMode();
返回说明
1表示兼容H5
0表示不兼容H5
setRtcEngineEventListener
设置本地用户行为的通知事件的监听。
public abstract void setRtcEngineEventListener(AliRtcEngineEventListener listener);
该接口用于设置接收与本端用户自身相关的事件回调。例如,加入/离开频道的结果、用户角色变化、音视频推流状态变化、音视频订阅流状态变化、网络质量变化和探测结果、截图结果、设备状态及异常通知、SDK 错误通知等。开发者通过实现该类的回调方法,可以处理本地用户与 RTC 相关的生命周期和状态变化。
默认所有接口都有空实现,开发者不需要实现所有回调,可根据自身业务来实现对应的事件方法。
如果需要实现与远端用户相关回调、首帧首包回调、音效伴奏播放状态及鉴权信息回调请实现
AliRtcEngineNotify
类相关回调并调用setRtcEngineNotify
接口。不建议在回调方法中做耗时操作,如调用engine本身的destroy方法,这将有可能引起不必要的阻塞从而影响SDK的运行。
调用时机
该方法需要在入会前调用。
相关回调
SDK 在运行过程中如遇到异常情况,会优先尝试内部重试机制以自动恢复。对于无法自行解决的错误,SDK 会通过预定义的回调接口通知您的应用程序。以下是一些 SDK 无法处理、需由应用层监听和响应的关键回调:
异常发生原因 | 回调及参数 | 解决方案 | 说明 |
鉴权失败 | onJoinChannelResult回调中的result返回AliRtcErrJoinBadToken | 发生错误时App需要检查Token是否正确。 | 在用户主动调用API时,若鉴权失败,系统将在调用API的回调中返回鉴权失败的错误信息。 |
网络连接异常 | onConnectionStatusChange回调返回AliRtcConnectionStatusFailed。 | 发生该异常时APP需要重新入会。 | SDK具备一定时间断网自动恢复能力,但若断线时间超出预设阈值,会触发超时并断开连接。此时,App应检查网络状态并指导用户重新加入会议。 |
本地设备异常 | onLocalDeviceException | 发生该异常时App需要检测权限、设备硬件是否正常。 | RTC服务支持设备检测和异常诊断的能力;当本地设备发生异常时,RTC服务会通过回调的方式通知客户本地设备异常,此时,若SDK无法自行解决问题,则App需要介入以查看设备是否正常。 |
参数说明
参数 | 类型 | 描述 |
listener | 设置本地用户行为的通知事件的监听。 |
setRtcEngineNotify
设置远端用户行为的通知事件的监听。
public abstract void setRtcEngineNotify(AliRtcEngineNotify listener);
该接口主要用于设置接收与远端用户相关的事件回调。例如远端用户的上线/下线通知、远端用户音视频推流状态、远端用户分辨率变化、远端及本地音视频首帧/首包的发送与接收状态、本端及远端音效伴奏播放状态、静音状态、本地及远端音视频流统计信息、SEI 接收、自定义消息接收、鉴权信息变化等。开发者通过实现该类的回调方法,可以处理与远端用户交互相关的事件信息。
默认所有接口都有空实现,开发者不需要实现所有方法,可根据自身业务来实现对应的事件方法。
不建议在回调方法中做耗时操作,如调用engine本身的destroy方法,这将有可能引起不必要的阻塞从而影响SDK的运行。
调用时机
该方法需要在加入频道前调用。
相关回调
在运行过程中如遇到异常情况,会优先尝试内部重试机制以自动恢复。对于无法自行解决的错误,SDK 会通过预定义的回调接口通知您的应用程序。以下是一些 SDK 无法处理、需由应用层监听和响应的关键回调:
异常发生原因 | 回调及参数 | 解决方案 | 说明 |
被踢下线 | onBye |
| RTC服务提供了管理员可以主动移除参与者的功能。 |
鉴权将要过期 | onWillAuthInfoExpire | 发生该异常时App需要重新获取最新的鉴权信息后,再调用refreshAuthInfo刷新鉴权信息。 | 鉴权过期错误在两种情况下出现:用户调用API或程序执行期间。因此,错误反馈将通过API回调或通过独立的错误回调通知。 |
鉴权过期 | onAuthInfoExpired | 发生该异常时App需要重新入会。 | 鉴权过期错误在两种情况下出现:用户调用API或程序执行期间。因此,错误反馈将通过API回调或通过独立的错误回调通知。 |
参数说明
参数 | 类型 | 描述 |
listener | 设置远端用户行为的通知事件的监听,用于接收来自engine的消息。 |
getSdkVersion
查询 sdk 当前版本。
public static String getSdkVersion();
返回说明
当前的SDK版本号,格式为字符串,例:"2.5.0.x"。
setChannelProfile
设置频道模式。
public abstract int setChannelProfile(AliRTCSdkChannelProfile channelProfile);
该接口用于设置频道模式,目前主要提供视频通话场景和互动直播场景:
视频通话模式:所有用户都是主播角色,可以进行推流和拉流。
互动直播模式:需要调用
setClientRole
(设置角色),在频道内推流的用户设置主播角色(AliRTCSdkInteractive
);如果用户只需要拉流,不需要推流,则设置观众角色(AliRTCSdkLive
)。RTC 场景推荐设置为此模式。
RTC 场景都推荐使用互动直播模式,即调用本接口设置为
AliRTCSdkInteractiveLive
。相同频道内的用户必须使用同一种频道场景。
调用时机
该接口只可以在加入频道之前调用,会议中不可以重新设置,离开频道后可以重新设置。
参数说明
参数 | 类型 | 描述 |
channelProfile | 频道类型。RTC 场景都建议使用互动模式。 |
返回说明
0表示方法调用成功,其他表示方法调用失败,1:SDK未初始化或已销毁。
setAudioProfile
设置音频编码模式及场景模式。
public abstract int setAudioProfile(AliRtcAudioProfile profile, AliRtcAudioScenario scenario);
该接口用于设置音频编码模式以及音频场景模式。详情请参考音频常用操作和配置。ARTC SDK 默认使用高音质模式(AliRtcEngineHighQualityMode)和音乐场景模式(AliRtcSceneMusicMode)。如果默认设置无法满足您的需求,您需要调用此接口进行设置。
调用时机
该接口只可以在加入频道之前调用,加入频道后不可以重新设置,离开频道后可以重新设置。
参数说明
参数 | 类型 | 描述 |
profile | 音频采集或编码模式参数,建议使用高音质模式(AliRtcEngineHighQualityMode)。 说明 如果需要与 web 互通,需要设置采样率为 48k。
| |
scenario | 音频场景模式参数,主要包含:
|
返回说明
0:调用成功,小于0:调用失败。
isAudioOnly
检查当前是否纯音频模式。
public abstract boolean isAudioOnly();
返回说明
true纯音频模式,false音视频模式。
setAudioOnlyMode
是否开启纯音频模式。
public abstract int setAudioOnlyMode(boolean audioOnly);
参数说明
参数 | 类型 | 描述 |
audioOnly | boolean | 设置音频模式还是音视频模式,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
joinChannel[1/3]
加入频道(单参入会)。
public abstract int joinChannel(String token, String channelId, String userId, String userName);
该接口用于加入频道。ARTC 通过频道组织用户,用户需要加入频道才能“发布”或“订阅”音视频流。本接口与 joinChannel[2/3]
和接口joinChannel[3/3]
均可以加入频道,区别在于通过的认证方式和传递的用户信息,具体如下:
本接口为单参入会接口,传入Token鉴权生成单参入会的 Token 即可入会。RTC 场景推荐使用该接口加入频道。
joinChannel[2/3]
为多参入会接口,需要传入Token鉴权生成的多参入会 Token,并传入生成 Token 使用的用户信息入会。joinChannel[3/3]
为 AI 实时互动场景使用,传入单参入会 Token,并根据场景设置用户属性capabilityProfile
。
如果没有特殊配置,加入频道时默认订阅频道内所有其他用户的音视频流,默认推送音视频流到远端,如果想要取消默认订阅可在调用本接口前调用setDefaultSubscribeAllRemoteAudioStreams
和setDefaultSubscribeAllRemoteVideoStreams
关闭对音频流或视频流的订阅。
调用时机
需要在创建引擎后调用。
调用限制
加入频道成功后,如果中途需要加入其他频道,必须先调用
leaveChannel
离开当前频道,并确保收到AliRtcEngineEventListener
中的onLeaveChannelResult
回调,之后才能再次调用入会。该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道失败重试时无需调用。
相关回调
成功调用该接口后会触发以下回调:
本端加入频道的结果会通过
AliRtcEngineEventListener
中的onJoinChannelResult
回调进行通知加入频道的结果成功加入频道后,远端会触发
onRemoteUserOnLineNotify
回调。
参数说明
参数 | 类型 | 描述 |
token | String | 单参数入会的鉴权信息。 |
channelId | String | 入会频道,必须和产生token的值一样。 |
userId | String | 入会的userid,必须和产生token的值一样。 |
userName | String | 用户的显示名称(不是用户ID)。 |
返回说明
0表示方法调用成功,非0表示方法调用失败。
joinChannel[2/3]
加入频道(多参入会)。
public abstract int joinChannel(AliRtcAuthInfo authInfo, String userName);
该接口用于加入频道。ARTC 通过频道组织用户,用户需要加入频道才能“发布”或“订阅”音视频流。本接口与 joinChannel[1/3]
和接口joinChannel[3/3]
均可以加入频道,区别在于通过的认证方式和传递的用户信息,具体如下:
joinChannel[1/3]
为单参入会接口,传入Token鉴权生成单参入会的Token 即可入会。RTC 场景推荐使用该接口加入频道。本接口为多参入会接口,需要传入Token鉴权生成多参入会Token,并传入生成 Token 使用的用户信息入会。
joinChannel[3/3]
为 AI 实时互动场景使用,传入单参入会 Token,并根据场景设置用户属性capabilityProfile
。
如果没有特殊配置,加入频道时默认订阅频道内所有其他用户的音视频流,默认推送音视频流到远端,如果想要取消默认订阅可在调用本接口前调用
setDefaultSubscribeAllRemoteAudioStreams
和setDefaultSubscribeAllRemoteVideoStreams关闭对音频流或视频流的订阅。
本接口为多参入会接口,调用前请参照Token鉴权生成多参入会的 Token。
调用限制
加入频道成功后,如果中途需要加入其他频道,必须先调用
leaveChannel
离开当前频道,并确保收到AliRtcEngineEventListener
中的onLeaveChannelResult
回调,之后才能再次调用入会。该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
相关回调
成功调用该接口后会触发以下回调:
本端加入频道的结果会通过
AliRtcEngineEventListener
中的onJoinChannelResult
回调进行通知加入频道的结果成功加入频道后,远端会触发
onRemoteUserOnLineNotify
回调。
参数说明
参数 | 类型 | 描述 |
authInfo | 鉴权信息,其中 token 为多参 token,其他参数中与 token 生成相关的需要与生成 Token 时一致,且不可为空。 | |
userName | String | 用户的显示名称(不是用户ID),可以为空。 |
返回说明
0表示方法调用成功,非0表示方法调用失败。
joinChannel[3/3]
加入频道(单参入会)。
public abstract int joinChannel(String token, AliRTCSdkChannelParam channelParam);
该接口用于加入频道。ARTC 通过频道组织用户,用户需要加入频道才能“发布”或“订阅”音视频流。本接口与 joinChannel[1/3]
和接口joinChannel[2/3]
均可以加入频道,区别在于通过的认证方式和传递的用户信息,具体如下:
joinChannel[1/3]
为 RTC 场景单参入会接口,传入Token鉴权生成单参入会的 Token 即可入会。RTC 场景推荐使用该接口加入频道。joinChannel[2/3]
为多参入会接口,需要传入Token鉴权生成多参入会的 Token,并传入生成 Token 使用的用户信息入会。本接口为 AI 实时互动场景使用,传入单参入会 Token,并根据场景设置用户属性
capabilityProfile
,如果要与 AI 智能体通话时设置为AliCapabilityProfileAiHuman
。
如果没有特殊配置,加入频道时默认订阅频道内所有其他用户的音视频流,默认推送音视频流到远端,如果想要取消默认订阅可在调用本接口前调用setDefaultSubscribeAllRemoteAudioStreams
和setDefaultSubscribeAllRemoteVideoStreams
关闭对音频流或视频流的订阅。
调用限制
加入频道成功后,如果中途需要加入其他频道,必须先调用
leaveChannel
离开当前频道,并确保收到AliRtcEngineEventListener
中的onLeaveChannelResult
回调,之后才能再次调用加入频道。该方法仅支持用户一次加入一个频道。
使用不同 App ID 的 App 不能互通。
加入频道失败重试时无需调用。
相关回调
成功调用该接口后会触发以下回调:
本端加入频道的结果会通过
AliRtcEngineEventListener
中的onJoinChannelResult
回调进行通知加入频道的结果成功加入频道后,远端会触发
onRemoteUserOnLineNotify
回调。
参数说明
参数 | 类型 | 描述 |
token | String | 单参加入频道 Token。 |
channelParam | 加入频道参数,主要为 AI 实时互动场景使用,主要包含
|
返回说明
0表示方法调用成功,非0表示方法调用失败。
leaveChannel
离开频道。调用该方法后,SDK 会终止音视频互动、离开当前频道。
public abstract int leaveChannel();
该方法为异步操作,方法调用成功时并没有真正退出频道,需要等待
onLeaveChannelResult
回调后才会真正退出频道。leaveChannel 完成后请销毁引擎并将引擎置空。
mAliRtcEngine.leaveChannel(); mAliRtcEngine.destroy(); mAliRtcEngine = null;
调用时机
应该在加入频道后需要离开频道时调用该方法。
如果已经加入频道且需要加入其他频道需要调用此接口先退出频道。
相关回调
本端:调用本方法后会触发
onLeaveChannelResult
回调通知离会结果。远端:调用该接口成功后远端用户会触发
onRemoteUserOffLineNotify
回调。
返回说明
0表示方法调用成功,非0表示方法调用失败。
isInCall
检查当前是否在频道中。
public abstract boolean isInCall();
返回说明
true表示在频道中,false表示不在频道中。
setClientRole
设置用户角色。
public abstract int setClientRole(AliRTCSdkClientRole clientRole);
该方法用于设置用户角色为主播/观众。
互动模式下,加入频道前:
设置用户角色为主播:SDK默认会自动推送本地音视频流,并接收其他主播的音视频流
设置用户角色为观众:SDK不会推送本地的音视频流,但会接收其他主播的音视频流。
调用时机
该方法在加入频道前后均可调用,可以在入会前调用设置用户角色,也可以在入会后调用进行用户角色切换。
调用限制
该方法在互动模式下才有效,即调用setChannelProfile
接口设置为AliRTCSdkInteractiveLive
时才有效。
互动模式下建议入会前显式调用设置用户角色。
参数说明
参数 | 类型 | 描述 |
clientRole | 用户角色类型,互动模式下角色类型才有效。 |
getCurrentClientRole
获取用户角色。
public abstract AliRTCSdkClientRole getCurrentClientRole();
返回说明
返回当前用户角色。
refreshAuthInfo[1/2]
刷新鉴权信息。
public abstract int refreshAuthInfo(AliRtcAuthInfo authInfo);
该方法用于更新鉴权信息。Token 会在一定时间后失效,此时 SDK 将无法和服务器建立连接。
本接口与refreshAuthInfo[2/2]
功能均为更新鉴权信息,只是本接口用于更新多参入会的 Token,refreshAuthInfo[2/2]
用户更新单参入会的 Token。有关 Token 生成请参考Token鉴权。
调用时机
在以下情况下:
当收到
onAuthInfoWillExpire
回调报告鉴权信息即将过期时,推荐你在你的服务端重新生成 Token,然后调用该方法传入新的 Token。如果没有及时更新 Token,会触发
onAuthInfoExpired
通告鉴权已经过期,此时需要重新生成 Token 然后调用joinChannel
重新加入频道。
参数说明
参数 | 类型 | 描述 |
authInfo | 鉴权信息。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
refreshAuthInfo[2/2]
刷新鉴权信息。
public abstract int refreshAuthInfo(String token);
该方法用于更新 Token。Token 会在一定时间后失效,此时 SDK 将无法和服务器建立连接。
本接口与refreshAuthInfo[1/2]
功能均为更新鉴权信息,只是本接口用于更新单参入会的 Token,refreshAuthInfo[1/2]
用户更新多参入会的 Token。有关 Token 生成请参考Token鉴权。
调用时机
在以下情况下,推荐你在你的服务端重新生成 Token,然后调用该方法传入新的 Token:
当收到
onAuthInfoWillExpire
回调报告鉴权信息即将过期时。如果没有及时更新 Token,会触发
onAuthInfoExpired
通告鉴权已经过期,此时需要调用joinChannel
重新加入频道。
参数说明
参数 | 类型 | 描述 |
token | String | 单参数入会的鉴权信息。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
publishLocalAudioStream
停止或恢复发布本地视频流。
public abstract int publishLocalAudioStream(boolean enable);
该方法用于控制是否发布本地采集的音频流。SDK默认设置推送音频流,如果您不想默认推送音频流,可以在入会前调用publishLocalAudioStream(false)
关闭音频流的推送。
调用时机
加入频道前后均可调用。加入频道前调用可修改默认配置,在加入频道时生效。
相关回调
本地音频推流结果发生变化时,本端会触发onAudioPublishStateChanged
回调通知音频推流最新状态,远端会触发onRemoteTrackAvailableNotify
通知远端用户的音视频流发生变化。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 是否发布音频流,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
isLocalAudioStreamPublished
查询当前是否发布音频流。
public abstract boolean isLocalAudioStreamPublished();
返回说明
true表示发布音频流,false表示不发布音频流。
setDefaultSubscribeAllRemoteAudioStreams
设置是否默认接收音频流。
public abstract int setDefaultSubscribeAllRemoteAudioStreams(boolean sub);
该接口用于配置系统是否默认订阅远端用户的音频流,该设置将影响新加入频道用户的音频流订阅行为。无特殊场景需求建议设置为 true。
调用时机
加入频道前后均可调用。
加入频道前:
SDK 加入频道时默认订阅远端用户的音频流,如果希望修改此行为,可在加入频道前调用该接口。
加入频道后:
如果希望停止默认订阅,可调用
setDefaultSubscribeAllRemoteAudioStreams(false)
,则不会订阅后续加入频道的用户的音频流。停止默认订阅后,如果希望恢复订阅指定用户的音频流,请调用subscribeRemoteAudioStream 接口,如果希望恢复多个用户请多次调用。
停止默认订阅后,调用
setDefaultSubscribeAllRemoteAudioStreams(true)
仅恢复后续加入频道的用户的音频流,对于停止期间加入的远端用户不会订阅。
参数说明
参数 | 类型 | 描述 |
sub | boolean | 是否默认接收音频流,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeRemoteAudioStream
停止或恢复特定远端用户的音频流拉取。
public abstract int subscribeRemoteAudioStream(String uid, boolean sub);
该接口用于停止或恢复订阅特定远端用户的音频流,无特殊场景需求建议设置为 true。
SDK 在入会时默认会订阅所有远端用户的音频流,如果要修改此行为,可以在入会前调用setDefaultSubscribeAllRemoteAudioStreams(false)
取消该默认配置。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
sub | boolean | 停止或恢复特定远端用户的音频流拉取,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeAllRemoteAudioStreams
设置是否接收所有远端音频流。
public abstract int subscribeAllRemoteAudioStreams(boolean sub);
该接口为订阅远端音频流的总开关,建议设为 true。 如果设置为 false,则会导致:
当前会议中所有远端音频停止订阅;
后续入会的新用户也不再订阅;
无法通过
subscribeRemoteAudioStream
单独操控指定用户的音频流。
如果需要重新订阅,请再次调用本接口并设置为 true 恢复订阅。
SDK 在入会时默认会订阅所有远端用户的音频流,如果要修改此行为,可以在入会前调用setDefaultSubscribeAllRemoteAudioStreams(false)
取消该默认配置。
参数说明
参数 | 类型 | 描述 |
sub | boolean | 是否接收所有远端音频流,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
publishLocalVideoStream
设置是否发布相机流。
public abstract int publishLocalVideoStream(boolean enable);
该方法用于控制是否发布本地采集的视频流。
SDK默认推送视频流,如果需要关闭视频流推送,请在入会前调用publishLocalVideoStream(false)。
调用时机
加入频道前后均可调用。
加入频道前调用可修改默认配置,在加入频道时生效。
相关回调
本地音频推流结果发生变化时,本端会触发onVideoPublishStateChanged
回调通知音频推流最新状态,远端会触发onRemoteTrackAvailableNotify
通知远端用户的音视频流发生变化
参数说明
参数 | 类型 | 描述 |
enable | boolean | 是否发布相机流,取值:
|
返回说明
0表示接口调用成功,其他表示方法调用失败。
isLocalVideoStreamPublished
查询当前是否发布相机流。
public abstract boolean isLocalVideoStreamPublished();
返回说明
true表示发布相机流,false表示不发布相机流。
setDefaultSubscribeAllRemoteVideoStreams
设置是否默认接收视频流。
public abstract int setDefaultSubscribeAllRemoteVideoStreams(boolean sub);
该接口用于设置是否默认订阅视频流,SDK 默认订阅。
调用时机
加入频道前后均可调用。如果在加入频道后调用 setDefaultSubscribeAllRemoteVideoStreams(false),会接收不到设置后加入频道的用户的视频流。
停止接收视频流后,如果想要恢复接收,请调用subscribeRemoteVideoStream,并指定你想要接收的远端用户ID;如果想恢复接收多个用户的视频流,则需要多次调用subscribeRemoteVideoStream;setDefaultSubscribeAllRemoteVideoStreams(true) 只能恢复接收后面加入频道的用户的视频流。
该接口用于设置是否默认订阅远端用户的视频流。
SDK 入会时默认订阅远端用户的音视频流,如果希望修改此行为,可在加入频道前调用该接口。
参数说明
参数 | 类型 | 描述 |
sub | boolean | 是否默认接收视频流,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeRemoteVideoStream
停止或恢复订阅指定的远端视频流。
public abstract int subscribeRemoteVideoStream(String uid, AliRtcVideoTrack track, boolean sub);
对指定用户的视频流进行订阅和取消订阅的操作。
SDK 在入会时默认会订阅所有远端用户的视频流,如果要修改此行为,可以在入会前调用setDefaultSubscribeAllRemoteVideoStreams(false)
取消该默认配置。
调用时机
入会前入会后均可调用。
参数说明
参数 | 类型 | 描述 |
uid | String | 用户 uid |
track | 视频流类型。 | |
sub | boolean | 是否接收指定用户的视频流。
|
返回说明
0: 执行此接口成功。
非 0: 执行此接口失败。
subscribeAllRemoteVideoStreams
停止或恢复接收所有远端视频流。
public abstract int subscribeAllRemoteVideoStreams(boolean sub);
该接口为订阅远端视频流的总开关,如果设置为 false,则会导致:
当前会议中所有远端视频流停止订阅;
后续入会的新用户也不再订阅(即使设置了
setDefaultSubscribeAllRemoteVideoStreams(true)默认订阅)
;无法通过
subscribeRemoteVideoStream
单独操控指定用户的视频流。
如果需要重新订阅,请再次调用本接口并设置为 true 恢复订阅。
SDK 在入会时默认会订阅所有远端用户的视频流,如果要修改此行为,可以在入会前调用setDefaultSubscribeAllRemoteVideosStreams(false)
取消该默认配置。
参数说明
参数 | 类型 | 描述 |
sub | boolean | 停止或恢复接收所有远端视频流,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeRemoteMediaStream[1/2]
停止或恢复特定远端用户的媒体流。
public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, boolean subVideo, boolean subAudio);
该接口用于合并订阅远端音视频流。
在该接口中 AliRtcVideoTrack 的AliRtcVideoTrackNo
是无效的,设置不会有任何效果。
相关接口
相比subscribeRemoteMediaStream[2/2]
,本接口通过两个布尔类型参数 subVideo、subAudio 决定是否订阅远端音视频流,videoTrack 用于控制拉取哪一路视频流。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
videoTrack | 视频流类型。 | |
subVideo | boolean | 停止或恢复特定远端用户的视频流拉取,取值:
|
subAudio | boolean | 停止或恢复特定远端用户的音频流拉取,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeRemoteMediaStream[2/2]
停止/恢复订阅远端用户的音视频流。
public abstract int subscribeRemoteMediaStream(String uid, AliRtcVideoTrack videoTrack, AliRtcAudioTrack audioTrack) ;
该接口用于合并订阅远端音视频流。
相关接口
相比于subscribeRemoteMediaStream[1/2]
,这个接口通过 videoTrack、audioTrack 两个参数在一个接口中把想要订阅的状态告知SDK,例如:
希望订阅相机流和麦克风流,则在调用时将 videoTrack 和 audioTrack 分别置为
AliRtcVideoTrackCamera
和AliRtcAudioTrackMic
。希望取消订阅相机流但保留麦克风,则在再次调用时将 videoTrack 和 audioTrack 分别置为
AliRtcVideoTrackNo
和AliRtcAudioTrackMic
。如果希望都取消,则在再次调用时将 videoTrack 和 audioTrack 分别置为
AliRtcVideoTrackNo
和AliRtcAudioTrackNo
。如果希望同时订阅相机流和屏幕共享流两路视频流,将 videoTrack 设置为
AliRtcVideoTrackBoth
,音频同理。
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID,从App server分配的唯一标示符。 |
videoTrack | 视频流类型。 | |
audioTrack | 音频流类型。 |
返回说明
0:设置成功。
<0:设置失败。
subscribeRemoteDestChannelStream
跨频道订阅指定用户的流。
public abstract int subscribeRemoteDestChannelStream(String channelId, String uid, AliRtcVideoTrack track, boolean sub_audio, boolean sub);
参数说明
参数 | 类型 | 描述 |
channelId | String | 远端频道ID。 |
uid | String | 远端用户ID。 |
track | 需要订阅的视频流。 | |
sub_audio | boolean | 停止或恢复特定远端用户的音频流拉取,取值:
|
sub | boolean | 停止或恢复跨频道订阅指定用户的流。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
subscribeRemoteDestChannelAllStream
停止或恢复订阅跨频道所有用户的流。
public abstract int subscribeRemoteDestChannelAllStream(String channelId, AliRtcVideoTrack track, boolean sub_audio, boolean sub);
参数说明
参数 | 类型 | 描述 |
channelId | String | 远端目标频道 ID。 |
videoTrack | 需要订阅的视频流类型。 | |
sub_audio | boolean | 是否订阅远端用户的音频流。
|
sub | boolean | 停止或恢复跨频道订阅指定用户流。
|
返回说明
0:调用此方法成功。
非 0:调用此方法失败。
setRemoteAudioVolume
调节拉流的播放音量。
public abstract int setRemoteAudioVolume(String uid, int volume);
通过此接口,本端用户调节指定用户的音频流在本设备上的播放音量。
此设置仅影响本地设备的收听效果。
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID,用户的唯一标识,一般由App server分配。 |
volume | int | 播放音量,取值范围[0,100]。
|
返回说明
0:执行此方法成功。
非 0:执行此方法失败,例如音量值为无效值等。
muteLocalMic
停止或恢复本地音频数据发送。
public abstract int muteLocalMic(boolean mute, AliRtcMuteLocalAudioMode mode);
静音是指音频流发送静音帧,采集和编码模块仍然在工作。
调用时机
加入频道前后均可调用。
相关回调
调用成功后,远端用户触发onUserAudioMuted
通知该用户是否静音。
参数说明
参数 | 类型 | 描述 |
mute | boolean | 停止或恢复本地音频数据发送,取值:
|
mode | 静音模式,默认麦克风静音模式。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。mute只是发送音频数据为静音帧,采集和编码模块仍然在工作。
muteRemoteAudioPlaying
停止或恢复远端的音频播放。
public abstract int muteRemoteAudioPlaying(String uid, boolean mute);
该接口仅用于停止或者恢复远端指定用户的音频的播放,但是不影响对远端音频的拉流和解码,如果希望取消订阅某个用户的音频流,请调用subscribeRemoteAudioStream
完成。
调用时机
入会前后均可设置。
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID。 |
mute | boolean | 停止或恢复远端的音频播放,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
muteAllRemoteAudioPlaying
停止或恢复远端所有的音频播放。
public abstract int muteAllRemoteAudioPlaying(boolean mute);
该接口用于停止或恢复远端所有音频播放。
本接口仅是停止播放,拉流和解码不受影响。
调用时机
加入频道前后均可设置。
参数说明
参数 | 类型 | 描述 |
mute | boolean | 停止或恢复远端所有的音频播放,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
startAudioCapture[1/2]
开启音频采集。
public abstract int startAudioCapture();
此接口用于控制开启音频采集。此外在入会前调用可以控制提前打开音频采集,如果不设置,则SDK会自动控制音频采集设备。调用stopAudioCapture
关闭音频采集后如果想要打开,请调用此接口。
调用时机
入会前后均可调用。
相关接口
startAudioCapture[2/2]
接口通过参数可以控制离会后音频采集设备是否保持开启状态。
相关回调
调用此接口修改本地音频采集状态后,可通过onLocalAudioStateChanged 回调来获取状态变化。
返回说明
0表示方法调用成功,其他表示方法调用失败。
startAudioCapture[2/2]
开启音频采集。
public abstract int startAudioCapture(boolean keepAlive);
静音后关闭麦克风采集。
此接口用于控制开启音频采集。此外在入会前调用可以控制提前打开音频采集,如果不设置,则SDK会自动控制音频采集设备。
调用时机
入会前后均可调用。
相关接口
相比startAudioCapture[1/2]
,本接口允许通过 keepAlive 参数控制离会后采集设备是否保持开启。
相关回调
调用此接口修改本地音频采集状态后,可通过onLocalAudioStateChanged 回调来获取状态变化。
参数说明
参数 | 类型 | 描述 |
keepAlive | boolean | 离会后采集设备的状态,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
stopAudioCapture
关闭音频采集。
public abstract int stopAudioCapture();
SDK默认开启音频采集,如果没有特殊配置,启动预览、加入频道等行为会自动启动音频采集,如果希望停止音频设备采集,请调用本接口。
相关回调
调用此接口修改本地音频采集状态后,可通过onLocalAudioStateChanged 回调来获取状态变化。
返回说明
0表示方法调用成功,其他表示方法调用失败。
setDefaultAudioRoutetoSpeakerphone
设置默认音频输出是否为扬声器。
public abstract int setDefaultAudioRoutetoSpeakerphone(boolean defaultToSpeakerphone);
该接口用于在入会前设置默认的音频路由设备,可选择默认输出到听筒或扬声器,SDK 内部默认为扬声器,如果您希望修改该默认配置可在入会前调用本接口。
音频路由的优先级在 SDK 内部已经定义好,并会根据当前外设连接状态自动切换,优先级如下:有线耳机>蓝牙耳机>用户设置>默认设置
,因此如果没有连接外设且没有通过enableSpeakerphone
进行设置,则会使用默认设置。
更多有关音频路由设置相关细节请参考音频路由设置。
手机设备一般有两个音频路由设备,分别是听筒和扬声器:
当音频路由为听筒时,声音比较小,只有将耳朵凑近才能听清楚,隐私性较好,适合用于接听电话。
当音频路由为扬声器时,声音比较大,不用将手机贴脸也能听清,因此可以实现“免提”的功能。
相关接口
该接口用于修改默认音频路由设置,enableSpeakerphone
接口用于设置当前路由设备。
调用时机
入会前后均可调用。
参数说明
参数 | 类型 | 描述 |
defaultToSpeakerphone | boolean | 是否默认使用扬声器。
|
返回说明
0: 该方法调用成功。
<0: 该方法调用失败。
enableSpeakerphone
设置音频输出为听筒还是扬声器。
public abstract int enableSpeakerphone(boolean enable);
该接口用于在入会后设置当前播放的音频设备,在听筒和扬声器之间选择。如果没有设置该功能,将使用默认音频路由所设置的设备进行播放。
音频路由的优先级在 SDK 内部已经定义好,并会根据当前外设连接状态自动切换,优先级如下:有线耳机>蓝牙耳机>用户设置>默认设置
,因此当连接外设时,该接口调用不生效。更多有关音频路由设置相关细节请参考音频路由设置。
调用时机
加入频道前后均可调用。
相关接口
setDefaultAudioRoutetoSpeakerphone
用于修改默认音频路由设置,本接口用于设置当前路由设备。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 音频输出为听筒还是扬声器,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
isSpeakerOn
获取当前音频输出为听筒还是扬声器。
public abstract boolean isSpeakerOn();
返回说明
true为扬声器,false为听筒。
enableAudioVolumeIndication
开启用户音量提示。
public abstract int enableAudioVolumeIndication(int interval, int smooth, int reportVad);
该接口允许 SDK 定期向 App 报告本地发流用户和瞬时音量最高的远端用户的音量相关信息。如果想使用该功能,请实现AliRtcAudioVolumeObserver
类,并调用registerAudioVolumeObserver
接口注册接收对象。
调用时机
加入频道前后均可调用。
相关回调
成功调用该方法后,如果频道内存在发流用户时,SDK 会按照设置的时间间隔触发下面两个回调:
说话人的音频音量会通过AliRtcAudioVolumeObserver#onAudioVolume 回调通知,回调频率会根据 interval 决定。
语音激励,当监测到活跃用户时,说话人uid会通过AliRtcAudioVolumeObserver#onActiveSpeaker回调。
参数说明
参数 | 类型 | 描述 |
interval | int | 时间间隔。
|
smooth | int | 平滑系数,数值越大平滑程度越高,反之越低,实时性越好。
|
reportVad | int | 本地语音检测开关。
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
enableEarBack
启用耳返。
public abstract int enableEarBack(boolean enable);
该方法用于启用或关闭耳返功能。建议在戴耳机(有线或蓝牙均可)的情况下开启耳返,效果更好。
调用时机
加入频道前后均可调用。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 是否启用耳返,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
setEarBackVolume
设置耳返音量。
public abstract int setEarBackVolume(int volume) ;
该接口用于设置耳返的音量, 通过enableEarBack
开启耳返功能后才生效。
调用时机
加入频道前后均可调用。
参数说明
参数 | 类型 | 描述 |
volume | int | 音量,取值范围为 [0-100],默认值为 100。
|
返回说明
0: 方法调用成功。
<0: 方法调用失败。
startAudioPlayer
打开音频播放设备。
public abstract int startAudioPlayer();
此接口可以控制提前打开音频播放,如果不设置,则SDK会在订阅到音频流后自动打开音频播放。
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
stopAudioPlayer
关闭音频播放设备。
public abstract int stopAudioPlayer();
此接口可以控制关闭音频播放,与startAudioPlayer对应。
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
setPlayoutVolume
设置本地播放音量。
public abstract int setPlayoutVolume(int volume);
参数说明
参数 | 类型 | 描述 |
volume | int | 录音音量,取值范围[0,400]。
|
返回说明
0:调用成功。
非 0:调用失败。
setRecordingVolume
设置录音音量。
public abstract int setRecordingVolume(int volume);
参数说明
参数 | 类型 | 描述 |
volume | int | 录音音量,取值范围[0,400]。
|
返回说明
0:调用成功。
非 0:调用失败。
playAudioFileTest
播放音频文件。
public abstract int playAudioFileTest(String filePath) ;
该方法用于在入会前播放一个音频文件来进行音频播放测试。
调用时机
只能在入会前调用此接口。
调用限制
多次调用会相互覆盖,调用时会停止正在播放的文件(如果存在)。
参数说明
参数 | 类型 | 描述 |
filePath | filePath | 文件路径。 |
返回说明
0:调用成功。
非 0:调用失败。
stopAudioFileTest
停止播放音频文件。
public abstract int stopAudioFileTest();
本接口与 playAudioFileTest 相对应,用于停止播放音频文件。
调用限制
只能在入会前调用此接口。
返回说明
0:调用成功。
非 0:调用失败。
startAudioCaptureTest
通话前开启音频采集设备检测。
public abstract int startAudioCaptureTest();
此接口可以控制打开音频采集检测,用于在通话前测试本地音频采集设备能否正常工作。调用此方法后,SDK 通过AliRtcAudioVolumeObserver::OnTestAudioVolume 回调向开发者报告采集设备的音量信息。
调用时机
该方法需要在加入频道前调用。测试完成后,请确保调用stopAudioCaptureTest 停止检测设备检测,防止设备占用问题。
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
stopAudioCaptureTest
关闭音频采集检测。
public abstract int stopAudioCaptureTest();
该方法用于停止音频采集设备检测,调用startAudioCaptureTest 后必须调用该方法停止测试。
调用时机
加入频道前调用。
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
setAudioEffectVoiceChangerMode
设置变声音效模式。
public abstract int setAudioEffectVoiceChangerMode(AliRtcAudioEffectVoiceChangerMode mode);
参数说明
参数 | 类型 | 描述 |
mode | 变声音效模式,默认值为AliRtcSdk_AudioEffect_Voice_Changer_OFF(关闭)。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAudioEffectPitchValue
设置变调参数。
public abstract int setAudioEffectPitchValue(double value);
参数说明
参数 | 类型 | 描述 |
value | double | 参数取值范围:[0.5,2.0],默认值为1.0,表示音调不变。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAudioEffectReverbMode
设置混响音效模式。
public abstract int setAudioEffectReverbMode(AliRtcAudioEffectReverbMode mode);
参数说明
参数 | 类型 | 描述 |
mode | 音效混响模式,默认值为AliRtcAudioEffectReverb_Off(关闭)。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAudioEffectReverbParamType
设置混响音效类型和具体参数。
public abstract int setAudioEffectReverbParamType(AliRtcAudioEffectReverbParamType type, float value);
参数说明
参数 | 类型 | 描述 |
type | 音效混响参数。 | |
value | float | 具体参数值。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
addExternalAudioStream
新增外部音频流
public abstract int addExternalAudioStream(AliRtcExternalAudioStreamConfig config);
该接口用于新增一个外部音频流。以下为相关步骤:
调用
addExternalAudioStream
接口添加一个外部音频流并获取外部音频流 ID。调用
pushExternalAudioStreamRawData
向创建的音频流中传入音频数据。结束通话时,需要调用
removeExternalAudioStream
移除外部音频流。
如需在频道中发布自定义采集音频,可参考文档自定义音频采集。
参数说明
参数 | 类型 | 描述 |
config | AliRtcExternalAudioStreamConfig | 外部音频流配置。 |
返回说明
>0表示方法调用成功,返回值为外部音频流ID,其他表示方法调用失败。
pushExternalAudioStreamRawData
输入外部音频流数据。
public abstract int pushExternalAudioStreamRawData(int streamId, AliRtcAudioFrame rawData);
该接口用于向指定的音频流传入数据。以下为相关步骤:
调用
addExternalAudioStream
接口添加一个外部音频流并获取外部音频流 ID。调用
pushExternalAudioStreamRawData
向创建的音频流中传入音频数据。结束通话时,需要调用
removeExternalAudioStream
移除外部音频流。
如需在频道中发布自定义采集音频,可参考文档自定义音频采集。
调用时机
加入频道后调用。
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id。 |
rawData | AliRtcAudioFrame | 音频数据 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setExternalAudioStreamPublishVolume
设置外部音频流推流音量
public abstract int setExternalAudioStreamPublishVolume(int streamId, int publishVolume);
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id。 |
publishVolume | int | 推流音量,取值范围[0, 100]。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
getExternalAudioStreamPublishVolume
获取外部音频流推流音量
public abstract int getExternalAudioStreamPublishVolume(int streamId);
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id。 |
返回说明
[0, 100]推流音量,< 0: 失败。
setExternalAudioStreamPlayoutVolume
设置外部音频流播放音量
public abstract int setExternalAudioStreamPlayoutVolume(int streamId, int playoutVolume);
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id。 |
playoutVolume | int | 播放音量,取值范围[0, 100]。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
getExternalAudioStreamPlayoutVolume
获取外部音频流播放音量
public abstract int getExternalAudioStreamPlayoutVolume(int streamId);
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id。 |
返回说明
[0, 100] 播放音量,< 0表示调用失败。
removeExternalAudioStream
删除外部音频流。
public abstract int removeExternalAudioStream(int streamId);
该方法负责根据传入的 streamId 移除对应的外部音频流,与addExternalAudioStream 方法相对应,
调用时机
如果您想要使用自定义音频输入功能,需要调用addExternalAudioStream 方法添加一个音频流并获取外部音频流 Id,之后调用pushExternalAudioStreamRawData 接口向 sdk 输入您的音频数据。在您想要停止自定义音频输入时,调用当前接口移除对应的外部音频流并清理资源。
参数说明
参数 | 类型 | 描述 |
streamId | int | 外部音频流Id,是 addExternalAudioStream 方法调用成功时的返回值。 |
返回说明
0:调用成功。
<0:调用失败,返回错误码。
getAudioFileInfo
获取音频文件信息。
public abstract int getAudioFileInfo(String fileName);
开发者可调用此接口异步获取文件的时长信息。此接口为异步接口,可通过 onAudioFileInfo获取音频文件信息。
参数介绍
参数 | 类型 | 描述 |
fileName | String | 音频文件路径。 |
返回介绍
0:调用成功。
非 0:返回错误码。
startAudioAccompany
开始伴奏混音。
public abstract int startAudioAccompany(String fileName, AliRtcAudioAccompanyConfig config) ;
本接口用于播放本地或在线的伴奏文件。异步接口,调用此接口后可通过AliRtcEngineNotify#onAudioAccompanyStateChanged监听伴奏播放状态。
调用时机
入会后方可调用。
调用限制
与音效不同,伴奏某一时刻只能播放一个,重复调用会覆盖上一首伴奏的播放。
参数说明
参数 | 类型 | 描述 |
fileName | String | 伴奏文件路径。 |
config | 伴奏播放配置,包含是否仅本地播放、是否替换麦克、循环次数、起播位置、音量等设置。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
stopAudioAccompany
停止伴奏混音。
public abstract int stopAudioAccompany() ;
该接口与 startAudioAccompany 对应,用于停止伴奏播放。
调用时机
入会前后均可调用。
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
setAudioAccompanyVolume
设置伴奏音量,包含伴奏的本地播放音量和推流音量。
public abstract int setAudioAccompanyVolume( int volume) ;
本接口用于设置伴奏音量,同时设置伴奏本地播放音量与伴奏推流音量。此外,setAudioAccompanyPlayoutVolume 和 setAudioAccompanyPublishVolume 分别仅设置本地播放音量和伴奏推流的音量。
参数说明
参数 | 类型 | 描述 |
volume | int | 伴奏音量,取值范围[0, 100]。 0: 静音。 100:原始文件音量。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
setAudioAccompanyPublishVolume
设置伴奏推流音量。
public abstract int setAudioAccompanyPublishVolume(int volume) ;
参数说明
参数 | 类型 | 描述 |
volume | int | 伴奏音量,取值范围[0, 100]。 0: 静音。 100:原始文件音量。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
getAudioAccompanyPublishVolume
获取伴奏推流音量。
public abstract int getAudioAccompanyPublishVolume() ;
返回说明
伴奏音乐的推流音量。
[0-100]:成功。
其他:错误码。
setAudioAccompanyPlayoutVolume
设置伴奏本地播放音量。
public abstract int setAudioAccompanyPlayoutVolume(int volume) ;
参数说明
参数 | 类型 | 描述 |
volume | int | 伴奏音量,取值范围[0, 100]。 0: 静音。 100:原始文件音量。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
getAudioAccompanyPlayoutVolume
获取伴奏本地播放音量。
public abstract int getAudioAccompanyPlayoutVolume() ;
返回说明
伴奏音乐的本地播放音量。
[0-100]:成功。
其他:错误码。
pauseAudioAccompany
暂停伴奏混音。
public abstract int pauseAudioAccompany();
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
resumeAudioAccompany
重新开始伴奏混音。
public abstract int resumeAudioAccompany();
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
getAudioAccompanyDuration
获取伴奏文件时长, 单位为毫秒
public abstract int getAudioAccompanyDuration();
该接口用于获取当前伴奏文件的时长。
返回说明
>=0:伴奏文件时长。
<0:调用失败,返回错误码。
getAudioAccompanyCurrentPosition
获取伴奏文件播放进度,单位为毫秒。
public abstract int getAudioAccompanyCurrentPosition();
该方法用于获取当前伴奏文件的播放进度,单位为毫秒。
返回说明
>=0: 伴奏文件播放进度
<0:调用失败,返回错误码。
setAudioAccompanyPosition
设置伴奏文件的播放位置。
public abstract int setAudioAccompanyPosition(int posMs);
该方法用于主动设置伴奏的播放进度,用于实现进度条拖动等功能。调用该方法成功后,伴奏文件将从 posMs 对应位置播放。
参数说明
参数 | 类型 | 描述 |
posMs | int | 进度条位置,单位为毫秒。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
preloadAudioEffect
预加载音效文件。
public abstract int preloadAudioEffect(int soundId, String filePath);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
filePath | String | 音效文件路径。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
unloadAudioEffect
删除预加载的音效文件。
public abstract int unloadAudioEffect(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
playAudioEffect
开始播放音效。
public abstract int playAudioEffect(int soundId, String filePath, int cycles, boolean publish);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
filePath | String | 音效文件路径。 |
cycles | int | 循环次数,-1表示一直循环。 |
publish | boolean | 是否将音效音频流推到远端,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
stopAudioEffect
停止播放音效。
public abstract int stopAudioEffect(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
stopAllAudioEffects
停止播放所有音效。
public abstract int stopAllAudioEffects();
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAudioEffectPublishVolume
设置音效推流音量。
public abstract int setAudioEffectPublishVolume(int soundId, int volume);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
volume | int | 混音音量,取值范围:0~100,默认值为50。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
getAudioEffectPublishVolume
获取推流音效音量。
public abstract int getAudioEffectPublishVolume(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAudioEffectPlayoutVolume
设置音效本地播放音量。
public abstract int setAudioEffectPlayoutVolume(int soundId, int volume);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
volume | int | 混音音量,取值范围:0~100,默认值为50。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
getAudioEffectPlayoutVolume
获取音效本地播放音量(Android和iOS)。
public abstract int getAudioEffectPlayoutVolume(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAllAudioEffectsPublishVolume
设置所有音效推流混音音量。
public abstract int setAllAudioEffectsPublishVolume(int volume);
参数说明
参数 | 类型 | 描述 |
volume | int | 混音音量,取值范围:0~100,默认值为50。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setAllAudioEffectsPlayoutVolume
设置所有音效本地播音量(Android和iOS)。
public abstract int setAllAudioEffectsPlayoutVolume(int volume);
参数说明
参数 | 类型 | 描述 |
volume | int | 混音音量,取值范围:0~100,默认值为50。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
pauseAudioEffect
暂停音效。
public abstract int pauseAudioEffect(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
pauseAllAudioEffects
暂停所有音效。
public abstract int pauseAllAudioEffects();
返回说明
0表示方法调用成功,其他表示方法调用失败。
resumeAudioEffect
重新开始播放音效。
public abstract int resumeAudioEffect(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
resumeAllAudioEffects
重新开始播放所有音效。
public abstract int resumeAllAudioEffects();
返回说明
0表示方法调用成功,其他表示方法调用失败。
createRenderSurfaceView
创建SurfaceView渲染视图。
public abstract SophonSurfaceView createRenderSurfaceView(Context context);
显示视频视图必须调用该方法,而不是直接创建 SurfaceView。调用方式如下:
将返回值赋值AliRtcVideoCanvas#view
调用setLocalViewConfig设置本地预览显示视图或者调用setRemoteViewConfig设置远程预览显示视图。
调用时机
加入频道前后均可调用。
调用限制
请在主线程调用该方法。
参数说明
参数 | 类型 | 描述 |
context | Context | 安卓(Android Activity)的上下文。 |
setLocalViewConfig
为本地预览设置渲染窗口以及绘制参数。
public abstract int setLocalViewConfig(AliRtcVideoCanvas viewConfig, AliRtcVideoTrack track);
该方法用于设置本地预览视图,调用该方法会绑定本地视频流的显示视窗 (view),并设置本地用户视图的渲染模式、镜像模式和旋转角度等,只影响本地用户预览画面,不影响推流视频。如果需要设置远端用户界面视图请调用setRemoteViewConfig
。
如果AliRtcVideoCanvas中的view参数为空,则停止渲染。
如果在播放过程中需要重新设置AliRtcVideoCanvas的参数renderMode,请保持其他参数不变,仅修改renderMode,
如果在播放过程中需要重新设置AliRtcVideoCanvas的参数mirrorMode,请保持其他参数不变,仅修改mirrorMode。
建议显式调用 startPreview()启动本地预览。
调用时机
该方法在加入频道前后均可调用。
参数说明
参数 | 类型 | 描述 |
viewConfig | 渲染参数,包含渲染窗口以及渲染方式。 | |
track | 视频流类型。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setRemoteViewConfig
为远端的视频设置渲染窗口以及绘制参数。
public abstract int setRemoteViewConfig(AliVideoCanvas canvas, String uid,AliRtcVideoTrack track);
该方法会绑定远端用户指定视频流的显示视图,并设置远端用户视图在本地显示时的渲染模式、镜像模式和旋转角度等,只影响本地用户看到的视频画面。如果需要设置本地预览视图,请调用setLocalViewConfig
。
如果AliRtcVideoCanvas中的view参数为空,则停止渲染。
如果在播放过程中需要重新设置AliRtcVideoCanvas的参数renderMode,请保持其他参数不变,仅修改renderMode。
如果在播放过程中需要重新设置AliRtcVideoCanvas的参数mirrorMode,请保持其他参数不变,仅修改mirrorMode。
调用时机
建议在收到onRemoteTrackAvailableNotify 回调时调用,即远端用户视频可用时设置。
参数说明
参数 | 类型 | 描述 |
canvas | 渲染参数,包含渲染窗口以及渲染方式。 | |
uid | String | 用户ID。 |
track | 需要设置的视频流类型。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
setCameraCapturerConfiguration
设置摄像头采集偏好。
public abstract int setCameraCapturerConfiguration(AliEngineCameraCapturerConfiguration cameraCapturerConfiguration);
该接口用于配置摄像头采集时的偏好,例如摄像头方向、采集帧率等。
调用时机
必须在打开摄像头之前设置,例如在以下操作前调用:
startPreview(开始预览)
joinChannel(加入频道)
参数说明
参数 | 类型 | 描述 |
cameraCapturerConfiguration | 摄像头采集偏好,包括摄像头方向、帧率等。默认值:
以上-1表示使用SDK内部默认设置; |
返回说明
0表示方法调用成功,其他表示方法调用失败。
enableLocalVideo
禁用或重新启用本地视频采集。
public abstract int enableLocalVideo(boolean enable);
该方法用于控制本地视频采集的开启和关闭,当关闭本地视频采集时,本地预览和推流均没有视频数据,但是并不影响接收远端视频。如果调用此接口关闭了本地摄像头采集,那么本端预览和远端推流都会停留在最后一帧。
SDK 中本地视频采集默认开启。
调用时机
该方法在加入频道前后均可调用。
相关回调
成功调用本接口后会通过onUserVideoEnabled 回调通知远端用户。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 禁用或重新启用本地视频采集,取值:
|
返回说明
0表示方法调用成功,其他表示方法调用失败。
muteLocalCamera
停止或恢复本地视频数据发送。
public abstract int muteLocalCamera(boolean mute, AliRtcVideoTrack track);
推流时可调用此接口实现推送全黑色的视频帧,本地预览正常,采集,编码,发送模块仍然工作,只是视频内容是黑色帧。
此接口只是控制指定视频流上是否发送黑帧,采集和数据发送不会停止。如果需要关闭采集请使用enableLocalVideo接口,如果需要中止视频数据发送请使用publishLocalVideoStream接口或调用enableLocalVideo 停止采集
。
参数说明
参数 | 类型 | 描述 |
mute | boolean | 停止或恢复本地视频数据发送,取值:
|
track | 需要改变发布状态的视频流类型。 |
返回说明
0表示方法调用成功。
isCameraOn
检查摄像头是否打开。
public abstract boolean isCameraOn();
返回说明
true表示摄像头已打开,false表示摄像头未打开。
setVideoEncoderConfiguration
设置视频编码属性。
public abstract void setVideoEncoderConfiguration(AliRtcVideoEncoderConfiguration config);
该方法用于设置视频流编码属性对应的视频参数,如分辨率、帧率、码率、视频方向等。有视频场景都建议调用此接口。
所有设置的参数都有相应的范围限制,如果设置的参数不在有效范围内,SDK会自动调节。
调用时机
该方法在入会前和入会后都可以调用。如果每次入会只需要设置一次相机流视频编码属性,建议在入会前调用。
调用限制
该方法的 mirrorMode 和 setVideoMirrorMode 均可设置视频推流镜像,建议只使用一种,同时使用多种会导致镜像效果叠加从而造成设置镜像失败或错乱。
参数说明
参数 | 类型 | 描述 |
config | 预定义的编码属性。默认值:
以上-1表示使用SDK内部默认设置; |
setVideoDecoderConfiguration
设置视频解码属性。
public abstract void setVideoDecoderConfiguration(AliRtcVideoDecoderConfiguration config);
该方法用于设置视频流视频解码属性对应的视频参数。
调用时机
该方法建议在入会前调用。
参数说明
名称 | 类型 | 描述 |
config | AliRtcVideoDecoderConfiguration | 预定义的解码属性,默认值:
以上-1表示使用SDK内部默认设置; |
switchCamera
切换前后摄像头(默认为前置摄像头)。
public abstract int switchCamera();
此接口用于控制使用前置/后置摄像头,默认采用前置摄像头,可以在 App 运行期间根据可用摄像头实际情况来动态切换摄像头,而无需重启视频流或重新配置视频源。
调用时机
该方法必须在摄像头成功开启后调用。
调用限制
仅 Android 和 iOS 平台可用。
返回说明
0表示方法调用成功,其他表示方法调用失败。
getCurrentCameraDirection
获取当前摄像头方向。
public abstract AliRTCCameraDirection getCurrentCameraDirection();
返回说明
返回CAMERA_REAR(0)表示后置摄像头。
返回CAMERA_FRONT(1)表示前置摄像头。
返回CAMERA_INVALID(-1)表示无效。
此接口需要在摄像头打开之后调用,否则会返回CAMERA_INVALID(-1)。
startPreview
开始本地预览。
public abstract int startPreview();
该接口用于开启本地视频预览并自动打开摄像头,如果需要停止本地预览,可以调用stopPreview 接口。
leaveChannel 离开频道会自动停止本地预览;如果没有在推相机流,则会自动关闭摄像头。
调用时机
调用前需要通过 setLocalViewConfig 为本地预览设置视图,否则无法预览,但不影响推流。
如有需要可以在 joinChannel 加入频道前调用此接口开启预览,会自动开启摄像头。
返回说明
0表示方法调用成功,其他表示方法调用失败。
stopPreview
停止本地预览。
public abstract int stopPreview();
该接口用于关闭本地视频预览并关闭摄像头,停止预览后本端将保持在最后一帧,不影响推流。
leaveChannel 离开频道会自动停止本地预览;如果没有在推相机流,则会自动关闭摄像头。
调用时机
开启预览后如果需要关闭预览则可以调用此方法。
返回说明
0表示方法调用成功,其他表示方法调用失败。
setCameraZoom
设置摄像头缩放比例。
public abstract int setCameraZoom(float zoom);
设置摄像头的缩放比例。
调用限制
只有iOS和android提供这个接口。
调用时机
摄像头开启后设置才有效,每次摄像头重启后缩放也会重置。
参数说明
参数 | 类型 | 描述 |
zoom | float | 摄像头缩放比例。范围从 1 到 camera支持的最大 zoom值。可以通过GetCameraMaxZoomFactor 获取当前设备支持的最大缩放比例。 |
返回说明
0: 调用该方法成功。
非 0: 调用该方法失败。
GetCameraMaxZoomFactor
获取摄像头支持最大缩放(变焦)比例。
public abstract float GetCameraMaxZoomFactor();
返回说明
设备摄像头支持的最大缩放比例。
GetCurrentZoom
获取当前摄像头缩放比例设置。
public abstract float GetCurrentZoom();
返回说明
设备摄像头当前缩放比例。
SetExposure
设置摄像头曝光度。
public abstract int SetExposure(float exposure);
当拍摄环境光线不足或过于明亮时,会影响视频采集的画质。为了获得更好的视频效果,你可以使用该方法调节正在使用的摄像头的曝光度。可通过GetMinExposure 和GetMaxExposure 获取当前设备支持的曝光度范围。
参数说明
参数 | 类型 | 描述 |
exposure | float | 摄像头的曝光度,默认值为 0, 表示使用摄像头的默认曝光量。取值越大,曝光量越大。视频图像过曝时,你可以降低曝光系数;视频图像欠曝导致暗部细节丢失时,你可以增加曝光系数。如果传入的曝光度超出设备支持范围,SDK 会自动调节。 |
返回说明
0: 调用此方法成功。
非 0:调用此方法失败。
GetCurrentExposure
获取摄像头曝光度。
public abstract float GetCurrentExposure();
获取当前正在使用的摄像头的曝光度设置。
返回说明
当前摄像头曝光度。
GetMinExposure
获取摄像头支持的最小曝光度。
public abstract float GetMinExposure();
返回说明
摄像头最小曝光度。
GetMaxExposure
获取摄像头支持的最大曝光度。
public abstract float GetMaxExposure();
返回说明
摄像头最大曝光度。
setCameraFlash
设置摄像头闪光灯开关。
public abstract int setCameraFlash(boolean flash);
开启或关闭闪光灯。
一般只有后置摄像头才有闪光灯功能。
调用限制
只有iOS和android提供这个接口。
参数说明
参数 | 类型 | 描述 |
flash | boolean | 是否开启闪光灯。
|
返回说明
0: 设置成功。
非 0: 设置失败。
isCameraFocusPointSupported
当前设备是否支持手动聚焦。
public abstract boolean isCameraFocusPointSupported();
用来检查当前摄像机是否可以设置聚焦点以支持手动聚焦功能。
调用限制
只有iOS和android提供这个接口。
返回说明
true:设备支持手动对焦功能。
false:设备不支持手动对焦功能。
isCameraExposurePointSupported
是否支持设置摄像头曝光点。
public abstract boolean isCameraExposurePointSupported();
用于检查当前设备是否支持设置曝光点。
调用限制
只有iOS和android提供这个接口。
返回说明
true:支持设置摄像头曝光点。
false:不支持设置摄像头曝光点。
setCameraFocusPoint
设置摄像头手动聚焦点。
public abstract int setCameraFocusPoint(float x, float y);
设置当前摄像头的聚焦点。调用后camera对所设点做一次曝光调整,后面一直保持这个对焦值。调用此接口前建议调用isCameraFocusPointSupported 检查设备是否支持手动聚焦功能。
调用限制
只有iOS和android提供这个接口。
参数说明
参数 | 类型 | 描述 |
x | float | x轴坐标值。 |
y | float | y轴坐标值。 |
返回说明
0:此方法调用成功。
非 0:此方法调用失败。
setCameraExposurePoint
设置摄像头曝光点。
public abstract int setCameraExposurePoint(float x, float y);
设置摄像头曝光点。调用后camera对所设点做一次曝光调整,后面一直保持这个曝光值。调用此接口前建议调用isCameraExposurePointSupported 检查设备是否支持手动设置聚焦功能。
调用限制
只有iOS和android提供这个接口。
参数说明
参数 | 类型 | 描述 |
x | float | x轴坐标值 |
y | float | y轴坐标值 |
返回说明
0:此方法调用成功。
非 0:此方法调用失败。
isCameraAutoFocusFaceModeSupported
是否支持摄像头自动人脸聚焦。
public abstract boolean isCameraAutoFocusFaceModeSupported();
是否支持摄像头自动人脸聚焦。
调用时机
相机打开后调用才有效。如果在调用时相机没有打开会默认返回 false。在相机打开的情况下,如果当前相机同时支持人脸识别和对焦功能则返回true。
调用限制
只有iOS和android提供这个接口。
返回说明
true:支持自动人脸聚焦。
false:不支持自动人脸聚焦。
setCameraAutoFocusFaceModeEnabled
设置摄像头人脸聚焦。
public abstract boolean setCameraAutoFocusFaceModeEnabled(boolean enable);
调用此接口可以设置摄像机实时对焦到人脸上。在调用该方法前,请调用isCameraAutoFocusFaceModeSupported 验证设备是否支持此功能。
调用限制
只有iOS和android提供这个接口。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 开启或关闭摄像头人脸聚焦功能。
|
返回说明
true:调用成功。
false:调用失败。
setVideoMirrorMode
设置预览和推流视频镜像能力。
public abstract int setVideoMirrorMode(AliRtcVideoPipelineMirrorMode mirrorMode);
设置本地预览视频和推送的视频流是否开启镜像模式。
使用此接口的优先级会高于setLocalViewConfig&setVideoEncoderConfiguration,如果需要设置视频镜像模式,建议调用此接口。
调用时机
此接口在入会前和入会后均可以动态设置,SDK内部会记录状态,并在可以操作预览及编码(推流)的时候对视频进行操作。
调用限制
此接口与setLocalViewConfig&setVideoEncoderConfiguration里面的mirrorMode重合,建议只使用一个方式。
参数说明
参数 | 类型 | 描述 |
mirrorMode | 设置镜像的模式。 |
返回说明
0:设置成功。
<0:设置失败。
AliRtcErrInner: SDK内部状态错误,需检查是否创建SDK实例成功。
setCapturePipelineScaleMode
设置视频采集缩放时机。
public abstract void setCapturePipelineScaleMode(AliRtcCapturePipelineScaleMode mode);
设置视频数据采集缩放时机是采集的时候立即缩放还是编码时才进行缩放。例如当采集的分辨率与编码分辨率不一致时可以通过设置缩放的时机来决定预览数据与推流数据是否一致。
调用时机
此方法需要在打开摄像头之前进行设置,例如在 startPreview 开始预览、joinChannel 加入频道之前进行设置。
参数说明
参数 | 类型 | 描述 |
mode | AliRtcCapturePipelineScaleMode | 控制采集缩放时机的模式,默认是采集的时候立即缩放。 |
返回说明
无。
setExternalVideoSource
启用外部视频输入源。
public abstract void setExternalVideoSource(boolean enable,boolean useTexture,
AliRtcVideoTrack streamType,AliRtcRenderMode renderMode);
参数说明
参数 | 类型 | 描述 |
enable | boolean | 启用外部视频输入源,取值:
|
useTexture | boolean | 是否使用texture模式,取值:
|
type | 视频流类型。 | |
renderMode | 渲染模式。 |
pushExternalVideoFrame
输入视频数据。
public abstract int pushExternalVideoFrame(AliRtcRawDataFrame aliRawDataFrame,AliRtcVideoTrack streameType);
参数说明
参数 | 类型 | 描述 |
aliRawDataFrame | 帧数据。 | |
streameType | 视频流类型。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
startPublishLiveStream
开启旁路直播。
public abstract int startPublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);
参数说明
参数 | 类型 | 描述 |
streamUrl | String | 推流地址。 |
transcodingParam | 推流参数。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
updatePublishLiveStream
更新旁路直播相关参数。
public abstract int updatePublishLiveStream(String streamUrl,AliRtcLiveTranscodingParam transcodingParam);
参数说明
参数 | 类型 | 描述 |
streamUrl | String | 推流地址。 |
transcodingParam | 推流参数。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
stopPublishLiveStream
停止旁路直播。
public abstract int stopPublishLiveStream(String streamUrl);
参数说明
参数 | 类型 | 描述 |
streamUrl | String | 推流地址。 |
返回说明
0表示方法调用成功,其他表示方法调用失败。
getPublishLiveStreamState
获取旁路直播状态。
public abstract AliRtcEngine.AliRtcLiveTranscodingState getPublishLiveStreamState(String streamUrl);
参数说明
参数 | 类型 | 说明 |
streamUrl | String | 旁路直播推流地址。 |
返回说明
返回旁路直播状态。
startNetworkQualityProbeTest
开启网络质量探测。
public abstract int startNetworkQualityProbeTest(AlirtcNetworkQualityProbeConfig config);
参数说明
参数 | 类型 | 说明 |
config | AlirtcNetworkQualityProbeConfig | 探测配置的参数。 |
返回说明
0表示成功,其他表示失败。
stopNetworkQualityProbeTest
停止网络质量探测。
public abstract int stopNetworkQualityProbeTest();
返回说明
0表示成功,其他表示失败。
sendMediaExtensionMsg
发送媒体扩展信息。
public abstract int sendMediaExtensionMsg(byte[]message, int repeatCount, int delay, boolean isKeyFrame);
SDK提供了发送和接收媒体扩展信息的功能,当前方法实现了发送媒体扩展信息的功能,内部使用SEI扩展协议来实现。接收方可通过监听onMediaExtensionMsgReceived 获取信息。
常见使用场景包括:
使用媒体扩展信息传递时间戳,计算端到端的网络延迟,或者跟自身其他业务做数据同步
使用媒体扩展信息传递描述信息。目前可以传递最多 4k Byte数据,可以用来传输少量数据,建议使用Json或者纯字符串
调用时机
在开始推流后调用。
调用限制
使用媒体扩展信息时需要复用音视频数据通道,因此必须控制自定义消息的发送频率和消息数据长度,使用限制如下:
每秒最多发送profile 中设置的 fps 条消息,因为sei信息是放到h264/h265流中传输,有视频帧编码才能附加扩展信息;
为了不影响媒体数据的传输质量,自定义消息体长度限制为4k Byte,可以用来传输少量信息;
sendMediaExtensionMsg函数中repeatCount参数为自定义消息冗余度,若大于1,则会发送多次,
防止网络丢包导致的消息丢失,此时房间里的其他人也会收到多次相同的消息,需要去重;
发送的自定义消息,在旁路直播时,房间里的订阅者也一样会收到
同一时间只有一条MediaExtensionMsg在传输,多次调用sendMediaExtensionMsg,新调用的数据会覆盖前一次的数据。
相关回调
当推流方发送了媒体扩展信息后,拉流方可通过监听onMediaExtensionMsgReceived 回调获取信息。
参数说明
参数 | 类型 | 描述 |
message | byte[] | 媒体扩展信息,长度限制为最大4K字节。 |
repeatCount | int | 重复次数,代表消息冗余度,用于防止网络丢包导致的消息丢失,-1为无限传输。 |
delay | int | 延迟,单位毫秒,调用API后,最短多少毫秒发送扩展信息。 |
isKeyFrame | boolean | 是否只有关键帧才使用扩展信息 true表示只有关键帧才附加扩展信息。 |
返回说明
0:调用成功。
<0:调用失败,返回错误码。
ERR_INNER(-1): SDK内部错误,可能的情况为SDK未初始化或者SDK销毁后调用。
sendMediaExtensionMsgEx
发送媒体扩展信息。
public abstract int sendMediaExtensionMsgEx(byte[]message, int repeatCount, int delay, boolean isKeyFrame, int payloadType);
SDK提供了发送和接收媒体扩展信息的功能,当前方法实现了发送媒体扩展信息的功能,内部使用SEI扩展协议来实现。接收方可通过监听onMediaExtensionMsgReceived 获取信息。当payloadType 为 5 时等于使用sendMediaExtensionMsg 接口。
常见使用场景包括:
使用媒体扩展信息传递时间戳,计算端到端的网络延迟,或者跟自身其他业务做数据同步
使用媒体扩展信息传递描述信息。目前可以传递最多 4k Byte数据,可以用来传输少量数据,建议使用JSON或者纯字符串
调用时机
在开始推流后调用。
调用限制
使用媒体扩展信息时需要复用音视频数据通道,因此必须控制自定义消息的发送频率和消息数据长度,使用限制如下:
每秒最多发送profile 中设置的 fps 条消息,因为sei信息是放到h264/h265流中传输,有视频帧编码才能附加扩展信息;
为了不影响媒体数据的传输质量,自定义消息体长度限制为4k Byte,可以用来传输少量信息;
sendMediaExtensionMsg函数中repeatCount参数为自定义消息冗余度,若大于1,则会发送多次,
防止网络丢包导致的消息丢失,此时房间里的其他人也会收到多次相同的消息,需要去重;
发送的自定义消息,在旁路直播时,房间里的订阅者也一样会收到
同一时间只有一条MediaExtensionMsg在传输,多次调用sendMediaExtensionMsg,新调用的数据会覆盖前一次的数据。
参数说明
参数 | 类型 | 描述 |
message | byte[] | 媒体扩展信息,长度限制为最大4K字节。 |
repeatCount | int | 重复次数,代表消息冗余度,用于防止网络丢包导致的消息丢失,-1为无限传输。 |
delay | int | 延迟,单位毫秒,调用API后,最短多少毫秒发送扩展信息。 |
isKeyFrame | boolean | 是否只有关键帧才使用扩展信息 true表示只有关键帧才附加扩展信息。 |
payloadType | int | [5, 100..254]范围 payloadType=5等于使用sendMediaExtensionMsg 接口。 |
返回说明
0:调用成功。
<0:调用失败,返回错误码。
ERR_INNER(-1): SDK内部错误,可能的情况为SDK未初始化或者SDK销毁后调用。
onConnectionStatusChange
网络链接状态回调;客户需要关心此回调。
public void onConnectionStatusChange(AliRtcEngine.AliRtcConnectionStatus status,
AliRtcEngine.AliRtcConnectionStatusChangeReason reason);
参数说明
参数 | 类型 | 描述 |
status | 当前网络链接状态。 | |
reason | 网络链接状态改变原因。 |
OnLocalDeviceException
本地设备异常回调;客户需要关心此回调。
public void OnLocalDeviceException(AliRtcEngine.AliRtcEngineLocalDeviceType deviceType, AliRtcEngine.AliRtcEngineLocalDeviceExceptionType exceptionType, String msg)
参数说明
参数 | 类型 | 描述 |
deviceType | AliRtcEngineLocalDeviceType | 设备类型 |
exceptionType | AliRtcEngineLocalDeviceExceptionType | 设备异常类型 |
msg | String | 异常时携带的信息 |
onAuthInfoWillExpire
用户鉴权信息即将过期通知,收到后30秒鉴权过期;客户需要关心此回调。
public void onAuthInfoWillExpire();
该回调表示用户的鉴权信息即将失效,收到此回调后 30 秒鉴权过期,你需要重新获取新的 Token,然后通过下列任意一种方式更新鉴权信息:
调用
refreshAuthInfo
接口更新鉴权信息。调用
leaveChannel
离开当前频道,然后再调用joinChannel
重新加入频道。
触发时机
SDK 会在用户鉴权信息过期前 30s 触发此回调,收到该回调后应该及时更新鉴权信息。
onAuthInfoExpired
用户调用需要鉴权的接口,服务端返回信息过期。
public void onAuthInfoExpired();
该回调表示用户鉴权信息已过期,如果想继续在会中,需要在服务端生成新的 Token,然后通过下列方法更新鉴权信息:
调用
leaveChannel
离开当前频道,然后再调用joinChannel
重新加入频道。
触发时机
当用户鉴权信息过期时会触发此回调。
onJoinChannelResult
加入频道结果回调。
public void onJoinChannelResult(int result, String channel, String userId, int elapsed);
参数说明
参数 | 类型 | 描述 |
result | int | 加入频道结果,成功返回0;失败返回错误码,详情请参见错误码列表,下面为一些常见错误码:
|
channel | String | 频道ID。 |
userId | String | 用户ID。 |
elapsed | int | 加入频道耗时。单位:毫秒。 |
onLeaveChannelResult
离开频道结果回调。
public void onLeaveChannelResult(int result, AliRtcEngine.AliRtcStats stats);
触发条件
当应用成功调用leaveChannel
离会时会触发此回调返回离会的结果和本次频道会话的统计信息。
如果leaveChannel
后直接调用destroy
销毁引擎则不会触发此回调。
参数说明
参数 | 类型 | 描述 |
result | int | 离开频道结果,成功返回0,失败返回错误码。 |
stats | 本次频道内会话的数据统计汇总。 |
onRemoteUserOffLineNotify
远端用户下线回调。
public void onRemoteUserOffLineNotify(String uid, AliRtcUserOfflineReason reason);
该回调用于通知本地用户,远端用户因各种原因离开频道。当远端用户离线,该接口将被触发。
触发条件
当远端用户角色主动离开频道时,触发回调。
当远端主播调用
setClientRole
切换为观众角色(调用 AliRtcEngine#setClientRole 设置为 AliRTCSdkLive)时,触发回调。当长时间未收到远端主播数据并认为其掉线时,触发回调。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
reason | 用户离线的原因。 |
onRemoteUserOnLineNotify
远端用户上线回调。
public void onRemoteUserOnLineNotify(String uid, int elapsed);
该接口用于通知本地客户端远端用户加入频道。
触发条件
远端用户成功加入频道。
当前用户加入频道后,会收到频道中已有用户的加入回调,用于显示之前已加入的用户。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
elapsed | int | 用户加入频道时的耗时。单位:毫秒。 |
onRemoteTrackAvailableNotify
远端用户音视频流发生变化时回调。
public void onRemoteTrackAvailableNotify(String uid, AliRtcAudioTrack audioTrack,
AliRtcVideoTrack videoTrack);
当前回调在远端用户推流状态发生变化时触发,通过这个回调,开发者可以实时了解远端用户是否推送音频和视频流,并据此在界面上显示或隐藏远端用户的音视频信息。
该回调返回远端用户推流情况,如果需要知道本次变化哪一路流下线,请记录回调前后的状态变化。
触发条件
该回调在以下场景会被触发:
当远端用户从未推流变更为推流(包括音频和视频)
当远端用户从已推流变更为未推流(包括音频和视频)
互动模式下,远端用户调用 setClientRole 从观众切换为主播角色,同时设置了推流时,会触发该回调
以视频为例,假设远端用户设置不推流,那么不会触发此回调:
远端用户开始推送相机流(推流状态:不推视频流->仅推相机流),则本端回调返回
AliRtcVideoTrackCamera
表示远端用户相机流可用。远端用户又推送了屏幕共享流(推流状态:仅推相机流->推送相机流和屏幕共享流),则本端回调
AliRtcVideoTrackBoth
表示远端用户相机流和屏幕共享流均可用。远端用户停止推送相机流仅保留屏幕共享流(推流状态:推送相机流和屏幕共享流->仅推送屏幕共享流),则本端回调
AliRtcVideoTrackScreen
表示当前仅有屏幕共享流可用。远端用户又停止了屏幕共享流的推送(推流状态:仅推送屏幕共享流->不推视频流),则本端回调
AliRtcVideoTrackNo
表示当前无视频流可用。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
audioTrack | 远端用户发生变化后的音频流。 | |
videoTrack | 远端用户发生变化后的视频流。 |
onBye
被服务器踢出或者频道关闭时回调。
public void onBye(int code);
当用户因某种原因被断开或者会议结束,此回调便会被触发,开发者可以根据回调参数 code
来得知被断开的原因并作出相应处理。
触发条件
当前用户被服务器踢出。
会议结束(服务器主动移除频道)。
被动离开,需要客户端尝试恢复会话或重新连接。
参数说明
参数 | 类型 | 描述 |
code | int | onBye类型,更多信息,请参见AliRtcOnByeType。 |
onAudioPublishStateChanged
音频推流变更回调。
public void onAudioPublishStateChanged(AliRtcEngine.AliRtcPublishState oldState ,
AliRtcEngine.AliRtcPublishState newState,
int elapseSinceLastState, String channel);
该回调用于监听本地用户音频流推流状态变化。
触发条件
当用户的音频推流状态发生变化时,例如:
停止推流。
调用
setClientRole
切换为观众。
参数说明
参数 | 类型 | 描述 |
oldState | 之前的推流状态。 | |
newState | 当前的推流状态。 | |
elapseSinceLastState | int | 状态变更时间间隔。单位:毫秒。 |
channel | String | 当前频道ID。 |
onAudioSubscribeStateChanged
音频订阅情况变更回调。
public void onAudioSubscribeStateChanged(String uid,
AliRtcEngine.AliRtcSubscribeState oldState,
AliRtcEngine.AliRtcSubscribeState newState,
int elapseSinceLastState, String channel);
该回调用于通知本地用户远端用户音频流订阅状态发生变化。通过该回调,可以获知某个远端用户相机流的订阅状态变化,以及从上一状态到当前状态的时间间隔。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
oldState | 之前的订阅状态。 | |
newState | 当前的订阅状态。 | |
elapseSinceLastState | int | 状态变更时间间隔。单位:毫秒。 |
channel | String | 当前频道ID。 |
onUserAudioMuted
对端用户停止音频数据发送通知。
public void onUserAudioMuted(String uid ,boolean isMute);
参数说明
参数 | 类型 | 描述 |
uid | String | 执行muteAudio的用户。 |
isMute | boolean | 是否静音,取值:
|
onUserAudioInterruptedBegin
用户音频被中断通知。
public void onUserAudioInterruptedBegin(String uid);
参数说明
参数 | 类型 | 描述 |
uid | String | audio被中断的用户。 |
onUserAudioInterruptedEnded
用户音频中断结束通知。
public void onUserAudioInterruptedEnded(String uid);
参数说明
参数 | 类型 | 描述 |
uid | String | audio被中断的用户。 |
onVideoPublishStateChanged
视频推流变更回调。
public void onVideoPublishStateChanged(AliRtcEngine.AliRtcPublishState oldState ,
AliRtcEngine.AliRtcPublishState newState,
int elapseSinceLastState, String channel);
该回调用于监听本地用户视频推流状态的变化。
参数说明
参数 | 类型 | 描述 |
oldState | 之前的推流状态。 | |
newState | 当前的推流状态。 | |
elapseSinceLastState | int | 状态变更时间间隔。单位:毫秒。 |
channel | String | 当前频道ID。 |
onVideoSubscribeStateChanged
相机流订阅情况变更回调。
public void onVideoSubscribeStateChanged(String uid,
AliRtcEngine.AliRtcSubscribeState oldState,
AliRtcEngine.AliRtcSubscribeState newState,
int elapseSinceLastState, String channel);
该回调用于通知本地用户远端用户相机流订阅状态发生变化。通过该回调,可以获知某个远端用户相机流的订阅状态变化,以及从上一状态到当前状态的时间间隔。
相关回调
视频流主要包含相机流和屏幕共享流,本接口为相机流的订阅状态变化,屏幕共享流的相关回道接口为onScreenShareSubscribeStateChanged
。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
oldState | 之前的订阅状态。 | |
newState | 当前的订阅状态。 | |
elapseSinceLastState | int | 状态变更时间间隔。 |
channel | String | 当前频道ID。 |
onUserVideoMuted
对端用户发送视频黑帧数据发送通知。
public void onUserVideoMuted(String uid, boolean isMute);
参数说明
参数 | 类型 | 描述 |
uid | String | 执行enableLocalVideo的用户。 |
isMute | boolean | 是否发送黑帧,取值:
|
onUserVideoEnabled
对端用户关闭相机流采集发送通知。
public void onUserVideoEnabled(String uid, boolean isMute);
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户ID。 |
isMute | boolean | 是否开启相机流采集,取值:
|
onUserWillResignActive
远端用户应用退到后台。
public void onUserWillResignActive(String uid);
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID。 |
onUserWillBecomeActive
远端用户应用返回前台。
public void onUserWillBecomeActive(String uid);
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID。 |
onAliRtcStats
当前会话统计信息回调。SDK每两秒触发一次此统计信息回调。
public void onAliRtcStats(AliRtcEngine.AliRtcStats stats);
参数说明
参数 | 类型 | 描述 |
stats | 会话统计信息。 |
onAudioEffectFinished
本地音效播放结束回调。
void OnAudioEffectFinished(int soundId);
参数说明
参数 | 类型 | 描述 |
soundId | int | 用户给该音效文件分配的ID。 |
onAudioFileInfo
音频文件信息回调。
public void onAudioFileInfo(AliRtcEngine.AliRtcAudioFileInfo info, AliRtcEngine.AliRtcAudioAccompanyErrorCode errorCode);
当用户调用getAudioFileInfo 获取音频文件信息时,会触发此回调,向用户展示音频文件的时长等信息或者错误信息。
参数说明
参数 | 类型 | 描述 |
info | AliRtcEngine.AliRtcAudioFileInfo | 音频文件的信息,包含文件路径和时长。 |
errorCode | AliRtcEngine.AliRtcAudioAccompanyErrorCode | 音频伴奏错误码,主要包含文件打开失败或文件解码失败。 |
onMediaExtensionMsgReceived
收到媒体扩展信息回调。
public void onMediaExtensionMsgReceived(String uid, int payloadType, byte[]message);
当一端通过 sendMediaExtensionMsg发送信息后,其他端通过该回调接收数据。
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID,媒体信息发送用户的ID。 |
payloadType | int | payload类型,sendMediaExtensionMsg返回5,sendMediaExtensionMsgEx发送的会返回具体类型。 |
message | byte[] | 媒体扩展信息。 |
onFirstRemoteVideoFrameDrawn
远端用户的第一帧视频帧显示时触发这个消息。
public void onFirstRemoteVideoFrameDrawn(String uid,AliRtcVideoTrack videoTrack, int width, int height, int elapsed);
本接口是远端视频首帧渲染的回调,用于在本地用户成功接收到远端用户的第一个视频帧并完成渲染时触发通知。此回调可帮助开发者监控远端视频链路的建立时间、评估网络与设备性能,并优化用户体验。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
videoTrack | 接收视频流类型。 | |
width | int | 拉流视频宽度。 |
height | int | 拉流视频高度。 |
elapsed | int | 从本地用户加入频道直至显示拉流视频第一帧的延迟总耗时(毫秒)。 |
onFirstLocalVideoFrameDrawn
预览开始显示第一帧视频帧时触发这个消息。
public void onFirstLocalVideoFrameDrawn(int width, int height, int elapsed);
该接口是本地视频预览显示首帧的回调,用于在本地用户开启摄像头后,首次渲染本地视频帧时触发通知。此回调可帮助开发者监控本地视频预览的建立速度、评估设备性能,并优化用户体验(如提示“摄像头已就绪”或调整预览布局)。
参数介绍
参数 | 类型 | 描述 |
width | int | 本地预览视频宽度。 |
height | int | 本地预览视频高度。 |
elapsed | int | 从本地用户加入频道直至本地预览显示第一帧的延迟总耗时(毫秒)。 |
onFirstVideoFrameReceived
收到远端用户视频首帧的回调。
public void onFirstVideoFrameReceived(String uid, AliRtcVideoTrack videoTrack, int timeCost);
该接口是接收远端视频首帧的回调,在本地用户成功接收到远端用户的第一个视频帧时触发通知。此回调可帮助开发者监控视频链路的建立时间、评估网络质量,并优化用户体验(如提示“视频已就绪”或调整播放逻辑)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
videoTrack | 接收视频流类型。 | |
timeCost | int | 发送耗时,从入会开始到视频首包发送出去的耗时(单位:毫秒)。 |
onFirstVideoPacketSent
视频首包发送回调。
public void onFirstVideoPacketSent(String uid, AliRtcVideoTrack videoTrack, int timeCost);
该接口是本地视频首包发送的回调,在本地用户成功发送第一个视频数据包时触发通知。此回调可帮助开发者监控视频发送链路建立速度、评估本地设备性能,并优化用户体验(如提示“视频已发送”或调整采集策略)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
videoTrack | 接收视频流类型。 | |
timeCost | int | 发送耗时,从入会开始到视频首包发送出去的耗时(单位:毫秒)。 |
onFirstAudioPacketSent
音频首包发送回调。
public void onFirstAudioPacketSent(String uid, AliRtcAudioTrack track, int timeCost);
本接口用于本地音频首包发送的回调,在本地用户成功发送第一个音频数据包时触发通知。此回调可帮助开发者监控音频发送链路建立速度、评估本地设备及系统性能,并优化用户体验。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
track | 接收音频流类型。 | |
timeCost | int | 发送耗时,从入会开始到音频首包发送出去的耗时(单位:毫秒)。 |
onFirstVideoPacketReceived
视频首包接收回调。
public void onFirstVideoPacketReceived(String uid, AliRtcVideoTrack videoTrack, int timeCost)
该接口是远端视频首包接收的回调,在本地用户接收到远端用户的第一个视频数据包时触发通知。开发者可用该回调来监控视频链路建立速度或更新播放流的 UI 组件。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
videoTrack | 接收视频流类型。 | |
timeCost | int | 从本地用户加入频道到接收视频首包的耗时(单位:毫秒)。 |
onFirstAudioPacketReceived
音频首包接收回调。
public void onFirstAudioPacketReceived(String uid, AliRtcAudioTrack track, int timeCost)
该接口是远端音频首包接收的回调,在本地用户接收到远端用户的第一个音频数据包时触发通知。此回调可帮助开发者监控音频链路建立速度、评估网络质量,并优化用户体验(如提示“音频已连接”或调整播放策略)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
track | 接收音频流类型。 | |
timeCost | int | 从本地用户加入频道到接收音频首包的耗时(单位:毫秒)。 |
onFirstRemoteAudioDecoded
已解码远端音频首帧回调。
public void onFirstRemoteAudioDecoded(String uid, AliRtcAudioTrack track, int elapsed)
该接口是拉取远端音频流并解码完成首帧的回调,用于通知开发者远端用户的音频流已成功解码并可正常播放,开发者可利用该回调来统计首帧耗时或更新播放流的 UI 组件。
参数介绍
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
track | 接收音频流类型。 | |
elapsed | int | 从本地用户加入频道到音频首帧解码完成的延迟时间(单位:毫秒)。 |
onAudioAccompanyStateChanged
本地伴奏播放状态回调。
public void onAudioAccompanyStateChanged(AliRtcEngine.AliRtcAudioAccompanyStateCode playState, AliRtcEngine.AliRtcAudioAccompanyErrorCode errorCode);
该回调是本地伴奏播放状态变化的回调,用于实时通知开发者当前伴奏的播放状态(如开始、暂停、结束)及可能的错误码。开发者可通过此回调监控播放进度、处理异常并更新用户界面。
参数介绍
参数 | 类型 | 描述 |
playState | AliRtcEngine.AliRtcAudioAccompanyStateCode | 伴奏播放状态。 |
errorCode | AliRtcEngine.AliRtcAudioAccompanyErrorCode | 播放错误码,主要为打开文件错误和解码文件错误。 |
onRemoteAudioAccompanyStarted
远端用户伴奏播放开始回调。
public void onRemoteAudioAccompanyStarted(String uid);
该接口是远端用户伴奏播放开始的回调,用于在远端用户的音频伴奏(如背景音乐等)开始播放时通知本地应用。开发者可通过此回调执行初始化逻辑(如更新 UI、调整音量、通知其他用户等)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 伴奏播放开始的远端用户 ID。 |
onRemoteAudioAccompanyFinished
远端用户伴奏播放结束回调。
public void onRemoteAudioAccompanyFinished(String uid);
本接口是远端用户伴奏播放结束的回调,用于在远端用户的音频伴奏(如背景音乐、音效等)播放完成后通知本地应用。开发者可通过此回调执行后续逻辑(如提示用户、更新状态等)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 伴奏播放结束的远端用户 ID。 |
onVideoResolutionChanged
远端视频分辨率变化。
public void onVideoResolutionChanged(String uid,AliRtcVideoTrack videoTrack, int width, int height);
该接口是远端视频分辨率变化的通知回调,用于在远端用户的视频流分辨率发生改变时(如切换摄像头、调整清晰度、网络波动导致分辨率下降等)触发事件。开发者可通过此回调动态调整本地视频渲染逻辑(如 UI 布局、画布缩放、性能优化等)。
参数介绍
参数 | 类型 | 描述 |
uid | String | 分辨率发生变化的远端用户 ID。 |
videoTrack | 视频流类型,如相机流、屏幕流。 | |
width | int | 新的视频分辨率宽度。 |
height | int | 新的视频分辨率高度。 |
onRtcLocalVideoStats
发布本地视频流的数据统计。
public void onRtcLocalVideoStats(AliRtcEngine.AliRtcLocalVideoStats aliRtcStats);
该接口是本地视频流数据统计的回调,用于实时获取本地视频的编码和传输状态(如码率、帧率等)。开发者可通过此回调监控视频质量、诊断性能问题或动态调整编码参数。
参数介绍
参数 | 类型 | 描述 |
aliRtcStats | AliRtcEngine.AliRtcLocalVideoStats | 本地推送视频的统计信息,包含发布比特率、帧率等信息,详细请参考AliRtcLocalVideoStats。 |
onRtcRemoteVideoStats
订阅远端视频流的数据统计。
public void onRtcRemoteVideoStats(AliRtcEngine.AliRtcRemoteVideoStats aliRtcStats);
该接口是拉取远端视频流数据统计的回调,用于实时获取远端视频的编码和传输状态(如码率、帧率、分辨率、延迟、卡顿情况等)。开发者可通过此回调监控视频质量、诊断性能问题或动态调整解码参数。
参数介绍
参数 | 类型 | 描述 |
aliRtcStats | AliRtcEngine.AliRtcRemoteVideoStats | 拉取远端视频的统计信息,包含远端用户 ID、视频分辨率、帧率、卡顿次数等信息。详细请参考AliRtcRemoteVideoStats。 |
onRtcRemoteAudioStats
订阅远端音频流的数据统计。
public void onRtcRemoteAudioStats(AliRtcEngine.AliRtcRemoteAudioStats aliRtcStats);
该接口是订阅远端音频流数据统计的回调,用于实时获取远端用户的音频质量状态(如音质、丢包率、延迟等)。开发者可通过此回调监控远端音频链路的稳定性、诊断网络问题,并动态调整播放策略(如启用降噪或提示用户优化网络)。
参数介绍
参数 | 类型 | 描述 |
aliRtcStats | AliRtcEngine.AliRtcRemoteAudioStats | 拉取远端音频的统计信息,包含远端用户 ID、音质、丢包率、卡顿次数、延迟等信息,详细的介绍请参考AliRtcRemoteAudioStats。 |
onRtcLocalAudioStats
发布本地音频流数据统计。
public void onRtcLocalAudioStats(AliRtcEngine.AliRtcLocalAudioStats aliRtcStats);
该接口是本地音频推流数据统计的回调,用于实时获取本地音频的编码和传输状态(如码率、采样率、声道数、丢包率等)。开发者可通过此回调监控本地音频链路的稳定性、诊断性能问题,并动态调整编码策略(如降低码率等)。
参数介绍
参数 | 类型 | 描述 |
aliRtcStats | AliRtcEngine.AliRtcLocalAudioStats | 本地推送音频统计信息,包括音频流类型、发送码率、发送的采样率、声道数,详细介绍请参考AliRtcLocalAudioStats。 |
onAudioFocusChange
音频焦点变化回调(仅适用于Android平台)。
public void onAudioFocusChange(int focusChange);
音频焦点变化的结果通知,SDK内部默认会自动请求音频焦点,如外部再次使用音频焦点需要在收到SDK改变的回调中再次请求。
通知时机
当音频输出设备状态变化时触发(如插入/拔出耳机、切换蓝牙设备、切换听筒/扬声器等)。
参数说明
参数 | 类型 | 描述 |
focusChange | int | 焦点状态类型,取值与 android.media.AudioManager 焦点类型定义相同。 |
onAudioRouteChanged
音频路由发生变化回调(仅适用于Android、iOS平台)
public void onAudioRouteChanged(AliRtcEngine.AliRtcAudioRouteType routing);
该回调是音频路由变更通知回调,用于检测设备音频输出路径的变化(如耳机插入、扬声器切换等)。该回调仅适用于 Android 和 iOS 平台,开发者可通过此回调动态调整音频输出策略(如切换麦克风模式、调整音量等)。
参数说明
参数 | 类型 | 描述 |
routing | AliRtcEngine.AliRtcAudioRouteType | 当前使用的音频路由。 |
onRemoteUserSubscribedDataChannel
可以开始发送data channel消息回调。
public void onRemoteUserSubscribedDataChannel(String uid);
当前接口是当远端用户订阅了 Data Channel 时触发的回调。此回调通知本地用户,当前指定的远端用户已准备好接收自定义消息,开发者可以在此时安全地调用 sendDataChannelMsg 向其发送数据。该回调是确保消息可靠传递的关键机制,避免在目标用户未订阅 Data Channel 时发送消息导致丢包或失败。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
onDataChannelMessage
data channel 自定义消息接收回调。
public void onDataChannelMessage(String uid, AliRtcEngine.AliRtcDataChannelMsg msg);
ARTC SDK提供发送和接收自定义消息的能力,允许在传输音视频数据的同时再发送自定义的实时消息数据。该回调用于接收 data channel 自定义消息。具体使用方式请参考自定义消息发送和接收。
互动场景中,主播角色可以发送和接收消息,而观众角色仅支持接收消息。
该功能默认关闭,如需开启请在创建引擎后调用
setParameter
设置{\"data\":{\"enablePubDataChannel\":true" + ",\"enableSubDataChannel\":true}}
。
触发时机
发送方调用sendDataChannelMsg 发送自定义消息后,如果接收方开启了 data channel 功能,则接收方会触发此回调。
参数说明
参数 | 类型 | 描述 |
uid | String | 发送方用户 ID。 |
msg | AliRtcEngine.AliRtcDataChannelMsg | 接收到的自定义消息。 |
onAudioVolume
订阅的音频音量,语音状态和uid。
public void onAudioVolume(List<AliRtcEngine.AliRtcAudioVolume> speakers, int totalVolume);
该回调默认禁用,可通过调用enableAudioVolumeIndication
接口开启。开启后,只要频道内有推流的用户,SDK 会在加入频道后按照enableAudioVolumeIndication
设定的时间间隔触发本回调,回调结果包含本地和远端说话人音量信息。
参数说明
参数 | 类型 | 描述 |
speakers | List<AliRtcEngine.AliRtcAudioVolume> | 回调用户音量信息数组,包含用户uid、语音状态以及音量。 当uid为0时表示本地说话人。 |
totalVolume | int | 混音后的总音量,取值范围:[0,255]。 在本地用户的回调中,totalVolume为本地用户混音后的音量;在远端用户的回调中,totalVolume为所有说话者混音后的总音量。 |
onActiveSpeaker
订阅当前正在说话的人。
public void OnActiveSpeaker(String uid);
成功调用 enableAudioVolumeIndication
后,SDK 会持续监测音量最大的远端用户,并统计该用户被判断为音量最大者的次数。当前时间段内,该次数累积最多的远端用户为最活跃的用户。
触发条件
当频道内用户数量大于或等于 2 且有远端活跃用户时,SDK 会触发该回调并报告远端最活跃用户的 uid。
如果远端最活跃用户一直是同一位用户,则 SDK 不会再次触发
onActiveSpeaker
回调。如果远端最活跃用户有变化,则 SDK 会再次触发该回调并报告新的远端最活跃用户的 uid。
参数说明
参数 | 类型 | 描述 |
uid | String | 说话人的uid,当uid为0时表示本地说话人。其返回的是当前时间段内声音最大的用户ID,而不是瞬时声音最大的用户ID。 |
OnTestAudioVolume
通话前检测,音量信息回调。
public void OnTestAudioVolume(int volume);
进行通话前检测时,采集设备的音量信息回调,用于测试本地音频采集设备是否正常工作。用户调用startAudioCaptureTest 进行通话前音频设备检测时会触发。
参数说明
参数 | 类型 | 描述 |
volume | int | 音量值。 |
onCapturedAudioFrame
采集裸数据回调。
boolean onCapturedAudioFrame(AliRtcAudioFrame frame);
当前回调用于获取当前设备采集的原始音频数据。默认关闭,为了获取该音频数据:
通过enableAudioFrameObserver(true,audioSource,config) 中的 audioSource开启当前回调。此外,config 参数可以设置获取音频数据的采样率和声道数、读写模式等。
调用registerAudioFrameObserver 注册音频数据接收对象。
本接口支持设置采样率、声道数及读写模式。
调用限制
请不要在此回调函数中做任何耗时操作,否则可能导致声音异常。
参数说明
参数 | 类型 | 说明 |
frame | 音频数据。 |
返回说明
true:成功。
false:失败。
onProcessCapturedAudioFrame
3A后数据回调
boolean onProcessCapturedAudioFrame(AliRtcAudioFrame frame);
当前回调用于获取经过 3A 处理后的音频数据。默认关闭,为了获取该音频数据:
通过enableAudioFrameObserver(true,audioSource,config) 中的 audioSource开启当前回调。此外,config 参数可以设置获取音频数据的采样率和声道数、读写模式等。
调用registerAudioFrameObserver 注册音频数据接收对象。
本接口支持设置采样率、声道数及读写模式。
调用限制
请不要在此回调函数中做任何耗时操作,否则可能导致声音异常。
参数说明
参数 | 类型 | 说明 |
frame | 音频数据。 |
返回说明
true:成功。
false:失败。
onPublishAudioFrame
推流音频数据回调
boolean onPublishAudioFrame(AliRtcAudioFrame frame);
当前回调用于获取推流的音频数据。默认关闭,为了获取该音频数据:
通过enableAudioFrameObserver(true,audioSource,config) 中的 audioSource开启当前回调。此外,config 参数可以设置获取音频数据的采样率和声道数、读写模式等。
调用registerAudioFrameObserver 注册音频数据接收对象。
本接口支持设置采样率、声道数,但只能设置为只读模式。
调用限制
请不要在此回调函数中做任何耗时操作,否则可能导致声音异常。
参数说明
参数 | 类型 | 说明 |
frame | 音频数据。 |
返回说明
true:成功。
false:失败。
onPlaybackAudioFrame
播放数据回调
boolean onPlaybackAudioFrame(AliRtcAudioFrame frame);
当前回调用于获取播放的音频数据。默认关闭,为了获取该音频数据:
通过enableAudioFrameObserver(true,audioSource,config) 中的 audioSource开启当前回调。此外,config 参数可以设置获取音频数据的采样率和声道数、读写模式等。
调用registerAudioFrameObserver 注册音频数据接收对象。
本接口支持设置采样率、声道数及读写模式。
调用限制
请不要在此回调函数中做任何耗时操作,否则可能导致声音异常。
参数说明
参数 | 类型 | 说明 |
frame | AliRtcAudioFrame | 音频数据。 |
返回说明
true:成功。
false:失败。
onRemoteUserAudioFrame
远端拉流数据回调
boolean onRemoteUserAudioFrame(String uid, AliRtcAudioFrame frame);
当前回调用于获取拉取的指定用户的远端音频数据。默认关闭,为了获取该音频数据:
通过enableAudioFrameObserver(true,audioSource,config) 中的 audioSource开启当前回调。此外,config 参数可以设置获取音频数据的采样率和声道数、读写模式等。
调用registerAudioFrameObserver 注册音频数据接收对象。
本接口不支持设置采样率、声道数,但可以设置读写模式。
调用限制
请不要在此回调函数中做任何耗时操作,否则可能导致声音异常。
参数说明
参数 | 类型 | 说明 |
uid | String | 用户 id。 |
frame | 音频数据。 |
返回说明
true:成功。
false:失败。
OnDestroyCompletion
引擎销毁完成回调。
void OnDestroyCompletion();
此回调表明sdk 引擎实例销毁完成,可以进行新一次的创建。
触发时机
当用户调用destroy[2/2]
后,引擎销毁完成后触发此回调。
onTextureCreate
OpenGL上下文创建回调。
void onTextureCreate(long context);
该回调是在SDK内部OpenGL上下文创建的时候触发。
触发条件
该回调是在SDK内部OpenGL上下文创建的时候触发,开发者可以初始化相关资源。
参数说明
参数 | 类型 | 说明 |
context | long | OpenGL 上下文。 |
onTextureUpdate
OpenGL纹理更新回调。
int onTextureUpdate(int textureId, int width, int height, AliRtcVideoSample videoSample);
触发条件
该回调会在每一帧视频数据上传到OpenGL纹理之后触发,当外部注册了OpenGL纹理数据观测器,在该回调中可以对纹理进行处理,并返回处理后的纹理ID。
参数说明
参数 | 类型 | 说明 |
textureId | int | OpenGL 上下文。 |
width | int | 视频宽度。 |
height | int | 视频高度。 |
videoSample | 视频帧数据。 |
返回说明
返回新的textureid或者老的textureid,如果返回<0的值则视为未更新textureId。
onTextureDestroy
void onTextureDestroy();
触发条件
该回调是在SDK内部OpenGL上下文销毁的时候触发,开发者清理相关资源。
onLocalVideoSample
订阅的本地采集视频数据回调。
public boolean onLocalVideoSample(AliRtcVideoSourceType sourceType, AliRtcVideoSample videoSample);
当前接口是获取本地视频采集数据的回调,用于获取本地摄像头采集的原始视频帧(如 YUV 数据)。开发者可通过此回调实现自定义视频处理逻辑(如添加滤镜、水印、转码等),并决定是否将处理后的数据返回给 SDK 用于后续编码或渲染。如果你需要将处理后的视频发送给 SDK,请返回 true。
触发时机
成功调用registerVideoSampleObserver
注册视频数据观测器后,当 SDK 捕获到对应视频帧。
参数说明
参数 | 类型 | 描述 |
sourceType | 视频源类型。 | |
videoSample | 视频数据。 |
返回说明
true:需要写回SDK(默认写回,需要操作AliRtcVideoSample.data时必须要写回)
false:不需要写回SDK(需要直接操作AliRtcVideoSample.dataFrameY、AliRtcVideoSample.dataFrameU、AliRtcVideoSample.dataFrameV时使用)
onPreEncodeVideoSample
订阅的本地编码前视频数据回调。
public boolean onPreEncodeVideoSample(AliRtcVideoSourceType sourceType, AliRtcVideoSample videoRawData);
当前接口是获取本地视频编码前数据的回调,用于在 SDK 对视频帧进行编码前获取原始视频数据(如 YUV 格式)。开发者可通过此回调实现自定义处理逻辑(如添加水印、调整色彩、转码等),并决定是否将处理后的数据返回给 SDK 用于后续编码。
参数说明
参数 | 类型 | 描述 |
sourceType | 视频流类型 | |
videoRawData | 视频裸数据 |
返回说明
true:需要写回SDK(默认写回,需要操作AliRtcVideoSample.data时必须要写回)
false:不需要写回SDK(需要直接操作AliRtcVideoSample.dataFrameY、AliRtcVideoSample.dataFrameU、AliRtcVideoSample.dataFrameV时使用)
onRemoteVideoSample
订阅的远端视频数据回调。
public boolean onRemoteVideoSample(String callId,AliRtcVideoSourceType sourceType, AliRtcVideoSample videoSample);
当前接口是获取订阅的远端视频数据的回调,用于获取远端用户的原始视频帧数据(如 YUV 格式),开发者可通过此回调实现自定义处理逻辑(如添加滤镜、水印、转码等),并决定是否将处理后的数据返回给 SDK 用于后续渲染。
参数说明
参数 | 类型 | 描述 |
callId | String | 用户ID |
sourceType | 视频流类型 | |
videoSample | 视频裸数据 |
返回说明
true:需要写回SDK(默认写回,需要操作AliRtcVideoSample.data时必须要写回)
false:不需要写回SDK(需要直接操作AliRtcVideoSample.dataFrameY、AliRtcVideoSample.dataFrameU、AliRtcVideoSample.dataFrameV时使用)。
onGetVideoFormatPreference
视频数据输出格式
public AliRtcVideoFormat onGetVideoFormatPreference();
返回说明
期望的视频输出格式。
onGetObservedFramePosition
视频数据输出内容。
public int onGetObservedFramePosition();
该接口是用于获取视频数据输出内容或者说类型的回调,开发者可通过此回调获取 SDK 输出视频帧的处理阶段(如采集后、编码前、拉流后等)。
返回说明
期望视频输出内容,类型为AliRtcVideoObserPosition 的枚举值,表示采集数据、拉流数据、编码前数据。
onPublishLiveStreamStateChanged
旁路推流状态改变回调。
public void onPublishLiveStreamStateChanged(String streamUrl, AliRtcLiveTranscodingState state, AliEngineLiveTranscodingErrorCode errorCode);
参数说明
参数 | 类型 | 描述 |
streamUrl | String | 推流地址。 |
state | 旁路直播状态。 | |
errorCode | 错误码。 |
onPublishTaskStateChanged
旁路任务状态改变回调。
public void onPublishTaskStateChanged(String streamUrl, AliRtcTrascodingPublishTaskStatus state);
参数说明
参数 | 类型 | 描述 |
streamUrl | String | 推流地址。 |
state | 旁路直播推流任务状态。 |
onNetworkQualityChanged
网络质量变化回调。
public void onNetworkQualityChanged(String uid, AliRtcNetworkQuality upQuality, AliRtcNetworkQuality downQuality);
参数说明
参数 | 类型 | 描述 |
uid | String | 用户ID,为空时表示本地用户上下行网络状态。 |
upQuality | 上行网络状态。 | |
downQuality | 下行网络状态。 |
onNetworkQualityProbeTest
网络质量探测的回调,开始探测3秒左右提供该回调。
public void onNetworkQualityProbeTest(AliRtcNetworkQuality quality){}
参数说明
参数 | 类型 | 描述 |
quality | 网络质量。 |
onNetworkQualityProbeTestResult
网络质量探测的结果回调,探测30秒左右提供该回调。
public void onNetworkQualityProbeTestResult(int code, AliRtcEngine.AlirtcNetworkQualityProbeResult result){}
参数说明
参数 | 类型 | 描述 |
code | int | 返回值,0 表示探测成功,-1表示探测失败,网络状况较差导致断开链接。 |
result | 网络质量。 |
onSnapshotComplete
截图结果回调接口。
public void onSnapshotComplete(String userId, AliRtcVideoTrack trackType, Bitmap bitmap, boolean success)
该接口用于通知截图的结果和截图的详情。
参数说明
参数 | 类型 | 描述 |
userId | String | 用户ID。 |
trackType | 截图视频流类型。 | |
bitmap | Bitmap | 截图数据。 |
success | boolean | 截图是否成功。 |
onScreenSharePublishStateChanged
屏幕分享推流变更回调。
public void onScreenSharePublishStateChanged(AliRtcEngine.AliRtcPublishState oldState , AliRtcEngine.AliRtcPublishState newState, int elapseSinceLastState, String channel)
当前回调是屏幕分享推流状态变更的通知,用于在屏幕分享推流状态发生变化时触发通知。
参数说明
参数 | 类型 | 描述 |
oldState | AliRtcEngine.AliRtcPublishState | 推流状态变更前的旧状态。 |
newState | AliRtcEngine.AliRtcPublishState | 推流状态变更后的新状态。 |
elapseSinceLastState | int | 状态变更时间间隔(毫秒)。 |
channel | String | 当前所属频道名称。 |
onScreenShareSubscribeStateChanged
屏幕分享流订阅情况变更回调。
public void onScreenShareSubscribeStateChanged(String uid,
AliRtcEngine.AliRtcSubscribeState oldState,
AliRtcEngine.AliRtcSubscribeState newState,
int elapseSinceLastState, String channel);
当前回调为屏幕分享流订阅情况变更通知,当前用户对远端用户的屏幕共享流的订阅状态发生变化时触发此回调。
参数说明
参数 | 类型 | 描述 |
uid | String | 远端用户 ID。 |
oldState | AliRtcEngine.AliRtcSubscribeState | 之前的订阅状态。 |
newState | AliRtcEngine.AliRtcSubscribeState | 当前的订阅状态。 |
elapseSinceLastState | int | 状态变更时间间隔(毫秒)。 |
channel | String | 当前频道。 |
onOccurError
错误通知。
public void onOccurError(int error, String message);
ARTC SDK 的全局错误通知回调,用于在 SDK 内部引擎发生严重错误时通知应用层。开发者可通过此回调获取错误码和错误信息,进行异常处理、日志记录或用户提示。
参数说明
参数 | 类型 | 描述 |
error | int | 错误类型。参考错误码列表。 |
message | String | 错误消息。 |
OnLocalAudioStateChanged
本地音频设备状态回调。
public void OnLocalAudioStateChanged(int state);
当本地的音频采集设备状态发生变化时会触发此回调。例如调用startAudioCapture 开始音频采集或者调用stopAudioCapture 停止音频采集。
参数说明
参数 | 类型 | 描述 |
state | int |
|
setParameter
设置自定义参数
public abstract int setParameter(String param);
参数说明
参数 | 类型 | 描述 |
param | String | 自定义参数。 |
getParameter
获取自定义参数。
public abstract String getParameter(String param);
参数说明
参数 | 类型 | 描述 |
param | String | 自定义参数。 |
registerAudioVolumeObserver
注册音量数据输出对象。
public abstract void registerAudioVolumeObserver(AliRtcAudioVolumeObserver observer);
本接口用于注册音量数据输出对象。如果需要取消注册,请调用unRegisterAudioVolumeObserver
。
调用时机
当用户需要获取音量信息时需要调用
enableAudioVolumeIndication
设置回调频率和平滑系数,同时调用本接口注册相关数据的接收对象。当用户在入会前调用
startAudioCaptureTest
进行通话前音频设备检测时,可调用此接口并实现OnTestAudioVolume
回调。
参数说明
参数 | 类型 | 描述 |
observer | 音量数据接收对象。 |
unRegisterAudioVolumeObserver
取消注册音量数据输出对象。
public abstract void unRegisterAudioVolumeObserver();
本接口与registerAudioVolumeObserver
相对应,负责取消注册音量数据的输出对象。
调用时机
当调用registerAudioVolumeObserver
注册了音频数据接收对象后如果需要取消注册,请调用本接口。
enableAudioFrameObserver
设置音频回调参数。
public abstract int enableAudioFrameObserver(boolean enable, AliRtcAudioSource audioSource, AliRtcAudioFrameObserverConfig config);
该接口用于开启或关闭指定类型音频数据回调,允许开发者获取各类原始音频数据和已编码的音频数据,默认是关闭的,如果需要开启,请调用此接口。
调用此接口开启对应AliRtcAudioSource
的音频数据回调时,需要结合registerAudioFrameObserver 方法传入音频数据的接收对象。
调用时机
需要获取音频数据时,可以调用此接口开启。
参数说明
参数 | 类型 | 描述 |
enable | boolean | 是否允许音频数据回调。 |
audioSource | 回调数据源类型,包含采集后(0)、3A 后(1)、推流(2)、播放(3)、推流播放混音后(4)、拉流的音频数据(5)。 说明
| |
config | 音频回调参数设置,包含采样率、声道数、回调读写模式(只读、只写、读写)等。参数为 null 时默认为(48000,1, ReadOnly)。 |
返回说明
0: 方法调用成功。
<0:方法调用失败
registerAudioFrameObserver
注册音频数据回调。
public abstract void registerAudioFrameObserver(AliRtcAudioFrameObserver observer);
该方法用于注册音频回调数据的接收对象。
调用时机
当用户需要 SDK 触发onCapturedAudioFrame、onProcessCapturedAudioFrame、onPublishAudioFrame、onPlaybackAudioFrame、onRemoteUserAudioFrame 回调来获取各类音频数据时,需要调用此方法提供一个音频数据的接收对象。如果需要取消注册,请再次调用并传入 null。
调用限制
需要调用enableAudioFrameObserver开启具体AliRtcAudioSource的回调,否则当前传入的 oberver 无法获取数据。
参数说明
参数 | 类型 | 描述 |
observer | 音频数据回调接收对象实例,当传入为 null 时,表示取消注册。 |
registerVideoSampleObserver
注册视频数据输出对象。
public abstract void registerVideoSampleObserver(AliVideoObserver observer);
该接口用于注册视频数据的输出对象。如果要取消注册,请调用unRegisterVideoSampleObserver
接口。
调用时机
如果你需要获取原始音频数据(如 YUV 或 RGBA 格式),可以调用此接口注册一个视频数据监测器来获取各阶段的视频数据。AliRtcVideoObserver 为视频数据监测器类。
相关回调
成功注册视频数据输出监测器后,SDK 会在捕捉到每个视频帧时,触发你在 AliRtcVideoObserver 接口中实现的回调,请根据业务需要实现对应回调:
onLocalVideoSample:本地采集视频数据回调。
onRemoteVideoSample:远端视频数据回调。
onPreEncodeVideoSample:地编码前视频数据回调。
参数说明
参数 | 类型 | 描述 |
observer | 视频数据输出对象。 |
返回说明
输出数据将通过AliVideoObserver回调返回。
unRegisterVideoSampleObserver
取消注册视频数据输出对象。
public abstract void unRegisterVideoSampleObserver();
此接口与registerVideoSampleObserver
接口相对应,负责取消注册视频数据输出对象。
registerLocalVideoTextureObserver
注册本地相机流视频OpenGL纹理数据观测器。
public abstract void registerLocalVideoTextureObserver(AliTextureObserver observer);
如果您想获取原始视频数据,请调用registerVideoSampleObserver
接口注册相关回调;如果你希望获取内部纹理数据,请调用本接口。如果希望取消注册,请调用unRegisterLocalVideoTextureObserver
接口。
该接口只对本地相机流视频有效。
相关回调
成功注册本地相机流视频OpenGL纹理数据观测器后,SDK 会在捕捉到每个视频帧时,触发你在 AliRtcTextureObserver 接口中实现的回调,请根据业务需要实现对应回调:
onTextureCreate:该回调是在SDK内部OpenGL上下文创建的时候触发。
onTextureUpdate:该回调会在每一帧视频数据上传到OpenGL纹理之后触发,当外部注册了OpenGL纹理数据观测器,在该回调中可以对纹理进行处理,并返回处理后的纹理ID。注意该回调返回值必须为有效的纹理ID,如果不做任何处理必须返回参数textureId
onTextureDestroy:该回调是在SDK内部OpenGL上下文销毁的时候触发。
参数说明
参数 | 类型 | 描述 |
observer | OpenGL纹理数据观测器。 |
返回说明
输出数据将通过AliVideoObserver回调返回。
unRegisterLocalVideoTextureObserver
取消注册本地相机流视频OpenGL纹理数据观测器。
public abstract void unRegisterLocalVideoTextureObserver();
该接口与registerLocalVideoTextureObserver
相对应,负责取消注册。
snapshotVideo
视频截图功能。
public abstract int snapshotVideo(String userId, AliRtcVideoTrack trackType);
调用此接口对指定用户的指定视频流进行截图。
调用限制
该方法为异步操作,调用返回 0 时代表接口调用成功,但 SDK 并没有真正获取截图。
相关回调
成功调用该方法后,通过监听onSnapshotComplete回调获取截图是否成功及截图的详情。
参数说明
参数 | 类型 | 描述 |
userId | String | 用户ID。如果userId 为null或者为""代表对本地用户截图。 |
trackType | 视频流类型,表示对哪一路流进行截图,仅支持:
|
返回说明
0:仅代表当前方法调用成功,截图是否成功由回调onSnapshotComplete给出。
非 0:调用失败,返回错误码。
setLogDirPath
设置SDK日志文件保存路径。
public static int setLogDirPath(String logDirPath);
参数说明
参数 | 类型 | 描述 |
logDirPath | String | 日志文件保存绝对路径。默认路径:app目录下。 |
返回说明
0表示方法调用成功,非0表示方法调用失败。说明如需调用此接口,请在调用所有SDK接口前进行设置,避免日志丢失,同时App必须保证指定的路径已存在并且可写入。
setLogLevel
设置日志等级。
public static void setLogLevel(AliRtcLogLevel logLevel);
参数说明
参数 | 类型 | 描述 |
logLevel | Log级别。 |
setDeviceOrientationMode
设置设备方向。
public abstract void setDeviceOrientationMode(AliRtcOrientationMode mode);
该接口用于设置设备的方向模式,会影响到视频的显示。
调用限制
只有 android 和 ios 有这个接口。
参数说明
参数 | 类型 | 描述 |
mode | AliRtcOrientationMode | 设备方向。 |
返回说明
无。
requestAudioFocus
请求音频焦点。
public abstract int requestAudioFocus();
调用时机
启动SDK时,SDK内部会请求音频焦点,一般情况下用户无需主动请求音频焦点,如用户主动调用过abandonAudioFocus,则可调用此接口恢复音频焦点。
调用限制
仅限 Android 使用。
参数说明
无。
返回说明
0:失败。
1:成功。
abandonAudioFocus
放弃音频焦点。
public abstract int abandonAudioFocus();
调用时机
SDK销毁过程中内部会调用此接口释放音频焦点,用户某些场景下需要主动释放音频焦点,可调用此接口释放音频焦点,释放音频焦点后,部分设备可能出现播放无声或者声音小的问题,如需恢复,可主动调用requestAudioFocus。
调用限制
仅限 Android 使用。
返回说明
0:失败。
1:成功。
getNetworkTime
获取当前的网络时间。
public abstract long getNetworkTime();
该方法用于获取当前的网络时间(经过 NTP 校准并考虑时间偏移量后的当前时间戳),以 ms 为单位。
调用时机
在进行多端行为同步时,需要获取同步网络时间作为基准对当前时间进行校准。
返回说明
当前网络协议(NTP)时间(毫秒)。
sendDataChannelMsg
发送 data channel 自定义消息。
public abstract int sendDataChannelMsg(AliRtcDataChannelMsg Msg);
ARTC SDK提供发送和接收自定义消息的能力,允许在传输音视频数据的同时再发送自定义的实时消息数据,例如在音视频传输的同时传递实时控制指令、状态同步数据或其他业务消息时可调用此接口实现。具体使用方式请参考自定义消息发送和接收。
自定义消息通道默认关闭,如果需要使用该功能,请调用接口
setParameter
设置("{\"data\":{\"enablePubDataChannel\":true" + ",\"enableSubDataChannel\":true}}")接口开启自定义消息通道,加入频道前后均可开启。消息可以是任意数据(例如文字、图片等)。
相关回调
当有远端用户开启订阅 data chanenl 数据时触发此回调 onRemoteUserSubscribedDataChannel,收到此回调就可以向该用户发送 data channel 消息了。
当发送方成功开启自定义消息通道后,可以调用本接口发送自定义消息,接收方通过监听 onDataChannelMessage 回调接收自定义的消息。
调用时机
远端用户调用setParameter 开启了enableSubDataChannel接收 data channel 消息,本端收到onRemoteUserSubscribedDataChannel 回调后可调用。
调用限制
主播角色可以发送和接收消息,观众角色仅支持接收消息。
需要调用setParameter 开启自定义消息通道。
参数说明
参数 | 类型 | 描述 |
Msg | 消息内容。 |
返回说明
0:调用成功。
非 0:调用失败,返回错误码。
startScreenShare
此接口即将废弃,建议使用新接口startScreenShare。
开始共享屏幕和音频流。
public abstract int startScreenShare(Intent intent);
参数说明
名称 | 描述 |
intent | 外部创建启动屏幕分享的Activity,如果外部未创建则传入null,建议传入null。 |
返回值
0:成功
其他:失败
startScreenShare
startScreenShare
开始共享屏幕视频流。
public abstract int startScreenShare(Intent intent, AliRtcScreenShareMode screenShareMode);
参数说明
名称 | 描述 |
intent | 外部创建启动屏幕分享的Activity,外部未创建则传null,建议传null。 |
screenShareMode | 屏幕共享类型,详情请参见AliRtcScreenShareMode。 |
返回值
0:成功
其他:失败
stopScreenShare
停止屏幕共享流,包括共享的音频流。
public abstract int stopScreenShare();
返回值
0:成功
其他:失败
setAudioShareVolume
设置推流的音频流音量。
public abstract int setAudioShareVolume(int volume);
参数说明
名称 | 描述 |
volume | 音量大小。 取值范围[0, 100],默认值:50。 |
返回值
0:成功
其他:失败
isScreenSharePublished
查询是否在屏幕共享流推流中。
public abstract boolean isScreenSharePublished();
返回值
true:屏幕共享推流中。
false:未进行屏幕共享推流。
setScreenShareEncoderConfiguration
设置屏幕流视频编码属性。
public abstract void setScreenShareEncoderConfiguration(AliRtcScreenShareEncoderConfiguration config);
该方法用于设置屏幕流视频编码属性对应的视频参数,如分辨率、帧率、码率、视频方向等。
所有设置的参数都有相应的范围限制,如果设置的参数不在有效范围内,SDK会自动调节,因此实际配置可能与您的配置不同。
调用时机
该方法在入会前和入会后都可以调用,如果每次入会只需要设置一次屏幕流视频编码属性,建议在入会前调用。
参数说明
参数 | 类型 | 描述 |
config | 预定义的屏幕共享编码属性,如分辨率、帧率、码率、视频方向等。 |