Android JMRTC SDK 实时音视频

概述

极光 IM 为开发者提供稳定可靠的实时音视频开发框架(简称 JMRTC),开发者可集成 JMRTC SDK,快速实现实时音视频通讯功能,支持1对1语音/视频私聊,多人语音视频聊天。

集成指南

使用提示

  • JMRTC是基于JMessage功能上使用的,如果要集成JMRTC需要先集成JMessage,并且JMessage从2.6.0才开始支持JMRTC。
  • 如果您看到本文档,但还未下载Android With JMRTC SDK,请访问SDK下载页面下载。

  • 音视频服务需付费开通申请试用后才能使用,详细价格方案见:计费说明

JMessage with JMRTC SDK压缩包内容简介

  • demo/
    • 一个用来展示JMessage SDK接口和JMRTC接口基本用法的demo应用。
  • doc/jmessage
    • JMessage sdk中所包含所有对外接口的java doc。
  • doc/jmrtc
    • JMRTC sdk中所包含所有对外接口的java doc。
  • libs/jcore-android_v1.X.Y.jar
    • 极光开发者服务的核心包。
  • libs/jmessage-android-2.X.Y.jar
    • JMessage SDK开发包
  • libs/jmrtc-android-1.X.Y.jar
    • JMRTC SDK开发包
  • libs/agora-rtc-sdk.jar
    • agora SDK开发包
  • libs/(cpu-type)/libjcore1xy.so
    • 各种CPU类型的native开发包。

jcenter 自动集成步骤

  • 如果您没有集成过JMessage或JMessage版本低于2.6.0需要先集成JMessage,请见JMessage集成指南
  1. compile 'cn.jiguang.sdk:jmrtc:1.0.2' // 此处以jmrtc 1.0.2 版本为例

手动集成步骤:

  • 解压缩 jmessage-sdk-android-with-JMRTC-v2.X.Y.zip 集成压缩包
  • 如果您没有集成过JMessage或JMessage版本低于2.6.0需要先集成JMessage,请见JMessage集成指南
    • 注意下载的JMessage with JMRTC SDK包含JMessage SDK包,集成JMessage时无需再下载
  • 复制 libs/jmrtc-android-1.X.Y.jar.jar 到工程 libs/ 目录下。
  • 复制 libs/agora-rtc-sdk.jar 到工程 libs/ 目录下
  • 配置AndroidManifest.xml,查看AndroidManifest.xml是否包含以下内容,不包含则添加
  1. <!-- Required for jmrtc -->
  2. <uses-permission android:name="android.permission.RECORD_AUDIO" />
  3. <uses-permission android:name="android.permission.CAMERA" />
  4. <uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />
  • 混淆文件中添加JMRTC配置
  1. #========================JMRTC================================
  2. -dontwarn cn.jiguang.jmrtc.**
  3. -keep class cn.jiguang.jmrtc.api.** {*;}
  4. #========================Agora================================
  5. -dontwarn io.agora.rtc.**
  6. -keep class io.agora.rtc.** {*;}

开发指南

业务流程

JMRTC

音视频引擎初始化

在使用其他接口之前,必须先调用此接口初始化引擎。

  1. /**
  2. * @param listener 音视频相关事件回调监听类
  3. */
  4. JMRtcClient.getInstance().initEngine(JMRtcListener listener);

调用此接口,sdk背后会检查初始化所需要的权限。如果必要权限没有获取到,则会触发JMRtcListener#onPermissionNotGranted(String[])回调通知上层,获取权限成功以后调用下面接口重新初始化引擎。

  1. JMRtcClient.getInstance().reinitEngine();

释放音视频引擎

释放之后如果需要再次使用音视频服务,需要重新调用JMRtcClient.initEngine(JMRtcListener)来重新初始化音视频引擎。

  1. JMRtcClient.getInstance.releaseEngine();

主要通话行为

