Skip to main content
SDK access

Java SDK

This topic describes the key interfaces and request parameters for calling Qwen-TTS-Realtime models with the DashScope Java SDK.

Supported regions: Singapore and China North 2 (Beijing). Use an API key and endpoint from the region you call; see Regions and endpoints.

Prerequisites

Requires DashScope Java SDK 2.22.7 or later.

Getting started

  • Server commit mode
  • Commit mode
appendText()
import com.alibaba.dashscope.audio.qwen_tts_realtime.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import javax.sound.sampled.LineUnavailableException;
import javax.sound.sampled.SourceDataLine;
import javax.sound.sampled.AudioFormat;
import javax.sound.sampled.DataLine;
import javax.sound.sampled.AudioSystem;
import java.io.*;
import java.util.Base64;
import java.util.Queue;
import java.util.concurrent.CountDownLatch;
import java.util.concurrent.atomic.AtomicReference;
import java.util.concurrent.ConcurrentLinkedQueue;
import java.util.concurrent.atomic.AtomicBoolean;

public class Main {
    static String[] textToSynthesize = {
            "Right? I really love this kind of supermarket.",
            "Especially during the Chinese New Year.",
            "Going to the supermarket.",
            "It just makes me feel.",
            "Super, super happy!",
            "I want to buy so many things!"
    };
    public static QwenTtsRealtimeAudioFormat ttsFormat = QwenTtsRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT;

    // Real-time PCM audio player
    public static class RealtimePcmPlayer {
        private int sampleRate;
        private SourceDataLine line;
        private AudioFormat audioFormat;
        private Thread decoderThread;
        private Thread playerThread;
        private AtomicBoolean stopped = new AtomicBoolean(false);
        private Queue<String> b64AudioBuffer = new ConcurrentLinkedQueue<>();
        private Queue<byte[]> RawAudioBuffer = new ConcurrentLinkedQueue<>();
        private ByteArrayOutputStream totalAudioStream = new ByteArrayOutputStream();

