Alibaba AI Docs

Appearance

time speech recognition API reference-Java SDK ​

The parameters and interfaces of the Paraformer real-time speech recognition Java SDK. Important

This document applies only to the China (Beijing) region. To use the model, you must use an API key from the China (Beijing) region. User guide: For model descriptions and selection guidance, see Real-time speech recognition - Fun-ASR/Paraformer.

Prerequisites ​

  • You have activated the Model Studio and created an API key. Export it as an environment variable (not hard-coded) to prevent security risks. Note

For temporary access or strict control over high-risk operations (accessing/deleting sensitive data), use a temporary authentication token instead.

Compared with long-term API keys, temporary tokens are more secure (60-second lifespan) and reduce API key leakage risk.

To use a temporary token, replace the API key used for authentication in your code with the temporary authentication token.

  • Install the latest version of the DashScope SDK.

Model list ​

paraformer-realtime-v2paraformer-realtime-8k-v2
ScenariosScenarios such as live streaming and meetingsRecognition scenarios for 8 kHz audio, such as telephone customer service and voicemail
Sample rateAny8 kHz
LanguagesChinese (including Mandarin and various dialects), English, Japanese, Korean, German, French, and Russian Supported Chinese dialects: Shanghainese, Wu, Minnan, Northeastern, Gansu, Guizhou, Henan, Hubei, Hunan, Jiangxi, Ningxia, Shanxi, Shaanxi, Shandong, Sichuan, Tianjin, Yunnan, and CantoneseChinese
Punctuation prediction✅ Supported by default. No configuration is required.✅ Supported by default. No configuration is required.
Inverse Text Normalization (ITN)✅ Supported by default. No configuration is required.✅ Supported by default. No configuration is required.
Custom hotwords✅ For more information, see Custom hotwords✅ For more information, see Custom hotwords
Specify recognition language✅ Specified by the language_hints parameter.❌
Emotion recognition❌✅ (Click for usage instructions) Constraints: - paraformer-realtime-8k-v2 only - Requires semantic_punctuation_enabled false (default) - Only available when isSentenceEnd() returns true To get the emotion recognition results, call the getEmoTag and getEmoConfidence methods of the Sentence information (Sentence) object. These methods return the emotion and confidence level for the current sentence.

Getting started ​

The Recognition class provides interfaces for non-streaming and bidirectional streaming calls. Select a method based on your requirements:

  • Non-streaming: Recognizes local files and returns complete results in a single response. For pre-recorded audio.

  • Bidirectional streaming: Recognizes audio streams in real time. Audio can come from external devices (microphone) or local files. For scenarios requiring immediate feedback.

Non-streaming call ​

Submit a speech-to-text task for a local file and receive the complete result synchronously (blocking operation).

Instantiate Recognition and call call with request parameters and the file to recognize. Click to view the full example The audio file used in the example is: asr_example.wav.

HELPCODEESCAPE-java
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;

import java.io.File;

public class Main {
    public static void main(String[] args) {
        // Create a Recognition instance.
        Recognition recognizer = new Recognition();
        // Create a RecognitionParam.
        RecognitionParam param =
                RecognitionParam.builder()
                        // If you do not configure the API Key to an environment variable, uncomment the following line of code and replace yourApikey with your API Key.
                        // .apiKey("yourApikey")
                        .model("paraformer-realtime-v2")
                        .format("wav")
                        .sampleRate(16000)
                        // The "language_hints" parameter is supported only 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("asr_example.wav")));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Close the WebSocket connection after the task is complete.
            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 call: Based on callbacks ​

Submit speech-to-text tasks and receive streaming results via a callback interface.

  1. Start streaming speech recognition

    Instantiate the Recognition class and call the call method with the request parameters and the callback interface (ResultCallback) to start streaming speech recognition.

  2. Stream audio

    Call sendAudioFrame repeatedly to send binary audio segments (from local files or devices like microphones). While sending audio data, the server returns results in real time via onEvent callback.

    Recommended: ~100 ms duration per segment, 1-16 KB size.

  3. End processing

    Call the stop method of the Recognition class to stop speech recognition.

    This method blocks the current thread until the onComplete or onError callback of the callback interface (ResultCallback) is triggered.

Click to view the full example

Recognize speech from a microphone ​

HELPCODEESCAPE-java
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 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 {
        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 do not configure the API Key to an environment variable, replace apiKey with your API Key.
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("wav")
                .sampleRate(16000)
                // The "language_hints" parameter is supported only 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 an 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);
                    // The recording rate is limited. Sleep for a short period to prevent high CPU usage.
                    Thread.sleep(20);
                }
            }
            recognizer.stop();
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            // Close the WebSocket connection after the task is complete.
            recognizer.getDuplexApi().close(1000, "bye");
        }

        System.out.println(
                "[Metric] requestId: "
                        + recognizer.getLastRequestId()
                        + ", first package delay ms: "
                        + recognizer.getFirstPackageDelay()
                        + ", last package delay ms: "
                        + recognizer.getLastPackageDelay());
    }
}

