iOS JMRTC SDK 实时音视频
最近更新:2021-12-15

iOS JMRTC SDK 实时音视频

概述

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

JMRTC 集成文档

集成说明

  • JMRTC 是基于 JMessage 开发的,所以必须先集成 JMessage SDK,IM SDK 从 3.6.2 才开始支持JMRTC。
  • 如果您看到本文档,但还未下载 JMRTC SDK,请访问 SDK 下载页面下载。
  • 音视频服务需付费开通申请试用后才能使用,详细价格方案见:计费说明

集成步骤

步骤 1:准备环境
  • 请确保满足以下开发环境要求:
    • Apple XCode 6.0 或以上版本
    • iOS 7.0 或以上版本
    • 支持语音和视频功能的真机设备
步骤 2:添加必须 SDK
  • 自动导入

    • 安装 CocoaPods :sudo gem install cocoapods
    • 更新本地的索引库 :pod repo update
    • 在 Podfile 里添加引用:
      pod 'JMessage'
      pod 'AgoraRtcEngine_iOS', '2.2.1'
    • 导入依赖库:pod install
  • 手动导入

    • 下载最新的 JMRTC.framework 、JMessage.framework
    • 添加指定版本的 Agora SDK v2.2.1
步骤 3: 添加系统库
  • libc++.tbd
  • libresolv.tbd
  • libsqlite3.0.dylib
  • AVFoundation.framework
  • AudioToolbox.framework
  • VideoToolbox.framework
  • CoreMotion.framework
  • CoreMedia.framework
  • CoreAudio.framework
  • CoreTelephony.framework
  • CoreGraphics.framework
  • CFNetwork.framework
  • Security.framework
  • MobileCoreServices.framework
  • SystemConfiguration.framework
步骤 4: 授权使用音视频 SDK
  • 摄像头、麦克风
  • 在 info.plist 进行授权操作:
将 Privacy - Camera Usage Description 设置为 use camera to start video call 将 Privacy - Microphone Usage Description 设置为 use microphone to start video call
          将 Privacy - Camera Usage Description 设置为 use camera to start video call  
将 Privacy - Microphone Usage Description 设置为 use microphone to start video call

        
此代码块在浮窗中显示

步骤 5:其他设置
  • 在项目配置,Build Settings,Other Linker Flags 里增加如下 1 项:

    -ObjC
              -ObjC
    
            
    此代码块在浮窗中显示
  • 设置后台模式。在 Background Modes 里选择 Audio, AirPlay, and Picture in Picture __注意__:APP 支持后台运行的具体实现,需要开发者自己完成开发。

  • 选择当前 Target, 并按照下图禁用 bitcode , 因为 Agora SDK 不支持 bitcode 。

JMRTC 开发文档

1、初始化音视频引擎

在发起音视频通话之前,必须先初始化引擎,如果没有初始化或初始化失败,则无法使用所有音视频功能。

/*! * @abstract 初始化音视频引擎。 * * @param handler 初始话回调,error = nil 表示初始化成功 * * @discussion 在使用其他接口之前,必须先调用此接口初始化引擎。 */ + (void)initializeEngine:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 初始化音视频引擎。
 *
 * @param handler  初始话回调,error = nil 表示初始化成功
 *
 * @discussion 在使用其他接口之前,必须先调用此接口初始化引擎。
 */
+ (void)initializeEngine:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示

在挂断或不使用音视频功能时,建议释放引擎,以免占用系统内存。

/*! * @abstract 释放音视频引擎 * * @discussion 挂断后建议释放引擎,释放之后如果需要再次使用音视频服务,需要重新调用初始化接口来重新初始化音视频引擎。 */ + (void)releaseEngine;
          /*!
 * @abstract 释放音视频引擎
 *
 * @discussion 挂断后建议释放引擎,释放之后如果需要再次使用音视频服务,需要重新调用初始化接口来重新初始化音视频引擎。
 */
+ (void)releaseEngine;

        
此代码块在浮窗中显示

2、添加监听代理

您需要设置 JMRTCClient 的全局通话监听,来监听通话呼入、通话状态等。 建议在需要使用音视频的界面,最初始先添加监听代理,以免遗漏回调信息。

调用 JMRTCClient 类一下接口,添加代理监听

/*! * @abstract 添加音视频监听 * * @param delegate 需要监听的 Delegate Protocol * * @discussion 建议在 didFinishLaunchingWithOptions 方法中添加全局监听,避免遗漏监听 */ + (void)addDelegate:(id<JMRTCDelegate>_Nonnull)delegate;
          /*!
 * @abstract 添加音视频监听
 *
 * @param delegate 需要监听的 Delegate Protocol
 *
 * @discussion 建议在 didFinishLaunchingWithOptions 方法中添加全局监听,避免遗漏监听
 */
