本文介绍Gummy实时语音识别/翻译Java SDK的参数和接口细节。
用户指南:关于模型介绍和选型建议请参见实时语音识别和实时语音翻译。
在线体验:模型体验
前提条件
- 已开通服务并获得API-KEY:获取API Key。建议您配置API Key到环境变量,从而避免在代码里显示配置API Key,降低泄漏风险。 
- 已安装最新版DashScope SDK:安装SDK。 
模型与价格
| 模型名 | 模型简介 | 单价 | 
| gummy-realtime-v1 | Gummy实时语音识别、翻译模型。默认进行标点符号预测和逆文本正则化(INT,Inverse Text Normalization)。支持定制热词。 模型使用VAD(Voice Activity Detection)断句。 | 0.00015元/秒 重要  语音识别与翻译功能分别计费,费用按各自调用量独立计算。两项服务的单价一致。 | 
快速开始
TranslationRecognizerRealtime类提供了语音识别/翻译的关键接口,支持以下几种调用方式:
- 流式调用:可直接对音频流进行识别/翻译,并实时输出结果。音频流可以来自外部设备(如麦克风)或从本地文件读取。适合需要即时反馈的场景。 
- 同步调用:针对本地文件进行识别/翻译,并一次性返回完整的处理结果。适合处理录制好的音频。 
流式调用:基于回调
通过实现回调接口,实时流式输出识别结果。
- 启动流式语音识别/翻译 - 实例化TranslationRecognizerRealtime类,调用 - call方法绑定请求参数和回调接口(ResultCallback)并启动流式语音识别/翻译。
- 流式传输 - 循环调用TranslationRecognizerRealtime类的 - sendAudioFrame方法,将从本地文件或设备(如麦克风)读取的二进制音频流分段发送至服务端。- 在发送音频数据的过程中,服务端会通过回调接口(ResultCallback)的 - onEvent方法,将识别结果实时返回给客户端。- 建议每次发送的音频时长约为100毫秒,数据大小保持在1KB至16KB之间。 
- 结束处理 - 调用TranslationRecognizerRealtime类的 - stop方法结束语音识别/翻译。- 该方法会阻塞当前线程,直到回调接口(ResultCallback)的 - onComplete或者- onError回调触发后才会释放线程阻塞。
流式调用:基于Flowable
通过工作流(Flowable)的方式流式输出实时识别结果。
Flowable 是一个用于工作流和业务流程管理的开源框架,它基于 Apache 2.0 许可证发布。关于Flowable的使用,请参见Flowable API详情。
同步调用
通过传入本地文件路径,以同步阻塞方式获取识别或翻译结果。
实例化TranslationRecognizerRealtime类,调用call方法绑定请求参数和待识别文件,进行识别并最终获取同步调用结果(TranslationRecognizerResultPack)。
请求参数
通过TranslationRecognizerParam的链式方法配置模型、采样率、音频格式等参数。配置完成的参数对象传入TranslationRecognizerRealtime类的call/streamCall方法中使用。
| 参数 | 类型 | 默认值 | 是否必须 | 说明 | 
| model | String | - | 是 | 设置实时语音识别的模型。如需了解当前支持的模型,请参见模型与价格。 | 
| sampleRate | Integer | - | 是 | 设置待识别音频采样率(单位Hz)。支持16000Hz及以上采样率。 | 
| format | String | - | 是 | 设置待识别音频格式。 支持的音频格式:pcm、wav、mp3、opus、speex、aac、amr。 重要  opus/speex:必须使用Ogg封装; wav:必须为PCM编码; amr:仅支持AMR-NB类型。 | 
| vocabularyId | String | - | 否 | 设置热词ID,若未设置则不生效。 在本次语音识别中,将应用与该热词ID对应的热词信息。具体使用方法请参见定制热词。 | 
| sourceLanguage | String | auto | 否 | 设置源语言(待识别/翻译语言)代码。如果无法提前确定语种,可不设置,默认为 目前支持的语言代码: 
 | 
| transcriptionEnabled | boolean | true | 否 | 设置是否启用识别功能。 模型支持单独开启识别或翻译功能,也可同时启用两种功能,但至少需要开启其中一种能力。 重要  语音识别与翻译功能分别计费,费用按各自调用量独立计算。两项服务的单价一致。 | 
| translationEnabled | boolean | false | 否 | 设置是否启用翻译功能。要正常输出翻译结果,需配置 模型支持单独开启识别或翻译功能,也可同时启用两种功能,但至少需要开启其中一种能力。 | 
| translationLanguages | String[] | - | 否 | 设置翻译目标语言代码。目标语言的代码与 目前支持的翻译包括: 中->英,中->日,中->韩, 英->中,英->日,英->韩, (日、韩、粤、德、法、俄、意、西)->(中、英)。 重要  目前暂不支持同时翻译为多种语言,请仅设置一个目标语言以完成翻译。 | 
| maxEndSilence | Integer | 800 | 否 | 设置VAD(Voice Activity Detection,语音活动检测)断句的静音时长阈值(单位为ms)。 当一段语音后的静音时长超过该阈值时,系统会判定该句子已结束。 参数范围为200ms至6000ms,默认值为800ms。 | 
| apiKey | String | - | 否 | 设置用户API Key。 | 
关键接口
TranslationRecognizerRealtime类
TranslationRecognizerRealtime通过“import com.alibaba.dashscope.audio.asr.translation.TranslationRecognizerRealtime;”方式引入,提供语音识别/翻译的关键接口。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 
 | 无 | 启动流式语音识别/翻译。 
 适合需要即时反馈的场景。 详细的调用流程和参考示例请参见流式调用:基于回调。 | 
