Java

This page shows how to use X-ASR models with the Java API of sherpa-onnx. Two demos are given: one with a non-streaming model and one with a streaming model.

Requirements

  • JDK 11 or above

  • Maven 3.x

Non-streaming X-ASR

Step 1. Create the project directory

mkdir x-asr-demo
cd x-asr-demo

Step 2. Create the build file

Save the following as pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>sherpa-onnx-java-example</artifactId>
    <version>1.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>11</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <sherpa-onnx.version>v2.0.1</sherpa-onnx.version>
    </properties>

    <repositories>
        <!-- sherpa-onnx packages are hosted on JitPack -->
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.github.k2-fsa</groupId>
            <artifactId>sherpa-onnx</artifactId>
            <version>${sherpa-onnx.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.3.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>NonStreamingDecodeFileXasr</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Step 3. Download the model

wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03.tar.bz2
tar xf sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03.tar.bz2
rm sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03.tar.bz2

Step 4. Save the code

Save the following as src/main/java/NonStreamingDecodeFileXasr.java:

// Copyright 2026 Xiaomi Corporation

// This file shows how to use an X-ASR non-streaming zipformer transducer
// model to decode files.
//
// X-ASR is from https://github.com/Gilgamesh-J/X-ASR and supports both
// Chinese and English. The punct model used here also adds punctuations to
// the recognition result.
//
// Please see
// https://k2-fsa.github.io/sherpa/onnx/x-asr/index.html
// to download model files
import com.k2fsa.sherpa.onnx.*;

public class NonStreamingDecodeFileXasr {
  public static void main(String[] args) {
    String modelDir = "./sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03";
    String encoder = modelDir + "/encoder-epoch-99-avg-1.int8.onnx";
    String decoder = modelDir + "/decoder-epoch-99-avg-1.onnx";
    String joiner = modelDir + "/joiner-epoch-99-avg-1.int8.onnx";
    String tokens = modelDir + "/tokens.txt";

    String waveFilename = modelDir + "/test_wavs/0.wav";

    WaveReader reader = new WaveReader(waveFilename);

    OfflineTransducerModelConfig transducer =
        OfflineTransducerModelConfig.builder()
            .setEncoder(encoder)
            .setDecoder(decoder)
            .setJoiner(joiner)
            .build();

    OfflineModelConfig modelConfig =
        OfflineModelConfig.builder()
            .setTransducer(transducer)
            .setTokens(tokens)
            .setNumThreads(2)
            .setDebug(false)
            .build();

    OfflineRecognizerConfig config =
        OfflineRecognizerConfig.builder()
            .setOfflineModelConfig(modelConfig)
            .setDecodingMethod("greedy_search")
            .build();

    OfflineRecognizer recognizer = new OfflineRecognizer(config);
    long start = System.currentTimeMillis();
    OfflineStream stream = recognizer.createStream();
    stream.acceptWaveform(reader.getSamples(), reader.getSampleRate());

    recognizer.decode(stream);

    String text = recognizer.getResult(stream).getText();

    float timeElapsedSeconds = (System.currentTimeMillis() - start) / 1000.0f;
    System.out.printf("filename:%s\nresult:%s\n", waveFilename, text);
    float audioDuration = reader.getSamples().length / (float) reader.getSampleRate();
    System.out.printf("audio duration: %.3f s\n", audioDuration);
    System.out.printf("elapsed seconds: %.3f s\n", timeElapsedSeconds);
    System.out.printf(
        "RTF = %.3f/%.3f = %.3f\n", timeElapsedSeconds, audioDuration, timeElapsedSeconds / audioDuration);


    stream.release();
    recognizer.release();
  }
}

Step 5. Check the project layout

Your project directory should now look like this:

$ tree .
.
├── pom.xml
├── sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03
│   ├── bpe.model
│   ├── decoder-epoch-99-avg-1.onnx
│   ├── encoder-epoch-99-avg-1.int8.onnx
│   ├── joiner-epoch-99-avg-1.int8.onnx
│   ├── README.md
│   ├── test_onnx.py
│   ├── test_wavs
│   │   ├── 0.wav
│   │   ├── 1.wav
│   │   ├── 2.wav
│   │   └── 3.wav
│   └── tokens.txt
└── src
    └── main
        └── java
            └── NonStreamingDecodeFileXasr.java

6 directories, 13 files

$ ls -lh
total 8
-rw-r--r--@  1 fangjun  wheel   2.1K 19 Nov 12:23 pom.xml
drwxr-xr-x@ 10 fangjun  wheel   320B 29 Jun 16:31 sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03
drwxr-xr-x@  3 fangjun  wheel    96B 19 Nov 12:23 src

Step 6. Build and run

From the project directory, run:

mvn -q package
java -jar target/sherpa-onnx-java-example-1.0.jar

Output

filename:./sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03/test_wavs/0.wav
result:昨天是 Monday, today is 礼拜二, the day after tomorrow 是星期三。
audio duration: 10.053 s
elapsed seconds: 0.116 s
RTF = 0.116/10.053 = 0.012

Note

The timing above was measured on a MacBook Pro (Apple M4) using 2 threads. Please increase the number of threads for a smaller RTF on your machine.

Streaming X-ASR

Step 1. Create the project directory

mkdir x-asr-demo
cd x-asr-demo

Step 2. Create the build file

Save the following as pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.example</groupId>
    <artifactId>sherpa-onnx-java-example</artifactId>
    <version>1.0</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.release>11</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <sherpa-onnx.version>v2.0.1</sherpa-onnx.version>
    </properties>

    <repositories>
        <!-- sherpa-onnx packages are hosted on JitPack -->
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <dependencies>
        <dependency>
            <groupId>com.github.k2-fsa</groupId>
            <artifactId>sherpa-onnx</artifactId>
            <version>${sherpa-onnx.version}</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.3.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <mainClass>StreamingDecodeFileXasr</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-shade-plugin</artifactId>
                <version>3.5.1</version>
                <executions>
                    <execution>
                        <phase>package</phase>
                        <goals>
                            <goal>shade</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Step 3. Download the model

wget https://github.com/k2-fsa/sherpa-onnx/releases/download/asr-models/sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05.tar.bz2
tar xf sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05.tar.bz2
rm sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05.tar.bz2

Step 4. Save the code

Save the following as src/main/java/StreamingDecodeFileXasr.java:

// Copyright 2026 Xiaomi Corporation

// This file shows how to use an X-ASR streaming zipformer transducer model
// to decode files.
//
// X-ASR is from https://github.com/Gilgamesh-J/X-ASR and supports both
// Chinese and English. The punct model used here also adds punctuations to
// the recognition result.
//
// Please see
// https://k2-fsa.github.io/sherpa/onnx/x-asr/index.html
// to download model files
import com.k2fsa.sherpa.onnx.*;

public class StreamingDecodeFileXasr {
  public static void main(String[] args) {
    String modelDir =
        "./sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05";
    String encoder = modelDir + "/encoder.int8.onnx";
    String decoder = modelDir + "/decoder.onnx";
    String joiner = modelDir + "/joiner.int8.onnx";
    String tokens = modelDir + "/tokens.txt";

    String waveFilename = modelDir + "/test_wavs/0.wav";

    WaveReader reader = new WaveReader(waveFilename);

    OnlineTransducerModelConfig transducer =
        OnlineTransducerModelConfig.builder()
            .setEncoder(encoder)
            .setDecoder(decoder)
            .setJoiner(joiner)
            .build();

    OnlineModelConfig modelConfig =
        OnlineModelConfig.builder()
            .setTransducer(transducer)
            .setTokens(tokens)
            .setNumThreads(2)
            .setDebug(false)
            .build();

    OnlineRecognizerConfig config =
        OnlineRecognizerConfig.builder()
            .setOnlineModelConfig(modelConfig)
            .setDecodingMethod("greedy_search")
            .build();

    OnlineRecognizer recognizer = new OnlineRecognizer(config);
    long start = System.currentTimeMillis();
    OnlineStream stream = recognizer.createStream();
    stream.acceptWaveform(reader.getSamples(), reader.getSampleRate());

    float[] tailPaddings = new float[(int) (0.8 * reader.getSampleRate())];
    stream.acceptWaveform(tailPaddings, reader.getSampleRate());

    while (recognizer.isReady(stream)) {
      recognizer.decode(stream);
    }

    String text = recognizer.getResult(stream).getText();

    float timeElapsedSeconds = (System.currentTimeMillis() - start) / 1000.0f;
    System.out.printf("filename:%s\nresult:%s\n", waveFilename, text);
    float audioDuration = reader.getSamples().length / (float) reader.getSampleRate();
    System.out.printf("audio duration: %.3f s\n", audioDuration);
    System.out.printf("elapsed seconds: %.3f s\n", timeElapsedSeconds);
    System.out.printf(
        "RTF = %.3f/%.3f = %.3f\n", timeElapsedSeconds, audioDuration, timeElapsedSeconds / audioDuration);


    stream.release();
    recognizer.release();
  }
}

Step 5. Check the project layout

Your project directory should now look like this:

$ tree .
.
├── pom.xml
├── sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05
│   ├── bpe.model
│   ├── decoder.onnx
│   ├── encoder.int8.onnx
│   ├── joiner.int8.onnx
│   ├── README.md
│   ├── test_onnx.py
│   ├── test_wavs
│   │   ├── 0.wav
│   │   ├── 1.wav
│   │   ├── 2.wav
│   │   └── 3.wav
│   └── tokens.txt
└── src
    └── main
        └── java
            └── StreamingDecodeFileXasr.java

6 directories, 13 files

$ ls -lh
total 8
-rw-r--r--@  1 fangjun  wheel   2.1K 19 Nov 12:23 pom.xml
drwxr-xr-x@ 10 fangjun  wheel   320B 29 Jun 16:30 sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05
drwxr-xr-x@  3 fangjun  wheel    96B 19 Nov 12:23 src

Step 6. Build and run

From the project directory, run:

mvn -q package
java -jar target/sherpa-onnx-java-example-1.0.jar

Output

filename:./sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05/test_wavs/0.wav
result:昨天是 Monday, today is 礼拜二, the day after tomorrow 是星期三
audio duration: 10.053 s
elapsed seconds: 0.326 s
RTF = 0.326/10.053 = 0.032

Note

The timing above was measured on a MacBook Pro (Apple M4) using 2 threads. Please increase the number of threads for a smaller RTF on your machine.

Notes

Please see Java API if you want to use Gradle or Gradle KTS instead of Maven.