iOS JMRTC SDK 实时音视频

概述

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

JMRTC 集成文档

集成说明

集成步骤

步骤 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
  • 手动导入

步骤 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

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

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

2、添加监听代理

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

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

/*!
 * @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;

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

4、获取当前通话实体

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

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

5、通话实体

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

接听当前来电。
/*!
 * @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 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;
设置视频通话中某个用户的显示 View
/*!
 * @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 enabled  是否开启扬声器,音频通话默:NO,视频通话默认:YES
 *
 * @discussion 只在视频或语音通话连接建立之后调用有效
 */
- (BOOL)setSpeakerEnabled:(BOOL)enabled;
设置视频流状态
/*!
 * @abstract 设置视频流状态
 *
 * @param enabled  开启/关闭,音频通话默:NO,视频通话默认:YES
 *
 * @discussion 该方法不影响本地视频流获取,没有禁用摄像头,只是暂停发送本地视频流,只在视频通话连接建立之后调用有效。
 *
 * 通话中的其他用户,会触发 [JMRTCDelegate onCallUserVideoStreamEnabled:byUser:] 回调
 */
- (BOOL)setVideoStreamEnabled:(BOOL)enabled;
切换前后摄像头
/*!
 * @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;

7、通话相关回调

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

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

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

通话邀请已发出
/*!
 * @abstract 通话邀请已发出
 *
 * @param callSession 通话实体对象
 *
 * @discussion 在成功调用 [JMRTCClient startCallUsers:mediaType:handler:] 接口之后,会触发这个回调
 */
- (void)onCallOutgoing:(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)onCallConnected:(JMRTCSession *)callSession;
有用户加入通话
/*!
 * @abstract 有用户加入通话
 *
 * @param joinUser  加入的用户的用户信息
 */
- (void)onCallMemberJoin:(JMSGUser *)joinUser;
通话断开
/*!
 * @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 fromUser      邀请发起方用户信息
 * @param invitedUsers  被邀请方用户信息集合
 */
- (void)onCallOtherUserInvited:(NSArray <__kindof JMSGUser *>*)invitedUsers fromUser:(JMSGUser *)fromUser;
通话过程中发生错误
/*!
 * @abstract 通话过程中发生错误
 *
 * @param error 错误信息
 *
 * @discussion 错误具体情况请查看 error 的错误码和描述信息
 */
- (void)onCallError:(NSError *)error;
远端用户开启/关闭视频流
/*!
 * @abstract 远端用户开启/关闭视频流
 *
 * @param enabled  开启/关闭
 * @param user     远端用户
 */
- (void)onCallUserVideoStreamEnabled:(BOOL)enabled byUser:(JMSGUser *)user;

错误码定义

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


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

Documentation built with MkDocs.