本文介绍如何在你的项目中集成和使用喜马拉雅实时音色转换插件,包括 Android 平台和 iOS 平台。
喜马拉雅实时音色转换插件是对喜马拉雅实时音色转换服务核心 API 的封装。通过声网 SDK v4.x 提供的 setExtensionProperty 或 setExtensionPropertyWithVendor 方法,传入指定的 key
和 value
参数,你可以快速集成喜马拉雅的转换发言人音色能力。
以 setExtensionProperty
为例,其中的 key
参数与喜马拉雅的 API 名称完全对应,value
参数以 JSON 格式包装该 API 的部分或全部参数。因此,调用 setExtensionProperty
时只要传入指定的 key
和 value
,就可以调用对应的喜马拉雅 API,实现转换发言人音色的有关功能。setExtensionPropertyWithVendor
同理。
平台 | 语言 | 示例项目 |
---|---|---|
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 |
Android
克隆仓库:
git clone https://github.com/xm-open/agora-hi-stream-vc-demo.git
进入声网控制台 > 云市场页面,下载喜马拉雅实时音色转换插件的 Android 插件包。解压后,将所有 .aar
文件保存到 app/libs
,其中 libs
文件夹需要你自行创建。
在 Android Studio 中打开示例项目 agora-hi-stream-vc-demo/android
。
将项目与 Gradle 文件同步。
点击下载喜马拉雅实时音色转换插件的素材包,保存到项目文件夹的 app/src/main/assets
路径,其中 assets
文件夹需要你自行创建,完整路径如下:
.
└── app
└── src
└── main
└── assets
└── stream_vc
└── init.json
打开 res/values/string_configs.xml
文件,进行如下修改:
<YOUR_APP_ID>
替换为你的 App ID。获取 App ID 请参考开始使用 Agora 平台。<YOUR_APP_KEY>
和 <YOUR_APP_SECRET>
分别替换为你的 appKey
和 appSecret
。获取方式详见购买和激活插件。 <?xml version="1.0" encoding="utf-8"?>
<resources>
<string name="agora_app_id" translatable="false">YOUR_APP_ID</string>
<string name="appKey" translatable="false">YOUR_APP_KEY</string>
<string name="secret" translatable="false">YOUR_APP_SECRET</string>
</resources>
连接一台 Android 真机(非模拟器),运行项目。
iOS
克隆仓库:
git clone https://github.com/xm-open/agora-hi-stream-vc-demo.git
进入声网控制台 > 云市场页面,下载喜马拉雅实时音色转换插件的 iOS 插件包。解压后,将所有 .xcframework
文件保存到 agora-hi-stream-vc-demo/ios/HiStreamVCExample/ExtensionExample
路径下。
在终端中进入 agora-hi-stream-vc-demo/ios/HiStreamVCExample
,运行以下命令使用 CocoaPods 安装依赖:
pod install
在 Xcode 中打开项目 agora-hi-stream-vc-demo/ios/HiStreamVCExample/ExtensionExample.xcodeproj
,并且删除 Pods_ExtensionExample.framework
。
点击下载喜马拉雅实时音色转换插件的素材包,保存到项目文件夹的 Resource
路径,完整路径如下:
.
├── <ProjectName>
├── <ProjectName>.xcodeproj
└── Resource
└── stream_vc
└── init.json
打开 AppID.m
文件,进行如下修改:
<#YOUR_APP_ID#>
和 <#YOUR_TOKEN#>
替换为你的 App ID 和临时 Token(对应产品为 RTC)。获取方式请参考开始使用 Agora 平台。<#YOUR_APP_KEY#>
和 <#YOUR_APP_SECRET#>
分别替换为你的 appKey
和 appSecret
。获取方式详见购买和激活插件。NSString *const appID = <#YOUR_APP_ID#>;
NSString *const token = <#YOUR_TOKEN#>;
NSString *const appkey = <#YOUR_APP_KEY#>;
NSString *const secret = <#YOUR_APP_SECRET#>;
连接一台 iOS 真机(非模拟器),运行项目。
运行成功后,示例项目会安装到你的 Android 或 iOS 设备上。
Android
agora_app_id
参数)不是正确有效的。iOS
appID
参数)不是正确有效的。喜马拉雅实时音色转换插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话:
在声网控制台购买和激活喜马拉雅实时音色转换插件,保存好获取到的 appKey
和 appSecret
,后续初始化插件时需要用到。
参考如下步骤在你的项目中集成喜马拉雅实时音色转换插件:
Android
.aar
文件保存到项目文件夹,比如 /app/libs
路径。app/src/main/assets
路径:.
└── app
└── src
└── main
└── assets
└── stream_vc
└── init.json
app/build.gradle
文件,在 dependencies
中添加如下行:implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"])
iOS
.xcframework
库文件保存到你的项目文件夹下。.
├── <ProjectName>
├── <ProjectName>.xcodeproj
└── Resource
└── stream_vc
└── init.json
#import <AgoraRtcKit/AgoraRtcEngineKit.h>
下面介绍插件相关接口的调用流程。接口的参数解释详见接口说明。
Android
创建并初始化 RtcEngine
后,首先调用 enableExtension
启用插件,再调用其它 API(enableVideo
、joinChannel
等)。
RtcEngineConfig config = new RtcEngineConfig();
// 加载插件
config.addExtension("agora-histreamvc-filter");
// 监听插件事件,用于接收 onEvent 回调
config.mExtensionObserver = this;
mRtcEngine = RtcEngine.create(config);
// 开启插件
mRtcEngine.enableExtension("Ximalaya", "HiStreamVC", true);
iOS
创建并初始化 AgoraRtcEngineKit
后,首先调用 enableExtensionWithVendor
启用插件,再调用其它 API(enableVideo
、joinChannelByToken
等)。
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];
收到声网 SDK 的 onExtensionStarted
回调后,调用 setExtensionProperty
(Android)或 setExtensionPropertyWithVendor
(iOS)并传入对应的 key 和 value。
初始化对应的 key 为 init_vc
,value 为 JSON 格式的字符串,包含四个键值对:
appkey
:在声网控制台激活插件后获取的 appKey。secret
:在声网控制台激活插件后获取的 appSecret。init_json
:素材包中 init.json
的路径。init_dir
: 素材包中 init.json
所在的目录。Android
private void initExtension() {
try {
JSONObject jsonObject = new JSONObject();
// 传入在声网控制台激活插件后获取的 appKey
jsonObject.put("appkey", "iamkey");
// 传入在声网控制台激活插件后获取的 appSecret
jsonObject.put("secret", "iamsecret");
jsonObject.put("init_json",
Objects.requireNonNull(getApplicationContext()).getExternalFilesDir(STREAM_VC_ASSET + "/init.json"));
jsonObject.put("init_dir",
Objects.requireNonNull(getApplicationContext()).getExternalFilesDir(STREAM_VC_ASSET));
engine.setExtensionProperty("Ximalaya", "HiStreamVC", ExtensionManager.KEY_INIT_FILTER, jsonObject.toString());
} catch (JSONException e) {
Log.e(TAG, e.toString());
e.printStackTrace();
}
}
iOS
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);
Android
private void start_vc(){
JSONObject jsonObject = new JSONObject();
setExtensionProperty(ExtensionManager.KEY_START_VC, jsonObject.toString());
}
iOS
- (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);
}
Android
private void stop_vc(){
JSONObject jsonObject = new JSONObject();
setExtensionProperty(ExtensionManager.KEY_STOP_VC, jsonObject.toString());
}
iOS
- (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);
}
需要停止使用插件时,按照以下步骤释放资源:
Android
mRtcEngine.enableExtension("Ximalaya", "HiStreamVC", false);
iOS
[self.agoraKit enableExtensionWithVendor:@"Ximalaya"
extension:@"HiStreamVC"
enabled:NO];
插件所有相关接口的参数解释详见接口说明。