发起通话邀请
  1. /**
  2. * 发起通话邀请。
  3. * 任何通话的发起都应该以此接口开始。
  4. * <p>
  5. * 邀请发出之后,触发{@link JMRtcListener#onCallOutgoing(JMRtcSession)}回调,通知上层正在发起通话。之后进入outgoing状态。
  6. * <p>
  7. * 被邀请方收到邀请时,触发{@link JMRtcListener#onCallInviteReceived(JMRtcSession)}回调,通知上层收到邀请。
  8. *
  9. * @param invitedUsers 被邀请的用户的UserInfo集合
  10. * @param mediaType 通话类型
  11. * @param callback 结果回调
  12. */
  13. JMRtcClient.getInstance().call(List<UserInfo> invitedUsers, JMSignalingMessage.MediaType mediaType, final BasicCallback callback);
邀请其他用户加入通话

与发起通话邀请的区别是此时用户已经处在通话频道中,邀请其他用户加入该频道

  1. /**
  2. * 向其他用户发起邀请,加入通话。
  3. * 此接口只能在通话建立、sdk回调了{@link JMRtcListener#onCallConnected(JMRtcSession, SurfaceView)}接口之后,才能发起调用。
  4. * <p>
  5. * 邀请发出之后,当前通话中的其他用户会触发{@link JMRtcListener#onCallOtherUserInvited(UserInfo, List, JMRtcSession)}回调,通知上层有其他人被邀请加入通话
  6. * <p>
  7. * 被邀请方收到邀请时,触发{@link JMRtcListener#onCallInviteReceived(JMRtcSession)}回调,通知上层收到邀请。
  8. *
  9. * @param invitedUsers 被邀请的用户的UserInfo集合
  10. * @param callback 结果回调
  11. */
  12. JMRtcClient.getInstance().invite(List<UserInfo> invitedUsers, final BasicCallback callback);
接受通话邀请
  1. /**
  2. * 接受通话邀请。
  3. * 此接口只能在收到通话邀请、sdk回调了{@link JMRtcListener#onCallInviteReceived(JMRtcSession)}之后,才能发起调用。
  4. * <p>
  5. * 成功调用后,双方都会触发{@link JMRtcListener#onCallConnected(JMRtcSession, SurfaceView)}通知上层通话连接已建立。
  6. * 并且sdk会通过{@link JMRtcListener#onCallMemberJoin(UserInfo, SurfaceView)}上报当前已经在通话频道内的用户。
  7. *
  8. * @param callback 结果回调
  9. */
  10. JMRtcClient.getInstance().accept(final BasicCallback callback);
拒绝通话邀请
  1. /**
  2. * 拒绝通话邀请。
  3. * 此接口只能在收到通话邀请、sdk回调了{@link JMRtcListener#onCallInviteReceived(JMRtcSession)}之后,才能发起调用。
  4. * <p>
  5. * 成功调用后,被邀请方会触发{@link JMRtcListener#onCallDisconnected(DisconnectReason)}通知上层连接断开,通话已结束。
  6. * <p>
  7. * 邀请方触发{@link JMRtcListener#onCallMemberOffline(UserInfo, DisconnectReason)}通知上层有用户离线,离线原因{@link DisconnectReason#refuse}
  8. *
  9. * @param callback 结果回调
  10. */
  11. JMRtcClient.getInstance().refuse(final BasicCallback callback);
通话挂断
  1. /**
  2. * 通话挂断。
  3. * 此接口可以在邀请阶段以及通话阶段由任意通话中用户发起
  4. * <p>
  5. * 成功调用后,调用者会触发{@link JMRtcListener#onCallDisconnected(DisconnectReason)}通知上层连接断开,通话已结束。
  6. * <p>
  7. * 其他用户触发{@link JMRtcListener#onCallMemberOffline(UserInfo, DisconnectReason)}通知上层有用户离线,离线原因{@link DisconnectReason#hangup}
  8. *
  9. * @param callback 结果回调
  10. */
  11. JMRtcClient.getInstance().hangup(final BasicCallback callback);

通话属性设置

设置本地音频输出开关
  1. /**
  2. * 设置本地音频输出开关。只在视频或语音通话连接建立之后调用有效。
  3. * <p>
  4. * 默认打开。
  5. *
  6. * @param isEnable true - 开启音频输出, false - 关闭音频输出
  7. * @return 操作结果。 true - 操作成功,false - 操作失败
  8. */
  9. JMRtcClient.getInstance().enableAudio(boolean isEnable);
