Skip to main content

Qwen-Audio-TTS HarmonyOS SDK

Saiba mais sobre a integração do SDK do HarmonyOS, parâmetros, APIs, callbacks e código de exemplo para síntese de fala em tempo real.

NativeNui

O SDK do HarmonyOS fornece texto para fala em streaming através de NativeNui.
  • Crie uma instância de conversão de texto em fala em streaming chamando new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS). NativeNui.GetInstance() retorna um singleton MODE_DIALOG e não pode ser usado para conversão de texto em fala em streaming.
  • Não chame initialize() no modo de conversão de texto em fala em streaming. Passe as credenciais e os parâmetros de síntese diretamente para startStreamInputTts(), playStreamInputTts() ou asyncPlayStreamInputTts().
  • Receba eventos de síntese e áudio através de INativeStreamInputTtsCallback.
  • O SDK retorna STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED quando a tarefa inicia, áudio através de onStreamInputTtsDataCallback, STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE quando a tarefa termina 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 chamada

Qwen-Audio-TTS suporta entrada única e entrada de streaming. 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. O segundo retorna imediatamente e sintetiza em segundo plano. Não chame startStreamInputTts primeiro e não chame um método de parada depois.
  2. Receba áudio em onStreamInputTtsDataCallback.
  3. A síntese termina quando STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE é recebido.
Entrada em streaming é adequada para conversas em tempo real ou síntese incremental de textos longos. O SSML não é suportado neste modo.
  1. Chame startStreamInputTts para abrir a conexão e configurar o callback 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. Consulte a API WebSocket do Qwen-Audio-TTS.

startStreamInputTts

Inicia a síntese de streaming bidirecional, abre a conexão e registra o callback. Este método pode bloquear. Não o chame na thread de UI.
startStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number
ParâmetroTipoDescrição
callbackINativeStreamInputTtsCallbackCallback de evento e áudio.
ticketstringString JSON que contém configurações de autenticação, conexão e depuração.
parametersstringString JSON que contém configurações de síntese.
session_idstringID de sessão especificado pelo cliente. Passe uma string vazia para permitir que o servidor gere um.
log_levelnumberNível de log do SDK. Use um Constants.LogLevel valor: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) ou 5 (NONE).
save_logbooleanSe deve salvar logs localmente. Se definido como true, defina debug_path em ticket.
O método retorna um código de erro. Constants.NuiResultCode.SUCCESS (0) indica sucesso.

campos do ticket

