Skip to main content

Qwen-TTS-Realtime Java SDK

Cette rubrique présente les interfaces principales et les paramètres de requête pour appeler les modèles de la série Qwen-TTS-Realtime avec le SDK DashScope pour Java.

Prérequis

DashScope Java SDK version 2.22.7 ou ultérieure requis.

Démarrage rapide

  • 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")
                // China (Beijing) region
                .url("wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime")
                // API keys differ between Singapore and China (Beijing). See https://www.alibabacloud.com/help/en/model-studio/get-api-key.
                .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);
    }
}
Pour d'autres exemples, consultez le dépôt GitHub.

Paramètres de requête

Configurez les paramètres suivants via les méthodes chaînées ou les setters d'un objet QwenTtsRealtimeParam, puis transmettez cet objet au constructeur QwenTtsRealtime.

Paramètre

Type

Obligatoire

Description

model

String

Oui

Nom du modèle (voir Modèles pris en charge).

url

String

Oui

Chine (Pékin) : wss://dashscope.aliyuncs.com/api-ws/v1/realtime

Singapour : wss://dashscope-intl.aliyuncs.com/api-ws/v1/realtime

Définissez les paramètres suivants via les méthodes chaînées ou les setters d'un objet QwenTtsRealtimeConfig, puis passez cet objet à la méthode updateSession.
ParamètreTypeObligatoireDescription
voiceStringOuiVoix utilisée pour la synthèse vocale. Pour plus d'informations, voir Liste des voix Qwen-TTS.
languageTypeStringNonSpécifie la langue de l'audio synthétisé. La valeur par défaut est Auto.
  • Auto : À utiliser lorsque la langue du texte est incertaine ou mixte. Le modèle adapte automatiquement la prononciation aux différents segments linguistiques, sans toutefois garantir une précision absolue.
  • Langue spécifique : Recommandé pour les textes monolingues. Spécifier une langue améliore considérablement la qualité de la synthèse et donne généralement de meilleurs résultats que le mode Auto. Les valeurs valides sont les suivantes :
    • Chinese
    • English
    • German
    • Italian
    • Portuguese
    • Spanish
    • Japanese
    • Korean
    • French
    • Russian
modeStringNonMode d'interaction. Valeurs valides :
  • server_commit (par défaut) : Le serveur détermine automatiquement le moment opportun pour synthétiser la parole, assurant un équilibre entre latence et qualité. Ce mode convient à la plupart des scénarios.
  • commit : Le client déclenche manuellement la synthèse. Bien qu'il offre la latence la plus faible, ce mode exige que vous gériez vous-même l'intégrité des phrases.
formatStringNonFormat de sortie audio du modèle.Formats pris en charge :
  • pcm (par défaut)
  • wav
  • mp3
  • opus
sampleRateintNonFréquence d'échantillonnage de la sortie audio du modèle, exprimée en Hz.Fréquences d'échantillonnage prises en charge :
  • 8000
  • 16000
  • 24000 (par défaut)
  • 48000
speechRatefloatNonVitesse de lecture de l'audio. Une valeur de 1,0 correspond à la vitesse normale. Une valeur inférieure à 1,0 ralentit la lecture, tandis qu'une valeur supérieure à 1,0 l'accélère.Valeur par défaut : 1,0.Plage valide : [0,5, 2,0].
volumeintNonVolume de l'audio.Plage valide : [0, 100].
pitchRatefloatNonHauteur tonale de l'audio synthétisé.Valeur par défaut : 1,0.Plage valide : [0,5, 2,0].
bitRateintNonDéfinit le débit binaire de l'audio en kbps. Un débit plus élevé améliore la qualité audio mais augmente la taille du fichier. Ce paramètre n'est disponible que si le format audio (response_format) est défini sur opus.Valeur par défaut : 128.Plage valide : [6, 510].

Référence de l’API

Classe QwenTtsRealtime

Importation :
import com.alibaba.dashscope.audio.qwen_tts_realtime.QwenTtsRealtime;
MéthodeSignatureÉvénements serveurDescription
connect
public void connect() throws NoApiKeyException, InterruptedException
session.created
Session créée
session.updated
Configuration de session mise à jour
Ouvre une connexion WebSocket vers le serveur.
updateSession
public void updateSession(QwenTtsRealtimeConfig config)
session.updated
Configuration de session mise à jour
Met à jour la configuration de la session. Voir Paramètres de requête.Après la connexion, le serveur renvoie les configurations d'entrée et de sortie par défaut pour la session. Appelez cette méthode immédiatement après connect() pour remplacer les valeurs par défaut.Le serveur valide les paramètres lors de la réception d'un événement session.update. Si un paramètre est invalide, le serveur renvoie une erreur. Dans le cas contraire, il met à jour la configuration de la session côté serveur.
appendText
public void appendText(String text)
AucunAjoute un segment de texte au tampon d'entrée côté serveur. Le tampon stocke le texte jusqu'à sa soumission.
  • En mode server_commit, le serveur décide du moment où valider et synthétiser le texte mis en tampon.
  • En mode commit, le client doit déclencher la synthèse en appelant commit.
clearAppendedText
public void clearAppendedText()
input_text_buffer.cleared
Efface le texte reçu par le serveur
Efface tout le texte présent dans le tampon d'entrée côté serveur.
commit
public void commit()
input_text_buffer.committed
Valide le texte et déclenche la synthèse vocale
response.output_item.added
Nouveau contenu de sortie apparu dans la réponse
response.content_part.added
Nouveau contenu de sortie ajouté à l'élément de message de l'assistant
response.audio.delta
Génération incrémentielle de l'audio par le modèle
response.audio.done
Génération audio terminée
response.content_part.done
Flux audio du message de l'assistant terminé
response.output_item.done
Flux complet de l'élément de sortie du message de l'assistant terminé
response.done
Réponse terminée
Valide le texte précédemment ajouté au tampon côté serveur et synthétise immédiatement l'ensemble du texte. Renvoie une erreur si le tampon est vide.
  • En mode server_commit, le client n'a pas besoin d'appeler cette méthode. Le serveur effectue la validation automatiquement.
  • En mode commit, le client doit appeler commit pour déclencher la synthèse.
finish
public void finish()
session.finished
Réponse terminée
Arrête la tâche en cours.
close
public void close()
AucunFerme la connexion.
getSessionId
public String getSessionId()
AucunRenvoie l'ID de session de la tâche en cours.
getResponseId
public String getResponseId()
AucunRenvoie l'ID de la réponse la plus récente.
getFirstAudioDelay
public long getFirstAudioDelay()
AucunRenvoie la latence du premier paquet audio en millisecondes.

Interface de rappel (QwenTtsRealtimeCallback)

MéthodeParamètresValeur de retourDescription
public void onOpen()
AucunAucunAppelé immédiatement après l'établissement de la connexion WebSocket.
public abstract void onEvent(JsonObject message)
message : événement de réponse côté serveur.AucunAppelé lorsque le serveur envoie un événement, y compris les réponses aux appels API et l'audio généré par le modèle. Voir Événements côté serveur.
public abstract void onClose(int code, String reason)
code : code d'état de fermeture WebSocket.reason : motif de fermeture.AucunAppelé après la fermeture de la connexion par le serveur.