使用说明

本文介绍如何在你的项目中集成和使用喜马拉雅实时音色转换插件。

技术原理

喜马拉雅实时音色转换插件是对喜马拉雅实时音色转换服务核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionPropertyWithVendor 方法，传入指定的 key 和 value 参数，你可以快速集成喜马拉雅的转换发言人音色能力。

setExtensionPropertyWithVendor 方法的 key 参数与喜马拉雅的 API 名称完全对应，value 参数以 JSON 格式包装该 API 的部分或全部参数。因此，调用该方法时只要传入指定的 key 和 value，就可以调用对应的喜马拉雅 API，实现转换发言人音色的有关功能。

前提条件

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

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

示例项目

喜马拉雅实时音色转换插件提供了一个 GitHub 示例项目，你可以前往克隆或下载并进行体验。

平台	语言	示例项目
Android	Java	https://github.com/xm-open/agora-hi-stream-vc-demo/tree/main/android
iOS	Objective-C	https://github.com/xm-open/agora-hi-stream-vc-demo/tree/main/ios/HiStreamVCExample

运行步骤

参考以下步骤快速跑通示例项目：

1. 克隆仓库：

   Shell

   git clone https://github.com/xm-open/agora-hi-stream-vc-demo.git
   

2. 进入声网控制台 > 云市场页面，下载喜马拉雅实时音色转换插件的 iOS 插件包。解压后，将所有 .xcframework 文件保存到 agora-hi-stream-vc-demo/ios/HiStreamVCExample/ExtensionExample 路径下。

3. 在终端中进入 agora-hi-stream-vc-demo/ios/HiStreamVCExample，运行以下命令使用 CocoaPods 安装依赖：

   Shell

   pod install

4. 在 Xcode 中打开项目 agora-hi-stream-vc-demo/ios/HiStreamVCExample/ExtensionExample.xcodeproj，并且删除 Pods_ExtensionExample.framework。

5. 点击下载喜马拉雅实时音色转换插件的素材包，保存到项目文件夹的 Resource 路径，完整路径如下:

   Shell

   .
   ├── <ProjectName>
   ├── <ProjectName>.xcodeproj
   └── Resource
       └── stream_vc
           └── init.json

6. 打开 AppID.m 文件，进行如下修改：

   • 将 <#YOUR_APP_ID#> 和 <#YOUR_TOKEN#> 替换为你的 App ID 和临时 Token（对应产品为 RTC）。获取方式请参考开通服务。

   • 将 <#YOUR_APP_KEY#> 和 <#YOUR_APP_SECRET#> 分别替换为你的 appKey 和 appSecret。获取方式详见购买和激活插件。

     Objective-C

     NSString *const appID = <#YOUR_APP_ID#>;
     NSString *const token = <#YOUR_TOKEN#>;
     NSString *const appkey = <#YOUR_APP_KEY#>;
     NSString *const secret = <#YOUR_APP_SECRET#>;

7. 连接一台 iOS 真机（非模拟器），运行项目。

预期效果

运行成功后，示例项目会安装到你的设备上。参考如下步骤体验音色转换效果：

信息

为了更好地体验示例项目的音色转换效果，建议使用女声作为输入。输入的女声会转换成男性青年音色。

1. 启动 App，可以看到界面上的加入频道按钮。
2. 输入 channel id（使用临时 token 生成器时填入的频道名），然后点击加入频道进入指定频道，加入频道按钮会变为离开频道。如果加入频道按钮变灰，但是没有变为离开频道，可能是因为你的声网 App ID（appID 参数）不是正确有效的。
3. 点击初始化插件按钮初始化插件，初始化插件按钮会变为不可选，start_vc 按钮会变为可选。
4. 点击 start_vc 开始音色转换。此时 start_vc 按钮会变为不可选，stop_vc 按钮变为可选。
5. 点击 stop_vc 结束音色转换。
6. 点击离开频道按钮退出频道，同时关闭实时音色转换插件。

集成和调用流程

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

1. 集成 SDK 和插件

开始前，你需要在项目中分别集成声网音频 SDK 和喜马拉雅实时音色转换插件。

1.1 集成声网音频 SDK

喜马拉雅实时音色转换插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话：

实现语音通话

信息

喜马拉雅实时音色转换插件支持声网 SDK v4.1.1 或以上版本。

1.2 购买和激活插件

