自定义视频采集

1 功能简介

自定义视频采集的功能指的是由开发者自定义向 ZegoExpressEngine SDK 提供视频输入源输入视频数据，并由 ZegoExpressEngine SDK 进行编码推流的功能。当用户开启自定义视频采集的功能后，默认情况下，ZegoExpressEngine SDK 在推流端内部将对本端预览画面进行渲染，用户无需自行进行渲染。

当开发者业务中出现以下情况时，推荐使用 SDK 的自定义视频采集功能：

• 开发者开发的 App 使用了第三方美颜厂商的美颜 SDK，可以直接对接 ZegoExpressEngine SDK 的自定义视频采集功能。即由第三方美颜厂商的美颜 SDK 负责视频数据的采集，视频数据的前处理，由 ZegoExpressEngine SDK 负责视频数据的编码以及将音视频流推到 ZEGO 音视频云端。
• 直播过程中，开发者需要使用摄像头完成的额外功能和 ZegoExpressEngine SDK 的默认的视频采集逻辑有冲突，导致摄像头无法正常使用。例如，直播到一半，需要录制短视频。
• 直播非摄像头采集的数据。例如本地视频文件播放、屏幕分享、游戏直播等。

2 示例源码下载

请参考 下载示例源码 获取源码。

相关源码请查看 “/ZegoExpressExample/Topics/CustomVideoCapture” 目录下的文件。

3 前提条件

在进行自定义视频采集前，请确保：

• 已在项目中集成 ZEGO Express SDK，实现基本的实时音视频功能，详情请参考 快速开始。
• 已在 ZEGO 控制台 创建项目，并申请有效的 AppID 和 AppSign，详情请参考 控制台 - 项目管理。

4 使用步骤

自定义视频采集的使用流程如下：

1. 创建 ZegoExpressEngine 引擎。
2. 开启自定义视频采集功能。
3. 设置自定义视频采集回调对象并实现对应方法。
4. 登录房间并推流，将收到自定义视频采集回调通知开始采集。
5. 调用发送视频帧方法向 SDK 提供视频帧数据。
6. 结束推流，将收到自定义视频采集回调通知停止采集。

API 接口调用的时序图如下：

4.1 开启自定义视频采集功能

调用 ZegoCustomVideoCaptureConfig 接口创建自定义视频采集对象，设置属性 bufferType，向 SDK 提供视频帧数据类型；调用引擎的接口 enableCustomVideoCapture 开启自定义视频采集功能。

由于 iOS 采集的多样性，SDK 支持多种视频帧数据类型 bufferType，开发者需告知 SDK 使用的数据类型。目前 SDK 支持 CVPixelBuffer 类型 “ZegoVideoBufferTypeCVPixelBuffer”、GLTexture2D 类型 “ZegoVideoBufferTypeGLTexture2D” 和编码类型 “ZegoVideoBufferTypeEncodedData”，设置其他枚举值将无法向 SDK 提供视频帧数据。

ZegoCustomVideoCaptureConfig *captureConfig = [[ZegoCustomVideoCaptureConfig alloc] init];
// 选择 CVPixelBuffer 类型视频帧数据
captureConfig.bufferType = ZegoVideoBufferTypeCVPixelBuffer;

[[ZegoExpressEngine sharedEngine] enableCustomVideoCapture:YES config:captureConfig channel:ZegoPublishChannelMain];

4.2 设置自定义视频采集回调

4.2.1 设置自定义视频采集回调对象

将 “ViewController” 作为自定义视频采集回调对象，遵循 ZegoCustomVideoCaptureHandler 协议。

@interface ViewController () <ZegoEventHandler, ZegoCustomVideoCaptureHandler>

    ......

@end

调用 setCustomVideoCaptureHandler 接口设置自定义视频采集回调。

// 将自身作为自定义视频采集回调对象
[[ZegoExpressEngine sharedEngine] setCustomVideoCaptureHandler:self];

4.2.2 实现自定义视频采集回调方法

实现 onStart 和 onStop 自定义采集回调方法。

