• Android JMRTC SDK 实时音视频
    • 概述
      • 集成指南
        • 使用提示
        • JMessage with JMRTC SDK压缩包内容简介
        • jcenter 自动集成步骤
        • 手动集成步骤:
      • 开发指南
        • 业务流程
        • 音视频引擎初始化
        • 释放音视频引擎
        • 主要通话行为
          • 发起通话邀请
          • 邀请其他用户加入通话
          • 接受通话邀请
          • 拒绝通话邀请
          • 通话挂断
        • 通话属性设置
          • 设置本地音频输出开关
          • 设置本地视频输出开关
          • 设置使用本地外置扬声器开关
          • 切换前置/后置摄像头
          • 设置视频输出的编码属性
          • 获取当前设置的视频编码属性
        • 通话元信息Session
          • 获取当前通话Session(通话元信息)对象
          • 获取通话类型
          • 获取用户在通信中的角色
          • 获取邀请者用户信息
          • 获取当前被邀请的用户的用户信息集合
          • 获取当前已加入通信的用户的用户信息集合
        • 相关事件回调
          • JMRtc引擎初始化结果
          • 通话已播出(onCallOutgoing)
          • 收到通话邀请(onCallInviteReceived)
          • 通话过程中，有其他用户被邀请(onCallOtherUserInvited)
          • 音视频通信连接已建立(onCallConnected)
          • 有用户加入通信(onCallMemberJoin)
          • 通话过程中，有用户退出通话
          • 通话连接断开
          • 通话过程中发生错误
          • 音视频初始化失败
          • 对方用户禁用/启用视频流
      • 错误码定义

    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.** {*;}
    5. #========================Agora================================
    6. -dontwarn io.agora.rtc.**
    7. -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 错误码列表