Skip to main content
QwenCloud home page
Docs
Paraformer-Realtime

Paraformer real-time speech recognition Java SDK

This topic describes the parameters and interface details of the Paraformer real-time speech recognition Java SDK.

Paraformer models are available only in the China North 2 (Beijing) region. Use an API key created in that region. See Regions and endpoints.
User guide: For model introduction and selection recommendations, see Real-time speech recognition - Fun-ASR/Paraformer.

Prerequisites

When 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 (Recommended)paraformer-realtime-8k-v2 (Recommended)
Use caseLive streaming, meetings, and similar scenariosRecognition of 8 kHz audio in scenarios such as telephone customer service and voicemail
Sample rateAny8kHz
LanguageChinese (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, CantoneseChinese
Punctuation predictionSupported by default, no configuration requiredSupported by default, no configuration required
Inverse text normalization (ITN)Supported by default, no configuration requiredSupported by default, no configuration required
Custom hot wordsSee Custom hotwordsSee Custom hotwords
Specify recognition languageSpecify via the language_hints parameter
Sentiment recognitionSentiment recognition follows these constraints:
  • Only available for the paraformer-realtime-8k-v2 model.
  • Semantic segmentation must be disabled (controlled via Request parameters semantic_punctuation_enabled). Semantic segmentation is disabled by default.
  • Sentiment recognition results are only shown when the isSentenceEnd method of Real-time recognition result (RecognitionResult) returns true.
How to obtain sentiment recognition results: Call the getEmoTag and getEmoConfidence methods of Sentence information (Sentence) to obtain the sentiment and sentiment confidence of the current sentence respectively.

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.
image
Instantiate Recognition class, call the call method with Request parameters and the file to be recognized, perform recognition, and obtain the recognition result. 
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) {
        // China North 2 (Beijing). This model is available only in this region.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        Constants.baseWebsocketApiUrl = "wss://cn-beijing.maas.qwencloudapi.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.
image
  1. Start streaming speech recognition Instantiate Recognition class, call the call method with Request parameters and Callback interface (ResultCallback) to start streaming speech recognition.
  2. Stream audio data Call the sendAudioFrame method 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 onEvent method 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.
  3. Finish processing Call the stop method of Recognition class to end speech recognition. This method blocks the current thread until the onComplete or onError callback of Callback interface (ResultCallback) is triggered. 
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 {
        // China North 2 (Beijing). This model is available only in this region.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        Constants.baseWebsocketApiUrl = "wss://cn-beijing.maas.qwencloudapi.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());
    }
}

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.
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:
  • RecognitionParam instance (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 a Flowable<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 {
        // China North 2 (Beijing). This model is available only in this region.
        // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
        Constants.baseWebsocketApiUrl = "wss://cn-beijing.maas.qwencloudapi.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. 
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();
ParameterTypeDefaultRequiredDescription
modelString-YesThe model for real-time speech recognition. For more information, see Model list.
sampleRateInteger-YesSet the sample rate (in Hz) of the audio to be recognized. Varies by model:
  • paraformer-realtime-v2 supports any sample rate.
  • paraformer-realtime-8k-v2 only supports 8000 Hz sample rate.
formatString-YesSet the audio format to be recognized. Supported audio formats: pcm, wav, mp3, opus, speex, aac, amr. Tip: opus/speex: Must use Ogg encapsulation. wav: Must be PCM encoded. amr: Only AMR-NB type is supported.
vocabularyIdString-NoSet 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.
disfluencyRemovalEnabledbooleanfalseNoSet whether to filter filler words:
  • true: Filter filler words
  • false (default): Do not filter filler words
language_hintsString[]["zh", "en"]NoSet 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:
  • zh: Chinese
  • en: English
  • ja: Japanese
  • yue: Cantonese
  • ko: Korean
  • de: German
  • fr: French
  • ru: Russian
This parameter only takes effect for models that support multiple languages (see Model list). Note: language_hints must be set through the RecognitionParam instance's parameter method or parameters method: See Example 1 below See Example 2 below
semantic_punctuation_enabledbooleanfalseNoSet whether to enable semantic segmentation. Disabled by default.
  • true: Enable semantic segmentation and disable VAD (Voice Activity Detection) segmentation.
  • false (default): Enable VAD (Voice Activity Detection) segmentation and disable semantic segmentation.
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 semantic_punctuation_enabled parameter, you can flexibly switch the speech recognition segmentation method to suit different scenarios. This parameter only takes effect when the model is v2 or later. Note: semantic_punctuation_enabled must be set through the RecognitionParam instance's parameter method or parameters method: See Example 3 below See Example 4 below
max_sentence_silenceInteger800NoSet 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 semantic_punctuation_enabled parameter is false (VAD segmentation) and the model is v2 or later. Note: max_sentence_silence must be set through the RecognitionParam instance's parameter method or parameters method: See Example 5 below See Example 6 below
multi_threshold_mode_enabledbooleanfalseNoWhen 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 semantic_punctuation_enabled parameter is false (VAD segmentation) and the model is v2 or later. Note: multi_threshold_mode_enabled must be set through the RecognitionParam instance's parameter method or parameters method: See Example 7 below See Example 8 below
punctuation_prediction_enabledbooleantrueNoSet whether to automatically add punctuation in the recognition results:
  • true (default): Yes
  • false: No
This parameter only takes effect when the model is v2 or later. Note: punctuation_prediction_enabled must be set through the RecognitionParam instance's parameter method or parameters method: See Example 9 below See Example 10 below
heartbeatbooleanfalseNoWhen you need to maintain a long connection with the server, use this switch to control the behavior:
  • true: The connection with the server can be maintained without interruption when continuously sending silent audio.
  • false (default): Even when silent audio is continuously sent, the connection times out and closes after a period of time.
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. This parameter only takes effect when the model is v2 or later. Note: The SDK version must be 2.19.1 or later to use this field. heartbeat must be set through the RecognitionParam instance's parameter method or parameters method: See Example 11 below See Example 12 below
inverse_text_normalization_enabledbooleantrueNoSet 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: inverse_text_normalization_enabled must be set through the RecognitionParam instance's parameter method or parameters method: See Example 13 below See Example 14 below
apiKeyString-NoUser API Key.
Example 1 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("language_hints", new String[]{"zh", "en"})
 .build();
Example 2 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("language_hints", new String[]{"zh", "en"}))
 .build();
Example 3 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("semantic_punctuation_enabled", true)
 .build();
Example 4 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("semantic_punctuation_enabled", true))
 .build();
