Qwen-Audio-TTS/CosyVoice SDK HarmonyOS

Aprenda sobre a integração, parâmetros, APIs, retornos de chamada e código de exemplo do HarmonyOS SDK para Qwen-Audio-TTS/CosyVoice síntese de fala em tempo real.

Para visões gerais de modelos e seleção de voz, consulte Modelos de conversão de texto em fala.

NativeNui

O HarmonyOS SDK fornece streaming de texto para fala por meio de NativeNui.

• Crie uma instância de streaming de texto para fala ligando para new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS). NativeNui.GetInstance() retorna um MODE_DIALOG singleton e não pode ser usado para streaming de texto para fala.
• Não ligue initialize() no modo de streaming de texto para fala. Passe credenciais e parâmetros de síntese diretamente para startStreamInputTts(), playStreamInputTts(), ou asyncPlayStreamInputTts().
• Receba eventos de síntese e áudio através INativeStreamInputTtsCallback.
• O SDK retorna STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED quando a tarefa é iniciada, o áudio passa onStreamInputTtsDataCallback, STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE quando a tarefa terminar, e STREAM_INPUT_TTS_EVENT_TASK_FAILED quando a síntese falha.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);

Fluxos de chamadas

Qwen-Audio-TTS/CosyVoice suporta entrada única e entrada de streaming.

A entrada única é adequada para textos curtos ou cenários que exigem SSML.

1. Chame playStreamInputTts ou asyncPlayStreamInputTts para passar o texto completo e iniciar a síntese. O primeiro bloqueia até que a síntese termine. Este último retorna imediatamente e sintetiza em segundo plano. Não ligue startStreamInputTts primeiro e não chame um método stop depois.
2. Receba áudio em onStreamInputTtsDataCallback.
3. A síntese termina quando STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE é recebido.

A entrada de streaming é adequada para conversas em tempo real ou síntese incremental de texto longo. SSML não é suportado neste modo.

1. Chame startStreamInputTts para abrir a conexão e configurar o retorno de chamada e os parâmetros.
2. Chame sendStreamInputTts para enviar fragmentos de texto.
3. Receba áudio em onStreamInputTtsDataCallback.
4. Depois que todo o texto for enviado, chame stopStreamInputTts.
5. A síntese termina quando STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE é recebido.

Quando a conversão de texto em fala não for mais necessária, chame releaseStreamInputTts para liberar recursos.

Tanto o comprimento de uma única entrada de texto quanto o comprimento cumulativo de múltiplas entradas são limitados. Veja o CosyVoice API WebSocket.

startStreamInputTts

Inicia a síntese de streaming bidirecional, abre a conexão e registra o retorno de chamada. Este método pode bloquear. Não chame isso no thread da UI.

startStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

O método retorna um código de erro. Constants.NuiResultCode.SUCCESS (0) indica sucesso.

campos de ticket

{
  "url": "wss://maas.qwencloudapi.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}

campos de parâmetros

{
  "model": "qwen-audio-3.0-tts-flash",
  "voice": "longanlingxi",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1.0,
  "pitch": 1.0,
  "enable_audio_decoder": true
}

sendStreamInputTts

sendStreamInputTts(text: string): number

Envia um fragmento de texto após startStreamInputTts consegue. Este método não analisa tags SSML. Depois que todo o texto for enviado, ligue stopStreamInputTts().

O método retorna um código de erro.

stopStreamInputTts

stopStreamInputTts(flag_async: boolean = true): number

Termina a entrada de streaming.

• true (padrão): termina de forma assíncrona e retorna imediatamente. Espere por STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE para determinar que a síntese foi concluída.
• false: Bloqueie até que todo o áudio e o evento de conclusão da síntese sejam recebidos. O tempo limite é controlado por complete_waiting_ms.

Chamar um método cancel após uma parada síncrona pode bloquear. Recomendamos o modo assíncrono padrão.

O método retorna um código de erro.

cancelarStreamInputTts

cancelStreamInputTts(): number

Fecha imediatamente a conexão e encerra a tarefa atual. Não serão recebidos mais retornos de chamada de áudio após esta chamada. O método retorna um código de erro.

cancelStreamInputTtsKeepConnection

cancelStreamInputTtsKeepConnection(): number

Envia um comando de cancelamento em nível de protocolo para encerrar a tarefa atual, mas manter a conexão WebSocket aberta. Utilize este método quando outra rodada de síntese precisar começar imediatamente, evitando o custo de reabertura da conexão. O método retorna um código de erro.

###playStreamInputTts

playStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Síntese síncrona one-shot. Este método inicializa a tarefa, envia o texto, recebe todo o áudio e depois retorna. Não ligue startStreamInputTts primeiro e não chame um método stop depois. SSML está habilitado por padrão. Se enable_ssml for definido explicitamente, esse valor terá precedência. Não chame esse método no thread da UI.

callback, ticket, parameters, session_id, log_levele save_log são definidos em startStreamInputTts. text é o texto a ser sintetizado e suporta SSML. O método retorna um código de erro.

asyncPlayStreamInputTts

asyncPlayStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Síntese assíncrona one-shot. Este método retorna imediatamente e entrega resultados por meio de retornos de chamada. Não ligue startStreamInputTts primeiro e não chame um método stop depois. SSML está habilitado por padrão. Se enable_ssml for definido explicitamente, esse valor terá precedência.

callback, ticket, parameters, session_id, log_levele save_log são definidos em startStreamInputTts. text é o texto a ser sintetizado e suporta SSML. O método retorna um código de erro.

releaseStreamInputTts

releaseStreamInputTts(): number

Libera a instância TTS de streaming e seus recursos. Chame esse método quando a página for destruída ou a conversão de texto em fala não for mais necessária. O método retorna um código de erro.

INativeStreamInputTtsCallback

export interface INativeStreamInputTtsCallback {
  onStreamInputTtsEventCallback(
    event: StreamInputTtsEvent,
    task_id: string,
    session_id: string,
    ret_code: number,
    error_msg: string,
    timestamp: string,
    all_response: string
  ): void;

  onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;
}

onStreamInputTtsEventCallback

onStreamInputTtsDataCallback

onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;

Retorna continuamente fragmentos de áudio. Observe o seguinte:

• Os dados MP3 e Opus requerem um decodificador de streaming. Alternativamente, defina enable_audio_decoder para true para permitir que o SDK retorne PCM.
• Para montar um arquivo completo, anexe os dados de retorno de chamada em ordem.
• Para WAV e MP3, apenas o primeiro retorno de chamada contém o cabeçalho do arquivo. Cada quadro Opus é uma página Ogg independente e pode ser concatenada em ordem.

StreamInputTtsEvent

Exemplo de resposta com falha na tarefa:

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "[tts:]Engine return error code: 418",
    "attributes": {}
  },
  "payload": {}
}