+ (void)addDelegate:(id<JMRTCDelegate>_Nonnull)delegate;

        
此代码块在浮窗中显示

通话状态发生变化时会通过您传入的 delegate 进行回调,您可以监听到所有回调信息。

3、发起通话

您可以调用 JMRTCClient 类以下接口,发起通话

/*! * @abstract 发起一个通话 * * @param users 邀请的用户列表 * @param type 发起的通话媒体类型 * @param handler 回调,error = nil 表示成功,result 为 JMRTCSession 对象 * * @discussion 在此接口成功之后,可以设置会话中用户展示视图、摄像头、扩音器等属性; * 如果被邀请人中包含未登录用户只会向已登录用户发起邀请。 */ + (void)startCallUsers:(NSArray <__kindof JMSGUser *>*_Nonnull)users mediaType:(JMRTCMediaType)type handler:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 发起一个通话
 *
 * @param users            邀请的用户列表
 * @param type             发起的通话媒体类型
 * @param handler          回调,error = nil 表示成功,result 为 JMRTCSession 对象
 *
 * @discussion 在此接口成功之后,可以设置会话中用户展示视图、摄像头、扩音器等属性;
 * 如果被邀请人中包含未登录用户只会向已登录用户发起邀请。
 */
+ (void)startCallUsers:(NSArray <__kindof JMSGUser *>*_Nonnull)users
             mediaType:(JMRTCMediaType)type
               handler:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示

其中,您可以通过返回的通话实体,操控通话和获取通话相关信息。

4、获取当前通话实体

您可以通过 JMRTCClient 的以下接口,直接查询当前的通话实体。

/*! * @abstract 当前的通话会话实体 */ + (JMRTCSession *_Nullable)currentCallSession;
          /*!
 * @abstract 当前的通话会话实体
 */
+ (JMRTCSession *_Nullable)currentCallSession;

        
此代码块在浮窗中显示

5、通话实体

通话实体 JMRTCSession 包含当前通话的所有信息,您可以通过其中的接口,操控当前通话,如:接听、挂断、邀请等;也可获取相关信息,如:通话类型、当前被邀请列表等。

接听当前来电。
/*! * @abstract 接听来电 * * ### 此接口只能在收到通话邀请回调 [JMRTCDelegate onCallReceiveInvite:] 之后才能调用; * * ### 调用成功后,双方都会触发 [JMRTCDelegate onCallConnected:] 回调,通知上层通话连接已建立; * * ### 并且 SDK 会触发 [JMRTCDelegate onCallMemberJoin:] 通知当前已经在通话频道内的用户有新用户加入。 */ - (void)accept:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 接听来电
 *
 * ### 此接口只能在收到通话邀请回调 [JMRTCDelegate onCallReceiveInvite:] 之后才能调用;
 *
 * ### 调用成功后,双方都会触发 [JMRTCDelegate onCallConnected:] 回调,通知上层通话连接已建立;
 *
 * ### 并且 SDK 会触发 [JMRTCDelegate onCallMemberJoin:] 通知当前已经在通话频道内的用户有新用户加入。
 */
- (void)accept:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示
挂断当前通话
/*! * @abstract 挂断通话 * * ### 调用成功后,挂断方会触发 [JMRTCDelegate onCallDisconnect::disconnectReason:]通知上层连接断开,通话结束; * * ### 其他用户会触发 [JMRTCDelegate onCallMemberLeave:reason:]通知上层有用户离开. * * @discussion 注意:SDK 一般情况不会主动调用 hangup,挂断通话操作由上层决定。此接口可以在邀请阶段以及通话阶段由任意通话中用户发起 */ - (void)hangup:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 挂断通话
 *
 * ### 调用成功后,挂断方会触发 [JMRTCDelegate onCallDisconnect::disconnectReason:]通知上层连接断开,通话结束;
 *
 * ### 其他用户会触发 [JMRTCDelegate onCallMemberLeave:reason:]通知上层有用户离开.
 *
 * @discussion 注意:SDK 一般情况不会主动调用 hangup,挂断通话操作由上层决定。此接口可以在邀请阶段以及通话阶段由任意通话中用户发起
 */
