# 开发音频插件 (/zh-CN/realtime-media/marketplace/build/create-extensions/audio-filter) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). <_PlatformTabsGroup> <_PlatformProcessedMarker groupMode="structured" canonicalPlatform="web" platform="android" /> 本文展示如何使用声网 SDK 提供的 API 开发一个音频插件。开发音频插件需要使用以下接口: - `IAudioFilter`:实现音频数据的处理能力,包括接收、处理和返回处理完的音频帧。 - `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` 路径下的头文件拷贝至你的项目文件夹中。 ## 开发音频插件 [#开发音频插件] ### 实现插件 [#实现插件] 音频插件通过 `IAudioFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。你需要实现 `IAudioFilter` 接口类的如下方法: - [`adaptAudioFrame`](#adaptaudioframe) - [`setEnabled`](#setenabled) - [`isEnabled`](#isenabled) - [`setProperty`](#setproperty) - [`getProperty`](#getproperty) - [`getName`](#getname) - [`getPreferredSampleRate`](#getpreferredsamplerate)(可选) - [`getPreferredChannelNumbers`](#getpreferredchannelnumbers)(可选) #### adaptAudioFrame [#adaptaudioframe] 处理音频帧。该方法是 `IAudioFilter` 类的核心方法。调用该方法后,SDK 处理 `inAudioFrame` 中的音频数据,然后通过 `adaptedFrame` 返回处理后的数据。该方法目前仅支持输入输出 PCM 格式的音频数据。 ```cpp virtual bool adaptAudioFrame(const media::base::AudioPcmFrame& inAudioFrame, media::base::AudioPcmFrame& adaptedFrame) = 0; ``` | 参数 | 描述 | | :----------------- | :----------------------------------------------------------- | | `inAudioFrame` | 输入参数。待处理的音频帧。 | | `adaptedFrame` | 输出参数。处理后的音频帧。 | #### setEnabled [#setenabled] 启用或关闭音频插件。 ```cpp virtual void setEnabled(bool enable) {} ``` | 参数 | 描述 | | --- | --- | | `enable` | [audio-filter-android-ios-macos-windows-html-0-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-0-1-1) | **audio-filter-android-ios-macos-windows-html-0-1-1 details** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### isEnabled [#isenabled] 检查音频插件是否已启用。 ```cpp virtual bool isEnabled() { return true; } ``` **返回值** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### setProperty [#setproperty] 设置音频插件属性。App 开发者调用 `setExtensionProperty` 时,SDK 会调用该方法。你需要返回音频插件的属性。 ```cpp size_t 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 size_t getProperty(const char* key, char* property, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getName [#getname] 查询插件的名称。你需要在该方法中返回使用的音频插件的名称。 ```cpp virtual const char * getName() const = 0; ``` #### getPreferredSampleRate [#getpreferredsamplerate] 查询音频插件需要的音频采样率。 该方法为可选。如果你在该方法中返回一个指定的采样率,SDK 会将音频数据重采样成指定的采样率,然后传入音频插件。 ```cpp virtual int getPreferredSampleRate() { return 0; }; ``` #### getPreferredChannelNumbers [#getpreferredchannelnumbers] 查询音频插件需要的音频声道数。 该方法为可选。如果你在该方法中返回一个指定的声道数,SDK 会将音频数据重采样成指定的声道数,然后传入音频插件。 ```cpp virtual int getPreferredChannelNumbers() { return 0; }; ``` #### 示例代码 [#示例代码] 参考如下示例代码了解如何使用上述方法实现一个音频插件: ```cpp // 在收到需要处理的音频数据后,调用 adaptAudioFrame 方法,对收到的音频数据进行处理。 bool ExtensionAudioFilter::adaptAudioFrame(const media::base::AudioPcmFrame& inAudioPcmFrame, media::base::AudioPcmFrame& adaptedPcmFrame) { return audioProcess_->processFrame(inAudioPcmFrame, adaptedPcmFrame) == 0; } // 调用 setProperty 设置音频插件参数。 int ExtensionAudioFilter::setProperty(const char* key, const void* buf, int buf_size) { std::string str_volume = "100"; if (std::string(key) == "volume") { str_volume = std::string(static_cast(buf), buf_size); } int int volume_ = atoi(str_volume.c_str()); audioProcessor_->setVolume(int_volume_); return ERR_OK; } // 调用 getProperty 查询音频插件参数。 int ExtensionAudioFilter::getProperty(const char* key, void* buf, int buf_size) const override {return ERR_OK; } // 调用 setEnabled 开启音频插件。 void ExtensionAudioFilter::setEnabled(bool enable) override { enabled_ = enable; } // 调用 isEnabled 查询音频插件开启状态。 bool ExtensionAudioFilter::isEnabled() const override {return enabled_; } // 在 getName 的返回值中传入插件名称。 const char* ExtensionAudioFilter::getName() const override { return "YourExtensionName"; } // (可选)在 getPreferredSampleRate 的返回值中指定音频插件需要的音频采样率。 const char* ExtensionAudioFilter::getPreferredSampleRate() override { return 48000; } // (可选)在 getPreferredChannelNumbers 的返回值中指定音频插件需要的音频声道数。 int ExtensionAudioFilter::getPreferredChannelNumbers() override { return 2; }; ``` ### 封装插件 [#封装插件] 封装插件通过 `IExtensionProvider` 接口类实现。该接口类位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并实现如下方法: - [`setExtensionControl`](#setextensioncontrol) - [`enumerateExtensions`](#enumerateextensions) - [`createAudioFilter`](#createaudiofilter) `IExtensionProvider` 是插件动态库的提供者,由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件,如音频前处理插件库可以提供不同功能的音频插件(Audio filter)。每个插件是一个具体的 Extension 对象。 #### setExtensionControl [#setextensioncontrol] 设置插件控制。 ```cpp virtual void setExtensionControl(IExtensionControl* control) ``` 成功调用该方法后,你需要保存 SDK 在该方法中返回的 `IExtensionControl` 对象。该对象用于触发事件或日志,实现插件与 App 之间的交互。例如,如果你调用了 `IExtensionControl` 中的 `fireEvent` 方法: ```cpp void ByteDanceProcessor::dataCallback(const char* data){ if (control_ != nullptr) { control_->fireEvent(id_, "beauty", data); } } ``` App 层在初始化 `RtcEngine` 时注册的 `IMediaExtensionObserver` 实例会收到该信息,并在 App 层触发如下回调: ```cpp @Override public void onEvent(String vendor, String key, String value) { // 其中的 vendor 为注册插件时的 VENDOR_NAME,key/value 是插件消息的键值对 ... } ``` #### enumerateExtensions [#enumerateextensions] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | --- | --- | | `extension_list` | [audio-filter-android-ios-macos-windows-html-1-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-1-1-1) | | `extension_count` | 支持封装的插件的总数量。 | **audio-filter-android-ios-macos-windows-html-1-1-1 details** 插件的信息,包括插件类型和插件名称。 支持的音频插件类型有: - `AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER`(上行) - `AUDIO_POST_PROCESSING_FILTER`(上行) - `AUDIO_REMOTE_USER_PLAYBACK_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` 方法中返回的插件类型为 `AUDIO_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionProvider` 对象后,SDK 会调用 `createAudioFilter` 方法。 #### createAudioFilter [#createaudiofilter] 创建音频插件。SDK 调用该方法后,你需要返回 `IAudioFilter` 实例。 ```cpp virtual agora_refptr createAudioFilter() ``` 成功创建 `IAudioFilter` 实例后,音频插件会在合适的时机通过 `IAudioFilter` 类对输入的音频数据进行处理。 #### 示例代码 [#示例代码-1] 参考如下示例代码了解如何使用上述方法封装音频插件: ```cpp void ExtensionProvider::enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER; i.extension_name = "YourExtensionName"; extension_list[0] = i; } agora_refptr ExtensionAudioProvider::createAudioFilter() { PRINTF_ERROR("ExtensionAudioProvider::createAudioFilter"); auto audioFilter = new agora::RefCountedObject(audioProcessor_); return audioFilter; } void ExtensionAudioProvider::setExtensionControl(rtc::IExtensionControl* control){ audioProcessor_->setExtensionControl(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 开发一个音频插件。 开发音频插件需要使用以下接口: - `IAudioFilter`:实现音频数据的处理能力,包括接收、处理和返回处理完的音频帧。 - `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] 音频插件通过 `IAudioFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。你需要实现 `IAudioFilter` 接口类的如下方法: - [`adaptAudioFrame`](#adaptaudioframe-1) - [`setEnabled`](#setenabled-1) - [`isEnabled`](#isenabled-1) - [`setProperty`](#setproperty-1) - [`getProperty`](#getproperty-1) - [`getName`](#getname-1) - [`getPreferredSampleRate`](#getpreferredsamplerate-1)(可选) - [`getPreferredChannelNumbers`](#getpreferredchannelnumbers-1)(可选) #### adaptAudioFrame [#adaptaudioframe-1] 处理音频帧。该方法是 `IAudioFilter` 类的核心方法。调用该方法后,SDK 处理 `inAudioFrame` 中的音频数据,然后通过 `adaptedFrame` 返回处理后的数据。该方法目前仅支持输入输出 PCM 格式的音频数据。 ```cpp virtual bool adaptAudioFrame(const media::base::AudioPcmFrame& inAudioFrame, media::base::AudioPcmFrame& adaptedFrame) = 0; ``` | 参数 | 描述 | | :----------------- | :----------------------------------------------------------- | | `inAudioFrame` | 输入参数。待处理的音频帧。 | | `adaptedFrame` | 输出参数。处理后的音频帧。 | #### setEnabled [#setenabled-1] 启用或关闭音频插件。 ```cpp virtual void setEnabled(bool enable) {} ``` | 参数 | 描述 | | --- | --- | | `enable` | [audio-filter-android-ios-macos-windows-html-0-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-0-1-1-1) | **audio-filter-android-ios-macos-windows-html-0-1-1 details** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### isEnabled [#isenabled-1] 检查音频插件是否已启用。 ```cpp virtual bool isEnabled() { return true; } ``` **返回值** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### setProperty [#setproperty-1] 设置音频插件属性。App 开发者调用 `setExtensionPropertyWithVendor` 时,SDK 会调用该方法。你需要返回音频插件的属性。 ```cpp size_t 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 size_t getProperty(const char* key, char* property, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getName [#getname-1] 查询插件的名称。你需要在该方法中返回使用的音频插件的名称。 ```cpp virtual const char * getName() const = 0; ``` #### getPreferredSampleRate [#getpreferredsamplerate-1] 查询音频插件需要的音频采样率。 该方法为可选。如果你在该方法中返回一个指定的采样率,SDK 会将音频数据重采样成指定的采样率,然后传入音频插件。 ```cpp virtual int getPreferredSampleRate() { return 0; }; ``` #### getPreferredChannelNumbers [#getpreferredchannelnumbers-1] 查询音频插件需要的音频声道数。 该方法为可选。如果你在该方法中返回一个指定的声道数,SDK 会将音频数据重采样成指定的声道数,然后传入音频插件。 ```cpp virtual int getPreferredChannelNumbers() { return 0; }; ``` #### 示例代码 [#示例代码-2] 参考如下示例代码了解如何使用上述方法实现一个音频插件: ```cpp // 在收到需要处理的音频数据后,调用 adaptAudioFrame 方法,对收到的音频数据进行处理。 bool ExtensionAudioFilter::adaptAudioFrame(const media::base::AudioPcmFrame& inAudioPcmFrame, media::base::AudioPcmFrame& adaptedPcmFrame) { return audioProcess_->processFrame(inAudioPcmFrame, adaptedPcmFrame) == 0; } // 调用 setProperty 设置音频插件参数。 int ExtensionAudioFilter::setProperty(const char* key, const void* buf, int buf_size) { std::string str_volume = "100"; if (std::string(key) == "volume") { str_volume = std::string(static_cast(buf), buf_size); } int int volume_ = atoi(str_volume.c_str()); audioProcessor_->setVolume(int_volume_); return ERR_OK; } // 调用 getProperty 查询音频插件参数。 int ExtensionAudioFilter::getProperty(const char* key, void* buf, int buf_size) const override {return ERR_OK; } // 调用 setEnabled 开启音频插件。 void ExtensionAudioFilter::setEnabled(bool enable) override { enabled_ = enable; } // 调用 isEnabled 查询音频插件开启状态。 bool ExtensionAudioFilter::isEnabled() const override {return enabled_; } // 在 getName 的返回值中传入插件名称。 const char* ExtensionAudioFilter::getName() const override { return "YourExtensionName"; } // (可选)在 getPreferredSampleRate 的返回值中指定音频插件需要的音频采样率。 const char* ExtensionAudioFilter::getPreferredSampleRate() override { return 48000; } // (可选)在 getPreferredChannelNumbers 的返回值中指定音频插件需要的音频声道数。 int ExtensionAudioFilter::getPreferredChannelNumbers() override { return 2; }; ``` ### 封装插件 [#封装插件-1] 封装插件通过 `IExtensionProvider` 接口类实现。该接口类位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并实现如下方法: - [`setExtensionControl`](#setextensioncontrol-1) - [`enumerateExtensions`](#enumerateextensions-1) - [`createAudioFilter`](#createaudiofilter-1) `IExtensionProvider` 是插件动态库的提供者,由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件,如音频前处理插件库可以提供不同功能的音频插件(Audio filter)。每个插件是一个具体的 Extension 对象。 #### setExtensionControl [#setextensioncontrol-1] 设置插件控制。 ```cpp virtual void setExtensionControl(IExtensionControl* control) ``` 成功调用该方法后,你需要保存 SDK 在该方法中返回的 `IExtensionControl` 对象。该对象用于触发事件或日志,实现插件与 App 之间的交互。例如,如果你调用了 `IExtensionControl` 中的 `fireEvent` 方法: ```cpp void ByteDanceProcessor::dataCallback(const char* data){ if (control_ != nullptr) { control_->fireEvent(id_, "beauty", data); } } ``` App 层在初始化 `AgoraRtcEngineKit` 时注册的 `AgoraMediaFilterEventDelegate` 实例会收到该信息,并在 App 层触发如下回调: ```cpp - (void)onEvent:(NSString *)provider extension:(NSString *)extension key:(NSString *)key value:(NSString *)value { // 其中的 vendor 为注册插件时的 VENDOR_NAME,key/value 是插件消息的键值对 ... } ``` #### enumerateExtensions [#enumerateextensions-1] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | --- | --- | | `extension_list` | [audio-filter-android-ios-macos-windows-html-1-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-1-1-1-1) | | `extension_count` | 支持封装的插件的总数量。 | **audio-filter-android-ios-macos-windows-html-1-1-1 details** 插件的信息,包括插件类型和插件名称。 支持的音频插件类型有: - `AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER`(上行) - `AUDIO_POST_PROCESSING_FILTER`(上行) - `AUDIO_REMOTE_USER_PLAYBACK_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` 方法中返回的插件类型为 `AUDIO_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionProvider` 对象后,SDK 会调用 `createAudioFilter` 方法。 #### createAudioFilter [#createaudiofilter-1] 创建音频插件。SDK 调用该方法后,你需要返回 `IAudioFilter` 实例。 ```cpp virtual agora_refptr createAudioFilter() ``` 成功创建 `IAudioFilter` 实例后,音频插件会在合适的时机通过 `IAudioFilter` 类对输入的音频数据进行处理。 #### 示例代码 [#示例代码-3] 参考如下示例代码了解如何使用上述方法封装音频插件: ```cpp void ExtensionProvider::enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER; i.extension_name = "YourExtensionName"; extension_list[0] = i; } agora_refptr ExtensionAudioProvider::createAudioFilter() { PRINTF_ERROR("ExtensionAudioProvider::createAudioFilter"); auto audioFilter = new agora::RefCountedObject(audioProcessor_); return audioFilter; } void ExtensionAudioProvider::setExtensionControl(rtc::IExtensionControl* control){ audioProcessor_->setExtensionControl(control); } ``` ## 打包音频插件 [#打包音频插件-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 开发一个音频插件。 开发音频插件需要使用以下接口: - `IAudioFilter`:实现音频数据的处理能力,包括接收、处理和返回处理完的音频帧。 - `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] ### 实现插件 [#实现插件-2] 音频插件通过 `IAudioFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。你需要实现 `IAudioFilter` 接口类的如下方法: - [`adaptAudioFrame`](#adaptaudioframe-2) - [`setEnabled`](#setenabled-2) - [`isEnabled`](#isenabled-2) - [`setProperty`](#setproperty-2) - [`getProperty`](#getproperty-2) - [`getName`](#getname-2) - [`getPreferredSampleRate`](#getpreferredsamplerate-2)(可选) - [`getPreferredChannelNumbers`](#getpreferredchannelnumbers-2)(可选) #### adaptAudioFrame [#adaptaudioframe-2] 处理音频帧。该方法是 `IAudioFilter` 类的核心方法。调用该方法后,SDK 处理 `inAudioFrame` 中的音频数据,然后通过 `adaptedFrame` 返回处理后的数据。该方法目前仅支持输入输出 PCM 格式的音频数据。 ```cpp virtual bool adaptAudioFrame(const media::base::AudioPcmFrame& inAudioFrame, media::base::AudioPcmFrame& adaptedFrame) = 0; ``` | 参数 | 描述 | | :----------------- | :----------------------------------------------------------- | | `inAudioFrame` | 输入参数。待处理的音频帧。 | | `adaptedFrame` | 输出参数。处理后的音频帧。 | #### setEnabled [#setenabled-2] 启用或关闭音频插件。 ```cpp virtual void setEnabled(bool enable) {} ``` | 参数 | 描述 | | --- | --- | | `enable` | [audio-filter-android-ios-macos-windows-html-0-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-0-1-1-2) | **audio-filter-android-ios-macos-windows-html-0-1-1 details** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### isEnabled [#isenabled-2] 检查音频插件是否已启用。 ```cpp virtual bool isEnabled() { return true; } ``` **返回值** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### setProperty [#setproperty-2] 设置音频插件属性。App 开发者调用 `setExtensionPropertyWithVendor` 时,SDK 会调用该方法。你需要返回音频插件的属性。 ```cpp size_t 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 size_t getProperty(const char* key, char* property, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getName [#getname-2] 查询插件的名称。你需要在该方法中返回使用的音频插件的名称。 ```cpp virtual const char * getName() const = 0; ``` #### getPreferredSampleRate [#getpreferredsamplerate-2] 查询音频插件需要的音频采样率。 该方法为可选。如果你在该方法中返回一个指定的采样率,SDK 会将音频数据重采样成指定的采样率,然后传入音频插件。 ```cpp virtual int getPreferredSampleRate() { return 0; }; ``` #### getPreferredChannelNumbers [#getpreferredchannelnumbers-2] 查询音频插件需要的音频声道数。 该方法为可选。如果你在该方法中返回一个指定的声道数,SDK 会将音频数据重采样成指定的声道数,然后传入音频插件。 ```cpp virtual int getPreferredChannelNumbers() { return 0; }; ``` #### 示例代码 [#示例代码-4] 参考如下示例代码了解如何使用上述方法实现一个音频插件: ```cpp // 在收到需要处理的音频数据后,调用 adaptAudioFrame 方法,对收到的音频数据进行处理。 bool ExtensionAudioFilter::adaptAudioFrame(const media::base::AudioPcmFrame& inAudioPcmFrame, media::base::AudioPcmFrame& adaptedPcmFrame) { return audioProcess_->processFrame(inAudioPcmFrame, adaptedPcmFrame) == 0; } // 调用 setProperty 设置音频插件参数。 int ExtensionAudioFilter::setProperty(const char* key, const void* buf, int buf_size) { std::string str_volume = "100"; if (std::string(key) == "volume") { str_volume = std::string(static_cast(buf), buf_size); } int int volume_ = atoi(str_volume.c_str()); audioProcessor_->setVolume(int_volume_); return ERR_OK; } // 调用 getProperty 查询音频插件参数。 int ExtensionAudioFilter::getProperty(const char* key, void* buf, int buf_size) const override {return ERR_OK; } // 调用 setEnabled 开启音频插件。 void ExtensionAudioFilter::setEnabled(bool enable) override { enabled_ = enable; } // 调用 isEnabled 查询音频插件开启状态。 bool ExtensionAudioFilter::isEnabled() const override {return enabled_; } // 在 getName 的返回值中传入插件名称。 const char* ExtensionAudioFilter::getName() const override { return "YourExtensionName"; } // (可选)在 getPreferredSampleRate 的返回值中指定音频插件需要的音频采样率。 const char* ExtensionAudioFilter::getPreferredSampleRate() override { return 48000; } // (可选)在 getPreferredChannelNumbers 的返回值中指定音频插件需要的音频声道数。 int ExtensionAudioFilter::getPreferredChannelNumbers() override { return 2; }; ``` ### 封装插件 [#封装插件-2] 封装插件通过 `IExtensionProvider` 接口类实现。该接口类位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并实现如下方法: - [`setExtensionControl`](#setextensioncontrol-2) - [`enumerateExtensions`](#enumerateextensions-2) - [`createAudioFilter`](#createaudiofilter-2) `IExtensionProvider` 是插件动态库的提供者,由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件,如音频前处理插件库可以提供不同功能的音频插件(Audio filter)。每个插件是一个具体的 Extension 对象。 #### setExtensionControl [#setextensioncontrol-2] 设置插件控制。 ```cpp virtual void setExtensionControl(IExtensionControl* control) ``` 成功调用该方法后,你需要保存 SDK 在该方法中返回的 `IExtensionControl` 对象。该对象用于触发事件或日志,实现插件与 App 之间的交互。例如,如果你调用了 `IExtensionControl` 中的 `fireEvent` 方法: ```cpp void ByteDanceProcessor::dataCallback(const char* data){ if (control_ != nullptr) { control_->fireEvent(id_, "beauty", data); } } ``` App 层在初始化 `AgoraRtcEngineKit` 时注册的 `AgoraMediaFilterEventDelegate` 实例会收到该信息,并在 App 层触发如下回调: ```cpp - (void)onEvent:(NSString *)provider extension:(NSString *)extension key:(NSString *)key value:(NSString *)value { // 其中的 vendor 为注册插件时的 VENDOR_NAME,key/value 是插件消息的键值对 ... } ``` #### enumerateExtensions [#enumerateextensions-2] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | --- | --- | | `extension_list` | [audio-filter-android-ios-macos-windows-html-1-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-1-1-1-2) | | `extension_count` | 支持封装的插件的总数量。 | **audio-filter-android-ios-macos-windows-html-1-1-1 details** 插件的信息,包括插件类型和插件名称。 支持的音频插件类型有: - `AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER`(上行) - `AUDIO_POST_PROCESSING_FILTER`(上行) - `AUDIO_REMOTE_USER_PLAYBACK_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` 方法中返回的插件类型为 `AUDIO_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionProvider` 对象后,SDK 会调用 `createAudioFilter` 方法。 #### createAudioFilter [#createaudiofilter-2] 创建音频插件。SDK 调用该方法后,你需要返回 `IAudioFilter` 实例。 ```cpp virtual agora_refptr createAudioFilter() ``` 成功创建 `IAudioFilter` 实例后,音频插件会在合适的时机通过 `IAudioFilter` 类对输入的音频数据进行处理。 #### 示例代码 [#示例代码-5] 参考如下示例代码了解如何使用上述方法封装音频插件: ```cpp void ExtensionProvider::enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER; i.extension_name = "YourExtensionName"; extension_list[0] = i; } agora_refptr ExtensionAudioProvider::createAudioFilter() { PRINTF_ERROR("ExtensionAudioProvider::createAudioFilter"); auto audioFilter = new agora::RefCountedObject(audioProcessor_); return audioFilter; } void ExtensionAudioProvider::setExtensionControl(rtc::IExtensionControl* control){ audioProcessor_->setExtensionControl(control); } ``` ## 打包音频插件 [#打包音频插件-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 搭配使用的音频插件。 ## 技术原理 [#技术原理] 声网为开发音频插件提供以下抽象类: - 必需的基础类: - `AudioExtension`:实现插件的初始化,包括创建插件、设置日志上报、设置事件上报等。 - `AudioProcessor`:实现音频数据的处理能力,包括接收、处理和返回处理完的音频数据。 - 可选的辅助类: - `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)。 ### 实现插件初始化 [#实现插件初始化] 插件初始化通过 `AudioExtension` 类实现。你需要实现 `AudioExtension` 类的 `createProcessor` 方法: #### createProcessor [#createprocessor] ```typescript abstract class AudioExtension { createProcessor(): T; } ``` 创建 `AudioProcessor` 实例。 插件使用者调用 `extension.createProcessor` 时,SDK 会调用该方法。你需要在该方法中返回创建好的 `AudioProcessor` 实例。 ### 实现音频数据处理 [#实现音频数据处理] 实现音频数据处理包括以下步骤: 1. 接收待处理的音频:通过 `AudioProcessor` 类的 `onNode` 方法和 `IAudioProcessorContext` 接口的 `getAudioContext` 方法实现。 2. 处理音频:需要你自行实现。 3. 输出处理后的音频:通过 `AudioProcessor` 类的 `output` 方法实现。 #### onNode [#onnode] ```typescript abstract onNode?(node: AudioNode, context: IAudioProcessorContext): void; ``` 从前一个节点接收到待处理的音频数据回调。 **参数** - `node`:前一个 `AudioNode`。`AudioNode` 是 Web Audio API 提供的接口类,详见 [Web Audio API interfaces](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#web_audio_api_interfaces)。 - `context`:当前音频处理管道的 context。 #### output [#output] ```typescript output(track: MediaStreamTrack | AudioNode, context: IProcessorContext): void; ``` 输出处理后的音频数据。 **参数** - `track`:处理后的音频数据。推荐使用 `AudioNode`。 - `context`:当前音频处理管道的 context。 #### getAudioContext [#getaudiocontext] ```typescript getAudioContext(): Promise; ``` 获取当前音频处理管道的 `AudioContext`。`AudioContext` 是 Web Audio API 提供的接口类,详见 [Web Audio API interfaces](https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API#web_audio_api_interfaces)。 ### 示例项目 [#示例项目-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 AudioExtension { // 创建 Processor protected _createProcessor(): YourProcessor { return new YourProcessor(); } } class CustomAudioProcessor extends AudioProcessor { // 从前一个 AudioNode 接收到音频数据 onNode(node: AudioNode, context: IAudioProcessorContext) { // 创建 AudioNode const audioContext = context.getAudioContext(); const gainNode = audioContext.createGain(); // 连接前一个 AudioNode node.connect(gainNode); } process() { // TODO:添加你的插件的音频处理逻辑 // 输出处理后的音频数据 this.output(gainNode, context); } } ``` ## API 参考 [#api-参考] 本节介绍开发音频插件的辅助类 API。 ### AudioProcessor [#audioprocessor] #### 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` 的开启状态变化回调。 #### inputNode [#inputnode] ```typescript protected inputNode?:AudioNode; ``` `Processor` 接收到的音频。 #### outputNode [#outputnode] ```typescript protected outputNode?:AudioNode; ``` `Processor` 处理后的音频。 ### IAudioProcessorContext [#iaudioprocessorcontext] ```typescript interface IAudioProcessorContext extends IProcessorContext { getAudioContext(): Promise; } ``` 用于 `AudioProcessor` 获取当前音频处理管道的 `AudioContext`。 ### 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 开发一个音频插件。 开发音频插件需要使用以下接口: - `IAudioFilter`:实现音频数据的处理能力,包括接收、处理和返回处理完的音频帧。 - `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] ### 实现插件 [#实现插件-3] 音频插件通过 `IAudioFilter` 接口实现。该接口位于 `NGIAgoraMediaNode.h` 文件中。你需要实现 `IAudioFilter` 接口类的如下方法: - [`adaptAudioFrame`](#adaptaudioframe-3) - [`setEnabled`](#setenabled-3) - [`isEnabled`](#isenabled-3) - [`setProperty`](#setproperty-3) - [`getProperty`](#getproperty-3) - [`getName`](#getname-3) - [`getPreferredSampleRate`](#getpreferredsamplerate-3)(可选) - [`getPreferredChannelNumbers`](#getpreferredchannelnumbers-3)(可选) #### adaptAudioFrame [#adaptaudioframe-3] 处理音频帧。该方法是 `IAudioFilter` 类的核心方法。调用该方法后,SDK 处理 `inAudioFrame` 中的音频数据,然后通过 `adaptedFrame` 返回处理后的数据。该方法目前仅支持输入输出 PCM 格式的音频数据。 ```cpp virtual bool adaptAudioFrame(const media::base::AudioPcmFrame& inAudioFrame, media::base::AudioPcmFrame& adaptedFrame) = 0; ``` | 参数 | 描述 | | :----------------- | :----------------------------------------------------------- | | `inAudioFrame` | 输入参数。待处理的音频帧。 | | `adaptedFrame` | 输出参数。处理后的音频帧。 | #### setEnabled [#setenabled-3] 启用或关闭音频插件。 ```cpp virtual void setEnabled(bool enable) {} ``` | 参数 | 描述 | | --- | --- | | `enable` | [audio-filter-android-ios-macos-windows-html-0-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-0-1-1-3) | **audio-filter-android-ios-macos-windows-html-0-1-1 details** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### isEnabled [#isenabled-3] 检查音频插件是否已启用。 ```cpp virtual bool isEnabled() { return true; } ``` **返回值** 是否启用音频插件: - true: 启用音频插件。 - false: (默认) 关闭音频插件。 #### setProperty [#setproperty-3] 设置音频插件属性。App 开发者调用 `setExtensionProperty` 时,SDK 会调用该方法。你需要返回音频插件的属性。 ```cpp size_t 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 size_t getProperty(const char* key, char* property, size_t buf_size) ``` | 参数 | 描述 | | :------- | :--------------------------- | | `key` | 插件属性的 `key`。 | | `property` | 插件属性指针。 | | `buf_size` | 插件属性 buffer 的内存大小。 | #### getName [#getname-3] 查询插件的名称。你需要在该方法中返回使用的音频插件的名称。 ```cpp virtual const char * getName() const = 0; ``` #### getPreferredSampleRate [#getpreferredsamplerate-3] 查询音频插件需要的音频采样率。 该方法为可选。如果你在该方法中返回一个指定的采样率,SDK 会将音频数据重采样成指定的采样率,然后传入音频插件。 ```cpp virtual int getPreferredSampleRate() { return 0; }; ``` #### getPreferredChannelNumbers [#getpreferredchannelnumbers-3] 查询音频插件需要的音频声道数。 该方法为可选。如果你在该方法中返回一个指定的声道数,SDK 会将音频数据重采样成指定的声道数,然后传入音频插件。 ```cpp virtual int getPreferredChannelNumbers() { return 0; }; ``` #### 示例代码 [#示例代码-6] 参考如下示例代码了解如何使用上述方法实现一个音频插件: ```cpp // 在收到需要处理的音频数据后,调用 adaptAudioFrame 方法,对收到的音频数据进行处理。 bool ExtensionAudioFilter::adaptAudioFrame(const media::base::AudioPcmFrame& inAudioPcmFrame, media::base::AudioPcmFrame& adaptedPcmFrame) { return audioProcess_->processFrame(inAudioPcmFrame, adaptedPcmFrame) == 0; } // 调用 setProperty 设置音频插件参数。 int ExtensionAudioFilter::setProperty(const char* key, const void* buf, int buf_size) { std::string str_volume = "100"; if (std::string(key) == "volume") { str_volume = std::string(static_cast(buf), buf_size); } int int volume_ = atoi(str_volume.c_str()); audioProcessor_->setVolume(int_volume_); return ERR_OK; } // 调用 getProperty 查询音频插件参数。 int ExtensionAudioFilter::getProperty(const char* key, void* buf, int buf_size) const override {return ERR_OK; } // 调用 setEnabled 开启音频插件。 void ExtensionAudioFilter::setEnabled(bool enable) override { enabled_ = enable; } // 调用 isEnabled 查询音频插件开启状态。 bool ExtensionAudioFilter::isEnabled() const override {return enabled_; } // 在 getName 的返回值中传入插件名称。 const char* ExtensionAudioFilter::getName() const override { return "YourExtensionName"; } // (可选)在 getPreferredSampleRate 的返回值中指定音频插件需要的音频采样率。 const char* ExtensionAudioFilter::getPreferredSampleRate() override { return 48000; } // (可选)在 getPreferredChannelNumbers 的返回值中指定音频插件需要的音频声道数。 int ExtensionAudioFilter::getPreferredChannelNumbers() override { return 2; }; ``` ### 封装插件 [#封装插件-3] 封装插件通过 `IExtensionProvider` 接口类实现。该接口类位于 `NGIAgoraExtensionProvider.h` 文件中。你需要先实现这个接口类,并实现如下方法: - [`setExtensionControl`](#setextensioncontrol-3) - [`enumerateExtensions`](#enumerateextensions-3) - [`createAudioFilter`](#createaudiofilter-3) `IExtensionProvider` 是插件动态库的提供者,由全局唯一的名字标识。每一个插件动态库可以提供一个或多个有不同功能的插件,如音频前处理插件库可以提供不同功能的音频插件(Audio filter)。每个插件是一个具体的 Extension 对象。 #### setExtensionControl [#setextensioncontrol-3] 设置插件控制。 ```cpp virtual void setExtensionControl(IExtensionControl* control) ``` 成功调用该方法后,你需要保存 SDK 在该方法中返回的 `IExtensionControl` 对象。该对象用于触发事件或日志,实现插件与 App 之间的交互。例如,如果你调用了 `IExtensionControl` 中的 `fireEvent` 方法: ```cpp void ByteDanceProcessor::dataCallback(const char* data){ if (control_ != nullptr) { control_->fireEvent(id_, "beauty", data); } } ``` App 层在初始化 `RtcEngine` 时注册的 `IMediaExtensionObserver` 实例会收到该信息,并在 App 层触发如下回调: ```cpp @Override public void onEvent(String vendor, String key, String value) { // 其中的 vendor 为注册插件时的 VENDOR_NAME,key/value 是插件消息的键值对 ... } ``` #### enumerateExtensions [#enumerateextensions-3] 提供所有支持封装的插件的信息。SDK 在加载插件时,会调用该方法向插件发送回调。收到该回调后,你需要通过返回值提供所有支持封装的插件的信息。 ```cpp virtual void enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { (void) extension_list; extension_count = 0; } ``` | 参数 | 描述 | | --- | --- | | `extension_list` | [audio-filter-android-ios-macos-windows-html-1-1-1 details](#table-slot-audio-filter-android-ios-macos-windows-html-1-1-1-3) | | `extension_count` | 支持封装的插件的总数量。 | **audio-filter-android-ios-macos-windows-html-1-1-1 details** 插件的信息,包括插件类型和插件名称。 支持的音频插件类型有: - `AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER`(上行) - `AUDIO_POST_PROCESSING_FILTER`(上行) - `AUDIO_REMOTE_USER_PLAYBACK_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` 方法中返回的插件类型为 `AUDIO_FILTER`,则在 App 开发者初始化 `RtcEngine` 并创建 `IExtensionProvider` 对象后,SDK 会调用 `createAudioFilter` 方法。 #### createAudioFilter [#createaudiofilter-3] 创建音频插件。SDK 调用该方法后,你需要返回 `IAudioFilter` 实例。 ```cpp virtual agora_refptr createAudioFilter() ``` 成功创建 `IAudioFilter` 实例后,音频插件会在合适的时机通过 `IAudioFilter` 类对输入的音频数据进行处理。 #### 示例代码 [#示例代码-7] 参考如下示例代码了解如何使用上述方法封装音频插件: ```cpp void ExtensionProvider::enumerateExtensions(ExtensionMetaInfo* extension_list, int& extension_count) { extension_count = 1; ExtensionMetaInfo i; i.type = EXTENSION_TYPE::AUDIO_RECORDING_LOCAL_PLAYBACK_FILTER; i.extension_name = "YourExtensionName"; extension_list[0] = i; } agora_refptr ExtensionAudioProvider::createAudioFilter() { PRINTF_ERROR("ExtensionAudioProvider::createAudioFilter"); auto audioFilter = new agora::RefCountedObject(audioProcessor_); return audioFilter; } void ExtensionAudioProvider::setExtensionControl(rtc::IExtensionControl* control){ audioProcessor_->setExtensionControl(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" />