{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}
CampoTipoObrigatórioDescrição
urlstringSimEndpoint do serviço. Use o endpoint público
wss://dashscope.aliyuncs.com/api-ws/v1/inference
, ou um endpoint específico do workspace:
wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
para Pequim ou
wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
para Singapura. Substitua {WorkspaceId} pelo seu ID do workspace.
apikeystringSimChave de API. Use uma chave de API temporária para reduzir o risco de expor uma chave de longa duração.
device_idstringSimUm identificador exclusivo de usuário final, como um ID de usuário no aplicativo ou um ID de dispositivo gerado pelo cliente. É usado principalmente para rastreamento de logs e solução de problemas.
complete_waiting_msnumberNãoTempo em milissegundos para aguardar o evento de conclusão da síntese após stopStreamInputTts(false). Padrão: 10000.
debug_pathstringNãoDiretório de log. Este campo é obrigatório quando save_log é true. O SDK mantém no máximo dois arquivos de log.
max_log_file_sizenumberNãoTamanho máximo de um único arquivo de log em bytes. Padrão: 104857600 (100 MiB). Este campo só tem efeito quando save_log é true.
log_track_levelnumberNãoNível de filtro de log de rastreamento interno. Padrão: 2. Os valores válidos são os mesmos de log_level. A interface de callback do HarmonyOS atualmente não expõe um callback de log de TTS em streaming, portanto, os logs filtrados são gravados apenas pelo SDK.

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
}
CampoTipoObrigatórioDescrição
modelstringSimNome do modelo. Consulte Modelos de síntese de fala.
voicestringSimVoz. Para vozes do sistema, consulte Vozes do Qwen-Audio-TTS. Você também pode usar uma voz criada por meio de clonagem de voz ou Voice Design.
formatstringNãoFormato de codificação de áudio: pcm, wav, mp3 (padrão) ou opus.
enable_audio_decoderbooleanNãoSe deve habilitar o decodificador do SDK. Padrão: false. Para MP3 ou Opus, defina isso como true para decodificar o áudio para PCM antes que ele seja retornado através do callback de dados.
volumenumberNãoVolume. Padrão: 50. Intervalo válido: [0, 100].
sample_ratenumberNãoTaxa de amostragem em Hz. Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100e 48000.
ratenumberNãoTaxa de fala. Padrão: 1.0. Intervalo válido: [0.5, 2.0].
pitchnumberNãoTom. Padrão: 1.0. Intervalo válido: [0.5, 2.0].
bit_ratenumberNãoTaxa de bits MP3 ou Opus em kbps. Padrão: 32. Intervalo válido: [6, 510].
enable_ssmlbooleanNãoSe deve habilitar o SSML. Padrão: false. Consulte Limites do SSML.
word_timestamp_enabledbooleanNãoSe deve retornar carimbos de data e hora no nível da palavra. Padrão: false. Este campo está disponível apenas para saída em streaming. Vozes clonadas são suportadas. Para as vozes do sistema compatíveis, consulte lista de vozes do Qwen-Audio-TTS. Os resultados de carimbo de data e hora estão incluídos em all_response de INativeStreamInputTtsCallback.
seednumberNãoSemente aleatória usada para variar o resultado sintetizado. Se a versão do modelo, o texto, a voz e todos os outros parâmetros forem os mesmos, a mesma seed reproduz o mesmo resultado. Padrão: 0. Intervalo válido: [0, 65535].
language_hintsstring[]NãoIdioma de síntese alvo. Esta configuração melhora a síntese e é independente do idioma do áudio de amostra usado para clonagem de voz. Para definir o idioma de origem de uma tarefa de clonagem de voz, consulte a referência da API de Clonagem de Voz. A versão atual usa apenas o primeiro elemento do array, portanto, passe um valor. Use este campo quando a leitura de números, abreviações ou símbolos for inesperada, ou quando a síntese em um idioma menos comum não for natural. Por exemplo, pode fazer com que "hello, this is 110" seja lido como “one one zero” em inglês em vez da leitura em chinês, ou fazer com que @ seja lido como “at”.
  • zh: Chinês
  • en: Inglês
  • fr: Francês
  • de: Alemão
  • ja: Japonês
  • ko: Coreano
  • ru: Russo
  • pt: Português
  • th: Tailandês
  • id: Indonésio
  • vi: Vietnamita
  • es: Espanhol
  • it: Italiano
  • ms: Malaio
  • fil: Filipino
  • ar: Árabe
  • other: Outros idiomas (compatíveis com qwen-audio-3.1-tts-flash) búlgaro, holandês, húngaro, romeno, dinamarquês, croata, grego, tcheco, norueguês, sueco, hindi, eslovaco, finlandês, urdu, sérvio, espanhol (México), lituano, letão, turco, persa, hebraico, mongol, esloveno, azerbaijano, polonês, catalão, khmer, português (Brasil), laosiano, georgiano, africâner, nepalês, bielorrusso, malaiala, luxemburguês, albanês, tâmil, cingalês, télugo, estoniano, cebuano, bósnio, birmanês, armênio, latim, islandês, maltês, suaíli, cazaque, crioulo francês seichelense, ucraniano.
instructionstringNãoInstrução que controla dialeto, emoção ou papel. Consulte Controle de instrução.
enable_aigc_tagbooleanNãoSe deve incorporar uma tag AIGC invisível. Padrão: false.
aigc_propagatorstringNãoContentPropagator na tag AIGC. Tem efeito apenas quando enable_aigc_tag é true. Padrão: o UID do Alibaba Cloud. Os modelos suportados são os mesmos de enable_aigc_tag.
aigc_propagate_idstringNãoPropagateID na tag AIGC. Tem efeito apenas quando enable_aigc_tag é true. Padrão: o ID da solicitação atual. Os modelos suportados são os mesmos de enable_aigc_tag.
hot_fixobjectNãoConfigurações de correção rápida de texto para pronúncia personalizada e substituição de texto. Para o esquema, consulte Eventos do cliente.

sendStreamInputTts

sendStreamInputTts(text: string): number
Envia um fragmento de texto após o sucesso de startStreamInputTts. Este método não analisa tags SSML. Depois que todo o texto for enviado, chame stopStreamInputTts().
ParâmetroTipoDescrição
textstringTexto a ser sintetizado. SSML não é suportado. As tags SSML são lidas como texto comum.
O método retorna um código de erro.

stopStreamInputTts

stopStreamInputTts(flag_async: boolean = true): number
Encerra a entrada de streaming.
  • true (padrão): Encerra de forma assíncrona e retorna imediatamente. Aguarde STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE para determinar que a síntese foi concluída.
  • false: Bloqueia 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 de cancelamento após uma parada síncrona pode bloquear. Recomendamos o modo assíncrono padrão.
ParâmetroTipoDescrição
flag_asyncbooleanSe deve encerrar de forma assíncrona. Padrão: true. true retorna sem aguardar uma resposta do servidor. false bloqueia até que a síntese seja concluída.
O método retorna um código de erro.