- (void)hangup:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示
拒绝通话邀请
/*! * @abstract 拒绝通话邀请 * * ### 此接口只能在收到通话邀请回调 [JMRTCDelegate onCallReceiveInvite:] 之后才能调用; * * ### 调用成功后,拒绝方会触发 [JMRTCDelegate onCallDisconnect:disconnectReason:]通知上层连接断开,通话结束; * * ### 其他用户会触发 [JMRTCDelegate onCallMemberLeave:reason:]通知上层有用户离开. * * @discussion 此接口可以在邀请阶段以及通话阶段由任意通话中用户发起 */ - (void)refuse:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 拒绝通话邀请
 *
 * ### 此接口只能在收到通话邀请回调 [JMRTCDelegate onCallReceiveInvite:] 之后才能调用;
 *
 * ### 调用成功后,拒绝方会触发 [JMRTCDelegate onCallDisconnect:disconnectReason:]通知上层连接断开,通话结束;
 *
 * ### 其他用户会触发 [JMRTCDelegate onCallMemberLeave:reason:]通知上层有用户离开.
 *
 * @discussion 此接口可以在邀请阶段以及通话阶段由任意通话中用户发起
 */
- (void)refuse:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示
邀请用户加入当前通话
/*! * @abstract 邀请用户加入通话 * * ### 被邀请方收到邀请时,会触发 [JMRTCDelegate onCallReceiveInvite:] 回调; * * ### 通话中的其他用户,会触发 [JMRTCDelegate onCallOtherUserInvited:fromUser:] 回调 * * @param users 用户列表 * @param handler 回调,error=nil 时表示操作成功 * * @discussion 在通话已经建立的前提下,再邀请其他用户加入当前通话. * 如果被邀请人中包含未登录用户只会向已登录用户发起邀请. */ - (void)inviteUsers:(NSArray <__kindof JMSGUser *>*_Nonnull )users handler:(JMRTCCompletionHandler _Nullable)handler;
          /*!
 * @abstract 邀请用户加入通话
 *
 * ### 被邀请方收到邀请时,会触发 [JMRTCDelegate onCallReceiveInvite:] 回调;
 *
 * ### 通话中的其他用户,会触发 [JMRTCDelegate onCallOtherUserInvited:fromUser:] 回调
 *
 * @param users      用户列表
 * @param handler    回调,error=nil 时表示操作成功
 *
 * @discussion 在通话已经建立的前提下,再邀请其他用户加入当前通话.
 * 如果被邀请人中包含未登录用户只会向已登录用户发起邀请.
 */
- (void)inviteUsers:(NSArray <__kindof JMSGUser *>*_Nonnull )users
            handler:(JMRTCCompletionHandler _Nullable)handler;

        
此代码块在浮窗中显示
设置视频通话中某个用户的显示 View
/*! * @abstract 设置用户视频展示 View * * @param view 视频的View * @param user 用户(自己或他人) * * @discussion 在发起通话邀请之后,设置视频的展示 view */ - (void)setVideoView:(UIView *_Nonnull)view user:(JMSGUser *_Nonnull)user;
          /*!
 * @abstract 设置用户视频展示 View
 *
 * @param view   视频的View
 * @param user    用户(自己或他人)
 *
 * @discussion 在发起通话邀请之后,设置视频的展示 view
 */
- (void)setVideoView:(UIView *_Nonnull)view user:(JMSGUser *_Nonnull)user;

        
此代码块在浮窗中显示
设置静音
/*! * @abstract设置静音状态 * * @param muted 是否静音 */ - (BOOL)setMuted:(BOOL)muted;
          /*!
 * @abstract设置静音状态
 *
 * @param muted 是否静音
 */
- (BOOL)setMuted:(BOOL)muted;

        
此代码块在浮窗中显示
设置扬声器状态
/*! * @abstract 设置扬声器状态 * * @param enabled 是否开启扬声器,音频通话默:NO,视频通话默认:YES * * @discussion 只在视频或语音通话连接建立之后调用有效 */ - (BOOL)setSpeakerEnabled:(BOOL)enabled;
          /*!
 * @abstract 设置扬声器状态
 *
 * @param enabled  是否开启扬声器,音频通话默:NO,视频通话默认:YES
 *
 * @discussion 只在视频或语音通话连接建立之后调用有效
 */
- (BOOL)setSpeakerEnabled:(BOOL)enabled;

        
此代码块在浮窗中显示
设置视频流状态
/*! * @abstract 设置视频流状态 * * @param enabled 开启/关闭,音频通话默:NO,视频通话默认:YES * * @discussion 该方法不影响本地视频流获取,没有禁用摄像头,只是暂停发送本地视频流,只在视频通话连接建立之后调用有效。 * * 通话中的其他用户,会触发 [JMRTCDelegate onCallUserVideoStreamEnabled:byUser:] 回调 */ - (BOOL)setVideoStreamEnabled:(BOOL)enabled;
          /*!
 * @abstract 设置视频流状态
 *
 * @param enabled  开启/关闭,音频通话默:NO,视频通话默认:YES
 *
 * @discussion 该方法不影响本地视频流获取,没有禁用摄像头,只是暂停发送本地视频流,只在视频通话连接建立之后调用有效。
 *
 * 通话中的其他用户,会触发 [JMRTCDelegate onCallUserVideoStreamEnabled:byUser:] 回调
 */
