Kotlin
This page shows how to use X-ASR models with the Kotlin API of sherpa-onnx. Two demos are given: one with a non-streaming model and one with a streaming model. You can build the project with either Maven or Gradle (Kotlin DSL).
On this page
Requirements
JDK 11 or above
Maven 3.x or Gradle 8.x+
Non-streaming X-ASR
Step 1. Create the project directory
mkdir x-asr-demo
cd x-asr-demo
Step 2. Create the build files
If you use Maven, create pom.xml. If you use Gradle (Kotlin DSL), create build.gradle.kts and settings.gradle.kts.
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>x-asr-kotlin-example</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
<properties>
<kotlin.version>2.2.20</kotlin.version>
<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>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-stdlib</artifactId>
<version>${kotlin.version}</version>
</dependency>
<dependency>
<groupId>com.github.k2-fsa</groupId>
<artifactId>sherpa-onnx</artifactId>
<version>${sherpa-onnx.version}</version>
</dependency>
</dependencies>
<build>
<sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<executions>
<execution>
<id>compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<jvmTarget>11</jvmTarget>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<configuration>
<archive>
<manifest>
<mainClass>XasrOfflineDemoKt</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>
Save the following as build.gradle.kts:
plugins {
kotlin("jvm") version "2.2.20"
application
}
application {
mainClass.set("XasrOfflineDemoKt")
}
repositories {
mavenCentral()
// sherpa-onnx packages are hosted on JitPack
maven { url = uri("https://jitpack.io") }
}
dependencies {
implementation("com.github.k2-fsa:sherpa-onnx:v2.0.1")
}
java {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
kotlin {
compilerOptions {
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
}
}
Save the following as settings.gradle.kts:
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}
rootProject.name = "x-asr-kotlin-example"
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/kotlin/XasrOfflineDemo.kt:
// This file shows how to use a non-streaming X-ASR model with sherpa-onnx
// in Kotlin.
//
// Before you run it, please 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
//
// Note: this file has a top-level main function, so the generated main
// class is XasrOfflineDemoKt (the file name plus the suffix Kt).
import com.k2fsa.sherpa.onnx.*
fun main() {
val modelDir = "./sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03"
// Step 1: Create the recognizer from the X-ASR model files.
val transducer = OfflineTransducerModelConfig.builder()
.setEncoder("$modelDir/encoder-epoch-99-avg-1.int8.onnx")
.setDecoder("$modelDir/decoder-epoch-99-avg-1.onnx")
.setJoiner("$modelDir/joiner-epoch-99-avg-1.int8.onnx")
.build()
val modelConfig = OfflineModelConfig.builder()
.setTransducer(transducer)
.setTokens("$modelDir/tokens.txt")
.setNumThreads(2)
.setDebug(false)
.build()
val config = OfflineRecognizerConfig.builder()
.setOfflineModelConfig(modelConfig)
.setDecodingMethod("greedy_search")
.build()
val recognizer = OfflineRecognizer(config)
// Step 2: Read the wave file you want to transcribe.
val filename = "$modelDir/test_wavs/0.wav"
val reader = WaveReader(filename)
// Step 3: Create a stream, send the whole audio to it, and decode.
val start = System.nanoTime()
val stream = recognizer.createStream()
stream.acceptWaveform(reader.getSamples(), reader.getSampleRate())
recognizer.decode(stream)
val elapsed = (System.nanoTime() - start) / 1e9
// Step 4: Print the result. X-ASR punct models also add punctuations.
println(filename)
println(recognizer.getResult(stream).getText())
val audioDuration = reader.getSamples().size.toDouble() / reader.getSampleRate()
println(String.format("audio duration: %.3f s", audioDuration))
println(String.format("elapsed seconds: %.3f s", elapsed))
println(String.format("RTF = %.3f/%.3f = %.3f", elapsed, audioDuration, elapsed / audioDuration))
stream.release()
recognizer.release()
}
Step 5. Check the project layout
Your project directory should now look like this:
$ tree .
.
├── build.gradle.kts
├── pom.xml
├── settings.gradle.kts
├── 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
└── kotlin
└── XasrOfflineDemo.kt
6 directories, 15 files
$ ls -lh
total 24
-rw-r--r--@ 1 fangjun wheel 548B 19 Nov 12:23 build.gradle.kts
-rw-r--r--@ 1 fangjun wheel 3.1K 19 Nov 12:23 pom.xml
-rw-r--r--@ 1 fangjun wheel 141B 19 Nov 12:23 settings.gradle.kts
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:
# Maven
mvn -q package
java -jar target/x-asr-kotlin-example-1.0.jar
# or Gradle KTS
gradle wrapper
./gradlew run
Output
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by com.k2fsa.sherpa.onnx.LibraryUtils in an unnamed module (file:/private/tmp/java-doc-work/test-kt-maven/target/x-asr-kotlin-example-1.0.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled
./sherpa-onnx-x-asr-zipformer-transducer-zh-en-punct-int8-2026-06-03/test_wavs/0.wav
昨天是 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 files
If you use Maven, create pom.xml. If you use Gradle (Kotlin DSL), create build.gradle.kts and settings.gradle.kts.
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>x-asr-kotlin-example</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
<properties>
<kotlin.version>2.2.20</kotlin.version>
<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>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-stdlib</artifactId>
<version>${kotlin.version}</version>
</dependency>
<dependency>
<groupId>com.github.k2-fsa</groupId>
<artifactId>sherpa-onnx</artifactId>
<version>${sherpa-onnx.version}</version>
</dependency>
</dependencies>
<build>
<sourceDirectory>${project.basedir}/src/main/kotlin</sourceDirectory>
<plugins>
<plugin>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-plugin</artifactId>
<version>${kotlin.version}</version>
<executions>
<execution>
<id>compile</id>
<phase>compile</phase>
<goals>
<goal>compile</goal>
</goals>
</execution>
</executions>
<configuration>
<jvmTarget>11</jvmTarget>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-jar-plugin</artifactId>
<version>3.3.0</version>
<configuration>
<archive>
<manifest>
<mainClass>XasrStreamingDemoKt</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>
Save the following as build.gradle.kts:
plugins {
kotlin("jvm") version "2.2.20"
application
}
application {
mainClass.set("XasrStreamingDemoKt")
}
repositories {
mavenCentral()
// sherpa-onnx packages are hosted on JitPack
maven { url = uri("https://jitpack.io") }
}
dependencies {
implementation("com.github.k2-fsa:sherpa-onnx:v2.0.1")
}
java {
sourceCompatibility = JavaVersion.VERSION_11
targetCompatibility = JavaVersion.VERSION_11
}
kotlin {
compilerOptions {
jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_11)
}
}
Save the following as settings.gradle.kts:
pluginManagement {
repositories {
mavenCentral()
gradlePluginPortal()
}
}
rootProject.name = "x-asr-kotlin-example"
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/kotlin/XasrStreamingDemo.kt:
// This file shows how to use a streaming X-ASR model with sherpa-onnx
// in Kotlin.
//
// Before you run it, please 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
//
// Note: this file has a top-level main function, so the generated main
// class is XasrStreamingDemoKt (the file name plus the suffix Kt).
import com.k2fsa.sherpa.onnx.*
fun main() {
val modelDir =
"./sherpa-onnx-x-asr-480ms-streaming-zipformer-transducer-zh-en-punct-int8-2026-06-05"
// Step 1: Create the recognizer from the X-ASR model files.
val transducer = OnlineTransducerModelConfig.builder()
.setEncoder("$modelDir/encoder.int8.onnx")
.setDecoder("$modelDir/decoder.onnx")
.setJoiner("$modelDir/joiner.int8.onnx")
.build()
val modelConfig = OnlineModelConfig.builder()
.setTransducer(transducer)
.setTokens("$modelDir/tokens.txt")
.setNumThreads(2)
.setDebug(false)
.build()
val config = OnlineRecognizerConfig.builder()
.setOnlineModelConfig(modelConfig)
.setDecodingMethod("greedy_search")
.build()
val recognizer = OnlineRecognizer(config)
// Step 2: Read the wave file you want to transcribe.
val filename = "$modelDir/test_wavs/0.wav"
val reader = WaveReader(filename)
val samples = reader.getSamples()
val sampleRate = reader.getSampleRate()
// Step 3: Create a stream and feed the audio in small chunks, just like
// a microphone would do in a real-time application.
val start = System.nanoTime()
val stream = recognizer.createStream()
// 0.2 second for 16 kHz audio
val chunk = 3200
var last = ""
var i = 0
while (i < samples.size) {
val end = minOf(i + chunk, samples.size)
stream.acceptWaveform(samples.copyOfRange(i, end), sampleRate)
while (recognizer.isReady(stream)) {
recognizer.decode(stream)
}
// Print the latest partial result when it changes.
val text = recognizer.getResult(stream).getText()
if (text.isNotEmpty() && text != last) {
last = text
println(text)
}
i += chunk
}
// Send some tail padding so the last words are flushed out.
stream.acceptWaveform(FloatArray((0.5 * sampleRate).toInt()), sampleRate)
while (recognizer.isReady(stream)) {
recognizer.decode(stream)
}
// Step 4: Print the final result.
val elapsed = (System.nanoTime() - start) / 1e9
println("Final result: " + recognizer.getResult(stream).getText())
val audioDuration = samples.size.toDouble() / sampleRate
println(String.format("audio duration: %.3f s", audioDuration))
println(String.format("elapsed seconds: %.3f s", elapsed))
println(String.format("RTF = %.3f/%.3f = %.3f", elapsed, audioDuration, elapsed / audioDuration))
stream.release()
recognizer.release()
}
Step 5. Check the project layout
Your project directory should now look like this:
$ tree .
.
├── build.gradle.kts
├── pom.xml
├── settings.gradle.kts
├── 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
└── kotlin
└── XasrStreamingDemo.kt
6 directories, 15 files
$ ls -lh
total 24
-rw-r--r--@ 1 fangjun wheel 550B 19 Nov 12:23 build.gradle.kts
-rw-r--r--@ 1 fangjun wheel 3.1K 19 Nov 12:23 pom.xml
-rw-r--r--@ 1 fangjun wheel 141B 19 Nov 12:23 settings.gradle.kts
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:
# Maven
mvn -q package
java -jar target/x-asr-kotlin-example-1.0.jar
# or Gradle KTS
gradle wrapper
./gradlew run
Output
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::load has been called by com.k2fsa.sherpa.onnx.LibraryUtils in an unnamed module (file:/private/tmp/java-doc-work/test-kt-maven-st/target/x-asr-kotlin-example-1.0.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled
昨
昨天是
昨天是 Mon
昨天是 Monday
昨天是 Monday,
昨天是 Monday, today
昨天是 Monday, today is 礼
昨天是 Monday, today is 礼拜二
昨天是 Monday, today is 礼拜二,
昨天是 Monday, today is 礼拜二, the day
昨天是 Monday, today is 礼拜二, the day after
昨天是 Monday, today is 礼拜二, the day after tomorro
昨天是 Monday, today is 礼拜二, the day after tomorrow
昨天是 Monday, today is 礼拜二, the day after tomorrow 是
Final result: 昨天是 Monday, today is 礼拜二, the day after tomorrow 是星期
audio duration: 10.053 s
elapsed seconds: 0.314 s
RTF = 0.314/10.053 = 0.031
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
A Kotlin file with a top-level main function is compiled to a class named after the file plus the suffix Kt, e.g., XasrOfflineDemo.kt -> XasrOfflineDemoKt. This is why the main class in the build files above ends with Kt.