使用说明

本文介绍如何在你的项目中集成和使用大饼 AI 变声插件。

技术原理

大饼 AI 变声插件是对实时 AI 声音转换核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor 方法，传入指定的 key 和 value 参数，你可以快速集成格子互动的实时 AI 声音转换能力。

setExtensionPropertyWithVendor 方法的 key 参数与格子互动的 API 名称完全对应，value 参数以 JSON 格式包装该 API 的部分或全部参数。因此，调用该方法时只要传入指定的 key 和 value，就可以调用对应的格子互动 API，实现实时 AI 声音转换的有关功能。

前提条件

iOS 开发环境需满足以下要求：

• Xcode 或以上版本。
• 运行 iOS 或以上版本的真机（非模拟器）。

示例项目

大饼 AI 变声插件提供了一个 GitHub 示例项目，你可以前往克隆或下载并进行体验。

平台	语言	示例项目
Android	Kotlin	https://github.com/Dubbing-AI-Voice-Changer/DubbingAgoraDemo/tree/main/Android
iOS	Objective-C	https://github.com/Dubbing-AI-Voice-Changer/DubbingAgoraDemo/tree/main/iOS

具体步骤如下：

1. 克隆仓库：

   Shell

   git clone https://github.com/Dubbing-AI-Voice-Changer/DubbingAgoraDemo.git

2. 参考仓库的 README.md 文件完成后续步骤。

集成和调用流程

本节介绍如何集成声网 SDK 和插件，并调用核心 API 实现变声功能。

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网音频 SDK 和 大饼 AI 变声插件。

1.1 集成声网音频 SDK

大饼 AI 变声插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话：

实现语音通话

1.2 集成大饼 AI 变声插件

参考如下步骤在你的项目中集成大饼 AI 变声插件：

1. 进入声网控制台 > 云市场页面，下载大饼 AI 变声插件的 iOS 插件包。

2. 解压文件夹，将所有 .framework 文件导入项目，并将 Embed 修改为 Embed & Sign。

3. 获取以下资源文件并保存到项目文件夹的同一路径（比如 Resource 路径）：

   • License 文件和音色文件：联系声网获取。其中音色文件的后缀名为 .dat，会根据 License 发放。
   • 模型文件：根据示例项目 Readme 的说明下载所需资源。
   

4. 在项目中导入 libc++ 系统库以及第三方动态库 'MJExtension'。

1.3 升级插件

声网云市场推荐你更新插件版本前使用数据库工具 (如 SQLite) 来实现插件版本管理，从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时，会出现 App 闪退、崩溃等现象。

以下是用 SQLite 来进行插件版本管理的示例：

1. 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
2. 每次项目初始化时，自动检测当前项目使用的资源包版本：
   • 如果无记录文件或记录的资源包版本为旧，则更新资源。成功更新后，回写最新资源包版本信息到 SQLite。
   • 如果记录的资源包版本与当前匹配，则正常实现业务。

如果你的项目已经集成过声网云市场提供的第三方插件，并需要更新插件，可以参考以下步骤来保证更新后的可用性。

以下升级流程以相芯美颜特效插件为例：

1. 参考集成插件章节下载所需平台最新版本的插件包和资源包。

2. 删除项目内旧版本的插件包及其资源包后，再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。

3. 删除设备上用老版本插件和资源包编译的 App，重新编译你的项目并运行。

信息

编译 App 时，系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行，否则可能会出现插件版本与资源包不匹配的情况，从而导致各种意外问题。

2. 启用插件

创建并初始化 AgoraRtcEngineKit 后，首先调用 enableExtensionWithVendor 启用插件，再调用其它 API（enableVideo、joinChannelByToken 等）。

Objective-C

AgoraRtcEngineConfig *cfg = [[AgoraRtcEngineConfig alloc] init];
cfg.appId = appId;
cfg.eventDelegate = self;
cfg.channelProfile = AgoraChannelProfileLiveBroadcasting;
cfg.audioScenario = AgoraAudioScenarioGameStreaming;
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:cfg delegate:self];
[self.agoraKit setClientRole:AgoraClientRoleBroadcaster];

[self.agoraKit enableExtensionWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" enabled:YES];

3. 设置资源文件路径

在集成插件时，你已经将 License 文件、音色文件、模型文件保存在指定目录。这一步只需要传入这些资源文件所在路径：

Objective-C

NSString *sourcePath = [[NSBundle mainBundle] resourcePath];
[self.agoraKit setExtensionPropertyWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" key:@"setResourcesFilePath" value:sourcePath];

4. 获取音色列表

收到声网 SDK 的 onExtensionStarted 回调后，调用 getExtensionPropertyWithVendor，传入 key 为 getSpeakersInfo，获取音色列表：

Objective-C

NSString *voices = [self.agoraKit getExtensionPropertyWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" key:@"getSpeakersInfo"];
// 将 JSON 转换为数组
NSData *nsData = [voices dataUsingEncoding:NSUTF8StringEncoding];
_speakerArray = [NSJSONSerialization JSONObjectWithData:nsData options:kNilOptions error:nil];

音色列表以 JSON 数据返回，你需要自行解析。

5. 开始变声

调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value。

Objective-C

[self.agoraKit setExtensionPropertyWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" key:@"startRealTimeTranscribe" value:@"startRealTimeTranscribe"];

6. 选择音色

传入第 4 步获取的音色列表中的音色 ID，即可设置成对应的音色：

Objective-C

[self.agoraKit setExtensionPropertyWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" key:@"changeSpeaker" value:@“”];

7. 停止变声

完成后调用 API 停止变声：

Objective-C

[self.agoraKit setExtensionPropertyWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" key:@"stopRealTimeTranscribe" value:@"stopRealTimeTranscribe"];

8. 释放资源

关闭插件，释放插件所占用的资源。

Objective-C

[self.agoraKit enableExtensionWithVendor:[EngineFilterManager vendorName] extension:@"RealTimeTranscribe" enabled:NO];

API 参考

• 声网 SDK 的插件相关方法和回调
• 插件的 key-value 说明