- (BOOL)setVideoStreamEnabled:(BOOL)enabled;

        
此代码块在浮窗中显示
切换前后摄像头
/*! * @abstract 切换前后摄像头 */ - (BOOL)switchCameraMode;
          /*!
 * @abstract 切换前后摄像头
 */
- (BOOL)switchCameraMode;

        
此代码块在浮窗中显示

6、获取通话实体相关信息

/// 当前通话的频道id @property(nonatomic, assign, readonly) SInt64 channelId; /// 当前用户使用的媒体类型 @property(nonatomic, assign, readonly) JMTRCMediaType mediaType; /// 邀请当前用户加入通话的邀请者 @property(nonatomic, strong, readonly) JMSGUser *_Nullable inviter; /// 正在邀请中的用户 @property(nonatomic, strong, readonly) NSArray <__kindof JMSGUser *>*_Nullable invitingMembers; /// 已经加入通话的用户 @property(nonatomic, strong, readonly) NSArray <__kindof JMSGUser *>*_Nullable joinedMembers; /// 连接建立时间 @property(nonatomic, assign, readonly) long long startTime;
          /// 当前通话的频道id
@property(nonatomic, assign, readonly) SInt64 channelId;
    
/// 当前用户使用的媒体类型
@property(nonatomic, assign, readonly) JMTRCMediaType mediaType;
    
/// 邀请当前用户加入通话的邀请者
@property(nonatomic, strong, readonly) JMSGUser *_Nullable inviter;
    
/// 正在邀请中的用户
@property(nonatomic, strong, readonly) NSArray <__kindof JMSGUser *>*_Nullable invitingMembers;
    
/// 已经加入通话的用户
@property(nonatomic, strong, readonly) NSArray <__kindof JMSGUser *>*_Nullable joinedMembers;
    
/// 连接建立时间
@property(nonatomic, assign, readonly) long long startTime;

        
此代码块在浮窗中显示

7、通话相关回调

如果您未实现并设置了 JMRTCDelegate,请通话如下方法添加代理:

+ (void)addDelegate:(id<JMRTCDelegate>_Nullable)delegate;

当通话状态发生变化的时候,如通话呼出、接通、结束、有人加入通话、有人挂断、发生错误等都会进行回调。

通话邀请已发出
/*! * @abstract 通话邀请已发出 * * @param callSession 通话实体对象 * * @discussion 在成功调用 [JMRTCClient startCallUsers:mediaType:handler:] 接口之后,会触发这个回调 */ - (void)onCallOutgoing:(JMRTCSession *)callSession;
          /*!
 * @abstract 通话邀请已发出
 *
 * @param callSession 通话实体对象
 *
 * @discussion 在成功调用 [JMRTCClient startCallUsers:mediaType:handler:] 接口之后,会触发这个回调
 */
- (void)onCallOutgoing:(JMRTCSession *)callSession;

        
此代码块在浮窗中显示
收到通话邀请
/*! * @abstract 收到通话邀请 * * @param callSession 通话实体对象 * * @discussion 被邀请者收到通话邀请,会触发此回调 */ - (void)onCallReceiveInvite:(JMRTCSession *)callSession;
          /*!
 * @abstract 收到通话邀请
 *
 * @param callSession 通话实体对象
 *
 * @discussion 被邀请者收到通话邀请,会触发此回调
 */
- (void)onCallReceiveInvite:(JMRTCSession *)callSession;

        
此代码块在浮窗中显示
通话正在连接
/*! * @abstract 通话正在连接 * * @param callSession 通话实体对象 * * @discussion 被邀请方调用 [JMRTCSession accept:] 接口之后,会触发此回调 */ - (void)onCallConnecting:(JMRTCSession *)callSession;
          /*!
 * @abstract 通话正在连接
 *
 * @param callSession 通话实体对象
 *
 * @discussion 被邀请方调用 [JMRTCSession accept:] 接口之后,会触发此回调
 */
