本文简述iOS环境下,接入即构科技音视频SDK进行推流简介以及操作步骤等。
1、简介
直播过程中,如果需要推送自己的画面,都需要进行推流操作。一般有下面 2 种情形:
-
主播推流。
-
主播与观众连麦成功后,观众推流。
无论推流时机如何,推流操作都是相同的。
本文主要以第一种情形为例。
2、步骤
2.1 初始化 SDK
参考文档:初级功能指南-初始化
2.2 设置推流代理对象
调用如下 API 设置 ZegoLivePublisherDelegate 代理对象。设置代理对象失败,会导致 App 收不到相关回调。
ZegoLiveRoomApi-Publisher.h
/**
设置 Publisher 代理对象
@param publisherDelegate 遵循 ZegoLivePublisherDelegate 协议的代理对象
@return true 成功,false 失败
@attention 使用 Publisher 功能,初始化相关视图控制器时需要设置代理对象
@note 未设置代理对象,或对象设置错误,可能导致无法正常收到相关回调
*/
- (bool)setPublisherDelegate:(id<ZegoLivePublisherDelegate>)publisherDelegate;
2.3 登录房间
SDK 提供了两个 API 用于登录房间,区别仅在于是否指定房间名称。登录成功后,才能开始推流。
ZegoLiveRoomApi.h
/**
登录房间
@param roomID 房间 ID,长度不可超过 255 bytes
@param role 成员角色,可取值为ZEGO_ANCHOR(主播),ZEGO_AUDIENCE(观众),详见 ZegoRole 定义
@param blk 回调 block
@return true 成功,false 失败
@attention 登录房间成功,才能开始直播
@note 观众登录房间成功后,会在 blk 中返回当前房间的流信息
*/
- (bool)loginRoom:(NSString *)roomID role:(int)role withCompletionBlock:(ZegoLoginCompletionBlock)blk;
/**
登录房间
@param roomID 房间 ID,长度不可超过 255 bytes
@param roomName 房间名称,可选,长度不可超过 255 bytes
@param role 成员角色,可取值为ZEGO_ANCHOR(主播),ZEGO_AUDIENCE(观众),详见 ZegoRole 定义
@param blk 回调 block
@return true 成功,false 失败
@attention 登录房间成功,才能开始直播
@note 观众登录房间成功后,会在 blk 中返回当前房间的流信息
*/
- (bool)loginRoom:(NSString *)roomID roomName:(NSString *)roomName role:(int)role withCompletionBlock:(ZegoLoginCompletionBlock)blk;
常见登录错误码参考如下:
请注意:
本 API 中的第一个参数 roomID,是由 App 业务端定义、实现并传入的。开发者在定义 roomID 时需要确保其唯一性。
回调 blk 中的是 ZegoStream 对象,内部封装了 userID、userName、streamID 和 extraInfo。
2.4 推流设置
开始推流前,建议开发者对推流参数、推流视图进行设置。
设置推流参数
推流参数众多,主要包含:手机方向、美颜参数、滤镜参数、镜像、麦克风、前后置摄像头、手电筒、采集监听等等。
开发者可在ZegoLiveRoomApi-Publisher.h中查询,按需调用。
设置预览视图
调用如下 API 设置预览视图、视图模式,并启动本地预览。
/**
设置本地预览视图
@param view 用于渲染本地预览视频的视图
@return true 成功,false 失败
@attention 建议本地预览结束后,调用该 API 设置预览视图为 nil
*/
- (bool)setPreviewView:(ZEGOView *)view;
/**
设置本地预览视频视图的模式
@param mode 模式,参考 ZegoVideoViewMode 定义。默认 ZegoVideoViewModeScaleAspectFill
@return true 成功,false 失败
@attention 推流开始前调用本 API 进行参数配置
*/
- (bool)setPreviewViewMode:(ZegoVideoViewMode)mode;
/**
启动本地预览
@return true 成功,false 失败
@attention 启动本地预览前,要调用 [ZegoLiveRoomApi (Publisher) -setPreviewView:] 设置本地预览视图
*/
- (bool)startPreview;
上述设置完成后,App 端即可观看到推流的画面。
2.5 开始推流
登录成功后,开发者可调用以下 API 进行推流。以下 2 个 API 的区别仅在于是否传入 extraInfo,该字段用户可自定义,用于满足某些特殊需求(例如混流时传递混流 ID)。
ZegoLiveRoomApi-Publisher.h
/**
开始发布直播
@param streamID 流 ID,长度不超过 255 bytes,支持可打印字符
@param title 直播名称,可选,默认为主播用户名
@param flag 直播属性,参考 ZegoApiPublishFlag 定义
@return true 成功,false 失败
@attention 发布直播成功后,等待 [ZegoLivePublisherDelegate -onPublishStateUpdate:streamID:streamInfo:] 通知
*/
- (bool)startPublishing:(NSString *)streamID title:(NSString *)title flag:(int)flag;
/**
开始发布直播
@param streamID 流 ID,长度不超过 255 bytes,支持可打印字符
@param title 直播名称,可选,默认为主播用户名
@param flag 直播属性,参考 ZegoApiPublishFlag 定义
@param extraInfo 流附加信息
@return true 成功,false 失败
@attention 发布直播成功后,等待 [ZegoLivePublisherDelegate -onPublishStateUpdate:streamID:streamInfo:] 通知
*/
- (bool)startPublishing:(NSString *)streamID title:(NSString *)title flag:(int)flag extraInfo:(NSString *)extraInfo;
其中,开发者需按照实际使用场景,指定推流场景,由 ZegoApiPublishFlag 定义:
/** 发布直播场景 */
enum ZegoApiPublishFlag
{
ZEGO_JOIN_PUBLISH = 0, /**< 连麦场景 */
ZEGO_MIX_STREAM = 1 << 1, /**< 混流场景 */
ZEGO_SINGLE_ANCHOR = 1 << 2, /**< 单主播场景 */
};
请注意, 此 API 接受的 streamID 和 title 均由 App 定义、实现并传入。
2.6 处理推流状态回调
推流开始后,开发者可在如下回调中获取推流状态和信息。
ZegoLiveRoomApi-Publisher.h
/**
推流状态更新
@param stateCode 状态码
@param streamID 流 ID,长度不超过 255 bytes,支持可打印字符
@param info 推流信息
@attention 主播调用 [ZegoLiveRoomApi (Publisher) -startPublishing:title:flag:] 推流成功后,通过该 API 通知主播方
*/
- (void)onPublishStateUpdate:(int)stateCode streamID:(NSString *)streamID streamInfo:(NSDictionary *)info;
常见推流错误码参考如下:
2.7 停止推流
调用如下 API 停止推流。停止推流不会触发退出房间,用户依然可以在当前房间中,重新推流。
建议用户在停止推流时,停止本地预览(stopPreview setPreviewView:nil),保持体验一致性。
ZegoLiveRoomApi-Publisher.h
/**
停止直播
@return true 成功,false 失败
@attention 注意混流结束后,要先调用 [-updateMixInputStreams] 将流列表清空结束混流,然后调用 stopPublishing 结束直播
*/
- (bool)stopPublishing;
2.8 退出房间
推流结束后,调用如下 API 退出房间。请开发者在退出房间前,确保停止推流,并清理相关状态与控件。
ZegoLiveRoomApi.h
/**
退出房间
@return true 成功,false 失败
@attention 连麦情况下,要 stop 所有的 stream 后,才能执行 logoutRoom
*/
- (bool)logoutRoom;