Recognize a local audio file ​

The audio file used in the example is: asr_example.wav.

HELPCODEESCAPE-java
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 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 {
        ExecutorService executorService = Executors.newSingleThreadExecutor();
        executorService.submit(new RealtimeRecognitionTask(Paths.get(System.getProperty("user.dir"), "asr_example.wav")));
        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 do not configure the API Key to an environment variable, replace apiKey with your API Key.
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("wav")
                .sampleRate(16000)
                // The "language_hints" parameter is supported only by the paraformer-realtime-v2 model.
                .parameter("language_hints", new String[]{"zh", "en"})
                .build();
        Recognition recognizer = new Recognition();

        String threadName = Thread.currentThread().getName();

        ResultCallback&lt;RecognitionResult&gt; callback = new ResultCallback&lt;RecognitionResult&gt;() {
            @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());
            // Set the chunk size to 1 second for a 16 kHz 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 is complete.
            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 call: Based on Flowable ​

You can submit a real-time speech-to-text task and receive streaming recognition results by implementing a Flowable workflow.

Flowable is an open-source framework for workflow and business process management that is released under the Apache 2.0 license. For more information, see Flowable API reference. Click to view the full example Directly call the streamCall method of the Recognition class to start recognition.

The streamCall method returns a Flowable&lt;RecognitionResult&gt; instance. Call methods of the Flowable instance, such as blockingForEach and subscribe, to process the recognition results. The results are encapsulated in RecognitionResult.

The streamCall method requires two parameters:

  • A RecognitionParam instance (request parameters): Use this instance to set parameters for speech recognition, such as the model, sample rate, and audio format.

  • A Flowable** instance: Create an instance of the Flowable&lt;ByteBuffer&gt; type and implement a method within the instance to parse the audio stream.

HELPCODEESCAPE-java
import com.alibaba.dashscope.audio.asr.recognition.Recognition;
import com.alibaba.dashscope.audio.asr.recognition.RecognitionParam;
import com.alibaba.dashscope.exception.NoApiKeyException;
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 {
        // Create a Flowable&lt;ByteBuffer&gt;.
        Flowable&lt;ByteBuffer&gt; audioSource =
                Flowable.create(
                        emitter -> {
                            new Thread(
                                    () -> {
                                        try {
                                            // Create an 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);
                                                    // The recording rate is limited. Sleep for a short period to prevent high CPU usage.
                                                    Thread.sleep(20);
                                                }
                                            }
                                            // Notify that the transcription is complete.
                                            emitter.onComplete();
                                        } catch (Exception e) {
                                            emitter.onError(e);
                                        }
                                    })
                                    .start();
                        },
                        BackpressureStrategy.BUFFER);

        // Create a Recognizer.
        Recognition recognizer = new Recognition();
        // Create a RecognitionParam and pass the created Flowable&lt;ByteBuffer&gt; to the audioFrames parameter.
        RecognitionParam param = RecognitionParam.builder()
                // If you do not configure the API Key to an environment variable, replace apiKey with your API Key.
                // .apiKey("yourApikey")
                .model("paraformer-realtime-v2")
                .format("pcm")
                .sampleRate(16000)
                // The "language_hints" parameter is supported only by the paraformer-realtime-v2 model.
                .parameter("language_hints", new String[]{"zh", "en"})
                .build();

        // Call the streaming 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 is complete.
        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 ​

Use the chained methods of RecognitionParam to configure parameters such as the model, sample rate, and audio format. Pass the configured parameter object to the call or streamCall method of the Recognition class. Click to view an example

HELPCODEESCAPE-java
RecognitionParam param = RecognitionParam.builder()
  .model("paraformer-realtime-v2")
  .format("pcm")
  .sampleRate(16000)
  // The "language_hints" parameter is supported only by the paraformer-realtime-v2 model.
  .parameter("language_hints", new String[]{"zh", "en"})
  .build();