        // Initialize the audio format and audio line.
        public RealtimePcmPlayer(int sampleRate) throws LineUnavailableException {
            this.sampleRate = sampleRate;
            this.audioFormat = new AudioFormat(this.sampleRate, 16, 1, true, false);
            DataLine.Info info = new DataLine.Info(SourceDataLine.class, audioFormat);
            line = (SourceDataLine) AudioSystem.getLine(info);
            line.open(audioFormat);
            line.start();
            decoderThread = new Thread(new Runnable() {
                @Override
                public void run() {
                    while (!stopped.get()) {
                        String b64Audio = b64AudioBuffer.poll();
                        if (b64Audio != null) {
                            byte[] rawAudio = Base64.getDecoder().decode(b64Audio);
                            RawAudioBuffer.add(rawAudio);
                            // Write audio data to totalAudioStream.
                            try {
                                totalAudioStream.write(rawAudio);
                            } catch (IOException e) {
                                throw new RuntimeException(e);
                            }
                        } else {
                            try {
                                Thread.sleep(100);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        }
                    }
                }
            });
            playerThread = new Thread(new Runnable() {
                @Override
                public void run() {
                    while (!stopped.get()) {
                        byte[] rawAudio = RawAudioBuffer.poll();
                        if (rawAudio != null) {
                            try {
                                playChunk(rawAudio);
                            } catch (IOException e) {
                                throw new RuntimeException(e);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        } else {
                            try {
                                Thread.sleep(100);
                            } catch (InterruptedException e) {
                                throw new RuntimeException(e);
                            }
                        }
                    }
                }
            });
            decoderThread.start();
            playerThread.start();
        }

        // Play an audio chunk and block until playback completes.
        private void playChunk(byte[] chunk) throws IOException, InterruptedException {
            if (chunk == null || chunk.length == 0) return;

            int bytesWritten = 0;
            while (bytesWritten < chunk.length) {
                bytesWritten += line.write(chunk, bytesWritten, chunk.length - bytesWritten);
            }
            int audioLength = chunk.length / (this.sampleRate*2/1000);
            // Wait for the buffered audio to finish playing.
            Thread.sleep(audioLength - 10);
        }

        public void write(String b64Audio) {
            b64AudioBuffer.add(b64Audio);
        }

        public void cancel() {
            b64AudioBuffer.clear();
            RawAudioBuffer.clear();
        }

        public void waitForComplete() throws InterruptedException {
            while (!b64AudioBuffer.isEmpty() || !RawAudioBuffer.isEmpty()) {
                Thread.sleep(100);
            }
            line.drain();
        }

        public void shutdown() throws InterruptedException, IOException {
            stopped.set(true);
            decoderThread.join();
            playerThread.join();

            // Save the complete audio file.
            File file = new File("TotalAudio_"+ttsFormat.getSampleRate()+"."+ttsFormat.getFormat());
            try (FileOutputStream fos = new FileOutputStream(file)) {
                fos.write(totalAudioStream.toByteArray());
            }

            if (line != null && line.isRunning()) {
                line.drain();
                line.close();
            }
        }
    }

    public static void main(String[] args) throws InterruptedException, LineUnavailableException, IOException {
        QwenTtsRealtimeParam param = QwenTtsRealtimeParam.builder()
                .model("qwen3-tts-flash-realtime")
                // Singapore (ap-southeast-1). For another region, replace ap-southeast-1 in the URL.
                // API keys are region-specific. See https://docs.qwencloud.com/developer-guides/getting-started/regions
                .url("wss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime")
                .apikey(System.getenv("DASHSCOPE_API_KEY"))
                .build();
        AtomicReference<CountDownLatch> completeLatch = new AtomicReference<>(new CountDownLatch(1));
        final AtomicReference<QwenTtsRealtime> qwenTtsRef = new AtomicReference<>(null);

        // Create a real-time audio player instance.
        RealtimePcmPlayer audioPlayer = new RealtimePcmPlayer(24000);

        QwenTtsRealtime qwenTtsRealtime = new QwenTtsRealtime(param, new QwenTtsRealtimeCallback() {
            @Override
            public void onOpen() {
                // Handle connection establishment.
            }
            @Override
            public void onEvent(JsonObject message) {
                String type = message.get("type").getAsString();
                switch(type) {
                    case "session.created":
                        // Handle session creation.
                        if (message.has("session")) {
                            String eventId = message.get("event_id").getAsString();
                            String sessionId = message.get("session").getAsJsonObject().get("id").getAsString();
                            System.out.println("[onEvent] session.created, session_id: "
                                    + sessionId + ", event_id: " + eventId);
                        }
                        break;
                    case "response.audio.delta":
                        String recvAudioB64 = message.get("delta").getAsString();
                        // Play audio in real time.
                        audioPlayer.write(recvAudioB64);
                        break;
                    case "response.done":
                        // Handle response completion.
                        break;
                    case "session.finished":
                        // Handle session termination.
                        completeLatch.get().countDown();
                    default:
                        break;
                }
            }
            @Override
            public void onClose(int code, String reason) {
                // Handle connection closure.
            }
        });
        qwenTtsRef.set(qwenTtsRealtime);
        try {
            qwenTtsRealtime.connect();
        } catch (NoApiKeyException e) {
            throw new RuntimeException(e);
        }
        QwenTtsRealtimeConfig config = QwenTtsRealtimeConfig.builder()
                .voice("Cherry")
                .responseFormat(ttsFormat)
                .mode("server_commit")
                .build();
        qwenTtsRealtime.updateSession(config);
        for (String text:textToSynthesize) {
            qwenTtsRealtime.appendText(text);
            Thread.sleep(100);
        }
        qwenTtsRealtime.finish();
        completeLatch.get().await();
        qwenTtsRealtime.close();

        // Wait for audio playback to complete, then shut down the player.
        audioPlayer.waitForComplete();
        audioPlayer.shutdown();
        System.exit(0);
    }
}
For more samples, see the GitHub repository.

Request parameters

Configure the following request parameters with the chaining methods or setters of a QwenTtsRealtimeParam object, then pass the object to the QwenTtsRealtime constructor.
ParameterTypeRequiredDescription
modelStringYesModel name (see Supported models).
urlStringYeswss://ap-southeast-1.maas.qwencloudapi.com/api-ws/v1/realtime (Singapore). For another region, replace ap-southeast-1 in the URL. See Regions.
Configure the following request parameters with the chaining methods or setters of a QwenTtsRealtimeConfig object, then pass the object to the updateSession method.
ParameterTypeRequiredDescription
voiceStringYesThe voice for speech synthesis. For more information, see Supported voices.
System voices and custom voices are supported:
  • System voices: Available only for the Qwen3-TTS-Instruct-Flash-Realtime and Qwen3-TTS-Flash-Realtime model series. For voice samples, see Supported voices.
  • Custom voices
    • Voices customized by the Voice Cloning (Qwen) feature: Available only for the Qwen3-TTS-VC-Realtime model series.
    • Voices customized by the Voice Design (Qwen) feature: Available only for the Qwen3-TTS-VD-Realtime model series.
languageTypeStringNoSpecifies the language of the synthesized audio. The default value is Auto.
  • Auto: Use this value when the language of the text is uncertain or contains multiple languages. The model automatically matches the pronunciation for different language segments in the text, but cannot guarantee perfect accuracy.
  • Specific language: Use this for single-language text. Specifying a language significantly improves synthesis quality and typically yields better results than Auto. Valid values include the following:
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian
modeStringNoThe interaction mode. Valid values:
  • server_commit (default): The server automatically determines when to synthesize speech, balancing latency and quality. This mode is recommended for most scenarios.
  • commit: The client manually triggers synthesis. This mode has the lowest latency, but you must manage sentence integrity yourself.
formatStringNoThe format of the audio output from the model.
Supported formats:
  • pcm (default)
  • wav
  • mp3
  • opus
sampleRateintNoThe sample rate of the audio output from the model, in Hz.
Supported sample rates:
  • 8000
  • 16000
  • 24000 (default)
  • 48000
speechRatefloatNoThe speech rate of the audio. A value of 1.0 is the normal speed. A value less than 1.0 is slower, and a value greater than 1.0 is faster.
Default value: 1.0.
Valid range: [0.5, 2.0].
volumeintNoThe volume of the audio.
Valid range: [0, 100].
pitchRatefloatNoThe pitch of the synthesized audio.
Default value: 1.0.
Valid range: [0.5, 2.0].
bitRateintNoSpecifies the bitrate of the audio in kbps. A higher bitrate results in better audio quality and a larger file size. This parameter is available only when the audio format (response_format) is set to opus.
Default value: 128.
Valid range: [6, 510].

Key interfaces

QwenTtsRealtime class

To import:
import com.alibaba.dashscope.audio.qwen_tts_realtime.QwenTtsRealtime;
MethodSignatureServer eventsDescription
connectSee Example 1 belowsession.created > Session created session.updated > Session configuration updatedOpens a WebSocket connection to the server.
updateSessionSee Example 2 belowsession.updated > Session configuration updatedUpdates the session configuration. See Request parameters. After connecting, the server returns default input and output configurations for the session. Call this method immediately after connect() to override defaults. The server validates parameters upon receiving a session.update event. If any parameter is invalid, the server returns an error. Otherwise, it updates the session configuration on the server side.
appendTextSee Example 3 belowNoneAppends a text segment to the server-side input buffer. The buffer stores text until you submit it.
  • In server_commit mode, the server decides when to commit and synthesize buffered text.
  • In commit mode, the client must trigger synthesis by calling commit.
clearAppendedTextSee Example 4 belowinput_text_buffer.cleared > Clears text received by the serverClears all text in the server-side input buffer.
commitSee Example 5 belowinput_text_buffer.committed > Commits text and triggers speech synthesis response.output_item.added > New output content appears in the response response.content_part.added > New output content added to the assistant message item response.audio.delta > Model generates audio incrementally response.audio.done > Audio generation completed response.content_part.done > Streaming of audio content for the assistant message is complete response.output_item.done > Streaming of the entire output item for the assistant message is complete response.done > Response completedCommits text previously appended to the server-side buffer and synthesizes all text immediately. Returns an error if the buffer is empty.
  • In server_commit mode, the client does not need to call this method. The server commits automatically.
  • In commit mode, the client must call commit to trigger synthesis.
finishSee Example 6 belowsession.finished > Response completedStops the current task.
closeSee Example 7 belowNoneCloses the connection.
getSessionIdSee Example 8 belowNoneReturns the session ID of the current task.
getResponseIdSee Example 9 belowNoneReturns the response ID of the most recent response.
getFirstAudioDelaySee Example 10 belowNoneReturns the latency of the first audio packet in milliseconds.
Example 1 (Signature):
public void connect() throws NoApiKeyException, InterruptedException
Example 2 (Signature):
public void updateSession(QwenTtsRealtimeConfig config)
Example 3 (Signature):
public void appendText(String text)
Example 4 (Signature):
public void clearAppendedText()
Example 5 (Signature):
public void commit()
Example 6 (Signature):
public void finish()
Example 7 (Signature):
public void close()
Example 8 (Signature):
public String getSessionId()
Example 9 (Signature):
public String getResponseId()
Example 10 (Signature):
public long getFirstAudioDelay()

Callback interface (QwenTtsRealtimeCallback)

MethodParametersReturn valueDescription
See Example 1 belowNoneNoneCalled immediately after the WebSocket connection is established.
See Example 2 belowmessage: server-side response event.NoneCalled when the server sends an event, including API call responses and model-generated audio. See Server-side events.
See Example 3 belowcode: WebSocket close status code. reason: Close reason.NoneCalled after the server closes the connection.
Example 1 (Method):
public void onOpen()
Example 2 (Method):
public abstract void onEvent(JsonObject message)
Example 3 (Method):
public abstract void onClose(int code, String reason)