cancelStreamInputTts

cancelStreamInputTts(): number
Fecha imediatamente a conexão e encerra a tarefa atual. Nenhum outro callback de áudio é recebido após esta chamada. O método retorna um código de erro.

cancelStreamInputTtsKeepConnection

cancelStreamInputTtsKeepConnection(): number
Envia um comando de cancelamento no nível do protocolo para encerrar a tarefa atual, mas mantém a conexão WebSocket aberta. Use este método quando outra rodada de síntese precisar iniciar imediatamente, evitando o custo de reabrir a 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 única síncrona. Este método inicializa a tarefa, envia o texto, recebe todo o áudio e então retorna. Não chame startStreamInputTts primeiro e não chame um método de parada depois. O SSML é habilitado por padrão. Se enable_ssml for definido explicitamente, esse valor terá precedência. Não chame este método na thread de UI. callback, ticket, parameters, session_id, log_level e 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 única assíncrona. Este método retorna imediatamente e entrega os resultados através de callbacks. Não chame startStreamInputTts primeiro e não chame um método de parada depois. O SSML é habilitado por padrão. Se enable_ssml for definido explicitamente, esse valor terá precedência. callback, ticket, parameters, session_id, log_level e 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 de TTS em streaming e seus recursos. Chame este método quando a página for destruída ou quando 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

ParâmetroTipoDescrição
eventStreamInputTtsEventEvento de síntese.
task_idstringID da tarefa de síntese.
session_idstringID da sessão. Um valor especificado pelo cliente é retornado inalterado. Caso contrário, o servidor gera um.
ret_codenumberCódigo de erro. Válido apenas para um evento de falha de tarefa.
error_msgstringMensagem de erro. Válida apenas para um evento de falha de tarefa.
timestampstringResultado do carimbo de data e hora.
all_responsestringResposta completa do servidor como uma string JSON. Analise-a para obter detalhes de uso, carimbo de data e hora e erros.

onStreamInputTtsDataCallback

onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;
Retorna fragmentos de áudio continuamente. Observe o seguinte:
  • Dados MP3 e Opus requerem um decodificador de streaming. Alternativamente, defina enable_audio_decoder como true para permitir que o SDK retorne PCM.
  • Para montar um arquivo completo, anexe os dados do callback em ordem.
  • Para WAV e MP3, apenas o primeiro callback contém o cabeçalho do arquivo. Cada quadro Opus é uma página Ogg independente e pode ser concatenado em ordem.

StreamInputTtsEvent

EventoDescrição
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDO servidor aceitou a solicitação e iniciou o processamento. Os primeiros dados de áudio geralmente chegam através de onStreamInputTtsDataCallback logo após este evento.
STREAM_INPUT_TTS_EVENT_SENTENCE_BEGINO servidor começou a sintetizar um enunciado.
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESISInformações de progresso da síntese, incluindo informações de faturamento e carimbos de data e hora.
STREAM_INPUT_TTS_EVENT_SENTENCE_ENDO servidor concluiu a síntese de um enunciado.
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEO servidor retornou todos os dados de áudio. onStreamInputTtsEventCallback não é chamado após este evento, que é o sinal explícito de fim de fluxo. Este evento não indica que a reprodução local foi concluída.
STREAM_INPUT_TTS_EVENT_TASK_FAILEDA síntese falhou. Recupere task_id, error_codee error_message de all_response, ou use os ret_code e error_msg argumentos de callback.
Exemplo de resposta de 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 de API. Não codifique rigidamente uma chave de API de longa duração em um aplicativo cliente. Recomendamos que o servidor do seu aplicativo obtenha uma chave de API temporária e a envie para o cliente.
  2. Baixe o pacote mais recente do SDK. Extraia o pacote, copie entry/libs/neonui.har para o diretório entry/libs do seu aplicativo e adicione a dependência a entry/oh-package.json5:
{
  "dependencies": {
    "neonui": "file:libs/neonui.har"
  }
}
  1. Abra o projeto de exemplo do pacote do 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 em streaming. Para reprodução de áudio completa, seleção de parâmetros e gerenciamento de estado da tarefa, consulte DashCosyVoiceStreamTtsPage.ets no pacote do 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://dashscope.aliyuncs.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, chame 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 taxa de fala, as pausas e outros detalhes da síntese. Limites: Apenas as APIs de entrada única playStreamInputTts e asyncPlayStreamInputTts suportam SSML. A API de entrada em streaming sendStreamInputTts não suporta. Uso: O SDK habilita o SSML por padrão para playStreamInputTts e asyncPlayStreamInputTts. Passe o texto SSML em text. Para 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 o texto que contém uma expressão matemática formatada em LaTeX em text. Para a sintaxe suportada, consulte Conversão de texto em fala LaTeX.