<b>Parameter** Type Default value Required Description model String - Yes The model for real-time speech recognition. For more information, see Model list. sampleRate Integer - Yes The audio sampling rate in Hz. This parameter varies by model:

  • paraformer-realtime-v2 supports any sample rate.

  • paraformer-realtime-8k-v2 supports only an 8000 Hz sample rate.

    format String - Yes The format of the audio to be recognized. Supported audio formats: pcm, wav, mp3, opus, speex, aac, and amr.

**

**Important ** opus/speex: Must be encapsulated in Ogg. wav: Must be PCM encoded. amr: Only the AMR-NB type is supported.

vocabularyId String - No The ID of the hotword vocabulary. This parameter takes effect only when it is set. Use this field to set the hotword ID for v2 and later models. The hotword information for this hotword ID is applied to the speech recognition request. For more information, see Custom hotwords. disfluencyRemovalEnabled boolean false No Specifies whether to filter out disfluent words:

  • true

  • false (default)

    language_hints String[] ["zh", "en"] No The language code for recognition. If you cannot determine the language in advance, leave this parameter unset for automatic detection. Currently supported language codes:

  • zh: Chinese

  • en: English

  • ja: Japanese

  • yue: Cantonese

  • ko: Korean

  • de: German

  • fr: French

  • ru: Russian

This parameter applies only to models that support multiple languages. For more information, see Model list.

**

**Note ** Set language_hints using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("language_hints", new String\[\]{"zh", "en"})
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("language_hints", new String\[\]{"zh", "en"}))
 .build();

semantic_punctuation_enabled boolean false No Specifies whether to enable semantic sentence segmentation (disabled by default):

  • true: Uses semantic segmentation (disables VAD segmentation).
  • false (default): Uses VAD segmentation. Semantic segmentation provides higher accuracy and is ideal for meeting transcription. VAD segmentation has lower latency and is ideal for interactive scenarios. Applies to v2 and later models.

**

**Note ** Set semantic_punctuation_enabled using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("semantic_punctuation_enabled", true)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("semantic_punctuation_enabled", true))
 .build();

max_sentence_silence Integer 800 No The VAD sentence segmentation silence threshold (ms). If silence after a speech segment exceeds this value, the sentence ends. Range: 200-6000 ms. Default: 800 ms. Applies only when semantic_punctuation_enabled is false (VAD mode) and model is v2 or later.

**

**Note ** Set max_sentence_silence using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("max_sentence_silence", 800)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("max_sentence_silence", 800))
 .build();

multi_threshold_mode_enabled boolean false No Specifies whether to prevent VAD from over-segmenting long sentences (disabled by default). Applies only when semantic_punctuation_enabled is false (VAD mode) and model is v2 or later.

**

**Note ** Set multi_threshold_mode_enabled using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("multi_threshold_mode_enabled", true)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("multi_threshold_mode_enabled", true))
 .build();

punctuation_prediction_enabled boolean true No Specifies whether to automatically add punctuation to results (enabled by default):

  • true (default)
  • false Applies to v2 and later models only.

**

**Note ** Set punctuation_prediction_enabled using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("punctuation_prediction_enabled", false)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("punctuation_prediction_enabled", false))
 .build();

heartbeat boolean false No Specifies whether to maintain a persistent server connection:

  • true: Keeps connection alive when sending silent audio continuously.
  • false (default): Connection times out after 60s even with silent audio. Silent audio: audio with no sound signal. Generate it with editing software (Audacity, Adobe Audition) or FFmpeg.

Applies to v2 and later models only.

**

**Note ** To use this field, your SDK version must be 2.19.1 or later. Set heartbeat using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("heartbeat", true)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("heartbeat", true))
 .build();

inverse_text_normalization_enabled boolean true No Specifies whether to enable Inverse Text Normalization (ITN). When enabled, Chinese numerals are converted to Arabic numerals (enabled by default). Applies to v2 and later models only.

**

**Note ** Set inverse_text_normalization_enabled using the parameter or parameters method of the RecognitionParam instance:

## Set using the parameter method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameter("inverse_text_normalization_enabled", false)
 .build();

## Set using the parameters method ​

