SDK Java do LiveTranslate

SDK Java do LiveTranslate

Guia do usuário: Para tutoriais e exemplos completos, consulte Tradução em tempo real.

Antes de começar

1. Instale o SDK do DashScope. Certifique-se de que a versão do SDK do DashScope seja 2.22.5 ou posterior.
2. Obtenha uma chave API.

Visão geral da configuração

Três objetos construtores controlam uma sessão de tradução:

OmniRealtimeParam          --> Connection: model, endpoint, API key
  +-- OmniRealtimeConfig   --> Session: audio formats, voice, modalities
       +-- OmniRealtimeTranslationParam  --> Translation: target language, custom terminology

Passe OmniRealtimeParam para o construtor. Depois de conectar, ligue updateSession() com OmniRealtimeConfig para definir opções de áudio e tradução. Os padrões se aplicam se você pular updateSession().

Início rápido

Conecte-se, envie áudio e receba texto traduzido:

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import java.util.Arrays;

// 1. Build connection parameters
OmniRealtimeParam param = OmniRealtimeParam.builder()
  .model("qwen3.5-livetranslate-flash-realtime")
  .url("wss://maas.qwencloudapi.com/api-ws/v1/realtime")
  .apikey(System.getenv("DASHSCOPE_API_KEY"))
  .build();

// 2. Define a callback to handle server events
OmniRealtimeCallback callback = new OmniRealtimeCallback() {
  @Override public void onOpen() { System.out.println("Connected"); }
  @Override
  public void onEvent(JsonObject message) {
    String type = message.get("type").getAsString();
    if ("response.audio_transcript.done".equals(type)) {
      System.out.println("Translation: " + message.get("transcript").getAsString());
    }
  }
  @Override
  public void onClose(int code, String reason) {
    System.out.println("Closed: " + code + " " + reason);
  }
};

// 3. Open a session and start streaming audio
OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);
conversation.connect();

// 4. Configure translation target language
OmniRealtimeConfig config = OmniRealtimeConfig.builder()
  .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
  .translationConfig(OmniRealtimeTranslationParam.builder()
    .language("en")
    .build())
  .build();
conversation.updateSession(config);

// 5. Send Base64-encoded audio chunks (PCM 16 kHz, 16-bit, mono)
conversation.appendAudio(audioBase64);

// 6. End the session when done
conversation.endSession();

Parâmetros de solicitação

OmniRealtimeParam

Crie parâmetros de conexão com OmniRealtimeParam.builder().

Código de amostra.

OmniRealtimeParam param = OmniRealtimeParam.builder()
  .model("qwen3.5-livetranslate-flash-realtime")
  .url("wss://maas.qwencloudapi.com/api-ws/v1/realtime")
  // If no environment variable is set, replace the next line with your API key: .apikey("YOUR_API_KEY")
  .apikey(System.getenv("DASHSCOPE_API_KEY"))
  .build();

OmniRealtimeConfig

Crie parâmetros de sessão com OmniRealtimeConfig.builder(), então ligue conversation.updateSession(config).

Código de amostra.

// Set custom translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeConfig config = OmniRealtimeConfig.builder()
  .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
  .voice("Tina")
  .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
  .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
  .InputAudioTranscription("qwen3-asr-flash-realtime")
  .translationConfig(OmniRealtimeTranslationParam.builder()
    .language("en")
    .corpus(OmniRealtimeTranslationParam.Corpus.builder()
      .phrases(phrases)
      .build())
    .build())
  .build();

conversation.updateSession(config);

OmniRealtimeTranslationParam

Crie parâmetros de tradução com OmniRealtimeTranslationParam.builder().

Código de amostra.

// Set translation phrases
Map<String, Object> phrases = new HashMap<>();
phrases.put("Inteligencia Artificial", "Artificial Intelligence");  // Source language word: Target language translation
phrases.put("Aprendizaje Automático", "Machine Learning");

OmniRealtimeTranslationParam translationParam = OmniRealtimeTranslationParam.builder()
  .language("en")  // Target language code
  .corpus(OmniRealtimeTranslationParam.Corpus.builder()
    .phrases(phrases)
    .build())
  .build();

Interfaces principais

OmniRealtimeConversation

Gerencia a conexão WebSocket e o streaming de áudio.

Importar: com.alibaba.dashscope.audio.omni.OmniRealtimeConversation

OmniRealtimeCallback

Lida com eventos do servidor via WebSocket. Estenda esta classe e implemente cada método.

Importar: com.alibaba.dashscope.audio.omni.OmniRealtimeCallback

Tipos de eventos comuns em onEvent:

Exemplo completo

Este exemplo grava o áudio do microfone e o traduz em tempo real.

Exemplo de código para tradução em tempo real a partir do microfone

import com.alibaba.dashscope.audio.omni.*;
import com.alibaba.dashscope.exception.NoApiKeyException;
import com.google.gson.JsonObject;
import javax.sound.sampled.*;
import java.util.*;
import java.util.concurrent.atomic.AtomicBoolean;

public class Main {
  private static final int INPUT_CHUNK_SIZE = 3200;
  private static final int OUTPUT_CHUNK_SIZE = 4800;
  private static final AtomicBoolean running = new AtomicBoolean(true);
  private static SourceDataLine speaker;

