使用说明
- Web
更新时间
了解云市场在不同平台上的集成讯飞转写及翻译插件方式,包括接入流程、关键配置和平台差异。
技术原理
本文介绍如何在你的项目中集成和使用讯飞语音实时转写及翻译(多语种)插件(以下简称“讯飞转写及翻译插件”)。讯飞转写及翻译插件的工作流程如下:
- 设置源语种和目标语种。
- 声网 SDK 通过麦克风来流式录音。
- 音频传递给讯飞转写及翻译插件。
- 插件把音频上传给语音转写服务,并下载语音转写结果。
- 解析语音转写结果,得到语音转写文本。
- 把语音转写文本上传给文本翻译服务,并下载文本翻译结果。
- 解析文本翻译结果,得到文本翻译文本。
前提条件
Android 开发环境需满足以下要求:
- Android Studio 4.1 以上版本。
- 运行 Android 4.1 或以上版本的真机(非模拟器)。
示例项目
讯飞转写及翻译插件提供了示例项目,你可以前往克隆或下载并进行体验。
运行步骤
参考以下步骤快速跑通示例项目:
-
在 Android Studio 中打开示例项目。
-
将项目与 Gradle 文件同步。
-
打开
AgoraWithHyAndroid/app/src/main/java/agoramarketplace/hy/demo/MainActivity.java文件,将#YOUR APP ID#替换为你的声网 App ID。获取 App ID 请参考开通云市场服务。Java private static final String appId = "#YOUR APP ID#"; -
打开
AgoraWithHyAndroid/app/src/main/java/agoramarketplace/hy/demo/HyUtil.java文件,填入以下参数:Java /** 在声网控制台购买插件后、由讯飞提供的 APPID */ public static final String APP_ID = ""; /** 在声网控制台购买插件后、由讯飞提供的 APIKey */ public static final String API_KEY = ""; /** 在声网控制台购买插件后、由讯飞提供的 APISecret */ public static final String API_SECRET = ""; -
连接一台 Android 真机(非模拟器),运行项目。
预期效果
运行成功后,示例项目会安装到你的设备上。
- 启动 App,你可以在界面上看到中译英下拉控件,start、flush、stop 按钮,以及 tip、ist_text、its_text 文本视图。
- 可以单击中译英下拉控件选择参数。
- 单击 start 按钮启动倾听。
- 对着麦克风说话,语音转写文本会显示在 ist_text 文本视图中,文本翻译文本会显示在 its_text 文本视图中。
- 单击 flush 按钮结束音频获取结果,或单击 stop 按钮停止倾听。
- tip 文本视图会显示 onEnd。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网音频 SDK 和讯飞转写及翻译插件。
1.1 集成声网音频 SDK
讯飞转写及翻译插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话:
1.2 购买和激活插件
你需要进入声网控制台 > 云市场页面,按照提示购买讯飞转写及翻译插件。购买成功后,你会收到由讯飞提供的 APPID、APIKey 和 APISecret,后续启动倾听时需要用到。
1.3 集成插件
参考以下步骤集成插件:
-
进入声网控制台 > 云市场页面下载**讯飞语音实时转写及翻译(多语种)**的 Android 插件包。
-
解压文件夹,将所有
.aar文件保存到项目文件夹的/app/libs路径。 -
打开
app/build.gradle文件,在dependencies中添加如下行:Java implementation fileTree(dir: "libs", include: ["*.jar", "*.aar"]) -
打开编写逻辑的 Java 文件,添加如下行,导入插件信息类:
Java import io.agora.hy.extension.ExtensionManager;
1.4 升级插件
声网云市场推荐你在更新插件版本前使用数据库工具(如 SQLite)实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。
以下是用 SQLite 来进行插件版本管理的示例:
- 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
- 每次项目初始化时,自动检测当前项目使用的资源包版本:
- 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。
- 如果记录的资源包版本与当前匹配,则正常实现业务。
如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。
以下升级流程以相芯美颜特效插件为例:
-
参考集成插件章节下载所需平台最新版本的插件包和资源包。
-
删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
-
删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。
注意
编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。
2. 初始化
集成插件后,你需要先初始化插件,步骤如下:
-
RtcEngineConfig实例调用addExtension,将插件添加到 SDK 中。Java config.addExtension(ExtensionManager.EXTENSION_NAME); -
RtcEngineConfig实例设置mExtensionObserver监听器。Java private final IMediaExtensionObserver mMediaExtensionObserver = new IMediaExtensionObserver() { @Override public void onEvent(String provider, String extension, String key, String value) { Log.i(TAG, "onEvent | provider: " + provider + ", extension: " + extension + ", key: " + key + ", value: " + value); if (!ExtensionManager.EXTENSION_VENDOR_NAME.equals(provider) || !ExtensionManager.EXTENSION_AUDIO_FILTER_NAME.equals(extension)) { return; } mHyUtil.onEvent(key, value); } }Java config.mExtensionObserver = mMediaExtensionObserver; -
在加入频道前,调用
enableExtension开启插件。Java mRtcEngine.enableExtension(ExtensionManager.EXTENSION_VENDOR_NAME, ExtensionManager.EXTENSION_AUDIO_FILTER_NAME, true); -
插件设置 logcat 日志等级。
Java mRtcEngine.setExtensionProviderProperty(ExtensionManager.EXTENSION_VENDOR_NAME, "log_lvl", "" + 8);
3. 启动倾听
空闲时可调用,调用后会进入会话。会话最长 5 小时。
public void start(ParamWrap paramWrap) {
mParser.clear();
String val = null;
try {
JSONObject rootJo = new JSONObject();
// 公共对象。必选。
JSONObject commonJo = new JSONObject();
{
// 应用标识。必选。对应在声网控制台购买插件后、由讯飞提供的 APPID。
commonJo.put("app_id", APP_ID);
// API 密钥。必选。对应在声网控制台购买插件后、由讯飞提供的 APIKey。
commonJo.put("api_key", API_KEY);
// API 秘密。必选。对应在声网控制台购买插件后、由讯飞提供的 APISecret。
commonJo.put("api_secret", API_SECRET);
}
rootJo.put("common", commonJo);
// 语音转写对象。必选。
JSONObject istJo = new JSONObject();
{
// URI。必选。
istJo.put("uri", "wss://ist-api.xfyun.cn/v2/ist");
// 请求对象。必选。
JSONObject reqJo = new JSONObject();
{
// 业务对象。必选。
JSONObject businessJo = new JSONObject();
{
// 语种。必选。
businessJo.put("language", paramWrap.mIstLanguage);
// 口音。必选。
businessJo.put("accent", paramWrap.mIstAccent);
// 领域。必选。
businessJo.put("domain", paramWrap.mIstDomain);
// 语言类型
// 值类型:int
// 值范围:
// 1:中英文模式,中文英文均可识别;
// 3:英文模式,只识别出英文
// 值默认:1
businessJo.put("language_type", paramWrap.mIstLanguageType);
// 动态修正
businessJo.put("dwa", paramWrap.mIstDwa);
}
reqJo.put("business", businessJo);
}
istJo.put("req", reqJo);
}
rootJo.put("ist", istJo);
// 文本翻译对象。
JSONObject itsJo = new JSONObject();
{
// URI。必选。
itsJo.put("uri", "https://itrans.xfyun.cn/v2/its");
// 请求对象。必选。
JSONObject reqJo = new JSONObject();
{
// 业务对象。必选。
JSONObject businessJo = new JSONObject();
{
// 源语种。必选。
businessJo.put("from", paramWrap.mItsFrom);
// 目标语种。必选。
businessJo.put("to", paramWrap.mItsTo);
}
reqJo.put("business", businessJo);
}
itsJo.put("req", reqJo);
}
rootJo.put("its", itsJo);
val = rootJo.toString();
} catch (JSONException e) {
mListener.onLogE(TAG + ".start | json fail", e);
return;
}
int errCode = mRtcEngine.setExtensionProperty(ExtensionManager.EXTENSION_VENDOR_NAME,
ExtensionManager.EXTENSION_AUDIO_FILTER_NAME, "start_listening", val);
mListener.onLogI(TAG + ".start | mRtcEngine.setExtensionProperty errCode: " + errCode);
}4. 结束音频获取结果
会话时可调用,调用后会先处理完音频和结果,再进入空闲,回调 "end"。
public void flush() {
// 值不能为空,否则收不到。
int errCode = mRtcEngine.setExtensionProperty(ExtensionManager.EXTENSION_VENDOR_NAME, ExtensionManager.EXTENSION_AUDIO_FILTER_NAME, "flush_listening", "{}");
mListener.onLogI(TAG + ".flush | mRtcEngine.setExtensionProperty errCode: " + errCode);
}讯飞转写及翻译插件会通过 onEvent 回调返回语音转写和文本翻译结果。识别结果的含义详见 onEvent 回调的 key。
5. 停止倾听
会话时可调用,调用后会先丢弃音频和结果,再进入空闲,回调 "end"。
public void stop() {
int errCode = mRtcEngine.setExtensionProperty(ExtensionManager.EXTENSION_VENDOR_NAME, ExtensionManager.EXTENSION_AUDIO_FILTER_NAME, "stop_listening", "{}");
mListener.onLogI(TAG + ".stop | mRtcEngine.setExtensionProperty errCode: " + errCode);
}参考信息
API 参考
常见问题
1. 在 MacBook 上运行 Android 示例项目为什么会编译失败?
由于示例项目中 Android NDK 的路径默认为 Windows 设备上的路径,因此在 MacBook 上会编译失败并提示 Location specified by ndk.dir did not contain a valid NDK。参考以下步骤解决:
-
在 Android Studio 的顶部菜单栏中依次点击 File > Project Structure... > SDK Location,将 Android NDK location 的路径替换为你的本地路径,并且复制该路径。
-
打开
local.properties文件,将ndk.dir的路径替换为你刚才复制的路径,并且保存修改。 -
连接 Android 设备,再次运行。
2. 为什么在编译 App 时会出现 models: no match 的报错?
该错误通常是由于资源包匹配问题引起的。很可能是因为在编译新插件时,没有删除旧版本的 App。建议你删除旧版 App 后重新编译运行。
本文介绍如何在你的项目中集成和使用讯飞语音实时转写及翻译(多语种)插件(以下简称“讯飞转写及翻译插件”)。
技术原理
讯飞转写及翻译插件的工作流程如下:
- 设置源语种和目标语种。
- 声网 SDK 通过麦克风来流式录音。
- 音频传递给讯飞转写及翻译插件。
- 插件把音频上传给语音转写服务,并下载语音转写结果。
- 解析语音转写结果,得到语音转写文本。
- 把语音转写文本上传给文本翻译服务,并下载文本翻译结果。
- 解析文本翻译结果,得到文本翻译文本。
前提条件
iOS 开发环境需满足以下要求:
- Xcode 9.0 或以上版本。
- 运行 iOS 9.0 或以上版本的真机(非模拟器)。
示例项目
讯飞转写及翻译插件提供了示例项目,你可以前往克隆或下载并进行体验。
运行步骤
参考以下步骤快速跑通示例项目:
-
在 Xcode 中打开
AgoraWithHyIos/AgoraWithHyIos.xcodeproj。 -
打开
AppID.m文件,将#YOUR APP ID#替换为你的声网 App ID。获取 App ID 请参考开通云市场服务。Objective-C NSString *const appID = @"#YOUR APP ID#"; -
打开
AgoraWithHyIos/VideoChatViewController.m文件,填入以下参数:Objective-C // "app_id"、"api_key"、"api_secret" 分别对应在声网控制台购买插件后、由讯飞提供的 APPID、APIKey 和 APISecret NSDictionary *commonDict = @{@"app_id":@"",@"api_key":@"",@"api_secret":@""}; -
连接一台 iOS 真机(非模拟器),运行项目。
预期效果
运行成功后,示例项目会安装到你的设备上。
- 启动 App,你可以在界面上看到中译英下拉控件,start、flush、stop 按钮,以及 tip、ist_text、its_text 文本视图。
- 可以单击中译英下拉控件选择参数。
- 单击 start 按钮启动倾听。
- 对着麦克风说话,语音转写文本会显示在 ist_text 文本视图中,文本翻译文本会显示在 its_text 文本视图中。
- 单击 flush 按钮结束音频获取结果,或单击 stop 按钮停止倾听。
- tip 文本视图会显示 onEnd。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网音频 SDK 和讯飞转写及翻译插件。
1.1 集成声网音频 SDK
讯飞转写及翻译插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话:
1.2 购买和激活插件
你需要进入声网控制台 > 云市场页面,按照提示购买讯飞转写及翻译插件。购买成功后,你会收到由讯飞提供的 APPID、APIKey 和 APISecret,后续启动倾听时需要用到。
1.3 集成插件
参考以下步骤集成插件:
-
进入声网控制台 > 云市场页面下载**讯飞语音实时转写及翻译(多语种)**的 iOS 插件包。
-
解压文件夹,将所有
.framework文件保存到你的项目文件夹下。以如下项目结构为例,你可以把插件保存到frameworks路径下。Shell . ├── <ProjectName> │ ├── frameworks ├── <ProjectName>.xcodeproj
1.4 升级插件
声网云市场推荐你在更新插件版本前使用数据库工具(如 SQLite)实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。
以下是用 SQLite 来进行插件版本管理的示例:
- 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
- 每次项目初始化时,自动检测当前项目使用的资源包版本:
- 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。
- 如果记录的资源包版本与当前匹配,则正常实现业务。
如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。
以下升级流程以相芯美颜特效插件为例:
-
参考集成插件章节下载所需平台最新版本的插件包和资源包。
-
删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
-
删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。
注意
编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。
2. 初始化
集成插件后,你需要先初始化插件,步骤如下:
-
开启插件。
Objective-C AgoraRtcEngineConfig *cfg = [AgoraRtcEngineConfig new]; cfg.appId = appID; cfg.eventDelegate = self; self.agoraKit = [AgoraRtcEngineKit sharedEngineWithConfig:cfg delegate:self]; [self.agoraKit enableExtensionWithVendor:@"Hy" extension:@"IstIts" enabled:YES]; -
实现代理方法。
Objective-C #pragma mark - AgoraMediaFilterEventDelegate (self需要实现代理方法) - (void)onEvent:(NSString * _Nullable)vendor extension:(NSString *)extension key:(NSString * _Nullable)key value:(NSString * _Nullable)value {} -
设置插件日志等级。
Objective-C [self.agoraKit setExtensionProviderPropertyWithVendor:@"Hy" key:@"log_lvl" value:@"4"];
3. 启动倾听
空闲时可调用,调用后会进入会话。会话最长 5 小时。
- (void)hyStart:(id)obj{
[itsDataDict removeAllObjects];
[istDataDict removeAllObjects];
NSString *type =@"中译英";
NSMutableDictionary *rootDict = [NSMutableDictionary dictionary];
// "app_id"、"api_key"、"api_secret" 分别对应在声网控制台购买插件后、由讯飞提供的 APPID、APIKey 和 APISecret
NSDictionary *commonDict = @{@"app_id":@"",@"api_key":@"",@"api_secret":@""};
[rootDict setObject:commonDict forKey:@"common"];
NSMutableDictionary *istDict = [NSMutableDictionary dictionary];
[istDict setObject:@"wss://ist-api.xfyun.cn/v2/ist" forKey:@"uri"];
NSMutableDictionary *itsDict = [NSMutableDictionary dictionary];
[itsDict setObject:@"https://itrans.xfyun.cn/v2/its" forKey:@"uri"];
if([mSelectedType isEqualToString:type]){
NSDictionary *istBusinessDict = @{@"language":@"zh_cn",@"accent":@"mandarin",@"domain":@"ist_ed_open",@"language_type":@1,@"dwa":@"wpgs"};
NSDictionary *istReqDict = @{@"business":istBusinessDict};
[istDict setObject:istReqDict forKey:@"req"];
[rootDict setObject:istDict forKey:@"ist"];
NSDictionary *itsBusinessDict = @{@"from":@"cn",@"to":@"en"};
NSDictionary *itsReqDict = @{@"business":itsBusinessDict};
[itsDict setObject:itsReqDict forKey:@"req"];
[rootDict setObject:itsDict forKey:@"its"];
}else{
NSDictionary *businessDict = @{@"language":@"zh_cn",@"accent":@"mandarin",@"domain":@"ist_ed_open",@"language_type":@3,@"dwa":@"wpgs"};
NSDictionary *reqDict = @{@"business":businessDict};
[istDict setObject:reqDict forKey:@"req"];
[rootDict setObject:istDict forKey:@"ist"];
NSDictionary *itsBusinessDict = @{@"from":@"en",@"to":@"cn"};
NSDictionary *itsReqDict = @{@"business":itsBusinessDict};
[itsDict setObject:itsReqDict forKey:@"req"];
[rootDict setObject:itsDict forKey:@"its"];
}
NSData *data=[NSJSONSerialization dataWithJSONObject:rootDict options:NSJSONWritingPrettyPrinted error:nil];
NSString *str=[[NSString alloc]initWithData:data encoding:NSUTF8StringEncoding];
[self.agoraKit setExtensionPropertyWithVendor:@"Hy" extension:@"IstIts" key:@"start_listening" value:str];
}4. 结束音频获取结果
会话时可调用,调用后会先处理完音频和结果,再进入空闲,回调 "end"。
- (void)hyFlush:(id)obj{
[self.agoraKit setExtensionPropertyWithVendor:@"Hy" extension:@"IstIts" key:@"flush_listening" value:@"{}"];
}讯飞转写及翻译插件会通过 onEvent 回调返回语音转写和文本翻译结果。识别结果的含义详见 onEvent 回调的 key。
5. 停止倾听
会话时可调用,调用后会先丢弃音频和结果,再进入空闲,回调 "end"。
- (void)hyStop:(id)obj{
[self.agoraKit setExtensionPropertyWithVendor:@"Hy" extension:@"IstIts" key:@"stop_listening" value:@"{}"];
}参考信息
API 参考
本文介绍如何在你的 Web 项目中集成和使用讯飞语音实时转写及翻译(多语种)插件(以下简称“讯飞转写及翻译插件”)。
前提条件
- Windows 或 macOS 计算机,需满足以下要求:
- 下载桌面端 Chrome 90 或以上版本。
- 具备物理音视频采集设备。
- 可连接到互联网。如果你的网络环境部署了防火墙,请参考应对防火墙限制以正常使用声网服务。
- 搭载 2.2 GHz Intel 第二代 i3/i5/i7 处理器或同等性能的其他处理器。
- 安装 Node.js 及 npm。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网 Web SDK 和讯飞转写及翻译插件。
1.1 集成声网 Web SDK
讯飞转写及翻译插件需要与声网 Web SDK 4.x(v4.10.0 或以上)搭配使用。参考以下文档集成 Web SDK 并实现基础的语音通话:
1.2 购买和激活插件
在声网控制台购买和激活讯飞转写及翻译插件。购买成功后,你会收到由讯飞提供的 appKey 和 appSecret,后续使用插件时需要用到。
1.3 集成插件
通过 npm 将讯飞转写及翻译插件集成到你的项目中。
-
运行以下命令安装插件:
Shell npm install hyrt -
在你的
.js文件中加入以下代码导入插件模块:JavaScript import { HySimpleAudioExtension } from 'hyrt'
2. 配置反向代理
如果需要使用插件的翻译功能,你需要配置反向代理以解决翻译跨域问题。
以 Nginx 为例:
server {
listen 80;
server_name localhost;
location / {
root D:\\proj\\test-plugin;
index index.html index.htm;
}
# 示例如下
location /v2/its {
proxy_http_version 1.1;
proxy_pass https://itrans.xfyun.cn/v2/its;
proxy_redirect off;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header Host 'itrans.xfyun.cn'; # 固定请求头中的Host
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_read_timeout 300;
proxy_send_timeout 300;
}
}3. 启用插件
启用插件的示例代码如下:
import AgoraRTC from "agora-rtc-sdk-ng"
import { HySimpleAudioExtension } from 'hyrt'
// 创建 extension 实例
const audioExtension = new HySimpleAudioExtension();
// 注册插件
AgoraRTC.registerExtensions([audioExtension]);
// 创建 processor 实例
const processor = audioExtension.createProcessor();
// 通过麦克风采集的音频创建音频轨道
const audioTrack = await AgoraRTC.createMicrophoneAudioTrack();
// 将讯飞插件注入声网的音频处理管道,并从扬声器输出
audioTrack.pipe(processor).pipe(audioTrack.processorDestination);
// 设置识别参数
processor.setOptions(common, ist, its, callback)
// 启用插件
processor.enable()
// 停止插件
setTimeout(() => { processor.disable() }, 60000)setOptions 方法中的参数设置详见插件独有 API。你可以使用 setOptions 方法中的 callback 参数来处理识别结果,示例如下:
function callback(r) {
if (r.key === 'ist_result') {
let sn = r.value.data.result.sn
let ws = r.value.data.result.ws
let words = ''
for (let index = 0; index < ws.length; index++) {
const element = ws[index];
words += element.cw[0].w
}
console.log(`sn: ${sn}, words: ${words}`)
} else if (r.key === 'its_result') {
let sn = r.value.ist_sn
let trans_result = r.value.data.result.trans_result
console.log(`sn: ${sn}, [${trans_result.src}] => [${trans_result.dst}]`)
} else if (r.key === 'error') {
console.log(r.key, r.value)
} else if (r.key === 'end') {
console.log('识别结束')
}
}API 参考
- 声网 Web SDK 的插件相关方法:
- 插件独有 API
本文介绍如何在你的项目中集成和使用讯飞语音实时转写及翻译(多语种)插件(以下简称“讯飞转写及翻译插件”)。
技术原理
讯飞转写及翻译插件的工作流程如下:
- 设置源语种和目标语种。
- 声网 SDK 通过麦克风来流式录音。
- 音频传递给讯飞转写及翻译插件。
- 插件把音频上传给语音转写服务,并下载语音转写结果。
- 解析语音转写结果,得到语音转写文本。
- 把语音转写文本上传给文本翻译服务,并下载文本翻译结果。
- 解析文本翻译结果,得到文本翻译文本。
前提条件
Windows 开发环境需满足以下要求:
- Microsoft Visual Studio 2017 或以上版本。
- Windows 7 或以上版本的设备。
示例项目
讯飞转写及翻译插件提供了示例项目,你可以前往克隆或下载并进行体验。
运行步骤
参考以下步骤快速跑通示例项目:
-
在 Microsoft Visual Studio 中打开
AgoraWithHyWin/AgoraWithHyWin.sln,并且安装 MFC 组件。 -
打开头文件筛选器中的
AgoraWithHyWinDlg.h文件,将#YOUR APP ID#替换为你的声网 App ID。获取 App ID 请参考开通云市场服务。C++ #define AGORA_APP_ID "#YOUR APP ID#" -
打开头文件筛选器中的
HyUtil.h文件,填入以下参数:C++ /** 在声网控制台购买插件后、由讯飞提供的 APPID */ #define EXTENSION_APP_ID "" /** 在声网控制台购买插件后、由讯飞提供的 APIKey */ #define EXTENSION_API_KEY "" /** 在声网控制台购买插件后、由讯飞提供的 APISecret */ #define EXTENSION_API_SECRET "" -
运行项目。
预期效果
运行成功后,示例项目会安装到你的设备上。
- 启动 App,你可以在界面上看到中译英下拉控件,start、flush、stop 按钮,以及 tip、ist_text、its_text 文本视图。
- 可以单击中译英下拉控件选择参数。
- 单击 start 按钮启动倾听。
- 对着麦克风说话,语音转写文本会显示在 ist_text 文本视图中,文本翻译文本会显示在 its_text 文本视图中。
- 单击 flush 按钮结束音频获取结果,或单击 stop 按钮停止倾听。
- tip 文本视图会显示 onEnd。
集成和调用流程
1. 集成 SDK 和插件
开始前,你需要在项目中分别集成声网音频 SDK 和讯飞转写及翻译插件。
1.1 集成声网音频 SDK
讯飞转写及翻译插件需要与声网音频 SDK v4.x 搭配使用。参考以下文档集成音频 SDK v4.x 并实现基础的语音通话:
1.2 购买和激活插件
你需要进入声网控制台 > 云市场页面,按照提示购买讯飞转写及翻译插件。购买成功后,你会收到由讯飞提供的 APPID、APIKey 和 APISecret,后续启动倾听时需要用到。
1.3 集成插件
参考以下步骤集成插件:
-
点击下载**讯飞语音实时转写及翻译(多语种)**的 Windows 插件包。
-
解压文件夹,将所有
.dll文件保存到项目生成的.exe文件所在的目录下。若要保存到其他目录,需要在调用loadExtensionProvider时传入对应的路径。
1.4 升级插件
声网云市场推荐你在更新插件版本前使用数据库工具(如 SQLite)实现插件版本管理,从而确保插件版本与对应的资源包版本一致。因为当插件版本和资源包版本未对齐时,会出现 App 闪退、崩溃等现象。
以下是用 SQLite 来进行插件版本管理的示例:
- 使用 SQLite 数据库自行维护插件包和资源包的版本信息。
- 每次项目初始化时,自动检测当前项目使用的资源包版本:
- 如果无记录文件或记录的资源包版本为旧,则更新资源。成功更新后,回写最新资源包版本信息到 SQLite。
- 如果记录的资源包版本与当前匹配,则正常实现业务。
如果你的项目已经集成过声网云市场提供的第三方插件,并需要更新插件,可以参考以下步骤来保证更新后的可用性。
以下升级流程以相芯美颜特效插件为例:
-
参考集成插件章节下载所需平台最新版本的插件包和资源包。
-
删除项目内旧版本的插件包及其资源包后,再将新版插件和资源包放入对应位置。或者直接在对应目录下用新版插件和资源包替换旧版。
-
删除设备上用老版本插件和资源包编译的 App,重新编译你的项目并运行。
注意
编译 App 时,系统会优先使用连接设备上存在的资源包。请务必在删除旧版本应用程序后再进行编译和运行,否则可能会出现插件版本与资源包不匹配的情况,从而导致各种意外问题。
2. 初始化
集成插件后,你需要先初始化插件,步骤如下:
-
初始化
IRtcEngine前,在RtcEngineContext实例中设置插件事件回调IRtcEngineEventHandler。C++ class CAgoraWithHyWinEventHandler: public agora::rtc::IRtcEngineEventHandler{ public: // 插件事件回调。 virtual void onExtensionEvent(const char * provider, const char * extension, const char * ky, const char * value) override { } private: HWND m_hMsgHanlder = NULL; HyUtil * mHyUtilPtr = NULL; }; m_rtcEngine = createAgoraRtcEngine(); CAgoraWithHyWinEventHandler m_eventHandler; agora::rtc::RtcEngineContext context; ······ context.eventHandler = &m_eventHandler; ······ ret = m_rtcEngine->initialize(context); -
调用
loadExtensionProvider,将插件添加到 SDK 中。C++ ret = m_rtcEngine->loadExtensionProvider("libagora-hy.dll"); -
在加入频道前,调用
enableExtension开启插件。C++ ret = m_rtcEngine->enableExtension(EXTENSION_PROVIDER_NAME, EXTENSION_AUDIO_FILTER_NAME, true); -
设置插件日志等级,需要在
enableVideo和enableAudio之前调用。C++ m_rtcEngine->setExtensionProviderProperty(EXTENSION_PROVIDER_NAME, "log_lvl", "8");
3. 启动倾听
空闲时可调用,调用后会进入会话。会话最长 5 小时。
int HyUtil::start(ParamWrap param) {
mParser.clear();
Json::Value root;
// 公共对象。必选。
Json::Value common; {
// 应用标识。必选。对应在声网控制台购买插件后、由讯飞提供的 APPID。
common["app_id"] = EXTENSION_APP_ID;
// API key。必选。对应在声网控制台购买插件后、由讯飞提供的 APIKey。
common["api_key"] = EXTENSION_API_KEY;
// API secret。必选。对应在声网控制台购买插件后、由讯飞提供的 APISecret。
common["api_secret"] = EXTENSION_API_SECRET;
}
root["common"] = common;
// 语音转写对象。必选。
Json::Value ist; {
// URI。必选。
ist["uri"] = EXTENSION_API_IST_URI;
// 请求对象。必选。
Json::Value req; {
Json::Value business; {
// 语种。必选。
business["language"] = param.mIstLanguage;
// 口音。必选。
business["accent"] = param.mIstAccent;
// 领域。必选。
business["domain"] = param.mIstDomain;
// 语言类型
// 值类型:int
// 值范围:
// 1:中英文模式,中文英文均可识别;
// 3:英文模式,只识别出英文
// 值默认:1
business["language_type"] = param.mIstLanguageType;
// 动态修正
business["dwa"] = param.mIstDwa;
}
req["business"] = business;
}
ist["req"] = req;
}
root["ist"] = ist;
// 文本翻译对象。
Json::Value its; {
// URI。必选。
its["uri"] = EXTENSION_API_ITS_URI;
// 请求对象。必选。
Json::Value req; {
// 业务对象。必选。
Json::Value business; {
// 源语种。必选。
business["from"] = param.mItsFrom;
// 目标语种。必选。
business["to"] = param.mItsTo;
}
req["business"] = business;
}
its["req"] = req;
}
root["its"] = its;
string val = root.toStyledString();
int errCode = m_rtcEngine->setExtensionProperty(EXTENSION_PROVIDER_NAME, EXTENSION_AUDIO_FILTER_NAME, "start_listening", val.c_str());
return errCode;
}4. 结束音频获取结果
会话时可调用,调用后会先处理完音频和结果,再进入空闲,回调 "end"。
int HyUtil::flush() {
return m_rtcEngine->setExtensionProperty(EXTENSION_PROVIDER_NAME, EXTENSION_AUDIO_FILTER_NAME, "flush_listening", "{}");
}讯飞转写及翻译插件会通过 onEvent 回调返回语音转写和文本翻译结果。识别结果的含义详见 onEvent 回调的 key。
5. 停止倾听
会话时可调用,调用后会先丢弃音频和结果,再进入空闲,回调 "end"。
int HyUtil::stop() {
return m_rtcEngine->setExtensionProperty(EXTENSION_PROVIDER_NAME, EXTENSION_AUDIO_FILTER_NAME, "stop_listening", "{}");
}