java
RecognitionParam param = RecognitionParam.builder()
 .model("paraformer-realtime-v2")
 .format("pcm")
 .sampleRate(16000)
 .parameters(Collections.singletonMap("inverse_text_normalization_enabled", false))
 .build();

apiKey String - No Your API key.

Key interfaces ​

Recognition class ​

Import: com.alibaba.dashscope.audio.asr.recognition.Recognition. Key interfaces: Interface/Method Parameters Return value Description

java
public void call(RecognitionParam param, final ResultCallback&lt;RecognitionResult&gt; callback)
  • param: Request parameters
  • callback: ResultCallback None Performs streaming recognition via callbacks (non-blocking).
java
public String call(RecognitionParam param, File file)
  • param: Request parameters
  • file: The audio file to be recognized Recognition result Non-streaming call for local files. Blocks until file is fully read. Requires read permissions.
java
public Flowable&lt;RecognitionResult&gt; streamCall(RecognitionParam param, Flowable** audioFrame)
  • param: Request parameters
  • audioFrame: A Flowable&lt;ByteBuffer&gt; instance Flowable&lt;RecognitionResult&gt; Performs streaming real-time recognition based on Flowable.
java
public void sendAudioFrame(ByteBuffer audioFrame)
  • audioFrame: A binary audio stream of the ByteBuffer type None Pushes audio stream segments. Recommended: ~100 ms duration, 1-16 KB size per packet.Results are returned via onEvent callback.
java
public void stop()

None None Stops recognition. Blocks until onComplete or onError callback is triggered.

java
recognizer.getDuplexApi().close(int code, String reason)

code: WebSocket Close Codereason: Reason for closingFor information about how to configure these two parameters, see The WebSocket Protocol document. true Close WebSocket after task ends to prevent leaks (even on exceptions). See Optimize Paraformer real-time speech recognition for high concurrency for connection reuse.

java
public String getLastRequestId()

None requestId Gets current task's request ID. Call after starting a task with call or streamingCall.

**

<strong>Note </strong> This method is available in SDK versions 2.18.0 and later.

java
public long getFirstPackageDelay()

None First-packet latency Gets first-packet latency (delay from sending first audio packet to receiving first result). Call after task completion.

**

<strong>Note </strong> This method is available in SDK versions 2.18.0 and later.

java
public long getLastPackageDelay()

None Last-packet latency Gets last-packet latency (time from sending stop to receiving last result). Call after task completion.

**

<strong>Note </strong> This method is available in SDK versions 2.18.0 and later.

ResultCallback ​

In bidirectional streaming, the server returns data via callbacks. Implement callback methods to handle server responses.

Inherit ResultCallback&lt;RecognitionResult&gt; to implement callbacks. RecognitionResult encapsulates server response data.

Because Java supports connection reuse, there are no onClose or onOpen methods. Example

HELPCODEESCAPE-java
ResultCallback&lt;RecognitionResult&gt; callback = new ResultCallback&lt;RecognitionResult&gt;() {
    @Override
    public void onEvent(RecognitionResult result) {
        System.out.println("RequestId is: " + result.getRequestId());
        // Implement the logic to process the speech recognition result here.
    }

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

    @Override
    public void onError(Exception e) {
        System.out.println("Task failed: " + e.getMessage());
    }
};

<b>Interface/Method** Parameters Return value Description

java
public void onEvent(RecognitionResult result)

result: Real-time recognition result (RecognitionResult) None Called when server sends a response.

java
public void onComplete()

None None Called when task completes.

java
public void onError(Exception e)

e: Exception information None Called when an exception occurs.

Response ​

Real-time recognition result (RecognitionResult) ​

RecognitionResult represents the result of a single real-time recognition. Interface/Method Parameters Return value Description

java
public String getRequestId()

None requestId Gets the request ID.

java
public boolean isSentenceEnd()

None Whether the sentence is complete, which means a sentence break has occurred Checks whether the given sentence has ended.

java
public Sentence getSentence()

None Sentence information (Sentence) Gets sentence info (timestamp and text).

Sentence information (Sentence) ​

Interface/Method Parameters Return value Description

java
public Long getBeginTime()

None Sentence start time, in ms Returns the start time of the sentence.

java
public Long getEndTime()

None Sentence end time, in ms Returns the end time of the sentence.

java
public String getText()

None Recognized text Returns the recognized text.

java
public List&lt;Word&gt; getWords()

None A list of Word timestamp information (Word) objects Returns word timestamp information.

java
public String getEmoTag()