|  | 
 | 无 | 推送音频,每次推送的音频流大小应适中,建议每包音频时长控制在100ms左右,大小保持在1KB~16KB之间。 识别/翻译结果并通过回调接口(ResultCallback)的 
 适合需要即时反馈的场景。 详细的调用流程和参考示例请参见流式调用:基于回调。 | 
|  | 无 | 无 | 结束流式语音识别/翻译。 该方法会阻塞当前线程,直至回调接口(ResultCallback)的 
 适合需要即时反馈的场景。 详细的调用流程和参考示例请参见流式调用:基于回调。 | 
|  | code: WebSocket关闭码(Close Code) reason:关闭原因 这两个参数可参考The WebSocket Protocol文档进行配置 | true | 在任务结束后,无论是否出现异常都需要关闭WebSocket连接,避免造成连接泄漏。 | 
|  | 
 | 基于本地文件的同步调用,该方法最终返回识别/翻译结果。要求待识别文件具有可读权限。 适合处理录制好的音频。 详细的调用流程和参考示例请参见同步调用。 | |
|  | 
 | 
 | 基于 详细的调用流程和参考示例请参见流式调用:基于Flowable。 | 
回调接口(ResultCallback)
ResultCallback通过“import com.alibaba.dashscope.common.ResultCallback;”方式引入。
使用流式调用:基于回调调用模式时通过回调接口ResultCallback获取识别结果。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 当服务有回复时会被回调。 | |
|  | 无 | 无 | 任务完成后该接口被回调。 | 
|  | 
 | 无 | 发生异常时该接口被回调。 | 
响应结果
实时识别/翻译结果(TranslationRecognizerResult)
TranslationRecognizerResult封装了识别结果(TranscriptionResult)和翻译结果(TranslationResult)。
由于语言间的词汇差异,识别和翻译的中间结果可能不会同时返回,因此某些情况下结果可能仅包含识别或翻译的部分。识别与翻译的进度会在isSentenceEnd为true时同步完成。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 获取实时识别结果。 | |
|  | 无 | 获取实时翻译结果。 | 
识别结果(TranscriptionResult)
TranscriptionResult封装了识别结果,包含时间戳、文本信息以及文本是否构成完整句子等信息。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 句子ID | 返回句子ID。 | 
|  | 无 | 句子开始时间,单位为ms | 返回句子开始时间。 | 
|  | 无 | 句子结束时间,单位为ms | 返回句子结束时间。 | 
|  | 无 | 识别文本 | 返回识别文本。 | 
|  | 无 | 字时间戳信息(Word)的List集合 | 返回字时间戳信息。 | 
|  | 无 | 
 | 当前文本是否构成完整的句子。 | 
翻译结果(TranslationResult)
TranslationResult封装了翻译结果,包含请求参数transcriptionTargetLanguages对应的所有语种的翻译结果。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 翻译结果中的所有语种列表 | 返回翻译结果中的所有语种列表。 | 
|  | 
 | 返回某语种对应的翻译结果。 | |
|  | 无 | 
 | 当前文本是否构成完整的句子。 | 
某语种对应的翻译结果(Translation)
TranscriptionResult封装了某种语言的翻译结果,包含时间戳、文本信息以及文本是否构成完整句子等信息。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 句子ID | 返回句子ID。 | 
|  | 无 | 翻译语种 | 返回翻译语种。 | 
|  | 无 | 句子开始时间,单位为ms | 返回句子开始时间。 | 
|  | 无 | 句子结束时间,单位为ms | 返回句子结束时间。 | 
|  | 无 | 识别文本 | 返回识别文本。 | 
|  | 无 | 字时间戳信息(Word)的List集合 | 返回字时间戳信息。 | 
|  | 无 | 
 | 当前文本是否构成完整的句子。 | 
字时间戳信息(Word)
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 字开始时间,单位为ms | 返回字开始时间。 | 
|  | 无 | 字结束时间,单位为ms | 返回字结束时间。 | 
|  | 无 | 字 | 返回识别的字。 | 
同步调用结果(TranslationRecognizerResultPack)
在同步调用中,返回结果会包含流式结果中所有成句(isSentenceEnd为true)的内容。
| 接口/方法 | 参数 | 返回值 | 描述 | 
|  | 无 | 本次任务的请求ID | 返回本次任务的请求ID。 | 
|  | 无 | 返回语音识别结果。 | |
|  | 无 | 返回语音翻译结果。 | |
|  | 无 | 计费信息 | 返回计费信息。 | 
|  | 无 | 异常信息 | 返回异常信息。 | 
错误码
如遇报错问题,请参见错误信息进行排查。
若问题仍未解决,请加入开发者群反馈遇到的问题,并提供Request ID,以便进一步排查问题。
更多示例
更多示例,请参见GitHub。
常见问题
故障排查
如遇代码报错问题,请根据错误信息进行排查。
Q:为什么没有输出翻译结果?
- 请求参数配置要正确。 - 需将参数 - translationEnabled设置为- true。
- 需通过参数 - translationLanguages指定翻译目标语言。注意,该参数类型为数组而非字符串。
 
- 获取翻译结果(TranslationResult)时,方法 - getTranslation的入参要和翻译目标语言(即参数- translationLanguages的值)相匹配。- 比如 - translationLanguages为- ["en"],却- getTranslation("zh")就无法获取翻译结果。
更多问题
请参见GitHub QA。