This topic describes the parameters and interfaces of the Java SDK for Qwen-Audio-3.0-ASR-Flash-Streaming/Fun-ASR-Realtime real-time speech recognition.
Alibaba Cloud Model Studio has released workspace-specific domains for the China (Beijing) and Singapore regions. The new dedicated domains deliver superior performance and higher stability for inference requests. We recommend migrating to the new domains:
China (Beijing): from
dashscope.aliyuncs.comto{WorkspaceId}.cn-beijing.maas.aliyuncs.comSingapore: from
dashscope-intl.aliyuncs.comto{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
Replace {WorkspaceId} with your actual Workspace ID. The existing domains remain fully functional.
User guide: For an introduction to the models and guidance on model selection, see Speech-to-text.
Prerequisites
The service is activated and Obtain an API key. To guard against security risks caused by code leaks, Configure API key as an environment variable, rather than hard-coding it in your code.
Quick start
The Recognition class provides interfaces for both synchronous calls and bidirectional streaming calls. Choose the approach that fits your needs:
Synchronous call: recognizes a local file and returns the complete result at once. Best for processing pre-recorded audio.
Bidirectional streaming call: recognizes an audio stream directly and returns results in real time. The audio stream can come from an external device, such as a microphone, or be read from a local file. Best for scenarios that require immediate feedback.
Synchronous call
Submit a single real-time speech recognition task and get the recognition result synchronously by passing in a local file. The call blocks until the result is returned.
Instantiate The Recognition class, and call the call method to bind Request parameters and the file to recognize. The method performs recognition and returns the final result.
Bidirectional streaming call: callback-based
Submit a single real-time speech recognition task and stream the real-time recognition results by implementing a callback interface.
Start streaming speech recognition
Instantiate The Recognition class, and call the
callmethod to bind Request parameters and The callback interface (ResultCallback) and start streaming speech recognition.Stream the audio
Call the
sendAudioFramemethod of The Recognition class in a loop to send the binary audio stream to the server in segments. Read the audio from a local file or a device such as a microphone.While the audio data is being sent, the server returns recognition results to the client in real time through the
onEventmethod of The callback interface (ResultCallback).Send about 100 ms of audio per frame, keeping each payload between 1 KB and 16 KB.
End the process
Call the
stopmethod of The Recognition class to end speech recognition.This method blocks the current thread until the
onCompleteoronErrorcallback of The callback interface (ResultCallback) is triggered, at which point the thread is released.
Bidirectional streaming call: Flowable-based
Submit a single real-time speech recognition task and stream the real-time recognition results by implementing a workflow (Flowable).
Flowable is an open-source framework for workflow and business process management, released under the Apache 2.0 license. For how to use Flowable, see Flowable API details.
High-concurrency calls
The DashScope Java SDK uses the connection pooling of OkHttp3 to reduce the overhead of repeatedly establishing connections. For details, see Optimize Paraformer real-time speech recognition for high concurrency.
Request parameters
Use the chained methods of RecognitionParam to configure the model, sample rate, audio format, and other parameters. Pass the configured parameter object to the call/streamCall method of The Recognition class.
Parameter | Type | Required | Description |
model | String | Yes | The model name. The Qwen-Audio-3.0-ASR-Flash-Streaming and Fun-ASR-Realtime model series are supported. For details, see Supported models and regions. |
sampleRate | Integer | Yes | The sample rate, in Hz. Valid values: 8 kHz models support only 8000 Hz; other models support any sample rate. |
format | String | Yes | The audio format. Valid values:
Important
opus/speex: Must use Ogg encapsulation. wav: Must use PCM encoding. amr: Only the AMR-NB type is supported. |
vocabularyId | String | No | The ID of a precompiled hot word list. Generate this ID in advance by calling the create hot word list API. Pass the ID during recognition to use the hot words in the list. Suitable for scenarios where the vocabulary is known and relatively stable, and where you need to reuse the same word list across requests. For usage details, see Precompiled hotwords. |
vocabulary | Map<String, Integer> | No | Instant hot words. Passed as key-value pairs, where the key is the hot word text ( Suitable for temporary, session-level hot word optimization. When configured together with precompiled hot words, only the instant hot words take effect. For usage details, see Instant hotwords. Important
Only Note Set Set through parameterSet through parameters |
semantic_punctuation_enabled | boolean | No | Whether to enable semantic segmentation. Default value: false.
Semantic segmentation is more accurate and is better suited to meeting transcription scenarios. VAD (Voice Activity Detection) segmentation has lower latency and is better suited to interactive scenarios. Note Set Set through parameterSet through parameters |
max_sentence_silence | Integer | No | The VAD silence threshold for segmentation, in ms. When the silence after a segment of speech exceeds this threshold, the system determines that the sentence has ended. When Default value: 1300. Valid values: [200, 6000]. Note Set Set through parameterSet through parameters |
multi_threshold_mode_enabled | boolean | No | Important
Takes effect only when Whether to enable multi-threshold mode. When enabled, this prevents VAD segments from becoming too long. Default value: false. Note Set Set through parameterSet through parameters |
punctuation_prediction_enabled | boolean | No | Sets whether to automatically add punctuation to the recognition results:
Note Set Set through parameterSet through parameters |
heartbeat | boolean | No | Whether to enable heartbeat packets. Default value: false.
Silent audio refers to content in an audio file or data stream that contains no sound signal. You can generate silent audio in several ways, such as using audio editing software like Audacity or Adobe Audition, or using a command-line tool like FFmpeg. Note To use this field, the SDK version must be 2.19.1 or later. Set Set through parameterSet through parameters |
language_hints | String[] | No | The language of the audio to recognize. There is no default value; if not set, the model detects the language automatically. For the Qwen-Audio-3.0-ASR-Flash-Streaming model series, you can set up to 4 values; if you set more than 4, only the first 4 take effect. For the Fun-ASR-Realtime model series, you can set only 1 value; if you set multiple values, only the first one takes effect. Note Set Set through parameterSet through parameters |
speech_noise_threshold | float | No | The threshold for distinguishing speech from noise, used to adjust the sensitivity of Voice Activity Detection (VAD). Valid values: [-1.0, 1.0]. Value descriptions:
This is an advanced configuration parameter. Adjusting it can significantly affect recognition results. Recommendations:
Note Set Set through parameterSet through parameters |
special_word_filter | String | No | Specifies the sensitive words to process during speech recognition, and supports setting different processing methods for different sensitive words. For details, see Sensitive word filtering. Note Set Set through parameterSet through parameters |
input | Map<String, Object> | No | Input object that passes in the conversation context. The context helps recognition and improves the recognition accuracy of proper terms. For usage, see Quick start. Important Only the The Map must contain a
Important Limits: context messages of the Important When you pass in context, the messages in Note To use this field, the SDK version must be 2.22.23 or later. Set |
apiKey | String | No | Your API key. |
Key interfaces
The Recognition class
Import Recognition with import com.alibaba.dashscope.audio.asr.recognition.Recognition;. Its key interfaces are as follows:
Interface/Method | Parameter | Return value | Description |
|
| None | Callback-based streaming real-time recognition. This method does not block the current thread. |
|
| The recognition result. | Non-streaming recognition of a local file. This method blocks the current thread until the entire audio file is read. The file must be readable. |
|
|
| Flowable-based streaming real-time recognition. |
|
| None | Sends audio. Keep each pushed audio chunk within a reasonable size. A recommended chunk holds about 100 ms of audio and is 1 KB to 16 KB in size. Recognition results are delivered through the onEvent method of the The callback interface (ResultCallback). |
| None | None | Stops real-time recognition. This method blocks the current thread until the |
| code: The WebSocket close code. reason: The reason for closing. For guidance on setting these two parameters, see The WebSocket Protocol. | true | After a task ends, always close the WebSocket connection, whether or not an exception occurred, to avoid connection leaks. To reuse connections for better efficiency, see Optimize Paraformer real-time speech recognition for high concurrency. |
| None | requestId | Gets the requestId of the current task. Available after a new task starts with Note This method is available only in SDK version 2.18.0 and later. |
| None | The first-packet latency. | Gets the first-packet latency, that is, the delay from sending the first audio packet to receiving the first recognition result. Use it after the task completes. Note This method is available only in SDK version 2.18.0 and later. |
| None | The last-packet latency. | Gets the last-packet latency, that is, the time from sending the Note This method is available only in SDK version 2.18.0 and later. |
The callback interface (ResultCallback)
During bidirectional streaming calls, the server returns key process information and data to the client through callbacks. Implement the callback methods to handle the information or data returned by the server.
Implement the callback methods by extending the abstract class ResultCallback. When you extend this class, you can set the generic type to RecognitionResult. RecognitionResult wraps the data structure returned by the server.
Because Java supports connection reuse, there is no onClose or onOpen.
Interface/Method | Parameter | Return value | Description |
| None | Called when the server sends a response. | |
| None | None | Called after the task completes. |
|
| None | Called when an exception occurs. |
Response
Real-time recognition result (RecognitionResult)
RecognitionResult represents the result of a single real-time recognition.
Interface/Method | Parameter | Return value | Description |
| None | requestId | Gets the requestId. |
| None | Whether a complete sentence has been formed, that is, whether a sentence boundary was detected. | Determines whether the given sentence has ended. |
| None | Gets the sentence information, including timestamps and text. |
Sentence information (Sentence)
Interface/Method | Parameter | Return value | Description |
| None | The sentence start time, in ms. | Returns the sentence start time. |
| None | The sentence end time, in ms. | Returns the sentence end time. |
| None | The recognized text. | Returns the recognized text. |
| None | A List of Word-level timestamp information (Word) objects. | Returns word-level timestamp information. |
Word-level timestamp information (Word)
Interface/Method | Parameter | Return value | Description |
| None | The word start time, in ms. | Returns the word start time. |
| None | The word end time, in ms. | Returns the word end time. |
| None | The word. | Returns the recognized word. |
| None | The punctuation. | Returns the punctuation. |
Error codes
If you encounter errors, see Error codes for troubleshooting.
If the issue persists, join the developer community to report your issue and provide the Request ID for further investigation.
FAQ
Features
Q: How do I keep the connection to the server alive during long periods of silence?
Set the request parameter heartbeat to true, and keep sending silent audio to the server.
Silent audio is audio that contains no sound signal in the file or data stream. You can generate silent audio in several ways, for example, by using audio editing software such as Audacity or Adobe Audition, or a command-line tool such as FFmpeg.
Q: How do I convert audio to a supported format?
Use the FFmpeg tool. For more usage, see the FFmpeg official website.
# Basic conversion command (universal template)
# -i, purpose: input file path, example values: audio.wav
# -c:a, purpose: audio encoder, example values: aac, libmp3lame, pcm_s16le
# -b:a, purpose: bitrate (audio quality control), example values: 192k, 320k
# -ar, purpose: sample rate, example values: 44100 (CD), 48000, 16000
# -ac, purpose: number of channels, example values: 1 (mono), 2 (stereo)
# -y, purpose: overwrite an existing file (no value needed)
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bitrate -ar sample_rate -ac channels output.ext
# Example: WAV -> MP3 (preserve original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Example: MP3 -> WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Example: M4A -> AAC (extract/convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac # Extract directly without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac # Re-encode for higher quality
# Example: FLAC lossless -> Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opusQ: How do I recognize a local file (a recording)?
There are two ways to recognize a local file:
Pass in the local file path directly: this approach returns the complete recognition result only after recognition finishes, so it isn't suitable for scenarios that need immediate feedback.
See Synchronous call, and pass the file path to the
callmethod of the The Recognition class to recognize the recording directly.Convert the local file to a binary stream for recognition: this approach recognizes the file and streams results at the same time, which suits scenarios that need immediate feedback.
See Bidirectional streaming call: callback-based, and send the binary stream to the server for recognition through the
sendAudioFramemethod of the The Recognition class.See Bidirectional streaming call: Flowable-based, and send the binary stream to the server for recognition through the
streamCallmethod of the The Recognition class.
Troubleshooting
Q: Why can't the speech be recognized (no recognition result)?
Check that the audio format (
format) and sample rate (sampleRate/sample_rate) in the request parameters are correct and meet the parameter constraints. Common mistakes include:The audio file has a .wav extension but is actually in MP3 format, while the request parameter
formatis set to mp3 (incorrect parameter setting).The audio sample rate is 3600 Hz, but the request parameter
sampleRate/sample_rateis set to 48000 (incorrect parameter setting).
Use the ffprobe tool to get the container, codec, sample rate, channels, and other information about the audio:
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxxCheck that the language set in
language_hintsmatches the actual language of the audio.For example, the audio is actually in Chinese, but
language_hintsis set toen(English).If none of the checks above reveal a problem, configure custom hotwords to improve recognition of specific terms.