This topic describes the parameters and interface details of the Paraformer real-time speech recognition Java SDK.
ImportantAlibaba Cloud Model Studio has released a workspace-specific domain for the China (Beijing) region. The new dedicated domain delivers superior performance and higher stability for inference requests. We recommend migrating from dashscope.aliyuncs.com to {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Replace {WorkspaceId} with your actual Workspace ID. The existing domain remains fully functional.
ImportantThis document applies only to the China (Beijing) region. To use models, you must use an API key from the China (Beijing) region.
User guide: For model introduction and selection recommendations, see Real-time speech recognition - Fun-ASR/Paraformer.
Prerequisites
You have activated the service and Obtain an API key. Please Configure API key as an environment variable instead of hardcoding it in your code to prevent security risks caused by code leakage.
NoteWhen you need to provide temporary access to third-party applications or users, or when you want to strictly control high-risk operations such as accessing or deleting sensitive data, we recommend using temporary authentication tokens.
Compared with long-term API Keys, temporary authentication tokens have a short validity period (60 seconds) and higher security, making them suitable for temporary call scenarios and effectively reducing the risk of API Key leakage.
Usage: In your code, replace the API Key originally used for authentication with the obtained temporary authentication token.
Model list
| paraformer-realtime-v2 | paraformer-realtime-8k-v2 | |
|---|---|---|
| Use case | Live streaming, meetings, and similar scenarios | Recognition of 8 kHz audio in scenarios such as telephone customer service and voicemail |
| Sample rate | Any | 8kHz |
| Language | Chinese (including Mandarin and various dialects), English, Japanese, Korean, German, French, Russian Supported Chinese dialects: Shanghainese, Wu, Minnan, Northeastern, Gansu, Guizhou, Henan, Hubei, Hunan, Jiangxi, Ningxia, Shanxi, Shaanxi, Shandong, Sichuan, Tianjin, Yunnan, Cantonese | Chinese |
| Punctuation prediction | Supported by default, no configuration required | Supported by default, no configuration required |
| Inverse text normalization (ITN) | Supported by default, no configuration required | Supported by default, no configuration required |
| Custom hot words | See Custom hotwords | See Custom hotwords |
| Specify recognition language | Specify via the | |
| Sentiment recognition | (Click to view usage) Sentiment recognition follows these constraints:
How to obtain sentiment recognition results: Call the |
Quick start
Recognition class provides non-streaming and bidirectional streaming call interfaces. Choose the appropriate call method based on your needs:
- Non-streaming call: Recognizes local files and returns the complete result at once. Suitable for processing pre-recorded audio.
- Bidirectional streaming call: Recognizes audio streams directly and outputs results in real time. The audio stream can come from external devices (such as a microphone) or be read from a local file. Suitable for scenarios that require immediate feedback.
Non-streaming call
Submit a single real-time speech-to-text task and synchronously obtain the transcription result by passing in a local file.
Instantiate Recognition class, call the call method with Request parameters and the file to be recognized, perform recognition, and obtain the recognition result.
Click to view complete example
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.utils.Constants;
import java.io.File;
public class Main {
public static void main(String[] args) {
// The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
// Create a Recognition instance
Recognition recognizer = new Recognition();
// Create RecognitionParam
RecognitionParam param =
RecognitionParam.builder()
// If you have not configured the API Key as an environment variable, uncomment the following line and replace apiKey with your own API Key
// .apiKey("yourApikey")
.model("paraformer-realtime-v2")
.format("wav")
.sampleRate(16000)
// "language_hints" is only supported by the paraformer-realtime-v2 model
.parameter("language_hints", new String[]{"zh", "en"})
.build();
try {
System.out.println("Recognition result: " + recognizer.call(param, new File("{YOUR_AUDIO_FILE}")));
} catch (Exception e) {
e.printStackTrace();
} finally {
// Close the WebSocket connection after the task ends
recognizer.getDuplexApi().close(1000, "bye");
}
System.out.println(
"[Metric] requestId: "
+ recognizer.getLastRequestId()
+ ", first package delay ms: "
+ recognizer.getFirstPackageDelay()
+ ", last package delay ms: "
+ recognizer.getLastPackageDelay());
System.exit(0);
}
}
Bidirectional streaming: callback-based
Submit a single real-time speech-to-text task and stream real-time recognition results through the callback interface.
-
Start streaming speech recognition
Instantiate Recognition class, call the
callmethod with Request parameters and Callback interface (ResultCallback) to start streaming speech recognition. -
Stream audio data
Call the
sendAudioFramemethod of Recognition class in a loop to send binary audio stream segments read from a local file or device (such as a microphone) to the server.During the audio data transmission, the server returns recognition results to the client in real time through the
onEventmethod of Callback interface (ResultCallback).It is recommended that each audio segment is approximately 100 milliseconds in duration, with a data size between 1 KB and 16 KB.
-
Finish processing
Call the
stopmethod of Recognition class to end speech recognition.This method blocks the current thread until the
onCompleteoronErrorcallback of Callback interface (ResultCallback) is triggered.
Click to view complete example
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionResult;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;
import java.nio.ByteBuffer;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
public class Main {
public static void main(String[] args) throws InterruptedException {
// The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
ExecutorService executorService = Executors.newSingleThreadExecutor();
executorService.submit(new RealtimeRecognitionTask());
executorService.shutdown();
executorService.awaitTermination(1, TimeUnit.MINUTES);
System.exit(0);
}
}
class RealtimeRecognitionTask implements Runnable {
@Override
public void run() {
RecognitionParam param = RecognitionParam.builder()
// If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
// .apiKey("yourApikey")
.model("paraformer-realtime-v2")
.format("wav")
.sampleRate(16000)
// "language_hints" is only supported by the paraformer-realtime-v2 model
.parameter("language_hints", new String[]{"zh", "en"})
.build();
Recognition recognizer = new Recognition();
ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
@Override
public void onEvent(RecognitionResult result) {
if (result.isSentenceEnd()) {
System.out.println("Final Result: " + result.getSentence().getText());
} else {
System.out.println("Intermediate Result: " + result.getSentence().getText());
}
}
@Override
public void onComplete() {
System.out.println("Recognition complete");
}
@Override
public void onError(Exception e) {
System.out.println("RecognitionCallback error: " + e.getMessage());
}
};
try {
recognizer.call(param, callback);
// Create audio format
AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
// Match the default recording device based on the format
TargetDataLine targetDataLine =
AudioSystem.getTargetDataLine(audioFormat);
targetDataLine.open(audioFormat);
// Start recording
targetDataLine.start();
ByteBuffer buffer = ByteBuffer.allocate(1024);
long start = System.currentTimeMillis();
// Record for 50s and perform real-time transcription
while (System.currentTimeMillis() - start < 50000) {
int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
if (read > 0) {
buffer.limit(read);
// Send the recorded audio data to the streaming recognition service
recognizer.sendAudioFrame(buffer);
buffer = ByteBuffer.allocate(1024);
// Recording rate is limited, sleep briefly to prevent high CPU usage
Thread.sleep(20);
}
}
recognizer.stop();
} catch (Exception e) {
e.printStackTrace();
} finally {
// Close the WebSocket connection after the task ends
recognizer.getDuplexApi().close(1000, "bye");
}
System.out.println(
"[Metric] requestId: "
+ recognizer.getLastRequestId()
+ ", first package delay ms: "
+ recognizer.getFirstPackageDelay()
+ ", last package delay ms: "
+ recognizer.getLastPackageDelay());
}
}
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionResult;
import com.alibaba.dashscope.common.ResultCallback;
import com.alibaba.dashscope.utils.Constants;
import java.io.FileInputStream;
import java.nio.ByteBuffer;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.time.LocalDateTime;
import java.time.format.DateTimeFormatter;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;
class TimeUtils {
private static final DateTimeFormatter formatter =
DateTimeFormatter.ofPattern("yyyy-MM-dd HH:mm:ss.SSS");
public static String getTimestamp() {
return LocalDateTime.now().format(formatter);
}
}
public class Main {
public static void main(String[] args) throws InterruptedException {
// The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
ExecutorService executorService = Executors.newSingleThreadExecutor();
executorService.submit(new RealtimeRecognitionTask(Paths.get(System.getProperty("user.dir"), "{YOUR_AUDIO_FILE}")));
executorService.shutdown();
// wait for all tasks to complete
executorService.awaitTermination(1, TimeUnit.MINUTES);
System.exit(0);
}
}
class RealtimeRecognitionTask implements Runnable {
private Path filepath;
public RealtimeRecognitionTask(Path filepath) {
this.filepath = filepath;
}
@Override
public void run() {
RecognitionParam param = RecognitionParam.builder()
// If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
// .apiKey("yourApikey")
.model("paraformer-realtime-v2")
.format("wav")
.sampleRate(16000)
// "language_hints" is only supported by the paraformer-realtime-v2 model
.parameter("language_hints", new String[]{"zh", "en"})
.build();
Recognition recognizer = new Recognition();
String threadName = Thread.currentThread().getName();
ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
@Override
public void onEvent(RecognitionResult message) {
if (message.isSentenceEnd()) {
System.out.println(TimeUtils.getTimestamp()+" "+
"[process " + threadName + "] Final Result:" + message.getSentence().getText());
} else {
System.out.println(TimeUtils.getTimestamp()+" "+
"[process " + threadName + "] Intermediate Result: " + message.getSentence().getText());
}
}
@Override
public void onComplete() {
System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] Recognition complete");
}
@Override
public void onError(Exception e) {
System.out.println(TimeUtils.getTimestamp()+" "+
"[" + threadName + "] RecognitionCallback error: " + e.getMessage());
}
};
try {
recognizer.call(param, callback);
// Please replace the path with your audio file path
System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] Input file_path is: " + this.filepath);
// Read file and send audio by chunks
FileInputStream fis = new FileInputStream(this.filepath.toFile());
// chunk size set to 1 seconds for 16KHz sample rate
byte[] buffer = new byte[3200];
int bytesRead;
// Loop to read chunks of the file
while ((bytesRead = fis.read(buffer)) != -1) {
ByteBuffer byteBuffer;
// Handle the last chunk which might be smaller than the buffer size
System.out.println(TimeUtils.getTimestamp()+" "+"[" + threadName + "] bytesRead: " + bytesRead);
if (bytesRead < buffer.length) {
byteBuffer = ByteBuffer.wrap(buffer, 0, bytesRead);
} else {
byteBuffer = ByteBuffer.wrap(buffer);
}
recognizer.sendAudioFrame(byteBuffer);
buffer = new byte[3200];
Thread.sleep(100);
}
System.out.println(TimeUtils.getTimestamp()+" "+LocalDateTime.now());
recognizer.stop();
} catch (Exception e) {
e.printStackTrace();
} finally {
// Close the WebSocket connection after the task ends
recognizer.getDuplexApi().close(1000, "bye");
}
System.out.println(
"["
+ threadName
+ "][Metric] requestId: "
+ recognizer.getLastRequestId()
+ ", first package delay ms: "
+ recognizer.getFirstPackageDelay()
+ ", last package delay ms: "
+ recognizer.getLastPackageDelay());
}
}
Bidirectional streaming: Flowable-based
Submit a single real-time speech-to-text task and stream real-time recognition results through a Flowable workflow.
Flowable is an open-source framework for workflow and business process management, released under the Apache 2.0 license. For more information about Flowable, see Flowable API documentation.
Click to view complete example
Directly call the streamCall method of Recognition class to start recognition.
The streamCall method returns a Flowable<RecognitionResult> instance. You can call methods such as Flowable instance's blockingForEach and subscribe to process recognition results. The recognition results are encapsulated in RecognitionResult.
The streamCall method requires two parameters:
RecognitionParaminstance (Request parameters): Use it to set parameters such as the model, sample rate, and audio format for speech recognition.Flowable<ByteBuffer>instance: You need to create aFlowable<ByteBuffer>type instance and implement the audio stream parsing method within it.
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.alibaba.dashscope.utils.Constants;
import io.reactivex.BackpressureStrategy;
import io.reactivex.Flowable;
import javax.sound.sampled.AudioFormat;
import javax.sound.sampled.AudioSystem;
import javax.sound.sampled.TargetDataLine;
import java.nio.ByteBuffer;
public class Main {
public static void main(String[] args) throws NoApiKeyException {
// The following configuration is for the China (Beijing) region. Replace "{WorkspaceId}" with your actual workspace ID. The configuration varies by region.
Constants.baseWebsocketApiUrl = "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference";
// Create a Flowable<ByteBuffer>
Flowable<ByteBuffer> audioSource =
Flowable.create(
emitter -> {
new Thread(
() -> {
try {
// Create audio format
AudioFormat audioFormat = new AudioFormat(16000, 16, 1, true, false);
// Match the default recording device based on the format
TargetDataLine targetDataLine =
AudioSystem.getTargetDataLine(audioFormat);
targetDataLine.open(audioFormat);
// Start recording
targetDataLine.start();
ByteBuffer buffer = ByteBuffer.allocate(1024);
long start = System.currentTimeMillis();
// Record for 50s and perform real-time transcription
while (System.currentTimeMillis() - start < 50000) {
int read = targetDataLine.read(buffer.array(), 0, buffer.capacity());
if (read > 0) {
buffer.limit(read);
// Send the recorded audio data to the streaming recognition service
emitter.onNext(buffer);
buffer = ByteBuffer.allocate(1024);
// Recording rate is limited, sleep briefly to prevent high CPU usage
Thread.sleep(20);
}
}
// Notify the end of transcription
emitter.onComplete();
} catch (Exception e) {
emitter.onError(e);
}
})
.start();
},
BackpressureStrategy.BUFFER);
// Create Recognizer
Recognition recognizer = new Recognition();
// Create RecognitionParam, pass the Flowable<ByteBuffer> created above to the audioFrames parameter
RecognitionParam param = RecognitionParam.builder()
// If you have not configured the API Key as an environment variable, replace apiKey with your own API Key
// .apiKey("yourApikey")
.model("paraformer-realtime-v2")
.format("pcm")
.sampleRate(16000)
// "language_hints" is only supported by the paraformer-realtime-v2 model
.parameter("language_hints", new String[]{"zh", "en"})
.build();
// Streaming call interface
recognizer
.streamCall(param, audioSource)
.blockingForEach(
result -> {
// Subscribe to the output result
if (result.isSentenceEnd()) {
System.out.println("Final Result: " + result.getSentence().getText());
} else {
System.out.println("Intermediate Result: " + result.getSentence().getText());
}
});
// Close the WebSocket connection after the task ends
recognizer.getDuplexApi().close(1000, "bye");
System.out.println(
"[Metric] requestId: "
+ recognizer.getLastRequestId()
+ ", first package delay ms: "
+ recognizer.getFirstPackageDelay()
+ ", last package delay ms: "
+ recognizer.getLastPackageDelay());
System.exit(0);
}
}
High-concurrency calls
The DashScope Java SDK uses OkHttp3 connection pooling to reduce the overhead of repeatedly establishing connections. For more information, see Optimize Paraformer real-time speech recognition for high concurrency.
Request parameters
Configure parameters such as the model, sample rate, and audio format through the chained methods of RecognitionParam. Pass the configured parameter object to the call/streamCall method of Recognition class.
Click to view example
RecognitionParam param = RecognitionParam.builder()
.model("paraformer-realtime-v2")
.format("pcm")
.sampleRate(16000)
// "language_hints" is only supported by the paraformer-realtime-v2 model
.parameter("language_hints", new String[]{"zh", "en"})
.build();
| Parameter | Type | Default | Required | Description |
|---|---|---|---|---|
model | String | Yes | The model for real-time speech recognition. For more information, see Model list. | |
sampleRate | Integer | Yes | Set the sample rate (in Hz) of the audio to be recognized. Varies by model:
| |
format | String | Yes | Set the audio format to be recognized. Supported audio formats: pcm, wav, mp3, opus, speex, aac, amr. Importantopus/speex: Must use Ogg encapsulation. wav: Must be PCM encoded. amr: Only AMR-NB type is supported. | |
vocabularyId | String | No | Set the hot word ID. If not set, hot words will not take effect. Use this field to set the hot word ID for v2 and later models. In the current speech recognition session, the hot word information corresponding to this hot word ID will be applied. For detailed usage, see Custom hotwords. | |
disfluencyRemovalEnabled | boolean | false | No | Set whether to filter filler words:
|
language_hints | String[] | ["zh", "en"] | No | Set the language codes for recognition. If you cannot determine the language in advance, you can leave this unset and the model will automatically detect the language. Currently supported language codes:
This parameter only takes effect for models that support multiple languages (see Model list). Note |
semantic_punctuation_enabled | boolean | false | No | Set whether to enable semantic segmentation. Disabled by default.
Semantic segmentation provides higher accuracy and is suitable for meeting transcription scenarios. VAD (Voice Activity Detection) segmentation has lower latency and is suitable for interactive scenarios. By adjusting the This parameter only takes effect when the model is v2 or later. Note |
max_sentence_silence | Integer | 800 | No | Set the silence duration threshold (in ms) for VAD (Voice Activity Detection) segmentation. When the silence duration after a speech segment exceeds this threshold, the system determines that the sentence has ended. The parameter range is 200 ms to 6000 ms, with a default value of 800 ms. This parameter only takes effect when the Note |
multi_threshold_mode_enabled | boolean | false | No | When this switch is enabled (true), it prevents VAD segmentation from cutting sentences that are too long. Disabled by default. This parameter only takes effect when the Note |
punctuation_prediction_enabled | boolean | true | No | Set whether to automatically add punctuation in the recognition results:
This parameter only takes effect when the model is v2 or later. Note |
heartbeat | boolean | false | No | When you need to maintain a long connection with the server, use this switch to control the behavior:
This parameter only takes effect when the model is v2 or later. NoteThe SDK version must be 2.19.1 or later to use this field.
|
inverse_text_normalization_enabled | boolean | true | No | Set whether to enable ITN (Inverse Text Normalization). Enabled by default (true). When enabled, Chinese numerals are converted to Arabic numerals. This parameter only takes effect when the model is v2 or later. Note |
apiKey | String | No | User API Key. |
Key interfaces
Recognition class
Recognition is imported via "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. |
|
| Recognition result | Non-streaming call based on a local file. This method blocks the current thread until all audio has been read. The file to be recognized must have read permissions. |
|
|
| Flowable-based streaming real-time recognition. |
|
| None | Send audio data. Each audio packet should not be too large or too small. It is recommended that each packet is approximately 100 ms in duration, with a size between 1 KB and 16 KB. Recognition results are obtained through the onEvent method of Callback interface (ResultCallback). |
| None | None | Stop real-time recognition. This method blocks the current thread until the |
| code: WebSocket close code reason: Close reason These two parameters can be configured according to The WebSocket Protocol documentation. | true | After the task ends, the WebSocket connection must be closed regardless of whether an exception occurred, to avoid connection leaks. For information on how to reuse connections to improve efficiency, see Optimize Paraformer real-time speech recognition for high concurrency. |
| None | requestId | Get the requestId of the current task. Available after starting a new task with NoteThis method is available starting from SDK version 2.18.0. |
| None | First package delay | Get the first package delay, which is the latency from sending the first audio packet to receiving the first recognition result. Use after the task is complete. NoteThis method is available starting from SDK version 2.18.0. |
| None | Last package delay | Get the last package delay, which is the latency from sending the NoteThis method is available starting from SDK version 2.18.0. |
Callback interface (ResultCallback)
During bidirectional streaming calls, the server returns key process information and data to the client through callbacks. You need to implement the callback methods to handle the information or data returned by the server.
Callback methods are implemented by extending the abstract class ResultCallback. When extending this abstract class, you can specify the generic type as RecognitionResult. RecognitionResult encapsulates the data structure returned by the server.
Since Java supports connection reuse, there are no onClose or onOpen callbacks.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | Called when the server has a response. | |
| None | None | Called when the task is complete. |
|
| None | Called when an exception occurs. |
Response
Real-time recognition result (RecognitionResult)
RecognitionResult represents the result of a real-time recognition session.
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | requestId | Get the requestId. |
| None | Whether it is a complete sentence, i.e., a sentence boundary has been reached | Determine whether the given sentence has ended. |
| None | Get sentence information, including timestamps and text. |
Sentence information (Sentence)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | Sentence start time in ms | Returns the sentence start time. |
| None | Sentence end time in ms | Returns the sentence end time. |
| None | Recognition text | Returns the recognized text. |
| None | Returns word-level timestamp information. | |
| None | Sentiment of the current sentence | Returns the sentiment of the current sentence:
Sentiment recognition follows these constraints:
|
| None | Sentiment confidence of the current sentence | Returns the sentiment confidence of the current sentence. Value range: [0.0, 1.0]. A higher value indicates higher confidence. Sentiment recognition follows these constraints:
|
Word timestamp information (Word)
| Interface/Method | Parameter | Return value | Description |
|---|---|---|---|
| None | Word start time in ms | Returns the word start time. |
| None | Word end time in ms | Returns the word end time. |
| None | Word | Returns the recognized word. |
| None | 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.
More examples
For more examples, see GitHub.
FAQ
Feature questions
Q: How to maintain a long connection with the server during prolonged silence?
Set the request parameter heartbeat to true and continuously send silent audio to the server.
Silent audio refers to audio files or data streams that contain no sound signal. Silent audio can be generated through various methods, such as using audio editing software like Audacity or Adobe Audition, or through command-line tools like FFmpeg.
Q: How to convert audio to a supported format?
You can use the FFmpeg tool. For more usage, refer to the FFmpeg official website.
# Basic conversion command (universal template)
# -i: Input file path. Example: audio.wav
# -c:a: Audio codec. Example: aac, libmp3lame, pcm_s16le
# -b:a: Bitrate (quality control). Example: 192k, 320k
# -ar: Sample rate. Example: 44100 (CD), 48000, 16000
# -ac: Number of channels. Example: 1 (mono), 2 (stereo)
# -y: Overwrite existing file (no value needed)
ffmpeg -i input_audio.ext -c:a codec_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 # Direct extraction 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.opus
Q: Does it support viewing the time range for each sentence?
Yes. The speech recognition results include the start and end timestamps for each sentence, which can be used to determine the time range of each sentence.
Q: How to recognize a local file (recorded audio)?
There are two ways to recognize local files:
-
Pass the local file path directly: This method obtains the complete recognition result only after the entire recognition is finished, and is not suitable for scenarios requiring immediate feedback.
See Non-streaming call. Pass the file path to the
callmethod of Recognition class to directly recognize the recorded file. -
Convert the local file to a binary stream for recognition: This method recognizes the file while streaming the recognition results, suitable for scenarios requiring immediate feedback.
- See Bidirectional streaming: callback-based. Use the
sendAudioFramemethod of Recognition class to send the binary stream to the server for recognition. - See Bidirectional streaming: Flowable-based. Use the
streamCallmethod of Recognition class to send the binary stream to the server for recognition.
- See Bidirectional streaming: callback-based. Use the
Troubleshooting
Q: What causes the failure to recognize speech (no recognition results)?
-
Check whether the audio format (
format) and sample rate (sampleRate/sample_rate) in the request parameters are correctly set and comply with parameter constraints. The following are common error examples:- The audio file extension is .wav, but the actual format is MP3, and 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).
You can use the ffprobe tool to obtain the container, codec, sample rate, channel, and other information about the audio:
- The audio file extension is .wav, but the actual format is MP3, and the request parameter
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
-
When using the
paraformer-realtime-v2model, check whether the language set inlanguage_hintsmatches the actual language of the audio.For example: The audio is actually in Chinese, but
language_hintsis set toen(English). -
If all the above checks pass, you can use custom hot words to improve recognition accuracy for specific words.