设置本地视频输出开关
  1. /**
  2. * 设置本地视频输出开关。只在视频通话连接建立之后调用有效。
  3. * <p>
  4. * 视频通话中默认打开。音频通话中此接口无效。
  5. *
  6. * @param isEnable true - 开启视频输出, false - 关闭视频输出
  7. * @return 操作结果。 true - 操作成功,false - 操作失败
  8. */
  9. JMRtcClient.getInstance().enableVideo(boolean isEnable) {
  10. if (null == stateMachine) {
  11. Logger.ee(TAG, "[enableVideo] failed. should init engine first.");
  12. return false;
  13. }
  14. return stateMachine.enableVideo(isEnable);
  15. }
设置使用本地外置扬声器开关
  1. /**
  2. * 设置使用本地外置扬声器开关。只在视频或语音通话连接建立之后调用有效。
  3. * <p>
  4. * 默认打开
  5. *
  6. * @param isEnable true - 使用外置扬声器, false - 不使用外置扬声器
  7. * @return 操作结果。 true - 操作成功,false - 操作失败
  8. */
  9. JMRtcClient.getInstance().enableSpeakerphone(boolean isEnable);
切换前置/后置摄像头
  1. /**
  2. * 切换前置/后置摄像头。只在视频或语音通话连接建立之后调用有效。
  3. * <p>
  4. * 默认使用前置摄像头
  5. *
  6. * @return 操作结果。 true - 操作成功,false - 操作失败
  7. */
  8. JMRtcClient.getInstance.switchCamera()
设置视频输出的编码属性
  1. /**
  2. * 设置视频输出的编码属性
  3. * <p>
  4. * 视频通话期间调用此接口设置的属性将在下次视频通话中生效
  5. *
  6. * @param videoProfile 视频编码属性
  7. */
  8. JMRtcClient.getInstance.setVideoProfile(VideoProfile videoProfile);
获取当前设置的视频编码属性
  1. /**
  2. * 获取当前设置的视频编码属性
  3. * <p>
  4. * 默认为{@link VideoProfile#Profile_360P}
  5. *
  6. * @return
  7. */
  8. JMRtcClient.getInstance.getVideoProfile();

通话元信息Session

获取当前通话Session(通话元信息)对象
  1. /**
  2. * 获取当前通话session对象。
  3. *
  4. * @return {@link JMRtcSession}对象,如果当前不在任何会话中,则返回null。
  5. */
  6. JMRtcClient.getInstance.getSession();
获取通话类型
  1. /**
  2. * 获取通话类型
  3. *
  4. * @return 通话类型
  5. */
  6. session.getMediaType();
获取用户在通信中的角色
  1. /**
  2. * 获取用户在通信中的角色,{@link SessionRole#inviter}邀请发起者,或者{@link SessionRole#invited}被邀请者。
  3. *
  4. * @return 通信中的角色
  5. */
  6. session.getSessionRole();
获取邀请者用户信息
  1. /**
  2. * 获取邀请者用户信息
  3. *
  4. * @param callback 结果回调
  5. */
  6. session.getInviterUserInfo(final RequestCallback<UserInfo> callback);
获取当前被邀请的用户的用户信息集合
  1. /**
  2. * 获取当前被邀请的用户的用户信息集合
  3. *
  4. * @param callback 结果回调
  5. */
  6. session.getInvitingUserInfos(final RequestCallback<List<UserInfo>> callback);
获取当前已加入通信的用户的用户信息集合
  1. /**
  2. * 获取当前已加入通信的用户的用户信息集合
  3. *
  4. * @param callback 结果回调
  5. */
  6. session.getJoiendMembers(final RequestCallback<List<UserInfo>> callback);

相关事件回调

JMRtc引擎初始化结果
  1. /**
  2. * jmrtc引擎初始化结果回调。
  3. *
  4. * @param errCode 错误码。 0 - 成功,其他错误码参见错误码定义表
  5. * @param errDesc 错误描述。
  6. */
  7. public void onEngineInitComplete(int errCode, String errDesc) {
  8. }