Example 5 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("max_sentence_silence", 800)
 .build();
Example 6 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("max_sentence_silence", 800))
 .build();
Example 7 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("multi_threshold_mode_enabled", true)
 .build();
Example 8 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("multi_threshold_mode_enabled", true))
 .build();
Example 9 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("punctuation_prediction_enabled", false)
 .build();
Example 10 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("punctuation_prediction_enabled", false))
 .build();
Example 11 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("heartbeat", true)
 .build();
Example 12 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("heartbeat", true))
 .build();
Example 13 (Description):
Set via parameter
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("inverse_text_normalization_enabled", false)
 .build();
Example 14 (Description):
Set via parameters
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("inverse_text_normalization_enabled", false))
 .build();

Key interfaces

Recognition class

Recognition is imported via "import com.alibaba.dashscope.audio.asr.recognition.Recognition;". Its key interfaces are as follows:
Interface/MethodParameterReturn valueDescription
See Example 1 belowNoneCallback-based streaming real-time recognition. This method does not block the current thread.
See Example 2 belowRecognition resultNon-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.
See Example 3 belowFlowable<RecognitionResult>Flowable-based streaming real-time recognition.
See Example 4 below
  • audioFrame: Binary audio stream of ByteBuffer type
NoneSend 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).
See Example 5 belowNoneNoneStop real-time recognition. This method blocks the current thread until the ResultCallback instance's onComplete or onError method is called.
See Example 6 belowcode: WebSocket close code reason: Close reason These two parameters can be configured according to The WebSocket Protocol documentation.trueAfter 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.
See Example 7 belowNonerequestIdGet the requestId of the current task. Available after starting a new task with call or streamingCall. Note: This method is available starting from SDK version 2.18.0.
See Example 8 belowNoneFirst package delayGet 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. Note: This method is available starting from SDK version 2.18.0.
See Example 9 belowNoneLast package delayGet the last package delay, which is the latency from sending the stop command to receiving the last recognition result. Use after the task is complete. Note: This method is available starting from SDK version 2.18.0.
Example 1 (Interface/Method): 
public void call(RecognitionParam param, final ResultCallback<RecognitionResult> callback)
Example 2 (Interface/Method): 
public String call(RecognitionParam param, File file)
Example 3 (Interface/Method): 
public Flowable<RecognitionResult> streamCall(RecognitionParam param, Flowable<ByteBuffer> audioFrame)
Example 4 (Interface/Method): 
public void sendAudioFrame(ByteBuffer audioFrame)
Example 5 (Interface/Method): 
public void stop()
Example 6 (Interface/Method): 
recognizer.getDuplexApi().close(int code, String reason)
Example 7 (Interface/Method): 
public String getLastRequestId()
Example 8 (Interface/Method): 
public long getFirstPackageDelay()
Example 9 (Interface/Method): 
public long getLastPackageDelay()

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.

