实时语音识别 Java SDK
使用指南: 模型概述和选型请参见实时语音识别。
Recognition 类提供三种调用方式:
传入本地文件,同步获取转写结果。此调用会阻塞当前线程。
实例化 Recognition 类,调用
通过实现回调接口实时接收识别结果。
使用 Flowable 工作流实时接收识别结果。
Flowable 是 RxJava 提供的响应式流类型,支持背压机制。详见 Flowable API 参考。
SDK 使用 OkHttp3 连接池来减少开销。详见高并发管理。
使用
导入:
在双向流式调用中,实现回调方法来处理服务端返回的结果。
继承
快速开始
Recognition 类提供三种调用方式:
- 非流式调用:一次性返回完整结果,适用于预录制音频。
- 双向流式调用:边输入音频边实时返回结果,适用于麦克风采集或需要即时反馈的场景。
非流式调用
传入本地文件,同步获取转写结果。此调用会阻塞当前线程。
实例化 Recognition 类,调用 call 方法并传入请求参数和音频文件。
点击查看完整示例
点击查看完整示例
示例中使用的音频文件为 asr_example.wav。
双向流式调用: 基于回调
通过实现回调接口实时接收识别结果。
1
启动流式识别
实例化 Recognition 类,调用
call 方法并传入请求参数和回调接口 (ResultCallback)。2
发送音频流
反复调用
sendAudioFrame 发送音频片段(来自文件或麦克风)。服务端通过 onEvent 回调返回识别结果。每次发送约 100 ms 时长的音频片段,大小为 1-16 KB。3
结束识别
调用
stop 结束识别。此方法会阻塞直到 onComplete 或 onError 被调用。点击查看完整示例
点击查看完整示例
- 从麦克风识别语音
- 识别本地音频文件
双向流式调用: 基于 Flowable
使用 Flowable 工作流实时接收识别结果。
Flowable 是 RxJava 提供的响应式流类型,支持背压机制。详见 Flowable API 参考。
点击查看完整示例
点击查看完整示例
调用
streamCall 启动识别,返回 Flowable<RecognitionResult>。使用 blockingForEach 或 subscribe 处理结果。streamCall 需要以下参数:RecognitionParam:模型、采样率和音频格式Flowable<ByteBuffer>:音频流
高并发调用
SDK 使用 OkHttp3 连接池来减少开销。详见高并发管理。
请求参数
使用 RecognitionParam 的构建器方法配置模型、采样率和音频格式,然后将配置好的对象传给 call 或 streamCall。
点击查看示例
点击查看示例
| 参数 | 类型 | 默认值 | 必选 | 说明 |
|---|---|---|---|---|
| model | String | - | 是 | 实时语音识别模型。 |
| sampleRate | Integer | - | 是 | 音频采样率,单位 Hz。fun-asr-realtime 支持 16000 Hz。 |
| format | String | - | 是 | 音频格式。支持:pcm、wav、mp3、opus、speex、aac、amr。 注意: opus/speex 必须使用 Ogg 封装。wav 必须为 PCM 编码。amr 仅支持 AMR-NB。 |
| vocabularyId | String | - | 否 | 自定义词表 ID。参见自定义热词。默认不设置。 |
| semantic_punctuation_enabled | boolean | false | 否 | 标点模式。true:语义标点(精度更高,适用于会议场景)。false(默认):VAD 标点(延迟更低,适用于交互场景)。 |
| max_sentence_silence | Integer | 1300 | 否 | VAD 标点模式下的静音断句阈值,单位毫秒。语音后的静音时长超过此值时,句子结束。取值范围:200 到 6000 ms。仅在 semantic_punctuation_enabled 为 false 时生效。 |
| multi_threshold_mode_enabled | boolean | false | 否 | 防止 VAD 过早切分长句。仅在 semantic_punctuation_enabled 为 false 时生效。 |
| punctuation_prediction_enabled | boolean | true | 否 | 自动为识别结果添加标点符号,固定为 true,不支持修改。 |
| heartbeat | boolean | false | 否 | 静音时保持持久连接。true:连接保持存活。false(默认):即使发送静音音频,60 秒后也会断开连接。 需要 SDK 2.19.1 或更高版本。 |
| language_hints | String[] | - | 否 | 识别语言代码。不设置则自动检测。支持的语言代码:zh(中文)、en(英文)、ja(日文)。 |
| speech_noise_threshold | float | - | 否 | VAD 灵敏度。取值范围:[-1.0, 1.0]。接近 -1:更多噪音被识别为语音。接近 +1:部分语音被过滤为噪音。 注意: 高级参数,调整会显著影响识别质量。请充分测试,并根据音频环境小幅调整(步长 0.1)。 |
| apiKey | String | - | 否 | 您的 API Key。 |
对于
RecognitionParam 构建器中未直接提供的参数(如 semantic_punctuation_enabled、heartbeat 和 language_hints),请使用 parameter 或 parameters 方法:- 使用 parameter 方法设置
- 使用 parameters 方法设置
核心接口
Recognition 类
导入:import com.alibaba.dashscope.audio.asr.recognition.Recognition;
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback) | param:请求参数 callback:回调接口 (ResultCallback) | 无 | 基于回调的流式识别,不阻塞当前线程。 |
public String call(RecognitionParam param, File file) | param:请求参数 file:待识别的音频文件 | 识别结果 | 非流式调用,传入本地文件。阻塞直到处理完成。文件必须可读。 |
public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame) | param:请求参数 audioFrame:Flowable<ByteBuffer> 实例 | Flowable<RecognitionResult> | 基于 Flowable 的流式识别。 |
public void sendAudioFrame(ByteBuffer audioFrame) | audioFrame:二进制音频流 (ByteBuffer) | 无 | 发送一个音频片段。每个数据包约 100 ms 时长,大小 1-16 KB。结果通过 ResultCallback 的 onEvent 方法返回。 |
public void stop() | 无 | 无 | 停止识别。阻塞直到 onComplete 或 onError 被调用。 |
boolean getDuplexApi().close(int code, String reason) | code:WebSocket 关闭码 reason:关闭原因 参见 The WebSocket Protocol。 | true | 每个任务完成后关闭 WebSocket 连接以防止泄漏(异常情况下也需关闭)。先通过 getDuplexApi() 获取连接对象后调用 close。如需复用连接,请参见高并发管理。 |
public String getLastRequestId() | 无 | requestId | 获取当前任务的请求 ID。需在 call 或 streamCall 启动任务后调用。 需要 SDK 2.18.0 或更高版本。 |
public long getFirstPackageDelay() | 无 | 首包延迟 | 获取从发送第一个音频包到收到第一个结果的延迟。需在任务完成后调用。 需要 SDK 2.18.0 或更高版本。 |
public long getLastPackageDelay() | 无 | 尾包延迟 | 获取从发送 stop 到最后一个结果返回的时间。需在任务完成后调用。 需要 SDK 2.18.0 或更高版本。 |
回调接口 (ResultCallback)
在双向流式调用中,实现回调方法来处理服务端返回的结果。
继承 ResultCallback<RecognitionResult> 并实现其方法。RecognitionResult 封装了服务端响应。
SDK 支持连接复用,因此没有 onClose 或 onOpen 方法。
示例
示例
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public void onEvent(RecognitionResult result) | result:实时识别结果 (RecognitionResult) | 无 | 服务端返回结果时调用。 |
public void onComplete() | 无 | 无 | 识别成功完成时调用。 |
public void onError(Exception e) | e:异常信息 | 无 | 发生错误时调用。 |
响应结果
实时识别结果 (RecognitionResult)
RecognitionResult 表示单条识别结果。
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public String getRequestId() | 无 | requestId | 获取请求 ID。 |
public boolean isSentenceEnd() | 无 | 句子是否结束 | 返回当前句子是否已结束(最终结果)。 |
public Sentence getSentence() | 无 | Sentence | 获取包含时间戳和文本的句子信息。 |
句子信息 (Sentence)
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public Long getBeginTime() | 无 | 句子开始时间,单位毫秒 | 返回句子的开始时间。 |
public Long getEndTime() | 无 | 句子结束时间,单位毫秒 | 返回句子的结束时间。 |
public String getText() | 无 | 识别文本 | 返回识别出的文本。 |
public List<Word> getWords() | 无 | 词时间戳信息 (Word) 列表 | 返回词级时间戳信息。 |
词时间戳信息 (Word)
| 接口/方法 | 参数 | 返回值 | 说明 |
|---|---|---|---|
public long getBeginTime() | 无 | 词开始时间,单位毫秒 | 返回词的开始时间。 |
public long getEndTime() | 无 | 词结束时间,单位毫秒 | 返回词的结束时间。 |
public String getText() | 无 | 词 | 返回识别出的词。 |
public String getPunctuation() | 无 | 标点 | 返回标点符号。 |