- (void)onCallConnecting:(JMRTCSession *)callSession;

        
此代码块在浮窗中显示
通话连接已建立
/*! * @abstract 通话连接已建立 * * @param callSession 通话实体对象 * * @discussion 当被邀请方有任意一方成功调用 [JMRTCSession accept:] 接受邀请后,邀请方和接受方都会触发此回调通知上层通信连接已建立 */ - (void)onCallConnected:(JMRTCSession *)callSession;
          /*!
 * @abstract 通话连接已建立
 *
 * @param callSession 通话实体对象
 *
 * @discussion 当被邀请方有任意一方成功调用 [JMRTCSession accept:] 接受邀请后,邀请方和接受方都会触发此回调通知上层通信连接已建立
 */
- (void)onCallConnected:(JMRTCSession *)callSession;

        
此代码块在浮窗中显示
有用户加入通话
/*! * @abstract 有用户加入通话 * * @param joinUser 加入的用户的用户信息 */ - (void)onCallMemberJoin:(JMSGUser *)joinUser;
          /*!
 * @abstract 有用户加入通话
 *
 * @param joinUser  加入的用户的用户信息
 */
- (void)onCallMemberJoin:(JMSGUser *)joinUser;

        
此代码块在浮窗中显示
通话断开
/*! * @abstract 通话断开 * * @param callSession 通话实体对象 * @param reason 断开原因 * * @discussion 连接主动断开或异常断开时会触发此回调,断开原因请查看的 JMRTCDisconnectReason */ - (void)onCallDisconnect:(JMRTCSession *)callSession disconnectReason:(JMRTCDisconnectReason)reason;
          /*!
 * @abstract 通话断开
 *
 * @param callSession 通话实体对象
 * @param reason      断开原因
 *
 * @discussion 连接主动断开或异常断开时会触发此回调,断开原因请查看的 JMRTCDisconnectReason
 */
- (void)onCallDisconnect:(JMRTCSession *)callSession disconnectReason:(JMRTCDisconnectReason)reason;

        
此代码块在浮窗中显示
有用户离开
/*! * @abstract 有用户离开 * * @param leaveUser 退出通话的用户的用户信息 * @param reason 退出原因 * * @discussion 不管是正在被邀请的用户离开,还是已经加入通话的用户离开,都会触发这个回调 */ - (void)onCallMemberLeave:(JMSGUser *)leaveUser reason:(JMRTCDisconnectReason)reason;
          /*!
 * @abstract 有用户离开
 *
 * @param leaveUser   退出通话的用户的用户信息
 * @param reason      退出原因
 *
 * @discussion 不管是正在被邀请的用户离开,还是已经加入通话的用户离开,都会触发这个回调
 */
- (void)onCallMemberLeave:(JMSGUser *)leaveUser reason:(JMRTCDisconnectReason)reason;

        
此代码块在浮窗中显示
通话过程中,有其他用户被邀请
/*! * @abstract 通话过程中,有其他用户被邀请 * * @param fromUser 邀请发起方用户信息 * @param invitedUsers 被邀请方用户信息集合 */ - (void)onCallOtherUserInvited:(NSArray <__kindof JMSGUser *>*)invitedUsers fromUser:(JMSGUser *)fromUser;
          /*!
 * @abstract 通话过程中,有其他用户被邀请
 *
 * @param fromUser      邀请发起方用户信息
 * @param invitedUsers  被邀请方用户信息集合
 */
- (void)onCallOtherUserInvited:(NSArray <__kindof JMSGUser *>*)invitedUsers fromUser:(JMSGUser *)fromUser;

        
此代码块在浮窗中显示
通话过程中发生错误
/*! * @abstract 通话过程中发生错误 * * @param error 错误信息 * * @discussion 错误具体情况请查看 error 的错误码和描述信息 */ - (void)onCallError:(NSError *)error;
          /*!
 * @abstract 通话过程中发生错误
 *
 * @param error 错误信息
 *
 * @discussion 错误具体情况请查看 error 的错误码和描述信息
 */
- (void)onCallError:(NSError *)error;

        
此代码块在浮窗中显示
远端用户开启/关闭视频流
/*! * @abstract 远端用户开启/关闭视频流 * * @param enabled 开启/关闭 * @param user 远端用户 */ - (void)onCallUserVideoStreamEnabled:(BOOL)enabled byUser:(JMSGUser *)user;
          /*!
 * @abstract 远端用户开启/关闭视频流
 *
 * @param enabled  开启/关闭
 * @param user     远端用户
 */
- (void)onCallUserVideoStreamEnabled:(BOOL)enabled byUser:(JMSGUser *)user;

        
此代码块在浮窗中显示

错误码定义

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

文档内容是否对您有帮助?

Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

在文档中心打开