// 注意：此回调不在主线程，如有 UI 操作请自行切换到主线程
- (void)onStart {

    // 收到回调后，开发者需要执行启动采集相关的业务逻辑，例如开启摄像头等

    // 此处示例启动一个自己实现的视频采集设备
    [self.captureDevice startCapture];
}

// 注意：此回调不在主线程，如有 UI 操作请自行切换到主线程
- (void)onStop {

    // 收到回调后，开发者需要执行停止采集相关的业务逻辑，例如关闭摄像头等

    // 此处示例停止一个自己实现的视频采集设备
    [self.captureDevice stopCapture];
}

4.3 向 SDK 发送视频帧数据

调用开始预览接口 startPreview 或者开始推流接口 startPublishingStream 后，将会收到 onStart 回调；开发者启动采集相关的业务逻辑后，调用发送自定义采集的视频帧数据接口向 SDK 发送视频帧数据，自定义采集的视频帧数据接口与 4.1 开启自定义视频采集功能 中向 SDK 提供视频帧数据类型 bufferType 一一对应：

以下代码是在接收到摄像头视频帧回调后调用 sendCustomVideoCapturePixelBuffer 接口向 SDK 发送视频帧数据。

#pragma mark - AVCaptureVideoDataOutputSampleBufferDelegate

- (void)captureOutput:(AVCaptureOutput *)captureOutput didOutputSampleBuffer:(CMSampleBufferRef)sampleBuffer fromConnection:(AVCaptureConnection *)connection {
    CVPixelBufferRef buffer = CMSampleBufferGetImageBuffer(sampleBuffer);
    CMTime timeStamp = CMSampleBufferGetPresentationTimeStamp(sampleBuffer);

    // Send pixel buffer to ZEGO SDK
    [[ZegoExpressEngine sharedEngine] sendCustomVideoCapturePixelBuffer:buffer timeStamp:timeStamp];
}

停止推流/预览后，将会收到 onStop 回调，开发者可停止采集相关的业务逻辑，例如关闭摄像头等。

5 API 参考列表

6 常见问题

1. 如何使用 “ZegoVideoBufferTypeGLTexture2D” 方式传递采集数据?

   4.1 开启自定义视频采集功能 中配置 ZegoCustomVideoCaptureConfig 的 bufferType 参数选择 GLTexture2D 类型 “ZegoVideoBufferTypeGLTexture2D”，然后调用 sendCustomVideoCaptureTextureData 方法。

2. 使用自定义视频采集，本地预览的画面正常，推出去观众端看到的画面变形了？

   自定义视频采集进来的图像比例和 SDK 默认设置的分辨率的比例不一致（比如自定义视频采集进来的视频帧画面比例是 4:3，SDK 默认推流画面分辨率比例是 16:9）。解决方案：

   • 方案一：开发者自行将自定义视频采集的视频分辨率比例修改为 16:9。

   • 方案二：开发者调用 setVideoConfig，将 SDK 的推流分辨率比例自定义为 4:3。

   • 方案三：开发者调用 setCustomVideoCaptureFillMode 方法，设置为 “ZegoViewModeAspectFit” 等比缩放（带黑边）或者 “ZegoViewModeAspectFill” 等比填充（画面被裁剪）模式。

3. 开启自定义视频采集后，采集的帧率和拉流播放帧率不一致？

   当自定义采集的帧率和拉流播放帧率不一致时，可以通过如下方式处理：

   • 向 SDK 提供 “ZegoVideoBufferTypeCVPixelBuffer” 类型视频帧数据时，设置 setVideoConfig 接口的帧率和调用自定义采集 sendCustomVideoCapturePixelBuffer 接口提供的视频数据的帧率一致。
   • 向 SDK 提供 “ZegoVideoBufferTypeGLTexture2D” 类型视频帧数据时，设置 setVideoConfig 接口的帧率和调用自定义采集 sendCustomVideoCaptureTextureData 接口提供的视频数据的帧率一致。

4. SDK 接收视频帧数据方法内部对传入的数据是同步处理还是异步处理？

   SDK 接收视频帧数据后，会先同步拷贝数据，然后再异步执行编码等操作，所以在将数据传入 SDK 后即可立即释放。