​
Overview

By the end of this tutorial, you’ll be able to transcribe audio from your microphone in Java.
Streaming Speech-to-Text is only available for English. See Supported languages.

​
Before you begin

To complete this tutorial, you need: Here’s the full sample code for what you’ll build in this tutorial: 
import com.assemblyai.api.RealtimeTranscriber;

import javax.sound.sampled.*;
import java.io.IOException;

import static java.lang.Thread.interrupted;

public final class App {

    public static void main(String... args) throws IOException {
        Thread thread = new Thread(() -> {
            try {
                RealtimeTranscriber realtimeTranscriber = RealtimeTranscriber.builder()
                        .apiKey("YOUR_API_KEY")
                        .sampleRate(16_000)
                        .onSessionBegins(sessionBegins -> System.out.println(
                                "Session opened with ID: " + sessionBegins.getSessionId()))
                        .onPartialTranscript(transcript -> {
                            if (!transcript.getText().isEmpty())
                                System.out.println("Partial: " + transcript.getText());
                        })
                        .onFinalTranscript(transcript -> System.out.println("Final: " + transcript.getText()))
                        .onError(err -> System.out.println("Error: " + err.getMessage()))
                        .build();

                System.out.println("Connecting to real-time transcript service");
                realtimeTranscriber.connect();

                System.out.println("Starting recording");
                AudioFormat format = new AudioFormat(16_000, 16, 1, true, false);
                // `line` is your microphone
                TargetDataLine line = AudioSystem.getTargetDataLine(format);
                line.open(format);
                byte[] data = new byte[line.getBufferSize()];
                line.start();
                while (!interrupted()) {
                    // Read the next chunk of data from the TargetDataLine.
                    line.read(data, 0, data.length);
                    realtimeTranscriber.sendAudio(data);
                }

                System.out.println("Stopping recording");
                line.close();

                System.out.println("Closing real-time transcript connection");
                realtimeTranscriber.close();
            } catch (LineUnavailableException e) {
                throw new RuntimeException(e);
            }
        });
        thread.start();

        System.out.println("Press ENTER key to stop...");
        System.in.read();
        thread.interrupt();
        System.exit(0);
    }
}

​
Step 1: Install the SDK

Include the latest version of AssemblyAI’s Java SDK in your project dependencies: 
<dependency>
    <groupId>com.assemblyai</groupId>
    <artifactId>assemblyai-java</artifactId>
    <version>ASSEMBLYAI_SDK_VERSION</version>
</dependency>

​
Step 2: Create a real-time transcriber

In this step, you’ll create a real-time transcriber and configure it to use your API key.
1

Browse to Account, and then click the text under Your API key to copy it.
2

Use the builder to create a new real-time transcriber with your API key, a sample rate of 16 kHz, and lambdas to log the different events. Replace YOUR_API_KEY with your copied API key.
import com.assemblyai.api.RealtimeTranscriber;

RealtimeTranscriber realtimeTranscriber = RealtimeTranscriber.builder()
     .apiKey("YOUR_API_KEY")
     .sampleRate(16_000)
     .onSessionBegins(sessionBegins -> System.out.println(
             "Session opened with ID: " + sessionBegins.getSessionId()))
     .onPartialTranscript(transcript -> {
         if (!transcript.getText().isEmpty())
             System.out.println("Partial: " + transcript.getText());
     })
     .onFinalTranscript(transcript -> System.out.println("Final: " + transcript.getText()))
     .onError(err -> System.out.println("Error: " + err.getMessage()))
     .build();
The real-time transcriber returns two types of transcripts: partial and final.
  • Partial transcripts are returned as the audio is being streamed to AssemblyAI.
  • Final transcripts are returned when the service detects a pause in speech.
You can configure the silence threshold for automatic utterance detection and programmatically force the end of an utterance to immediately get a Final transcript.
The sample_rate is the number of audio samples per second, measured in hertz (Hz). Higher sample rates result in higher quality audio, which may lead to better transcripts, but also more data being sent over the network.We recommend the following sample rates:
  • Minimum quality: 8_000 (8 kHz)
  • Medium quality: 16_000 (16 kHz)
  • Maximum quality: 48_000 (48 kHz)
If you don’t set a sample rate on the real-time transcriber, it defaults to 16 kHz.

​
Step 3: Connect the streaming service

Connect to the streaming service so you can send audio to it. 
System.out.println("Connecting to real-time transcript service");realtimeTranscriber.connect();

​
Step 4: Record audio from microphone

In this step, you’ll use Java’s built-in APIs for recording audio.
1

Create the audio format that the real-time service expects, which is single channel, pcm_s16le (PCM signed 16-bit little-endian) encoded, with a sample rate of 16_000. The sample rate needs to be the same value as you configured on the real-time transcriber.
import javax.sound.sampled.*;

System.out.println("Starting recording");
AudioFormat format = new AudioFormat(16_000.0f, 16, 1, true, false);
By default, transcriptions expect PCM16-encoded audio. If you want to use mu-law encoding, see Specifying the encoding.
2

Get the microphone and open it.
// `line` is your microphone
TargetDataLine line = AudioSystem.getTargetDataLine(format);
line.open(format);
3

Read the audio data into a byte array and send it to the real-time transcriber.
import static java.lang.Thread.interrupted;

byte[] data = new byte[line.getBufferSize()];
line.start();
while (!interrupted()) {
 // Read the next chunk of data from the TargetDataLine.
 line.read(data, 0, data.length);
 realtimeTranscriber.sendAudio(data);
}
The interrupted() method returns true when the current thread is interrupted. In this example, you will use it to stop the transcriber and recording when the user presses the ENTER key.

​
Step 5: Disconnect the real-time service

When you are done, close the transcriber. 
System.out.println("Stopping recording");
line.close();

System.out.println("Closing real-time transcript connection");
realtimeTranscriber.close();

​
Step 6: Run the code in a thread

To be able to listen for user input while the recording is happening, you need to run the code in a separate thread. When the user hits enter, interrupt the thread and exit the program. 
Thread thread = new Thread(() -> {
    try {
      // Your existing code here
    } catch (LineUnavailableException e) {
        throw new RuntimeException(e);
    }
});
thread.start();

System.out.println("Press ENTER key to stop...");
System.in.read();
thread.interrupt();
System.exit(0);

​
Next steps

To learn more about Streaming Speech-to-Text, see the following resources:

​
Need some help?

If you get stuck, or have any other questions, we’d love to help you out. Ask our support team in our Discord server.