// // ARMediaIO.h // ARtcKit // // Created by 余生丶 on 2020/6/15. // Copyright © 2020 zjq. All rights reserved. // #import #import #import "AREnumerates.h" /** 视频像素格式 关于 YVU 图像格式的描述，请参考： FourCC YUV 格式说明 Recommended 8-Bit YUV Formats for Video Rendering */ typedef NS_ENUM(NSUInteger, ARVideoPixelFormat) { /** I420 */ ARVideoPixelFormatI420 = 1, /** BGRA */ ARVideoPixelFormatBGRA = 2, /** NV12 */ ARVideoPixelFormatNV12 = 8, }; /** 视频的顺时针旋转角度 如果设置为其他数字，系统会自动忽略 */ typedef NS_ENUM(NSInteger, ARVideoRotation) { /** 顺时针旋转 0 度 */ ARVideoRotationNone = 0, /** 顺时针旋转 90 度*/ ARVideoRotation90 = 1, /** 顺时针旋转 180 度 */ ARVideoRotation180 = 2, /** 顺时针旋转 270 度 */ ARVideoRotation270 = 3, }; /** ARVideoFrameConsumer 支持接收两种 Buffer 类型的视频帧数据：PixelBuffer 和裸数据。 自定义视频源时，开发者需要通过 bufferType 来指定一种 Buffer 类型，并在自定义视频源中只使用与其对应的方法来传递视频帧数据。 */ @protocol ARVideoFrameConsumer /** PixelBuffer 类型 @param pixelBuffer PixelBuffer 类型的视频 Buffer @param timestamp 传入的视频帧的时间戳，开发者必须为每一个视频帧设置一个时间戳。 @param rotation 视频的顺时针旋转角度， 详见 ARVideoRotation */ - (void)consumePixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer withTimestamp:(CMTime)timestamp rotation:(ARVideoRotation)rotation; /** RawData 类型 @param rawData RawData 类型的视频 Buffer @param timestamp 传入的视频帧的时间戳，以毫秒为单位。 @param format ARVideoPixelFormat @param size 视频裸数据的尺寸 @param rotation 视频的顺时针旋转角度， 详见 ARVideoRotation */ - (void)consumeRawData:(void * _Nonnull)rawData withTimestamp:(CMTime)timestamp format:(ARVideoPixelFormat)format size:(CGSize)size rotation:(ARVideoRotation)rotation; @end /** ARVideoSourceProtocol 协议 ARVideoSourceProtocol 定义了一套协议，开发者通过实现该接口，来创建自定义的视频源，并设置给 sdk 底层的 Media Engine 实时通讯过程中，SDK 通常会启动默认的视频输入设备，即内置的摄像头，进行视频推流。 使用 ARVideoSourceProtocol 接口可以自定义视频源。通过调用 设置视频源 setVideoSource 接口，可以改变并控制默认的视频输入设备，再将自定义的视频源发送给 Media Engine，让 Media Engine 进行其它视频处理，如过滤视频、将视频发布到 RTC 链接等。 */ @protocol ARVideoSourceProtocol @required /** ARVideoFrameConsumer 协议，详见 ARVideoFrameConsumer */ @property (strong) id _Nullable consumer; /** 初始化视频源 Media Engine 在初始化视频源的时候会回调此方法。开发者可以在这个方法中做一些准备工作，例如打开 Camera，或者初始化视频源，并通过返回值告诉 Media Engine，自定义的视频源是否已经准备好。 **Note** 初始化视频源过程中，开发者需要在 bufferType 中指定一种 Buffer 类型，并在自定义视频源中只使用与其对应的方法来传递视频帧数据。 在初始化视频源过程中，Media Engine 会传递给开发者的一个 ARVideoFrameConsumer 对象。开发者需要保存该对象，并在视频源启动后，通过这个对象把视频帧输入给 Media Engine。 开发者需要手动输入 YES 或 NO，以告诉 Media Engine 自定义视频源是否已准备好。 @return 初始化状态： * YES: 自定义的视频源已经完成了初始化工作 * NO: 自定义的视频源设备没准备好或者初始化失败，Media Engine 会停下来并上报错误 */ - (BOOL)shouldInitialize; /** 启动视频源 Media Engine 在启动视频源时会回调这个方法。开发者可以在该方法中启动视频帧捕捉。开发者需要通过返回值告诉告知 Media Engine 自定义的视频源是否开启成功。 开发者需要手动输入 YES 或 NO，以告诉 Media Engine 自定义视频源是否开启： * YES:自定义的视频源已成功开启，接下来会打开 ARVideoFrameConsumer 的开关，接收开发者传输的视频帧 * NO：自定义的视频源设备启动失败，Media Engine 会停下来并上报错误 */ - (void)shouldStart; /** 停止视频源 Media Engine 在停止视频源的时候会回调这个方法。开发者可以在这个方法中停止视频的采集。Media Engine 通过这个回调通知开发者，ARVideoFrameConsumer 的帧输入开关即将关闭，之后输入的视频帧都会被丢弃。 */ - (void)shouldStop; /** 释放视频源 Media Engine 通知开发者视频源即将失效，开发者可以在这个方法中关闭视频源设备。引擎会销毁 ARVideoFrameConsumer 对象，开发者需要确保在此回调之后不再使用它。 */ - (void)shouldDispose; /** 获取 Buffer 类型 Media Engine 在初始化的时候，会调用这个方法来查询该视频源所使用的 Buffer 类型。开发者必须指定且只能指定一种 Buffer 类型并通过返回值告诉 Media Engine @return ARVideoBufferType */ - (ARVideoBufferType)bufferType; @end /** ARVideoSinkProtocol 协议 ARVideoSinkProtocol 定义了一套协议，开发者通过实现该接口，来创建自定义的视频渲染器，并设置给底层的 Media Engine。 实时通讯过程中，SDK 通常会启动默认的视频渲染器进行视频渲染。 ARVideoSinkProtocol 可以自定义视频渲染器，再通过调用 设置本地视频渲染器 setLocalVideoRenderer 和 设置远端视频渲染器 setRemoteVideoRenderer 接口，改变并控制默认的视频渲染器。 ARVideoSinkProtocol 由以下方法组成: - 初始化渲染器(shouldInitialize) - 启动渲染器 (shouldStart) - 停止渲染器 (shouldStop) - 释放渲染器 (shouldDispose) - 获取 Buffer 类型 (AgoraVideoBufferType) - 获取像素格式 (AgoraVideoPixelFormat) - (可选) 输出视频像素 Buffer (renderPixelBuffer) - (可选) 输出视频裸数据 (renderRawData) Note: ARVideoSinkProtocol 接口中定义的所有方法都是回调方法，Media Engine 内部维护着状态机，并使用这些方法将自定义视频源及渲染器的状态传给 Media Engine。因此请避免直接在 App 中直接调用这些接口。 下面这个例子给出了自定义 video sink 的步骤： - 调用 bufferType 和 AgoraVideoPixelFormat 方法设置视频帧的 Buffer 类型和像素格式。 - 实现 shouldInitialize、shouldStart、shouldStop 和 shouldDispose 管理自定义的 Video Sink。 - 根据 ARVideoFrameConsumer 实现 buffer 类型和像素格式。 - 创建 ARVideoFrameConsumer 自定义的 Video Sink 对象。 - 调用 setLocalVideoRenderer 和 setRemoteVideoRenderer 方法设置本地和远端视频渲染器。 - Media Engine 会根据内部状态调用 ARVideoSinkProtocol 接口中的方法。 */ @protocol ARVideoSinkProtocol @required /** 初始化渲染器 Media Engine 初始化渲染器的时候调用这个方法。开发者可以在这个方法中做渲染器的初始化工作。如果是耗时操作，也可以提前初始化好，然后在这个方法中通过返回值告知 Media Engine 自定义渲染器已初始化好。 该方法需要开发者手动输入 YES 或 NO，告知 Media Engine 自定义渲染器的状态。 @return - YES: Media Engine 会认为自定义的渲染器已经初始化好 - NO: Media Engine 会认为自定义的渲染器初始化失败，不继续往下运行 */ - (BOOL)shouldInitialize; /** 启动渲染器 Media Engine 在开启渲染功能的时候会回调这个方法。开发者可以在这个方法中启动渲染器。 该方法需要开发者手动输入 YES 或 NO，Media Engine 会根据输入值做对应的动作： - YES: Media Engine 继续进行渲染 - NO：Media Engine 认为出错而停止渲染器的功能 */ - (void)shouldStart; /** 停止渲染器 Media Engine 在停止渲染功能的时候会回调这个方法。开发者可以在这个方法中停止渲染。 */ - (void)shouldStop; /** 释放渲染器 Media Engine 通知开发者渲染器即将被废弃。在 shouldDispose 返回之后，开发者就可以释放掉资源了。 */ - (void)shouldDispose; /** 获取 Buffer 类型 用于在自定义渲染器的时候，需要指定 Buffer 类型，通过返回值告知引擎。Media Engine 会调用这个方法并检查返回值类型。 @return Buffer 类型 */ - (ARVideoBufferType)bufferType; /** 获取像素格式 @return 用于自定义渲染器的时候，还需要指定视频数据的像素格式。 */ - (ARVideoPixelFormat)pixelFormat; @optional /** （可选）输出视频的 PixelBuffer @param pixelBuffer 视频的 PixelBuffer @param rotation 视频像素的顺时针旋转角度, ARVideoRotation */ - (void)renderPixelBuffer:(CVPixelBufferRef _Nonnull)pixelBuffer rotation:(ARVideoRotation)rotation; /** 输出视频裸数据 @param rawData RawData 格式的视频 @param size 视频的尺寸 @param rotation 视频的顺时针旋转角度, ARVideoRotation */ - (void)renderRawData:(void * _Nonnull)rawData size:(CGSize)size rotation:(ARVideoRotation)rotation; @end