通话已播出(onCallOutgoing)
  1. /**
  2. * 邀请方成功调用{@link JMRtcClient#call(List, JMSignalingMessage.MediaType, BasicCallback)}后,会触发此回调通知上层通话已播出。
  3. *
  4. * @param callSession 保存通信元信息的实体对象
  5. */
  6. public void onCallOutgoing(JMRtcSession callSession) {
  7. }
收到通话邀请(onCallInviteReceived)

只有状态机处于Idle状态时,才会触发此回调

  1. /**
  2. * 被邀请方收到邀请时,会触发此回调通知上层收到通话邀请。
  3. *
  4. * @param callSession 保存通信元信息的实体对象
  5. */
  6. public void onCallInviteReceived(JMRtcSession callSession) {
  7. }
通话过程中,有其他用户被邀请(onCallOtherUserInvited)
  1. /**
  2. * 通话过程中,有其他用户被邀请。
  3. *
  4. * @param fromUserInfo 邀请发起方用户信息
  5. * @param invitedUserInfos 被邀请方用户信息集合
  6. * @param callSession 保存通信元信息的实体对象
  7. */
  8. public void onCallOtherUserInvited(UserInfo fromUserInfo, List<UserInfo> invitedUserInfos, JMRtcSession callSession) {
  9. }
音视频通信连接已建立(onCallConnected)
  1. /**
  2. * 音视频通信连接已建立。
  3. * 当被邀请方有任意一方成功调用{@link JMRtcClient#accept(BasicCallback)}接受邀请后,邀请方和接受方都会触发此回调通知上层通信连接已建立。
  4. *
  5. * @param callSession 保存通信元信息的实体对象
  6. * @param localSurfaceView 本地视频预览SurfaceView对象,对于视频聊天,上层可以直接用此对象在界面上进行渲染展示。
  7. */
  8. public void onCallConnected(JMRtcSession callSession, SurfaceView localSurfaceView) {
  9. }
有用户加入通信(onCallMemberJoin)

对于刚加入通信的用户,此接口会上报当前所有已在通信中的用户的信息,对于已加入通信的用户,此接口上报通信过程中加入的用户的信息。

  1. /**
  2. *
  3. * @param joinedUserInfo 加入的用户的用户信息
  4. * @param remoteSurfaceView 加入用户的视频预览SurfaceView对象。对于视频聊天,上层可以直接用此对象在界面上进行渲染展示。
  5. */
  6. public void onCallMemberJoin(UserInfo joinedUserInfo, SurfaceView remoteSurfaceView) {
  7. }
通话过程中,有用户退出通话
  1. /**
  2. * 通话过程中,有用户退出通话。
  3. *
  4. * @param leavedUserInfo 退出通话的用户的用户信息
  5. * @param reason 退出原因
  6. */
  7. public void onCallMemberOffline(UserInfo leavedUserInfo, JMRtcClient.DisconnectReason reason) {
  8. }
通话连接断开
  1. /**
  2. * 通话连接断开。
  3. *
  4. * @param reason 断开原因
  5. */
  6. public void onCallDisconnected(JMRtcClient.DisconnectReason reason) {
  7. }
通话过程中发生错误
  1. /**
  2. * 通话过程中发生错误
  3. *
  4. * @param errorCode 错误码
  5. * @param desc 错误描述
  6. */
  7. public void onCallError(int errorCode, String desc) {
  8. }
音视频初始化失败

音视频引擎初始化过程中,有些必要的权限没有获取到导致初始化失败时回调。

  1. /**
  2. * 上层收到此回调后,建议根据系统具体版本决定是否需要向用户动态申请权限(android 6.0之后)。
  3. * 权限申请成功之后,需要调用{@link JMRtcClient#reinitEngine()}重新初始化引擎。
  4. *
  5. * @param requiredPermissions 缺少的权限
  6. */
  7. public void onPermissionNotGranted(String[] requiredPermissions) {
  8. }
对方用户禁用/启用视频流
  1. /**
  2. * 对方用户禁用/启用视频流时的回调。
  3. *
  4. * @param remoteUser 用户信息
  5. * @param isMuted 是否禁用。 true - 禁用,false - 启用
  6. */
  7. public void onRemoteVideoMuted(UserInfo remoteUser, boolean isMuted) {
  8. }

错误码定义

参考文档:JMRTC Android SDK 错误码列表