Código de exemplo

1. Obtenha uma chave API. Não codifique uma chave de API de longa duração em um aplicativo cliente. Recomendamos que seu servidor de aplicativos obtenha uma chave de API temporária e envie para o cliente.
2. Baixe o pacote SDK mais recente. Extraia o pacote, copie entry/libs/neonui.har para o entry/libs diretório do seu aplicativo e adicione a dependência ao entry/oh-package.json5:

{
  "dependencies": {
    "neonui": "file:libs/neonui.har"
  }
}

3. Abra o projeto de amostra do pacote SDK no DevEco Studio. A página de exemplo é entry/src/main/ets/pages/dashscope/DashCosyVoiceStreamTtsPage.ets. Configure uma chave de API e execute o projeto.

O código a seguir mostra o fluxo principal de entrada de streaming. Para reprodução completa de áudio, seleção de parâmetros e gerenciamento de estado de tarefa, consulte DashCosyVoiceStreamTtsPage.ets no pacote SDK.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const callback: INativeStreamInputTtsCallback = {
  onStreamInputTtsEventCallback: (event: StreamInputTtsEvent, taskId: string,
    sessionId: string, retCode: number, errorMsg: string,
    timestamp: string, allResponse: string): void => {
    if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE) {
      // Synthesis is complete.
    } else if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_TASK_FAILED) {
      // Handle the error based on retCode, errorMsg, or allResponse.
    }
  },
  onStreamInputTtsDataCallback: (data: ArrayBuffer | null): void => {
    if (data != null) {
      // Write PCM to AudioRenderer, or append encoded audio data in order.
    }
  }
};

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
const ticket: Record<string, Object> = {
  'url': 'wss://maas.qwencloudapi.com/api-ws/v1/inference',
  'apikey': 'st-****',
  'device_id': 'my_device_id'
};
const parameters: Record<string, Object> = {
  'model': 'qwen-audio-3.0-tts-flash',
  'voice': 'longanlingxi',
  'format': 'mp3',
  'sample_rate': 24000,
  'enable_audio_decoder': true
};

const result = nuiInstance.startStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);

if (result == Constants.NuiResultCode.SUCCESS) {
  nuiInstance.sendStreamInputTts('Hello, ');
  nuiInstance.sendStreamInputTts('welcome to real-time speech synthesis.');
  nuiInstance.stopStreamInputTts(true);
}

// Call nuiInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Para entrada única, ligue diretamente playStreamInputTts ou asyncPlayStreamInputTts:

const oneShotInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
oneShotInstance.asyncPlayStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  'Hello, welcome to real-time speech synthesis.',
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);
// Call oneShotInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Recursos avançados

###SSML

Objetivo: incorporar tags XML no texto para controlar a pronúncia, a velocidade da fala, as pausas e outros detalhes de síntese.

Limites: apenas APIs únicas playStreamInputTts e asyncPlayStreamInputTts suporte SSML. A API de entrada de streaming sendStreamInputTts não.

Uso: o SDK habilita SSML por padrão para playStreamInputTts e asyncPlayStreamInputTts. Passar texto SSML text. Para obter mais informações, consulte SSML e LaTeX.

Expressões matemáticas

Objetivo: fazer com que o modelo leia corretamente fórmulas e expressões matemáticas comuns.

Uso: Passe texto que contém uma expressão matemática formatada em LaTeX em text. Para sintaxe suportada, consulte Conversão de texto em fala do LaTeX.