# 开发视频插件 (/zh-CN/realtime-media/marketplace/build/create-extensions/video-filter/ios) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文展示如何使用声网 SDK 提供的 API 开发一个视频插件。 开发视频插件需要使用以下接口: - `IExtensionVideoFilter`:实现视频数据的处理能力,包括接收、处理和返回处理完的视频帧。 - `IExtensionProvider`:将视频数据的处理能力封装为插件。 ## 前提条件 [#前提条件-1] 开发前,请确保你的开发环境满足以下要求: - Xcode 9.0 或以上版本。 - iOS 9.0 或以上版本的设备。 ## 准备开发环境 [#准备开发环境-1] 参考如下步骤将声网云市场的 API 添加到你的项目中: 1. 下载[视频 SDK v4.x](/zh-CN/realtime-media/rtc/reference/downloads),然后解压下载的 SDK 包。 2. 打开 **Xcode**,进入 **TARGETS** > **Project Name** > **General** > **Frameworks, Libraries, and Embedded Content** 菜单,点击 **+** > **Add Other...** > **Add Files**,将安装包中的 `/libs/AgoraRtcKit.framework` 文件添加至你的项目中。确保 **Embed** 属性设置为 **Do Not Embed**。 ## 开发视频插件 [#开发视频插件-1] ### 实现插件 [#实现插件-1] 视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法: - [`getProcessMode`](#getprocessmode-1) - [`start`](#start-1) - [`stop`](#stop-1) - [`getVideoFormatWanted`](#getvideoformatwanted-1) - [`adaptVideoFrame`](#adaptvideoframe-1) - [`pendVideoFrame`](#pendvideoframe-1) - [`deliverVideoFrame`(见 Control 定义)](#start-1) - [`setProperty`](#setproperty-1) - [`getProperty`](#getproperty-1) #### getProcessMode [#getprocessmode-1] 设置 SDK 与视频插件的交互模式。SDK 在加载插件时,会首先调用该方法向插件发送回调。收到该回调后,你需要在返回值中指定自己需要的交互模式。 ```cpp virtual void getProcessMode(ProcessMode& mode, bool& independent_thread) = 0; ``` | 参数 | 描述 | | --- | --- | | `mode` | [video-filter-android-ios-macos-windows-html-0-1-1 details](#table-slot-video-filter-android-ios-macos-windows-html-0-1-1-1) | | `independent_thread` | [video-filter-android-ios-macos-windows-html-0-2-1 details](#table-slot-video-filter-android-ios-macos-windows-html-0-2-1-1) | **video-filter-android-ios-macos-windows-html-0-1-1 details** SDK 和插件互相传递视频数据的模式,支持设为以下值: - `Sync`: 同步模式。该模式下,SDK 和插件通过 `adaptVideoFrame` 传递视频数据。 - `Async`: 异步模式。该模式下,SDK 通过 `pendVideoFrame` 将待处理的数据传给插件,插件通过 `deliverVideoFrame` 将处理后的数据返回给 SDK。 **video-filter-android-ios-macos-windows-html-0-2-1 details** 是否为插件创建独立的线程: - `true`: 为插件创建独立的线程。创建后,SDK 向插件发送的所有回调都在该独立线程上进行。 - `false`: 不为插件创建独立的线程。SDK 向插件发送的所有回调都在 SDK 的视频处理线程上进行。 你可以根据 YUV 运算的复杂度和是否使用 OpenGL 设置 `mode` 和 `independent_thread` 参数: - 根据 YUV 运算的复杂度设置: - 如果视频插件内部使用较复杂的 YUV 运算处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Async` 和 `false`。 - 如果视频插件内部使用简单的 YUV 运算处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Sync` 和 `false`。 - 如果视频插件内部使用了 OpenGL 处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Sync` 和 `true`。 #### start [#start-1] ```cpp virtual int start(agora::agora_refptr control) = 0; ``` 创建视频插件实例 `IExtensionVideoFilter` 后,会触发该回调。你可以在该回调中初始化 OpenGL。 SDK 会在该方法中传递一个 `Control` 对象,方便插件和 SDK 的后续交互。你需要保留收到的 `Control` 对象,并根据场景需要实现该对象中的相关方法: ```cpp class Control : public RefCountInterface { public: /** * 在异步模式下(mode 设为 Async),插件需要调用该方法向 SDK 返回处理后的视频帧。 * 使用该方法前,请确保 SDK 已经通过 pendVideoFrame 提交了待处理的视频帧。 */ virtual ProcessResult deliverVideoFrame(agora::agora_refptr frame) = 0; /** * 插件需要开辟新的内存空间时,可以调用该方法创建一个新的 IVideoFrame 对象。 * 例如:美颜插件如果需要同时保存原图和美化后的图片,可以调用该方法优化内存管理。你也可以自行管理内存。 */ virtual agora::agora_refptr getMemoryPool() = 0; /** * 插件可以调用该方法向 SDK 报告事件,SDK 会将该事件通知给 App。 */ virtual int postEvent(const char* key, const char* value) = 0; /** * 插件可以调用该方法向 SDK 打印日志。 */ virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; /** * 当插件内部出错且不可恢复时,可以调用该方法让 SDK 停止向插件发送视频帧。 * SDK 也会同步将该方法中设置的错误及具体报错信息同步给 App。 */ virtual void disableMe(int error, const char* msg) = 0; }; ``` #### stop [#stop-1] ```cpp virtual int stop() = 0; ``` 销毁视频插件实例 `IExtensionVideoFilter` 后,会触发该回调。你可以在该回调中释放 OpenGL。 #### getVideoFormatWanted [#getvideoformatwanted-1] 设置待处理视频数据的类型和格式。SDK 每向插件提供一帧待处理的视频数据,都会先调用该方法向插件发送回调。收到该回调后,你需要在返回值中指定这一帧的数据类型和格式。你可以给不同的视频帧指定不同的数据类型和格式。 ```cpp virtual void getVideoFormatWanted(VideoFrameData::Type& type, RawPixelBuffer::Format& format) = 0; ``` | 参数 | 描述 | | --- | --- | | `type` | 视频数据的类型,目前仅支持设为 `RawPixels`,代表原始数据。 | | `format` | [video-filter-android-ios-macos-windows-html-1-2-1 details](#table-slot-video-filter-android-ios-macos-windows-html-1-2-1-1) | **video-filter-android-ios-macos-windows-html-1-2-1 details** 视频数据的格式,支持设为以下值: - `Unknown`:未知格式。 - `I420`:I420 格式。 - `I422`:I422 格式。 - `NV21`:NV21 格式。 - `NV12`:NV12 格式。 - `RGBA`:RGBA 格式。 - `ARGB`:ARGB 格式。 - `BGRA`:BGRA 格式。 #### adaptVideoFrame [#adaptvideoframe-1] 处理视频帧。在同步模式下(`mode` 设为 `Sync`),SDK 通过该方法与视频插件互相传递数据。SDK 通过 `in` 将待处理的视频数据传递给插件,插件通过 `out` 将处理后的数据返回给 SDK。 ```cpp virtual ProcessResult adaptVideoFrame(agora::agora_refptr in, agora::agora_refptr& out) { return ProcessResult::kBypass; } ``` **参数** | 参数名 | 描述 | | :----- | :------------------------- | | `in` | 输入参数。待处理的视频帧。 | | `out` | 输出参数。处理后的视频帧。 | **返回值** 处理该视频帧的结果: - `Success`: 成功处理该视频帧。 - `ByPass`: 跳过处理该视频帧,并将它传递到后续链路。 - `Drop`: 丢弃该视频帧。 #### pendVideoFrame [#pendvideoframe-1] 提交待处理的视频帧。在异步模式下(`mode` 设为 `Async`),SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后,插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。 ```cpp virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) { return ProcessResult::kBypass; } ``` **参数** | 参数名 | 描述 | | :----- | :--------------- | | `frame` | 待处理的视频帧。 | **返回值** 处理该视频帧的结果: - `Success`: 成功处理该视频帧。 - `ByPass`: 跳过处理该视频帧,并将它传递到后续链路。 - `Drop`: 丢弃该视频帧。 #### setProperty [#setproperty-1] 设置视频插件属性。App 开发者调用 `setExtensionPropertyWithVendor` 时,SDK 会调用该方法。你需要返回视频插件的属性。 ```cpp int ExtensionVideoFilter::setProperty(const char *key, const void *buf, size_t buf_size) ``` | 参数 | 描述 | | :------- | :----------------------------------------------------------- | | `key` | 插件属性的 `key`。 | | `buf` | 插件属性 `key` 值对应的 buffer 地址,数据形式为 JSON 字符串。我们推荐使用第三方的 `nlohmann/json library` 开源库,帮助实现 C++ 的 struct 和 JSON 字符串之间的序列化和反序列化。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getProperty [#getproperty-1] 获取视频插件属性。App 开发者调用 `getProperty` 时,SDK 会调用该方法获取视频插件的属性。 ```cpp int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### 示例代码 [#示例代码-2] 参考如下示例代码了解如何使用上述方法实现一个视频插件: ```cpp #include "ExtensionVideoFilter.h" #include "../logutils.h" #include namespace agora { namespace extension { ExtensionVideoFilter::ExtensionVideoFilter(agora_refptr < ByteDanceProcessor > byteDanceProcessor): threadPool_(1) { byteDanceProcessor_ = byteDanceProcessor; } ExtensionVideoFilter::~ExtensionVideoFilter() { byteDanceProcessor_ -> releaseOpenGL(); } // 设置 SDK 与视频插件的交互模式。 void ExtensionVideoFilter::getProcessMode(ProcessMode & mode, bool & independent_thread) { mode = ProcessMode::kSync; independent_thread = false; mode_ = mode; } // 设置待处理视频数据的类型和格式。 void ExtensionVideoFilter::getVideoFormatWanted(rtc::VideoFrameData::Type & type, rtc::RawPixelBuffer::Format & format) { type = rtc::VideoFrameData::Type::kRawPixels; format = rtc::RawPixelBuffer::Format::kI420; } // 在 start 回调中保留 Control 对象并初始化 OpenGL int ExtensionVideoFilter::start(agora::agora_refptr < Control > control) { PRINTF_INFO("ExtensionVideoFilter::start"); if (!byteDanceProcessor_) { return -1; } if (control) { control_ = control; byteDanceProcessor_ -> setExtensionControl(control); } if (mode_ == ProcessMode::kAsync) { invoker_id = threadPool_.RegisterInvoker("thread_videofilter"); auto res = threadPool_.PostTaskWithRes(invoker_id, [byteDanceProcessor = byteDanceProcessor_] { return byteDanceProcessor -> initOpenGL(); }); isInitOpenGL = res.get(); } else { isInitOpenGL = byteDanceProcessor_ -> initOpenGL(); } return 0; } // 在 stop 回调中释放 OpenGL int ExtensionVideoFilter::stop() { PRINTF_INFO("ExtensionVideoFilter::stop"); if (byteDanceProcessor_) { byteDanceProcessor_ -> releaseOpenGL(); isInitOpenGL = false; } return 0; } // 如果 mode 设为 Async,则 SDK 和视频插件通过 pendVideoFrame 和 deliverVideoFrame 传递数据。 rtc::IExtensionVideoFilter::ProcessResult ExtensionVideoFilter::pendVideoFrame(agora::agora_refptr < rtc::IVideoFrame > frame) { if (!frame || !isInitOpenGL) { return kBypass; } bool isAsyncMode = (mode_ == ProcessMode::kAsync); if (isAsyncMode && byteDanceProcessor_ && control_ && invoker_id >= 0) { threadPool_.PostTask(invoker_id, [videoFrame = frame, byteDanceProcessor = byteDanceProcessor_, control = control_] { rtc::VideoFrameData srcData; videoFrame -> getVideoFrameData(srcData); byteDanceProcessor -> processFrame(srcData); control -> deliverVideoFrame(videoFrame); }); return kSuccess; } return kBypass; } // 如果 mode 设为 Sync,则 SDK 和视频插件通过 adaptVideoFrame 传递数据。 rtc::IExtensionVideoFilter::ProcessResult ExtensionVideoFilter::adaptVideoFrame(agora::agora_refptr < rtc::IVideoFrame > src, agora::agora_refptr < rtc::IVideoFrame > & dst) { if (!isInitOpenGL) { return kBypass; } bool isSyncMode = (mode_ == ProcessMode::kSync); if (isSyncMode && byteDanceProcessor_) { rtc::VideoFrameData srcData; src -> getVideoFrameData(srcData); byteDanceProcessor_ -> processFrame(srcData); dst = src; return kSuccess; } return kBypass; } // 设置视频插件属性。 int ExtensionVideoFilter::setProperty(const char * key, const void * buf, size_t buf_size) { PRINTF_INFO("setProperty %s %s", key, buf); std::string stringParameter((char * ) buf); byteDanceProcessor_ -> setParameters(stringParameter); return 0; } // 获取视频插件属性 int ExtensionVideoFilter::getProperty(const char * key, void * buf, size_t buf_size) { return -1; } } } ``` ### 封装插件 [#封装插件-1] 封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并至少实现如下方法: - [`enumerateExtensions`](#enumerateextensions-1) - [`createVideoFilter`](#createvideofilter-1) `IExtensionProvider` 是插件动态库的提供者,由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件,如视频前处理插件库可以提供不同功能的视频插件(Video filter)。每个插件是一个具体的 Extension 对象。 #### enumerateExtensions [#enumerateextensions-1] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | --- | --- | | `extension_list` | [video-filter-android-ios-macos-windows-html-2-1-1 details](#table-slot-video-filter-android-ios-macos-windows-html-2-1-1-1) | | `extension_count` | 支持封装的插件的总数量。 | **video-filter-android-ios-macos-windows-html-2-1-1 details** 插件的信息,包括插件类型和插件名称。支持的视频插件类型有: - `VIDEO_PRE_PROCESSING_FILTER`(上行) - `VIDEO_POST_PROCESSING_FILTER`(下行) 插件名由插件服务商指定,需要在 `IExtensionProvider` 对象内唯一。插件名为 String 型,支持如下字符: - 26 个小写字母 `a`~`z` - 数字和下划线(不能是第一个或最后一个) 如果插件名不符合规则,会无法通过编译。 其中,插件的信息定义如下: ```cpp // 插件类型指插件在音视频传输通道中的位置,分类如下: enum EXTENSION_TYPE { // 已废弃,请改用 AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER 或 AUDIO_POST_PROCESSING_FILTER AUDIO_FILTER, // 视频前处理插件 VIDEO_PRE_PROCESSING_FILTER, // 视频后处理插件 VIDEO_POST_PROCESSING_FILTER, // 预留参数 AUDIO_SINK, // 预留参数 VIDEO_SINK, // 用于处理本地采集(如耳返采集)的,用于本地播放的音频数据 AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER = 10000, // 经过 3A 算法后的本地音频数据后处理 AUDIO_POST_PROCESSING_FILTER = 10001, // 用于对远端用户的音频数据进行处理 AUDIO_REMOTE_USER_PLAYBACK_FILTER = 10002, }; // 插件的信息,包括插件类型和插件名称 struct ExtensionMetaInfo { EXTENSION_TYPE type; const char* extension_name; }; ``` 如果你在 `enumerateExtensions` 方法中返回的插件类型为 `VIDEO_PRE_PROCESSING_FILTER` 或 `VIDEO_POST_PROCESSING_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionVideoProvider` 对象后,SDK 会调用 `createVideoFilter` 方法。 #### createVideoFilter [#createvideofilter-1] 创建视频插件。SDK 调用该方法后,你需要返回 `IExtensionVideoFilter` 实例。 ```cpp virtual agora_refptr createVideoFilter(const char* name) { return NULL; } ``` 成功创建 `IExtensionVideoFilter` 实例后,视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。 #### 示例代码 [#示例代码-3] 参考如下示例代码了解如何使用上述方法封装视频插件: ```cpp #include "ExtensionProvider.h" #include "../logutils.h" #include "VideoProcessor.h" #include "plugin_source_code/JniHelper.h" namespace agora { namespace extension { ExtensionProvider::ExtensionProvider() { PRINTF_INFO("ExtensionProvider create"); byteDanceProcessor_ = new agora::RefCountedObject < ByteDanceProcessor > (); audioProcessor_ = new agora::RefCountedObject < AdjustVolumeAudioProcessor > (); } ExtensionProvider::~ExtensionProvider() { PRINTF_INFO("ExtensionProvider destroy"); byteDanceProcessor_.reset(); audioProcessor_.reset(); } // 提供所有支持封装的插件的信息。 void ExtensionProvider::enumerateExtensions(ExtensionMetaInfo * extension_list, int & extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::VIDEO_PRE_PROCESSING_FILTER; i.extension_name = "YourExtensionName"; extension_list[0] = i; } // 创建视频插件。 agora_refptr < agora::rtc::IExtensionVideoFilter > ExtensionProvider::createVideoFilter(const char * name) { PRINTF_INFO("ExtensionProvider::createVideoFilter %s", name); auto videoFilter = new agora::RefCountedObject < agora::extension::ExtensionVideoFilter > (byteDanceProcessor_); return videoFilter; } void ExtensionProvider::setExtensionControl(rtc::IExtensionControl * control) {} } } ``` ### 实现插件 [#实现插件-2] 视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法: - [`getProcessMode`](#getprocessmode-2) - [`start`](#start-2) - [`stop`](#stop-2) - [`getVideoFormatWanted`](#getvideoformatwanted-2) - [`adaptVideoFrame`](#adaptvideoframe-2) - [`pendVideoFrame`](#pendvideoframe-2) - [`deliverVideoFrame`(见 Control 定义)](#start-2) - [`setProperty`](#setproperty-2) - [`getProperty`](#getproperty-2) #### getProcessMode [#getprocessmode-2] 设置 SDK 与视频插件的交互模式。SDK 在加载插件时,会首先调用该方法向插件发送回调。收到该回调后,你需要在返回值中指定自己需要的交互模式。 ```cpp virtual void getProcessMode(ProcessMode& mode, bool& independent_thread) = 0; ``` | 参数 | 描述 | | --- | --- | | `mode` | [video-filter-android-ios-macos-windows-html-3-1-1 details](#table-slot-video-filter-android-ios-macos-windows-html-3-1-1) | | `independent_thread` | [video-filter-android-ios-macos-windows-html-3-2-1 details](#table-slot-video-filter-android-ios-macos-windows-html-3-2-1) | **video-filter-android-ios-macos-windows-html-3-1-1 details** SDK 和插件互相传递视频数据的模式,支持设为以下值: - `Sync`: 同步模式。该模式下,SDK 和插件通过 `adaptVideoFrame` 传递视频数据。 - `Async`: 异步模式。该模式下,SDK 通过 `pendVideoFrame` 将待处理的数据传给插件,插件通过 deliverVideoFrame 将处理后的数据返回给 SDK。 **video-filter-android-ios-macos-windows-html-3-2-1 details** 是否为插件创建独立的线程: - `true`: 为插件创建独立的线程。创建后,SDK 向插件发送的所有回调都在该独立线程上进行。 - `false`: 不为插件创建独立的线程。SDK 向插件发送的所有回调都在 SDK 的视频处理线程上进行。 你可以参考以下标准设置 `mode` 和 `independent_thread` 参数: - 根据 YUV 运算的复杂度和是否使用 OpenGL 设置: - 如果视频插件内部使用较复杂的 YUV 运算处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Async` 和 `false`。 - 如果视频插件内部使用简单的 YUV 运算处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Sync` 和 `false`。 - 如果视频插件内部使用了 OpenGL 处理数据,推荐将 `mode` 和 `independent_thread` 分别设为 `Sync` 和 `true`。 #### start [#start-2] ```cpp virtual int start(agora::agora_refptr control) = 0; ``` 创建视频插件实例 `IExtensionVideoFilter` 后,会触发该回调。你可以在该回调中初始化 OpenGL。 SDK 会在该方法中传递一个 `Control` 对象,方便插件和 SDK 的后续交互。你需要保留收到的 `Control` 对象,并根据场景需要实现该对象中的相关方法: ```cpp class Control : public RefCountInterface { public: /** * 在异步模式下(mode 设为 Async),插件需要调用该方法向 SDK 返回处理后的视频帧。 * 使用该方法前,请确保 SDK 已经通过 pendVideoFrame 提交了待处理的视频帧。 */ virtual ProcessResult deliverVideoFrame(agora::agora_refptr frame) = 0; /** * 插件需要开辟新的内存空间时,可以调用该方法创建一个新的 IVideoFrame 对象。 * 例如:美颜插件如果需要同时保存原图和美化后的图片,可以调用该方法优化内存管理。你也可以自行管理内存。 */ virtual agora::agora_refptr getMemoryPool() = 0; /** * 插件可以调用该方法向 SDK 报告事件,SDK 会将该事件通知给 App。 */ virtual int postEvent(const char* key, const char* value) = 0; /** * 插件可以调用该方法向 SDK 打印日志。 */ virtual void printLog(commons::LOG_LEVEL level, const char* format, ...) = 0; /** * 当插件内部出错且不可恢复时,可以调用该方法让 SDK 停止向插件发送视频帧。 * SDK 也会同步将该方法中设置的错误及具体报错信息同步给 App。 */ virtual void disableMe(int error, const char* msg) = 0; }; ``` #### stop [#stop-2] ```cpp virtual int stop() = 0; ``` 销毁视频插件实例 `IExtensionVideoFilter` 后,会触发该回调。你可以在该回调中释放 OpenGL。 #### getVideoFormatWanted [#getvideoformatwanted-2] 设置待处理视频数据的类型和格式。SDK 每向插件提供一帧待处理的视频数据,都会先调用该方法向插件发送回调。收到该回调后,你需要在返回值中指定这一帧的数据类型和格式。你可以给不同的视频帧指定不同的数据类型和格式。 ```cpp virtual void getVideoFormatWanted(VideoFrameData::Type& type, RawPixelBuffer::Format& format) = 0; ``` | 参数 | 描述 | | --- | --- | | `type` | 视频数据的类型,目前仅支持设为 `RawPixels`,代表原始数据。 | | `format` | [video-filter-android-ios-macos-windows-html-4-2-1 details](#table-slot-video-filter-android-ios-macos-windows-html-4-2-1) | **video-filter-android-ios-macos-windows-html-4-2-1 details** 视频数据的格式,支持设为以下值: - `Unknown`:未知格式。 - `I420`:I420 格式。 - `I422`:I422 格式。 - `NV21`:NV21 格式。 - `NV12`:NV12 格式。 - `RGBA`:RGBA 格式。 - `ARGB`:ARGB 格式。 - `BGRA`:BGRA 格式。 #### adaptVideoFrame [#adaptvideoframe-2] 处理视频帧。在同步模式下(`mode` 设为 `Sync`),SDK 通过该方法与视频插件互相传递数据。SDK 通过 `in` 将待处理的视频数据传递给插件,插件通过 `out` 将处理后的数据返回给 SDK。 ```cpp virtual ProcessResult adaptVideoFrame(agora::agora_refptr in, agora::agora_refptr& out) { return ProcessResult::kBypass; } ``` **参数** | 参数名 | 描述 | | :----- | :------------------------- | | `in` | 输入参数。待处理的视频帧。 | | `out` | 输出参数。处理后的视频帧。 | **返回值** 处理该视频帧的结果: - `Success`: 成功处理该视频帧。 - `ByPass`: 跳过处理该视频帧,并将它传递到后续链路。 - `Drop`: 丢弃该视频帧。 #### pendVideoFrame [#pendvideoframe-2] 提交待处理的视频帧。在异步模式下(`mode` 设为 `Async`),SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后,插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。 ```cpp virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) { return ProcessResult::kBypass; } ``` **参数** | 参数名 | 描述 | | :----- | :--------------- | | `frame` | 待处理的视频帧。 | **返回值** 处理该视频帧的结果: - `Success`: 成功处理该视频帧。 - `ByPass`: 跳过处理该视频帧,并将它传递到后续链路。 - `Drop`: 丢弃该视频帧。 #### setProperty [#setproperty-2] 设置视频插件属性。App 开发者调用 `setExtensionPropertyWithVendor` 时,SDK 会调用该方法。你需要返回视频插件的属性。 ```cpp int ExtensionVideoFilter::setProperty(const char *key, const void *buf, size_t buf_size) ``` | 参数 | 描述 | | :------- | :----------------------------------------------------------- | | `key` | 插件属性的 `key`。 | | `buf` | 插件属性 `key` 值对应的 buffer 地址,数据形式为 JSON 字符串。我们推荐使用第三方的 `nlohmann/json library` 开源库,帮助实现 C++ 的 struct 和 JSON 字符串之前的序列和反序列化。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getProperty [#getproperty-2] 获取视频插件属性。App 开发者调用 `getProperty` 时,SDK 会调用该方法获取视频插件的属性。 ```cpp int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### 示例代码 [#示例代码-4] 参考如下示例代码了解如何使用上述方法实现一个视频插件: ```cpp #include "BDVideoFilterCpp.h" #include "BDVideoFilterCpp.h" namespace agora { namespace rtc { BDVideoFilterCpp::BDVideoFilterCpp(): mode_(ProcessMode::kSync), opengl_released_(false) { } BDVideoFilterCpp::~BDVideoFilterCpp() { releaseOpenGL(); opengl_released_ = true; delete processor_; processor_ = nullptr; } // 设置 SDK 与视频插件的交互模式。 void BDVideoFilterCpp::getProcessMode(ProcessMode & mode, bool & isolated) { mode = ProcessMode::kSync; isolated = false; mode_ = mode; } // 在 start 回调中传递 Control 对象和初始化 OpenGL int BDVideoFilterCpp::start(agora::agora_refptr < Control > control) { if (control) { control_ = control; } processor_ = new ByteDance::Extension::BDProcessorCpp(control_); initOpenGL(); makeCurrent(); return 0; } // 在 stop 回调中释放 OpenGL int BDVideoFilterCpp::stop() { releaseOpenGL(); opengl_released_ = true; return 0; } // 设置待处理视频数据的类型和格式。 void BDVideoFilterCpp::getVideoFormatWanted(VideoFrameData::Type & type, RawPixelBuffer::Format & format) { type = VideoFrameData::Type::kRawPixels; format = RawPixelBuffer::Format::kI420; } // 如果 mode 设为 Async,则 SDK 和视频插件通过 pendVideoFrame 和 deliverVideoFrame 传递数据。 IExtensionVideoFilter::ProcessResult BDVideoFilterCpp::pendVideoFrame(agora::agora_refptr < IVideoFrame > frame) { @autoreleasepool { if (!frame) { return kBypass; } bool isAsyncMode = (mode_ == ProcessMode::kAsync); if (isAsyncMode) { if (processor_ && control_) { VideoFrameData data; frame -> getVideoFrameData(data); processor_ -> processFrame(data); auto dst = control_ -> getMemoryPool() -> createVideoFrame(data); control_ -> deliverVideoFrame(dst); return kSuccess; } return kBypass; } return kBypass; } } // 如果 mode 设为 Sync,则 SDK 和视频插件通过 adaptVideoFrame 传递数据。 IExtensionVideoFilter::ProcessResult BDVideoFilterCpp::adaptVideoFrame(agora::agora_refptr < IVideoFrame > src, agora::agora_refptr < IVideoFrame > & dst) { @autoreleasepool { bool isSyncMode = (mode_ == ProcessMode::kSync); if (isSyncMode) { if (processor_ && control_) { VideoFrameData srcData; src -> getVideoFrameData(srcData); processor_ -> processFrame(srcData); dst = control_ -> getMemoryPool() -> createVideoFrame(srcData); return kSuccess; } return kBypass; } return kBypass; } } // 设置视频插件属性。 int BDVideoFilterCpp::setProperty(const char * key, const void * buf, size_t buf_size) { @autoreleasepool { if (!buf || !key || * key == 0) { return -1; } if (!processor_) { return -1; } std::string param((char * ) buf); processor_ -> setParameters(param); return 0; } } // 获取视频插件属性 int BDVideoFilterCpp::getProperty(const char * key, void * buf, size_t buf_size) { return -1; } void BDVideoFilterCpp::initOpenGL() { if (_context == nil) { _context = [ [EAGLContext alloc] initWithAPI: kEAGLRenderingAPIOpenGLES2 ]; } [EAGLContext setCurrentContext: _context]; } void BDVideoFilterCpp::releaseOpenGL() { [EAGLContext setCurrentContext: nil]; _context = nil; } void BDVideoFilterCpp::makeCurrent() { EAGLContext * prev = [EAGLContext currentContext]; if (prev != _context) { [EAGLContext setCurrentContext: _context]; } } } } ``` ### 封装插件 [#封装插件-2] 封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并至少实现如下方法: - [`enumerateExtensions`](#enumerateextensions-2) - [ `createVideoFilter`](#createvideofilter-2) #### enumerateExtensions [#enumerateextensions-2] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | :--------------- | :----------------------------------- | | `extension_list` | 插件的信息,包括插件类型和插件名称。 | | `extension_count` | 支持封装的插件的总数量。 | 其中,插件的信息定义如下: ```cpp // 插件类型指插件在音视频传输通道中的位置,分类如下: enum EXTENSION_TYPE { // 音频处理插件 AUDIO_FILTER, // 视频前处理插件 VIDEO_PRE_PROCESSING_FILTER, // 视频后处理插件 VIDEO_POST_PROCESSING_FILTER, // 预留参数 AUDIO_SINK, // 预留参数 VIDEO_SINK, // 预留参数 UNKNOWN, }; // 插件的信息,包括插件类型和插件名称 struct ExtensionMetaInfo { EXTENSION_TYPE type; const char* extension_name; }; ``` 如果你在 `enumerateExtensions` 方法中返回的插件类型为 `VIDEO_PRE_PROCESSING_FILTER` 或 `VIDEO_POST_PROCESSING_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionVideoProvider` 对象后,SDK 会调用 `createVideoFilter` 方法。 #### createVideoFilter [#createvideofilter-2] 创建视频插件。SDK 调用该方法后,你需要返回 `IExtensionVideoFilter` 实例。 ```cpp virtual agora_refptr createVideoFilter(const char* name) { return NULL; } ``` 成功创建 `IExtensionVideoFilter` 实例后,视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。 #### 示例代码 [#示例代码-5] 参考如下示例代码了解如何使用上述方法封装视频插件: ```cpp #import "BDVideoFilterProviderCpp.h" #include "BDVideoFilterCpp.h" #include #include #include // 注册视频插件 REGISTER_AGORA_EXTENSION_PROVIDER(ByteDance, agora::rtc::BDVideoFilterProviderCpp); namespace agora { namespace rtc { BDVideoFilterProviderCpp::BDVideoFilterProviderCpp(): control_(nullptr) { } BDVideoFilterProviderCpp::~BDVideoFilterProviderCpp() { control_ = nullptr; } // 提供所有支持封装的插件的信息。 void BDVideoFilterProviderCpp::enumerateExtensions(ExtensionMetaInfo * extension_list, int & extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::VIDEO_PRE_PROCESSING_FILTER; i.extension_name = "Beauty"; extension_list[0] = i; } // 创建视频插件。 agora_refptr < IExtensionVideoFilter > BDVideoFilterProviderCpp::createVideoFilter(const char * name) { return new RefCountedObject < BDVideoFilterCpp > (); } int BDVideoFilterProviderCpp::log(int level, const char * message) { if (!control_) { return -1; } return control_ -> log(static_cast < commons::LOG_LEVEL > (level), message); } int BDVideoFilterProviderCpp::fireEvent(const char * provider_name, const char * ext_name, const char * event_key, const char * event_json_str) { if (!control_) { return -1; } return control_ -> fireEvent(provider_name, ext_name, event_key, event_json_str); } } } ``` ## 打包视频插件 [#打包视频插件-1] 完成插件开发后,你需要对其进行注册、打包,并将最终的 `.framework` 或 `.xcframework` 文件,连同一个包含了插件名称、服务商名称和 Filter 名称的文件提交给声网进行验证。 插件通过宏 `REGISTER_AGORA_EXTENSION_PROVIDER` 进行注册,该宏位于 `AgoraExtensionProviderEntry.h` 文件中。 你需要在插件的入口使用这个宏。SDK 在加载插件时,该宏会自动向 SDK 注册你的插件。注意填入 `PROVIDER_NAME` 时不要填写标点符号。示例: ```cpp REGISTER_AGORA_EXTENSION_PROVIDER(ByteDance, agora::extension::ExtensionProvider); ``` ## 示例项目 [#示例项目-1] 声网提供一个 iOS 插件开发的示例项目 [SimpleFilter](https://github.com/AgoraIO/API-Examples/tree/4.0.0-GA/iOS/SimpleFilter) 供你参考。