None Emotion of the current sentence Returns sentence emotion:

  • positive: Happy, satisfied
  • negative: Angry, dull
  • neutral: No obvious emotion

Constraints:

  • paraformer-realtime-8k-v2 only
  • Requires semantic_punctuation_enabled false (default)
  • Only available when isSentenceEnd() returns true
java
public Double getEmoConfidence()

None Confidence level of the recognized emotion for the current sentence Returns the confidence level of the recognized emotion for the current sentence. The value ranges from 0.0 to 1.0. A larger value indicates a higher confidence level. Constraints:

  • paraformer-realtime-8k-v2 only
  • Requires semantic_punctuation_enabled false (default)
  • Only available when isSentenceEnd() returns true

Word timestamp information (Word) ​

Interface/Method Parameters Return value Description

java
public long getBeginTime()

None Word start time, in ms Returns the start time of the word.

java
public long getEndTime()

None Word end time, in ms Returns the end time of the word.

java
public String getText()

None Word Returns the recognized word.

java
public String getPunctuation()

None Punctuation Returns the punctuation.

Error codes ​

If an error occurs, see Error messages for troubleshooting.

If the problem persists, join the developer group to report the issue. Provide the Request ID to help us investigate the issue.

More examples ​

For more examples, see GitHub.

FAQ ​

Features ​

Q: How to maintain a persistent connection with the server during long periods of silence? ​

Set heartbeat parameter to true and send silent audio continuously. Silent audio: audio with no sound signal. Generate it with editing software (Audacity, Adobe Audition) or FFmpeg.

Q: How to convert an audio format to the required format? ​

You can use the FFmpeg tool. For more information, see the official FFmpeg website.

HELPCODEESCAPE-bash

# -i: Specifies the input file path. Example: audio.wav
# -c:a: Specifies the audio encoder. Examples: aac, libmp3lame, pcm_s16le
# -b:a: Specifies the bit rate (controls audio quality). Examples: 192k, 320k
# -ar: Specifies the sample rate. Examples: 44100 (CD), 48000, 16000
# -ac: Specifies the number of sound channels. Examples: 1 (mono), 2 (stereo)
# -y: Overwrites an existing file (no value needed).
ffmpeg -i input_audio.ext -c:a encoder_name -b:a bit_rate -ar sample_rate -ac num_channels output.ext

# Example: WAV to MP3 (maintain original quality)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3
# Example: MP3 to WAV (16-bit PCM standard format)
ffmpeg -i input.mp3 -c:a pcm_s16le -ar 44100 -ac 2 output.wav
# Example: M4A to AAC (extract/convert Apple audio)
ffmpeg -i input.m4a -c:a copy output.aac  # Directly extract without re-encoding
ffmpeg -i input.m4a -c:a aac -b:a 256k output.aac  # Re-encode to improve quality
# Example: FLAC lossless to Opus (high compression)
ffmpeg -i input.flac -c:a libopus -b:a 128k -vbr on output.opus

Q: Can I view the time range for each sentence? ​

Yes. Results include start/end timestamps for each sentence to determine time ranges.

Q: How to recognize a local file (recorded audio file)? ​

There are two ways to recognize a local file:

  • Pass local file path: Returns complete result after processing entire file. Not for scenarios requiring immediate feedback.

    Pass file path to call method for recognition.

  • Convert file to binary stream: Provides real-time results during streaming. For scenarios requiring immediate feedback.

Troubleshooting ​

Q: Why there is no recognition result? ​

  1. Verify audio format and sampleRate/sample_rate match parameter constraints. Common errors:

    • The audio file has a .wav extension but is in MP3 format, and the format parameter is incorrectly set to `mp3`.

    • The audio sample rate is 3600 Hz, but the sampleRate/sample_rate parameter is incorrectly set to 48000.

    Use ffprobe to check audio info (container, encoding, sample rate, channels):

    HELPCODEESCAPE-sh
ffprobe -v error -show_entries format=format_name -show_entries stream=codec_name,sample_rate,channels -of default=noprint_wrappers=1 input.xxx

  2. When you use 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 in Chinese, but language_hints is set to en (English).

  3. If all the preceding checks pass, you can use custom hotwords to improve the recognition of specific words.

Mirror of Alibaba Cloud Model Studio docs for reference and RAG. Not affiliated with Alibaba Cloud.

Source: alibabacloud.com/help/en/model-studio