  public static void main(String[] args) throws InterruptedException {
    String apiKey = System.getenv("DASHSCOPE_API_KEY");
    if (apiKey == null || apiKey.isEmpty()) {
      System.err.println("Set the DASHSCOPE_API_KEY environment variable.");
      System.exit(1);
    }

    OmniRealtimeParam param = OmniRealtimeParam.builder()
      .model("qwen3.5-livetranslate-flash-realtime")
      .url("wss://maas.qwencloudapi.com/api-ws/v1/realtime")
      .apikey(apiKey)
      .build();

    OmniRealtimeCallback callback = new OmniRealtimeCallback() {
      @Override
      public void onOpen() {
        System.out.println("[Connection established]");
      }

      @Override
      public void onEvent(JsonObject message) {
        String type = message.get("type").getAsString();
        switch (type) {
          case "input_audio_buffer.speech_started":
            System.out.println("====== Speech input detected ======");
            break;
          case "input_audio_buffer.speech_stopped":
            System.out.println("====== Speech input ended ======");
            break;
          case "conversation.item.input_audio_transcription.completed":
            String originalText = message.get("transcript").getAsString();
            System.out.println("[Original text] " + originalText);
            break;
          case "response.audio_transcript.done":
            String translatedText = message.get("transcript").getAsString();
            System.out.println("[Translation result] " + translatedText);
            break;
          case "response.audio.delta":
            String audioB64 = message.get("delta").getAsString();
            byte[] audioBytes = Base64.getDecoder().decode(audioB64);
            if (speaker != null) {
              speaker.write(audioBytes, 0, audioBytes.length);
            }
            break;
          case "error":
            JsonObject error = message.get("error").getAsJsonObject();
            System.err.println("[Error] " + error.get("message").getAsString());
            break;
        }
      }

      @Override
      public void onClose(int code, String reason) {
        System.out.println("[Connection closed] code: " + code + ", reason: " + reason);
      }
    };

    OmniRealtimeConversation conversation = new OmniRealtimeConversation(param, callback);

    try {
      AudioFormat speakerFormat = new AudioFormat(24000, 16, 1, true, false);
      DataLine.Info speakerInfo = new DataLine.Info(SourceDataLine.class, speakerFormat);
      speaker = (SourceDataLine) AudioSystem.getLine(speakerInfo);
      speaker.open(speakerFormat, OUTPUT_CHUNK_SIZE * 4);
      speaker.start();

      AudioFormat micFormat = new AudioFormat(16000, 16, 1, true, false);
      DataLine.Info micInfo = new DataLine.Info(TargetDataLine.class, micFormat);
      if (!AudioSystem.isLineSupported(micInfo)) {
        System.err.println("Microphone is not available.");
        System.exit(1);
      }
      TargetDataLine microphone = (TargetDataLine) AudioSystem.getLine(micInfo);
      microphone.open(micFormat);
      microphone.start();

      conversation.connect();

      Map<String, Object> phrases = new HashMap<>();
      phrases.put("Inteligencia Artificial", "Artificial Intelligence");
      phrases.put("Aprendizaje Automático", "Machine Learning");

      OmniRealtimeConfig config = OmniRealtimeConfig.builder()
        .modalities(Arrays.asList(OmniRealtimeModality.AUDIO, OmniRealtimeModality.TEXT))
        .voice("Cherry")
        .inputAudioFormat(OmniRealtimeAudioFormat.PCM_16000HZ_MONO_16BIT)
        .outputAudioFormat(OmniRealtimeAudioFormat.PCM_24000HZ_MONO_16BIT)
        .InputAudioTranscription("qwen3-asr-flash-realtime")
        .translationConfig(OmniRealtimeTranslationParam.builder()
          .language("en")
          .corpus(OmniRealtimeTranslationParam.Corpus.builder()
            .phrases(phrases)
            .build())
          .build())
        .build();

      conversation.updateSession(config);

      Runtime.getRuntime().addShutdownHook(new Thread(() -> {
        System.out.println("\n[Exiting...]");
        running.set(false);
        microphone.stop();
        microphone.close();
        speaker.stop();
        speaker.close();
        try {
          conversation.endSession();
        } catch (InterruptedException e) {
          Thread.currentThread().interrupt();
        }
        conversation.close(1000, "User stopped");
      }));

      System.out.println("[Starting real-time translation] Speak into the microphone. Press Ctrl+C to exit.");

      byte[] buffer = new byte[INPUT_CHUNK_SIZE];
      while (running.get()) {
        int bytesRead = microphone.read(buffer, 0, buffer.length);
        if (bytesRead > 0) {
          conversation.appendAudio(Base64.getEncoder().encodeToString(buffer));
        }
      }
    } catch (NoApiKeyException e) {
      System.err.println("API Key error: " + e.getMessage());
    } catch (Exception e) {
      System.err.println("An exception occurred: " + e.getMessage());
      e.printStackTrace();
    }
  }
}

Referências

• Qwen-LiveTranslate visão geral do modelo – Idiomas, vozes e recursos suportados
• Eventos do cliente -- Tipos e parâmetros de eventos do cliente
• Referência de eventos do servidor -- Tipos de eventos, esquemas JSON e códigos de erro
• Instale o SDK do DashScope - Instalação e configuração de dependências
• Obtenha uma chave de API - Criação e gerenciamento de chave de API