自定义视频采集的功能指的是由开发者自定义向 ZegoExpressEngine SDK 提供视频输入源输入视频数据,并由 ZegoExpressEngine SDK 进行编码推流的功能。当用户开启自定义视频采集的功能后,默认情况下,ZegoExpressEngine SDK 在推流端内部将对本端预览画面进行渲染,用户无需自行进行渲染。
当开发者业务中出现以下情况时,推荐使用 SDK 的自定义视频采集功能:
请参考 下载示例源码 获取源码。
相关源码请查看 “/ZegoExpressExample/Examples/AdvancedVideoProcessing/CustomVideoCapture” 目录下的文件。
在进行自定义视频采集前,请确保:
自定义视频采集的使用流程如下:
API 接口调用的时序图如下:
开启自定义视频采集功能时需要将 enableCamera 接口保持默认配置 “True” ,否则推流没有视频数据。
调用 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];
将 “ViewController” 作为自定义视频采集回调对象,遵循 ZegoCustomVideoCaptureHandler 协议。
@interface ViewController () <ZegoEventHandler, ZegoCustomVideoCaptureHandler>
......
@end
调用 setCustomVideoCaptureHandler 接口设置自定义视频采集回调。
// 将自身作为自定义视频采集回调对象
[[ZegoExpressEngine sharedEngine] setCustomVideoCaptureHandler:self];
实现 onStart 和 onStop 自定义采集回调方法。
// 注意:此回调不在主线程,如有 UI 操作请自行切换到主线程
- (void)onStart {
// 收到回调后,开发者需要执行启动采集相关的业务逻辑,例如开启摄像头等
// 此处示例启动一个自己实现的视频采集设备
[self.captureDevice startCapture];
}
// 注意:此回调不在主线程,如有 UI 操作请自行切换到主线程
- (void)onStop {
// 收到回调后,开发者需要执行停止采集相关的业务逻辑,例如关闭摄像头等
// 此处示例停止一个自己实现的视频采集设备
[self.captureDevice stopCapture];
}
调用开始预览接口 startPreview 或者开始推流接口 startPublishingStream 后,将会收到 onStart 回调;开发者启动采集相关的业务逻辑后,调用发送自定义采集的视频帧数据接口向 SDK 发送视频帧数据,自定义采集的视频帧数据接口与 4.1 开启自定义视频采集功能 中向 SDK 提供视频帧数据类型 bufferType 一一对应:
视频帧类型 | bufferType | 发送视频帧数据接口 |
---|---|---|
CVPixelBuffer 类型 | ZegoVideoBufferTypeCVPixelBuffer | sendCustomVideoCapturePixelBuffer |
GLTexture2D 类型 | ZegoVideoBufferTypeGLTexture2D | sendCustomVideoCaptureTextureData |
编码类型 | ZegoVideoBufferTypeEncodedData | sendCustomVideoCaptureEncodedData |
在进行外部采集时,如果通过 sendCustomVideoCaptureEncodedData 接口向 SDK 发送的是视频帧编码后的数据,SDK 将无法预览,此时开发者需要自行预览。
以下代码是在接收到摄像头视频帧回调后调用 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 回调,开发者可停止采集相关的业务逻辑,例如关闭摄像头等。
推流端通过 setCustomVideoCaptureDeviceState 设置设备状态为 ZegoRemoteDeviceStateDisable 或 ZegoRemoteDeviceStateMute 都无效,即拉流端无法收到 onRemoteCameraStateUpdate 回调。
当推流端通过 enableCamera 关闭摄像头时,拉流端会在 onRemoteCameraStateUpdate 回调中收到 ZegoRemoteDeviceStateDisable 状态;当推流端通过 mutePublishStreamVideo 不推视频流时,拉流端会在 onRemoteCameraStateUpdate 回调中收到 ZegoRemoteDeviceStateMute 状态。
收到 onStart 回调后,可以根据需要调用 setCustomVideoCaptureDeviceState 接口设置指定推流通道的自定义采集设备状态。
拉流端可以通过监听 onRemoteCameraStateUpdate 回调获取推流端设备状态。
方法 | 描述 |
---|---|
setEngineConfig | 设置引擎进阶配置 |
setCustomVideoCaptureHandler | 设置自定义视频采集回调 |
onStart | SDK 通知将要开始采集视频帧 |
onStop | SDK 通知将要停止采集视频帧 |
sendCustomVideoCapturePixelBuffer | 向 SDK 发送 CVPixelBuffer 视频帧数据 |
sendCustomVideoCaptureTextureData | 向 SDK 发送 Texture 视频帧数据 |
如何使用 “ZegoVideoBufferTypeGLTexture2D” 方式传递采集数据?
4.1 开启自定义视频采集功能 中配置 ZegoCustomVideoCaptureConfig 的 bufferType 参数选择 GLTexture2D 类型 “ZegoVideoBufferTypeGLTexture2D”,然后调用 sendCustomVideoCaptureTextureData 方法。
使用自定义视频采集,本地预览的画面正常,推出去观众端看到的画面变形了?
自定义视频采集进来的图像比例和 SDK 默认设置的分辨率的比例不一致(比如自定义视频采集进来的视频帧画面比例是 4:3,SDK 默认推流画面分辨率比例是 16:9)。解决方案:
方案一:开发者自行将自定义视频采集的视频分辨率比例修改为 16:9。
方案二:开发者调用 setVideoConfig,将 SDK 的推流分辨率比例自定义为 4:3。
方案三:开发者调用 setCustomVideoCaptureFillMode 方法,设置为 “ZegoViewModeAspectFit” 等比缩放(带黑边)或者 “ZegoViewModeAspectFill” 等比填充(画面被裁剪)模式。
开启自定义视频采集后,采集的帧率和拉流播放帧率不一致?
当自定义采集的帧率和拉流播放帧率不一致时,可以通过如下方式处理:
SDK 接收视频帧数据方法内部对传入的数据是同步处理还是异步处理?
SDK 接收视频帧数据后,会先同步拷贝数据,然后再异步执行编码等操作,所以在将数据传入 SDK 后即可立即释放。
如何在自定义视频采集时实现视频旋转?
当开发者使用 自定义视频采集 时,监听设备方向变化后,可参考以下两种方式实现横竖屏切换:
联系我们
文档反馈