实时音视频
  • 平台类型
  • 框架 / 引擎
  • iOS
  • Android
  • macOS
  • Windows
  • Linux
  • Web
  • 小程序

自定义视频采集

更新时间:2021-04-25 20:25

1 功能简介

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

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

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

2 示例源码下载

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

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

3 前提条件

在进行自定义视频采集前,请确保:

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 实现自定义视频采集回调方法

实现 onStartonStop 自定义采集回调方法。

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

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

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

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

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

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

4.3 向 SDK 发送视频帧数据

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

视频帧类型 bufferType 发送视频帧数据接口
CVPixelBuffer 类型 ZegoVideoBufferTypeCVPixelBuffer sendCustomVideoCapturePixelBuffer
GLTexture2D 类型 ZegoVideoBufferTypeGLTexture2D sendCustomVideoCaptureTextureData
编码类型 ZegoVideoBufferTypeEncodedData sendCustomVideoCaptureEncodedData

以下代码是在接收到摄像头视频帧回调后调用 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 参考列表

方法 描述
setEngineConfig 设置引擎进阶配置
setCustomVideoCaptureHandler 设置自定义视频采集回调
onStart SDK 通知将要开始采集视频帧
onStop SDK 通知将要停止采集视频帧
sendCustomVideoCapturePixelBuffer 向 SDK 发送 CVPixelBuffer 视频帧数据
sendCustomVideoCaptureTextureData 向 SDK 发送 Texture 视频帧数据

6 常见问题

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

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

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

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

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

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

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

  1. 开启自定义视频采集后,采集的帧率和拉流播放帧率不一致?

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

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

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