在声网控制台购买和激活喜马拉雅实时音色转换插件，保存好获取到的 appKey 和 appSecret，后续初始化插件时需要用到。

1.3 集成插件

参考如下步骤在你的项目中集成喜马拉雅实时音色转换插件：

1. 进入声网控制台 > 云市场页面，下载喜马拉雅实时音色转换插件的 iOS 插件包。

2. 解压文件夹，将所有 .xcframework 库文件保存到你的项目文件夹下。

3. 点击下载喜马拉雅实时音色转换插件的素材包，保存到项目文件夹，比如 Resource 路径：

   Shell

   .
   ├── <ProjectName>
   ├── <ProjectName>.xcodeproj
   └── Resource
       └── stream_vc
           └── init.json

4. 在 Xcode 中进入 TARGETS > Build Settings > Build Options > Enable Bitcode，设置为 No，关闭 Bitcode。

5. 导入需要用到的头文件：

   Objective-C

   #import <AgoraRtcKit/AgoraRtcEngineKit.h>

1.4 升级插件

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

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

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

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

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

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

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

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

注意

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

2. 启用插件

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

Objective-C

AgoraRtcEngineConfig *config = [AgoraRtcEngineConfig new];
config.appId = appID;
// 监听插件事件，用于接收 onEvent 回调
config.eventDelegate = self;
AgoraLogConfig *logConfig = [AgoraLogConfig new];
logConfig.level = AgoraLogLevelInfo;
config.logConfig = logConfig;
self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:config
                                                    delegate:self];
// 开启插件
int ret = [self.agoraKit enableExtensionWithVendor:@"Ximalaya"
                                            extension:@"HiStreamVC"
                                            enabled:YES];

3. 初始化插件

收到声网 SDK 的 onExtensionStarted 回调后，调用 setExtensionPropertyWithVendor 并传入对应的 key 和 value。

初始化对应的 key 为 init_vc，value 为 JSON 格式的字符串，包含四个键值对：

• appkey：在声网控制台激活插件后获取的 appKey。
• secret：在声网控制台激活插件后获取的 appSecret。
• init_json：素材包中 init.json 的路径。
• init_dir: 素材包中 init.json 所在的目录。

Objective-C

NSError *error;
NSData *data = [NSJSONSerialization dataWithJSONObject:@{@"appkey": appkey,
                                                         @"secret": secret,
                                                         @"init_json": self.json_init,
                                                         @"init_dir": self.dir_init
                                                       }
                                               options:NSJSONWritingPrettyPrinted
                                                 error:&error];
int ret = [self.agoraKit
           setExtensionPropertyWithVendor:@"Ximalaya"
           extension:@"HiStreamVC"
           key:KEY_INIT_FILTER
           value:[[NSString alloc]
                  initWithData:data
                  encoding:NSUTF8StringEncoding]];
NSLog(@"after init: %d", ret);

4. 开始音色转换

调用 start_vc 开始音色转换。

Objective-C

- (IBAction)startVCAction:(id)sender {
    NSError *error;
    NSData *data = [NSJSONSerialization dataWithJSONObject:@{  }
                                                   options:NSJSONWritingPrettyPrinted
                                                     error:&error];
    int ret = [self.agoraKit
               setExtensionPropertyWithVendor:@"Ximalaya"
               extension:@"HiStreamVC"
               key:KEY_START_VC
               value:[[NSString alloc]
                      initWithData:data
                      encoding:NSUTF8StringEncoding]];
    NSLog(@"after start_vc: %d", ret);
}

4. 停止音色转换

完成后调用 stop_vc 停止音色转换。

Objective-C

- (IBAction)stopVCAction:(id)sender {
    NSError *error;
    NSData *data = [NSJSONSerialization dataWithJSONObject:@{  }
                                                   options:NSJSONWritingPrettyPrinted
                                                     error:&error];
    int ret = [self.agoraKit
               setExtensionPropertyWithVendor:@"Ximalaya"
               extension:@"HiStreamVC"
               key:KEY_STOP_VC
               value:[[NSString alloc]initWithData:data
                                          encoding:NSUTF8StringEncoding]];
    NSLog(@"after stop_vc: %d", ret);
}

5. 停用插件释放资源

需要停止使用插件时，按照以下步骤释放资源：

Objective-C

[self.agoraKit enableExtensionWithVendor:@"Ximalaya"
                               extension:@"HiStreamVC"
                                 enabled:NO];

API 参考

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