# 开发视频插件 (/zh-CN/realtime-media/marketplace/build/create-extensions/video-filter)
> For AI agents: see the complete documentation index at [llms.txt](/llms.txt).
<_PlatformTabsGroup>
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" />
本文展示如何使用声网 SDK 提供的 API 开发一个视频插件。开发视频插件需要使用以下接口：
- `IExtensionVideoFilter`：实现视频数据的处理能力，包括接收、处理和返回处理完的视频帧。
- `IExtensionProvider`：将视频数据的处理能力封装为插件。
## 前提条件 [#前提条件]
开发前，请确保你的开发环境满足以下要求：
- Android Studio 3.0 或以上版本。
- Android API 级别 16 或以上。
## 准备开发环境 [#准备开发环境]
参考如下步骤将声网云市场的 API 添加到你的项目中：
1. 下载[视频 SDK v4.x](/zh-CN/realtime-media/rtc/reference/downloads)，然后解压下载的 SDK 包。
2. 将 SDK 包中的 `/rtc/sdk/low_level_api/include` 路径下的头文件拷贝至你的项目文件夹中。
## 开发视频插件 [#开发视频插件]
### 实现插件 [#实现插件]
视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法：
- [`getProcessMode`](#getprocessmode)
- [`start`](#start)
- [`stop`](#stop)
- [`getVideoFormatWanted`](#getvideoformatwanted)
- [`adaptVideoFrame`](#adaptvideoframe)
- [`pendVideoFrame`](#pendvideoframe)
- [`deliverVideoFrame`](#delivervideoframe)
- [`setProperty`](#setproperty)
- [`getProperty`](#getproperty)
#### getProcessMode [#getprocessmode]
设置 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) |
| `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) |
**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]
```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]
```cpp
virtual int stop() = 0;
```
销毁视频插件实例 `IExtensionVideoFilter` 后，会触发该回调。你可以在该回调中释放 OpenGL。
#### getVideoFormatWanted [#getvideoformatwanted]
设置待处理视频数据的类型和格式。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) |
**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]
处理视频帧。在同步模式下（`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]
提交待处理的视频帧。在异步模式下（`mode` 设为 `Async`），SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后，插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。
```cpp
virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) {
return ProcessResult::kBypass;
}
```
**参数**
| 参数名 | 描述 |
| :----- | :--------------- |
| `frame` | 待处理的视频帧。 |
**返回值**
处理该视频帧的结果：
- `Success`: 成功处理该视频帧。
- `ByPass`: 跳过处理该视频帧，并将它传递到后续链路。
- `Drop`: 丢弃该视频帧。
#### setProperty [#setproperty]
设置视频插件属性。App 开发者调用 `setExtensionProperty` 时，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]
获取视频插件属性。App 开发者调用 `getProperty` 时，SDK 会调用该方法获取视频插件的属性。
```cpp
int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size)
```
| 参数 | 描述 |
| :------- | :--------------------------- |
| `key` | 插件属性的 `key`。 |
| `property` | 插件属性指针。 |
| `buf_size` | 插件属性 buffer 的内存大小。 |
#### 示例代码 [#示例代码]
参考如下示例代码了解如何使用上述方法实现一个视频插件：
```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;
}
}
}
```
### 封装插件 [#封装插件]
封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类，并至少实现如下方法：
- [`enumerateExtensions`](#enumerateextensions)
- [`createVideoFilter`](#createvideofilter)
`IExtensionProvider` 是插件动态库的提供者，由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件，如视频前处理插件库可以提供不同功能的视频插件（Video filter）。每个插件是一个具体的 Extension 对象。
#### enumerateExtensions [#enumerateextensions]
提供所有支持封装的插件的信息。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) |
| `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]
创建视频插件。SDK 调用该方法后，你需要返回 `IExtensionVideoFilter` 实例。
```cpp
virtual agora_refptr createVideoFilter(const char* name) {
return NULL;
}
```
成功创建 `IExtensionVideoFilter` 实例后，视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。
#### 示例代码 [#示例代码-1]
参考如下示例代码了解如何使用上述方法封装视频插件：
```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) {}
}
}
```
## 打包视频插件 [#打包视频插件]
完成插件开发后，你需要对其进行注册、打包，并将最终的 `.aar` 或 `.so` 文件，连同一个包含了插件名称、服务商名称和 Filter 名称的文件提交给声网进行验证。
### 注册插件 [#注册插件]
插件通过宏 `REGISTER_AGORA_EXTENSION_PROVIDER` 进行注册，该宏位于 `AgoraExtensionProviderEntry.h` 文件中。
你需要在插件的入口使用这个宏。SDK 在加载插件时，该宏会自动向 SDK 注册你的插件。注意填入 `PROVIDER_NAME` 时不要填写标点符号。示例：
```cpp
REGISTER_AGORA_EXTENSION_PROVIDER(ByteDance, agora::extension::ExtensionProvider);
```
在 `CMakeLists.txt` 文件中，按照下表指定 SDK 包中 `libagora-rtc-sdk-jni.so` 文件的存储路径：
| 依赖文件 | 存储路径 |
| ---------------- | ---------------- |
| 64 位的 `libagora-rtc-sdk-jni.so` | `AgoraWithByteDanceAndroid/agora-bytedance/src/main/agoraLibs/arm64-v8a` |
| 32 位的 `libagora-rtc-sdk-jni.so` | `AgoraWithByteDanceAndroid/agora-bytedance/src/main/agoraLibs/arm64-v7a` |
### 提供插件信息 [#提供插件信息]
新建一个 `.java` 或 `.md` 文件，并在其中填入如下信息：
- `EXTENSION_NAME`：插件包的名称，如 `libagora-bytedance.so` 文件的 `EXTENSION_NAME` 就是 `agora-bytedance`。
- `EXTENSION_VENDOR_NAME`：服务商名称，即插件的 `Provider` 对象名称，用于在 `.cpp` 文件中进行注册。
- `EXTENSION_FILTER_NAME`：`ExtensionProvider.h` 文件中定义的 Filter 名称。
## 示例项目 [#示例项目]
声网提供一个 Android 插件开发的示例项目 [agora-simple-filter](https://github.com/AgoraIO/API-Examples/tree/main/Android/APIExample/agora-simple-filter) 供你参考。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="ios" />
本文展示如何使用声网 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) 供你参考。
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="macos" />
本文展示如何使用声网 SDK 提供的 API 开发一个视频插件。
开发视频插件需要使用以下接口：
- `IExtensionVideoFilter`：实现视频数据的处理能力，包括接收、处理和返回处理完的视频帧。
- `IExtensionProvider`：将视频数据的处理能力封装为插件。
## 前提条件 [#前提条件-2]
开发前，请确保你的开发环境满足以下要求：
- Xcode 9.0 或以上版本。
- macOS 10.10 或以上版本的设备。
## 准备开发环境 [#准备开发环境-2]
参考如下步骤将声网云市场的 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**。
## 开发视频插件 [#开发视频插件-2]
### 实现插件 [#实现插件-3]
视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法：
- [`getProcessMode`](#getprocessmode-3)
- [`start`](#start-3)
- [`stop`](#stop-3)
- [`getVideoFormatWanted`](#getvideoformatwanted-3)
- [`adaptVideoFrame`](#adaptvideoframe-3)
- [`pendVideoFrame`](#pendvideoframe-3)
- [`deliverVideoFrame`（见 Control 定义）](#start-3)
- [`setProperty`](#setproperty-3)
- [`getProperty`](#getproperty-3)
#### getProcessMode [#getprocessmode-3]
设置 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-2) |
| `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-2) |
**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-3]
```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-3]
```cpp
virtual int stop() = 0;
```
销毁视频插件实例 `IExtensionVideoFilter` 后，会触发该回调。你可以在该回调中释放 OpenGL。
#### getVideoFormatWanted [#getvideoformatwanted-3]
设置待处理视频数据的类型和格式。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-2) |
**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-3]
处理视频帧。在同步模式下（`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-3]
提交待处理的视频帧。在异步模式下（`mode` 设为 `Async`），SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后，插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。
```cpp
virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) {
return ProcessResult::kBypass;
}
```
**参数**
| 参数名 | 描述 |
| :----- | :--------------- |
| `frame` | 待处理的视频帧。 |
**返回值**
处理该视频帧的结果：
- `Success`: 成功处理该视频帧。
- `ByPass`: 跳过处理该视频帧，并将它传递到后续链路。
- `Drop`: 丢弃该视频帧。
#### setProperty [#setproperty-3]
设置视频插件属性。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-3]
获取视频插件属性。App 开发者调用 `getProperty` 时，SDK 会调用该方法获取视频插件的属性。
```cpp
int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size)
```
| 参数 | 描述 |
| :------- | :--------------------------- |
| `key` | 插件属性的 `key`。 |
| `property` | 插件属性指针。 |
| `buf_size` | 插件属性 buffer 的内存大小。 |
#### 示例代码 [#示例代码-6]
参考如下示例代码了解如何使用上述方法实现一个视频插件：
```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;
}
}
}
```
### 封装插件 [#封装插件-3]
封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类，并至少实现如下方法：
- [`enumerateExtensions`](#enumerateextensions-3)
- [`createVideoFilter`](#createvideofilter-3)
`IExtensionProvider` 是插件动态库的提供者，由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件，如视频前处理插件库可以提供不同功能的视频插件（Video filter）。每个插件是一个具体的 Extension 对象。
#### enumerateExtensions [#enumerateextensions-3]
提供所有支持封装的插件的信息。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-2) |
| `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-3]
创建视频插件。SDK 调用该方法后，你需要返回 `IExtensionVideoFilter` 实例。
```cpp
virtual agora_refptr createVideoFilter(const char* name) {
return NULL;
}
```
成功创建 `IExtensionVideoFilter` 实例后，视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。
#### 示例代码 [#示例代码-7]
参考如下示例代码了解如何使用上述方法封装视频插件：
```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) {}
}
}
```
### 实现插件 [#实现插件-4]
视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法：
- [`getProcessMode`](#getprocessmode-4)
- [`start`](#start-4)
- [`stop`](#stop-4)
- [`getVideoFormatWanted`](#getvideoformatwanted-4)
- [`adaptVideoFrame`](#adaptvideoframe-4)
- [`pendVideoFrame`](#pendvideoframe-4)
- [`deliverVideoFrame`（见 Control 定义）](#start-4)
- [`setProperty`](#setproperty-4)
- [`getProperty`](#getproperty-4)
#### getProcessMode [#getprocessmode-4]
设置 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-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-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-4]
```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-4]
```cpp
virtual int stop() = 0;
```
销毁视频插件实例 `IExtensionVideoFilter` 后，会触发该回调。你可以在该回调中释放 OpenGL。
#### getVideoFormatWanted [#getvideoformatwanted-4]
设置待处理视频数据的类型和格式。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-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-4]
处理视频帧。在同步模式下（`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-4]
提交待处理的视频帧。在异步模式下（`mode` 设为 `Async`），SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后，插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。
```cpp
virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) {
return ProcessResult::kBypass;
}
```
**参数**
| 参数名 | 描述 |
| :----- | :--------------- |
| `frame` | 待处理的视频帧。 |
**返回值**
处理该视频帧的结果：
- `Success`: 成功处理该视频帧。
- `ByPass`: 跳过处理该视频帧，并将它传递到后续链路。
- `Drop`: 丢弃该视频帧。
#### setProperty [#setproperty-4]
设置视频插件属性。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-4]
获取视频插件属性。App 开发者调用 `getProperty` 时，SDK 会调用该方法获取视频插件的属性。
```cpp
int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size)
```
| 参数 | 描述 |
| :------- | :--------------------------- |
| `key` | 插件属性的 `key`。 |
| `property` | 插件属性指针。 |
| `buf_size` | 插件属性 buffer 的内存大小。 |
#### 示例代码 [#示例代码-8]
参考如下示例代码了解如何使用上述方法实现一个视频插件：
```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];
}
}
}
}
```
### 封装插件 [#封装插件-4]
封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类，并至少实现如下方法：
- [`enumerateExtensions`](#enumerateextensions-4)
- [ `createVideoFilter`](#createvideofilter-4)
#### enumerateExtensions [#enumerateextensions-4]
提供所有支持封装的插件的信息。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-4]
创建视频插件。SDK 调用该方法后，你需要返回 `IExtensionVideoFilter` 实例。
```cpp
virtual agora_refptr createVideoFilter(const char* name) {
return NULL;
}
```
成功创建 `IExtensionVideoFilter` 实例后，视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。
#### 示例代码 [#示例代码-9]
参考如下示例代码了解如何使用上述方法封装视频插件：
```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);
}
}
}
```
## 打包视频插件 [#打包视频插件-2]
完成插件开发后，你需要对其进行注册、打包，并将最终的 `.framework` 或 `.xcframework` 文件，连同一个包含了插件名称、服务商名称和 Filter 名称的文件提交给声网进行验证。
插件通过宏 `REGISTER_AGORA_EXTENSION_PROVIDER` 进行注册，该宏位于 `AgoraExtensionProviderEntry.h` 文件中。
你需要在插件的入口使用这个宏。SDK 在加载插件时，该宏会自动向 SDK 注册你的插件。注意填入 `PROVIDER_NAME` 时不要填写标点符号。示例：
```cpp
REGISTER_AGORA_EXTENSION_PROVIDER(ByteDance, agora::extension::ExtensionProvider);
```
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="web" />
本文展示如何开发一个与声网 Web SDK 4.x 搭配使用的视频插件。
## 技术原理 [#技术原理]
声网为开发视频插件提供以下抽象类：
- 必需的基础类：
- `Extension`：实现插件的初始化，包括创建插件、设置日志上报、设置事件上报等。
- `VideoProcessor`：实现视频数据的处理能力，包括接收、处理和返回处理完的视频数据。
- 可选的辅助类：
- `Ticker`：帮助管理周期性任务。
- `Logger`：向声网 SDK 上传日志。
- `Reporter`：向声网 SDK 报告事件。
## 前提条件 [#前提条件-3]
开发前，请确保你的开发环境满足以下要求：
- Windows 或 macOS 计算机，需满足以下要求：
- 下载声网 Web SDK [支持的浏览器](/zh-CN/realtime-media/rtc/reference/browser-compatibility)。声网强烈推荐使用[最新稳定版 Google Chrome 浏览器](https://www.google.com/chrome/)。
- 具备物理音视频采集设备。
- 可连接到互联网。如果你的网络环境部署了防火墙，请参考[应对防火墙限制](/zh-CN/realtime-media/rtc/build/setup-and-access/firewall)以正常使用声网服务。
- 搭载 2.2 GHz Intel 第二代 i3/i5/i7 处理器或同等性能的其他处理器。
- 安装 [Node.js 及 npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)。
## 准备开发环境 [#准备开发环境-3]
通过 npm 将插件开发模块（[agora-rte-extension](https://www.npmjs.com/package/agora-rte-extension)）集成到你的项目中：
1. 运行以下命令安装：
```shell
npm install --save agora-rte-extension
```
2. 在你的 `.js` 文件中加入以下代码导入插件开发模块：
```javascript
import {AudioExtension, AudioProcessor} from 'agora-rte-extension'
```
## 开发视频插件 [#开发视频插件-3]
本节详细介绍开发视频插件必须实现的 API。你还可以根据实际需要实现一些辅助类 API，优化插件的设计和性能，详见 [API 参考](#ref)。
### 实现插件初始化 [#实现插件初始化]
插件初始化通过 `Extension` 类实现。你需要实现 `Extension` 类的 `createProcessor` 方法：
```typescript
abstract class Extension {
createProcessor(): T;
}
```
创建 `VideoProcessor` 实例。
插件使用者调用 `extension.createProcessor` 时，SDK 会调用该方法。你需要在该方法中返回创建好的 `VideoProcessor` 实例。
### 实现视频数据处理 [#实现视频数据处理]
实现视频数据处理包括以下步骤：
1. 接收待处理的视频：通过 `VideoProcessor` 类的 `onTrack` 方法实现。
2. 处理视频：需要你自行实现。
3. 输出处理后的视频：通过 `VideoProcessor` 类的 `output` 方法实现。
#### onTrack [#ontrack]
```typescript
abstract onTrack?(track: MediaStreamTrack, context: IProcessorContext): void;
```
从前一个节点接收到待处理的视频数据回调。
**参数**
- `track`：前一个 `MediaStreamTrack`。`MediaStreamTrack` 是 Web API 提供的接口类，详见 [`MediaStreamTrack`](https://developer.mozilla.org/en-US/docs/Web/API/MediaStreamTrack)。
- `context`：当前视频处理管道的 context。
#### output [#output]
```typescript
output(track: MediaStreamTrack, context: IProcessorContext): void;
```
输出处理后的视频数据。
**参数**
- `track`：处理后的 `MediaStreamTrack`。
- `context`：当前视频处理管道的 context。
### 示例项目 [#示例项目-2]
声网提供一个 Web 插件开发的示例项目供你参考，你可以前往下载或查看其中的源代码。
- Gitee：[ExtensionDemo](https://gitee.com/agoraio-community/API-Examples-Web/tree/main/ExtensionDemo)
- GitHub：[ExtensionDemo](https://github.com/Shengwang-Lab/API-Examples-Web/tree/main/ExtensionDemo)
以下代码展示了如何开发一个视频插件：
```typescript
class YourExtension extends Extension {
// 创建 Processor
protected _createProcessor(): YourProcessor {
return new YourProcessor();
}
}
class CustomVideoProcessor extends VideoProcessor {
// 从前一个 MediaStreamTrack 接收到视频数据
onTrack(track: MediaStreamTrack, context: IProcessorContext) {
this.videoElement.srcObject = new MediaStream([track]);
this.videoElement.play();
this.loop();
}
// 连续抽取视频帧为 ImageData 对象，用于后续的视频处理
loop() {
this.ctx.drawImage(this.videoElement, 0, 0);
const imageData = this.ctx.getImageData(0, 0, this.canvas.width, this.canvas.height);
this.process(imageData);
requestAnimationFrame(() => this.loop());
}
process() {
//TODO：添加你的插件的视频处理逻辑
}
doneProcessing() {
// 组装成 MediaStreamTrack
const msStream = this.canvas.captureStream(30);
const outputTrack = msStream.getVideoTracks()[0];
// 输出处理后的视频数据
if (this.context) {
this.output(outputTrack, this.context);
}
}
}
```
## API 参考 [#api-参考]
本节介绍开发视频插件的辅助类 API。
### VideoProcessor [#videoprocessor]
#### name [#name]
```typescript
name: string;
```
`Processor` 的名称。
#### enabled [#enabled]
```typescript
enabled :boolean;
```
`Processor` 的开启状态。
#### ID [#id]
```typescript
public readonly ID:string;
```
`Processor` 的标识符。
#### Kind [#kind]
```typescript
public get Kind():'video' | 'audio';
```
`Processor` 的类型，分为视频和音频两种。
#### context [#context]
```typescript
protected context?: IProcessorContext;
```
用于 `Processor` 请求原始媒体流并重新进行采集。
#### onPiped [#onpiped]
```typescript
abstract onPiped?(context: IProcessorContext): void;
```
`LocalVideoTrack` 连接到当前媒体处理管道的回调。
:::warning[注意]
如果只是连接多个 `Processor`，不会触发该回调。例如：插件使用者调用 `processorA.pipe(processorB)`。
:::
#### onUnPiped [#onunpiped]
```typescript
abstract onUnPiped?(): void;
```
`Processor` 断开与媒体处理管道的连接回调。
#### onEnableChange [#onenablechange]
```typescript
abstract onEnableChange?(enabled: boolean): void | Promise;
```
`Processor` 的开启状态变化回调。
#### inputTrack [#inputtrack]
```typescript
protected inputTrack?:MediaStreamTrack;
```
当前 `Processor` 从前一个 `Processor` 或者 `LocalVideoTrack` 接收到的视频。
#### outputTrack [#outputtrack]
```typescript
protected outputTrack?:MediaStreamTrack;
```
当前 `Processor` 处理后的视频。调用 `output` 方法会自动设置 `outputTrack`。
### Ticker [#ticker]
#### constructor [#constructor]
```typescript
public constructor(type:"Timer" | "RAF" | "Oscillator", interval: number):Ticker;
```
`Ticker` 的构造函数。
**参数**
- `type`：类型，支持以下三种：
- `Timer`: 使用 `setTimeout` 作为插件内部的计时器。
- （推荐）`RAF`: 使用 `requestAnimationFrame` 作为插件内部的计时器。大多数情况下，该类型的 `Ticker` 渲染性能最好。
- `Oscillator`: 使用 `WebAudio` 的 `OscillatorNode` 作为插件内部的计时器。该类型的 `Ticker` 在浏览器页面不被浏览时也能运行。
- `interval`：两次回调之间的间隔。 `Ticker` 会按照这个间隔执行，但无法保证 100% 精准。
#### Ticker.add [#tickeradd]
```typescript
public add(fn: Function): void;
```
添加计时任务。
#### Ticker.remove [#tickerremove]
```typescript
public remove():void;
```
取消添加的计时任务。
#### Ticker.start [#tickerstart]
```typescript
public start():void;
```
开始计时。
#### Ticker.stop [#tickerstop]
```typescript
public stop():void;
```
停止计时。
### Logger [#logger]
```typescript
interface IExtensionLogger {
debug(...args: any): void;
error(...args: any): void;
info(...args: any): void;
warning(...args: any): void;
}
```
提供四种级别的日志。
插件使用者如果在调用 `AgoraRTC.registerExtension` 注册插件时选择了上传日志，则通过 `Logger` 类上报的日志会被上传。
### Reporter [#reporter]
#### Reporter.reportApiInvoke [#reporterreportapiinvoke]
```typescript
public reportApiInvoke(params: ReportApiInvokeParams): AgoraApiExecutor;
```
向 SDK 报告 API 调用的相关事件。
其中 `ReportApiInvokeParams` 和 `AgoraApiExecutor` 的定义如下：
```typescript
interface ReportApiInvokeParams {
// 被调用的 API 的名称
name: string;
// 与该 API 有关的参数或选项
options: any;
// 是否报告该 API 的调用结果
reportResult?: boolean;
// 定义多久为调用超时
timeout?: number;
}
interface AgoraApiExecutor {
// API 调用成功
onSuccess: (result: T) => void;
// API 调用失败
onError: (err: Error) => void;
}
```
<_PlatformProcessedMarker close="true" />
<_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="windows" />
本文展示如何使用声网 SDK 提供的 API 开发一个视频插件。
开发视频插件需要使用以下接口：
- `IExtensionVideoFilter`：实现视频数据的处理能力，包括接收、处理和返回处理完的视频帧。
- `IExtensionProvider`：将视频数据的处理能力封装为插件。
## 前提条件 [#前提条件-4]
开发前，请确保你的开发环境满足以下要求：
- Microsoft Visual Studio 2017 或以上版本。
- Windows 7 或以上版本的设备。
## 准备开发环境 [#准备开发环境-4]
参考如下步骤将声网云市场的 API 添加到你的项目中：
1. 下载[视频 SDK v4.x](/zh-CN/realtime-media/rtc/reference/downloads)，然后解压下载的 SDK 包。
2. 将 SDK 包中的 `/rtc/sdk/low_level_api/include` 路径下的头文件拷贝至你的项目文件夹中。
## 开发视频插件 [#开发视频插件-4]
### 实现插件 [#实现插件-5]
视频插件通过 `IExtensionVideoFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。`IExtensionVideoFilter` 接口类包含如下方法：
- [`getProcessMode`](#getprocessmode-5)
- [`start`](#start-5)
- [`stop`](#stop-5)
- [`getVideoFormatWanted`](#getvideoformatwanted-5)
- [`adaptVideoFrame`](#adaptvideoframe-5)
- [`pendVideoFrame`](#pendvideoframe-5)
- [`deliverVideoFrame`（见 Control 定义）](#start-5)
- [`setProperty`](#setproperty-5)
- [`getProperty`](#getproperty-5)
#### getProcessMode [#getprocessmode-5]
设置 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-3) |
| `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-3) |
**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-5]
```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-5]
```cpp
virtual int stop() = 0;
```
销毁视频插件实例 `IExtensionVideoFilter` 后，会触发该回调。你可以在该回调中释放 OpenGL。
#### getVideoFormatWanted [#getvideoformatwanted-5]
设置待处理视频数据的类型和格式。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-3) |
**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-5]
处理视频帧。在同步模式下（`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-5]
提交待处理的视频帧。在异步模式下（`mode` 设为 `Async`），SDK 通过该方法向视频插件提交待处理的视频帧。使用该方法后，插件必须通过 `Control` 类的 `deliverVideoFrame` 方法返回处理后的视频帧。
```cpp
virtual ProcessResult pendVideoFrame(agora::agora_refptr frame) {
return ProcessResult::kBypass;
}
```
**参数**
| 参数名 | 描述 |
| :----- | :--------------- |
| `frame` | 待处理的视频帧。 |
**返回值**
处理该视频帧的结果：
- `Success`: 成功处理该视频帧。
- `ByPass`: 跳过处理该视频帧，并将它传递到后续链路。
- `Drop`: 丢弃该视频帧。
#### setProperty [#setproperty-5]
设置视频插件属性。App 开发者调用 `setExtensionProperty` 时，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-5]
获取视频插件属性。App 开发者调用 `getProperty` 时，SDK 会调用该方法获取视频插件的属性。
```cpp
int ExtensionVideoFilter::getProperty(const char *key, void *buf, size_t buf_size)
```
| 参数 | 描述 |
| :------- | :--------------------------- |
| `key` | 插件属性的 `key`。 |
| `property` | 插件属性指针。 |
| `buf_size` | 插件属性 buffer 的内存大小。 |
#### 示例代码 [#示例代码-10]
参考如下示例代码了解如何使用上述方法实现一个视频插件：
```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;
}
}
}
```
### 封装插件 [#封装插件-5]
封装插件通过 `IExtensionProvider` 接口类实现。该接口位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类，并至少实现如下方法：
- [`enumerateExtensions`](#enumerateextensions-5)
- [`createVideoFilter`](#createvideofilter-5)
`IExtensionProvider` 是插件动态库的提供者，由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件，如视频前处理插件库可以提供不同功能的视频插件（Video filter）。每个插件是一个具体的 Extension 对象。
#### enumerateExtensions [#enumerateextensions-5]
提供所有支持封装的插件的信息。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-3) |
| `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-5]
创建视频插件。SDK 调用该方法后，你需要返回 `IExtensionVideoFilter` 实例。
```cpp
virtual agora_refptr createVideoFilter(const char* name) {
return NULL;
}
```
成功创建 `IExtensionVideoFilter` 实例后，视频插件会在合适的时机通过 `IExtensionFilter` 类对输入的视频数据进行处理。
#### 示例代码 [#示例代码-11]
参考如下示例代码了解如何使用上述方法封装视频插件：
```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) {}
}
}
```
## 打包视频插件 [#打包视频插件-3]
完成插件开发后，你需要对其进行注册、打包，并将最终的 `.dll` 文件，连同一个包含了插件名称、服务商名称和 Filter 名称的文件提交给声网进行验证。
### 注册插件 [#注册插件-1]
插件通过宏 `REGISTER_AGORA_EXTENSION_PROVIDER` 进行注册，该宏位于 `AgoraExtensionProviderEntry.h` 文件中。
你需要在插件的入口使用这个宏。SDK 在加载插件时，该宏会自动向 SDK 注册你的插件。注意填入 `PROVIDER_NAME` 时不要填写标点符号。示例：
```cpp
REGISTER_AGORA_EXTENSION_PROVIDER(ByteDance, agora::extension::ExtensionProvider);
```
### 提供插件信息 [#提供插件信息-1]
新建一个 `.md` 文件，并在其中填入如下信息：
- `EXTENSION_NAME`：插件包的名称，如 `libagora-bytedance.dll` 文件的 `EXTENSION_NAME` 就是 `agora-bytedance`。
- `EXTENSION_VENDOR_NAME`：服务商名称，即插件的 `Provider` 对象名称，用于在 `.cpp` 文件中进行注册。
- `EXTENSION_FILTER_NAME`：`ExtensionProvider.h` 文件中定义的 Filter 名称。
<_PlatformProcessedMarker close="true" />