Example

ResultCallback<RecognitionResult> callback = new ResultCallback<RecognitionResult>() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId: " + result.getRequestId());
        // Implement your logic to process speech recognition results here
    }

    @Override
    public void onComplete() {
        System.out.println("Task completed");
    }

    @Override
    public void onError(Exception e) {
        System.out.println("Task failed: " + e.getMessage());
    }
};
Interface/MethodParameterReturn valueDescription
See Example 1 belowresult: Real-time recognition result (RecognitionResult)NoneCalled when the server has a response.
See Example 2 belowNoneNoneCalled when the task is complete.
See Example 3 belowe: Exception informationNoneCalled when an exception occurs.
Example 1 (Interface/Method): 
public void onEvent(RecognitionResult result)
Example 2 (Interface/Method): 
public void onComplete()
Example 3 (Interface/Method): 
public void onError(Exception e)

Response

Real-time recognition result (RecognitionResult)

RecognitionResult represents the result of a real-time recognition session.
Interface/MethodParameterReturn valueDescription
See Example 1 belowNonerequestIdGet the requestId.
See Example 2 belowNoneWhether it is a complete sentence, i.e., a sentence boundary has been reachedDetermine whether the given sentence has ended.
See Example 3 belowNoneSentence information (Sentence)Get sentence information, including timestamps and text.
Example 1 (Interface/Method): 
public String getRequestId()
Example 2 (Interface/Method): 
public boolean isSentenceEnd()
Example 3 (Interface/Method): 
public Sentence getSentence()

Sentence information (Sentence)

Interface/MethodParameterReturn valueDescription
See Example 1 belowNoneSentence start time in msReturns the sentence start time.
See Example 2 belowNoneSentence end time in msReturns the sentence end time.
See Example 3 belowNoneRecognition textReturns the recognized text.
See Example 4 belowNoneList of Word timestamp information (Word)Returns word-level timestamp information.
See Example 5 belowNoneSentiment of the current sentenceReturns the sentiment of the current sentence:
  • positive: Positive sentiment, such as happy or satisfied
  • negative: Negative sentiment, such as angry or gloomy
  • neutral: No obvious sentiment
Sentiment recognition follows these constraints:
  • Only available for the paraformer-realtime-8k-v2 model.
  • Semantic segmentation must be disabled (controlled via Request parameters semantic_punctuation_enabled). Semantic segmentation is disabled by default.
  • Sentiment recognition results are only shown when the isSentenceEnd method of Real-time recognition result (RecognitionResult) returns true.
See Example 6 belowNoneSentiment confidence of the current sentenceReturns the sentiment confidence of the current sentence. Value range: [0.0, 1.0]. A higher value indicates higher confidence. Sentiment recognition follows these constraints:
  • Only available for the paraformer-realtime-8k-v2 model.
  • Semantic segmentation must be disabled (controlled via Request parameters semantic_punctuation_enabled). Semantic segmentation is disabled by default.
  • Sentiment recognition results are only shown when the isSentenceEnd method of Real-time recognition result (RecognitionResult) returns true.
Example 1 (Interface/Method): 
public Long getBeginTime()
Example 2 (Interface/Method): 
public Long getEndTime()
Example 3 (Interface/Method): 
public String getText()
Example 4 (Interface/Method): 
public List<Word> getWords()
Example 5 (Interface/Method): 
public String getEmoTag()
Example 6 (Interface/Method): 
public Double getEmoConfidence()

Word timestamp information (Word)

Interface/MethodParameterReturn valueDescription
See Example 1 belowNoneWord start time in msReturns the word start time.
See Example 2 belowNoneWord end time in msReturns the word end time.
See Example 3 belowNoneWordReturns the recognized word.
See Example 4 belowNonePunctuationReturns the punctuation.
Example 1 (Interface/Method): 
public long getBeginTime()
Example 2 (Interface/Method): 
public long getEndTime()
Example 3 (Interface/Method): 
public String getText()
Example 4 (Interface/Method): 
public String getPunctuation()

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 call method 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.

Troubleshooting

Q: What causes the failure to recognize speech (no recognition results)?

  1. 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 format is set to mp3 (incorrect parameter setting).
    • The audio sample rate is 3600 Hz, but the request parameter sampleRate/sample_rate is 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: 
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx
  1. When using the paraformer-realtime-v2 model, check whether the language set in language_hints matches the actual language of the audio. For example: The audio is actually in Chinese, but language_hints is set to en (English).
  2. If all the above checks pass, you can use custom hot words to improve recognition accuracy for specific words.