Pré-requisitos
- Obtenha e configure uma chave de API. Não insira chaves de API de longa duração diretamente no código do aplicativo móvel. Recomendamos gerar uma chave de API temporária no servidor do aplicativo e enviá-la ao cliente.
-
Baixe o pacote mais recente do SDK. Extraia o pacote, copie
entry/libs/neonui.harpara o diretórioentry/libsdo seu aplicativo e adicione a dependência aentry/oh-package.json5:
Início rápido
Qwen-Audio-TTS / CosyVoice
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.
Para executar este exemplo com o CosyVoice, defina model como cosyvoice-v3-plus e voice como longanyang.
playStreamInputTts ou asyncPlayStreamInputTts:
Parâmetros da solicitação
campos do ticket
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | Endpoint 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/inferencepara Pequim ou wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferencepara Singapura. Substitua {WorkspaceId} pelo seu ID do workspace. |
apikey | string | Sim | Chave de API. Use uma chave de API temporária para reduzir o risco de expor uma chave de longa duração. |
device_id | string | Sim | Um 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_ms | number | Não | Tempo em milissegundos para aguardar o evento de conclusão da síntese após stopStreamInputTts(false). Padrão: 10000. |
debug_path | string | Não | Diretó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_size | number | Não | Tamanho 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_level | number | Não | Ní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. |
Qwen-Audio-TTS
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | string | Sim | Nome do modelo. Consulte Modelos de síntese de fala. |
voice | string | Sim | Voz. 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. |
format | string | Não | Formato de codificação de áudio: pcm, wav, mp3 (padrão) ou opus. |
enable_audio_decoder | boolean | Não | Se 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. |
volume | number | Não | Volume. Padrão: 50. Intervalo válido: [0, 100]. |
sample_rate | number | Não | Taxa de amostragem em Hz. Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100e 48000. |
rate | number | Não | Taxa de fala. Padrão: 1.0. Intervalo válido: [0.5, 2.0]. |
pitch | number | Não | Tom. Padrão: 1.0. Intervalo válido: [0.5, 2.0]. |
bit_rate | number | Não | Taxa de bits MP3 ou Opus em kbps. Padrão: 32. Intervalo válido: [6, 510]. |
enable_ssml | boolean | Não | Se deve habilitar o SSML. Padrão: false. Consulte Limites do SSML. |
word_timestamp_enabled | boolean | Não | Se 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. |
seed | number | Não | Semente 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_hints | string[] | Não | Para as vozes multilíngues e dialetais do qwen-audio-3.1-tts-flash, este parâmetro define o idioma ou dialeto. Para mais detalhes, consulte a seção de configuração de vozes multilíngues e dialetais. "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”.
Valores válidos
|
instruction | string | Não | Instrução que controla dialeto, emoção ou papel. Consulte Controle de instrução. |
enable_aigc_tag | boolean | Não | Se deve incorporar uma tag AIGC invisível. Padrão: false. |
aigc_propagator | string | Não | ContentPropagator 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_id | string | Não | PropagateID 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_fix | object | Não | Configurações de correção rápida de texto para pronúncia personalizada e substituição de texto. Para o esquema, consulte Eventos do cliente. |
CosyVoice
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | string | Sim | Nome do modelo. Consulte Modelos de síntese de fala. |
voice | string | Sim | Voz. Para vozes do sistema, consulte Vozes do CosyVoice. Você também pode usar uma voz criada por meio de clonagem de voz ou Voice Design. |
format | string | Não | Formato de codificação de áudio: pcm, wav, mp3 (padrão) ou opus. |
enable_audio_decoder | boolean | Não | Se 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. |
volume | number | Não | Volume. Padrão: 50. Intervalo válido: [0, 100]. |
sample_rate | number | Não | Taxa de amostragem em Hz. Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100e 48000. |
rate | number | Não | Taxa de fala. Padrão: 1.0. Intervalo válido: [0.5, 2.0]. |
pitch | number | Não | Tom. Padrão: 1.0. Intervalo válido: [0.5, 2.0]. |
bit_rate | number | Não | Taxa de bits MP3 ou Opus em kbps. Padrão: 32. Intervalo válido: [6, 510]. |
enable_ssml | boolean | Não | Se deve habilitar o SSML. Padrão: false. Consulte Limites do SSML. |
word_timestamp_enabled | boolean | Não | Se 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. Ele suporta vozes clonadas de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, e vozes do sistema marcadas como suportadas na lista de vozes do CosyVoice. Vozes clonadas de outros modelos não são suportadas. Os resultados de carimbo de data e hora estão incluídos em all_response de INativeStreamInputTtsCallback. |
seed | number | Não | Semente 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_hints | string[] | Não | Idioma 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”.
Valores válidos Valores suportados: zh, en, fr, de, ja, ko, ru, pt, th, id, vi, es, it, ms, file ar. |
instruction | string | Não | Instrução que controla dialeto, emoção ou papel. Consulte Controle de instrução. |
enable_aigc_tag | boolean | Não | Se deve incorporar uma tag AIGC invisível. Padrão: false.Suportado por cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2. |
aigc_propagator | string | Não | ContentPropagator 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_id | string | Não | PropagateID 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_fix | object | Não | Configurações de correção rápida de texto para pronúncia personalizada e substituição de texto.cosyvoice-v2 não suportam este campo. |
Referência da API
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 singletonMODE_DIALOGe 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 parastartStreamInputTts(),playStreamInputTts()ouasyncPlayStreamInputTts(). - Receba eventos de síntese e áudio através de
INativeStreamInputTtsCallback. - O SDK retorna
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDquando a tarefa inicia, áudio através deonStreamInputTtsDataCallback,STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEquando a tarefa termina eSTREAM_INPUT_TTS_EVENT_TASK_FAILEDquando a síntese falha.
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.
| Parâmetro | Tipo | Descrição |
|---|---|---|
callback | INativeStreamInputTtsCallback | Callback de evento e áudio. |
ticket | string | String JSON que contém configurações de autenticação, conexão e depuração. |
parameters | string | String JSON que contém configurações de síntese. |
session_id | string | ID de sessão especificado pelo cliente. Passe uma string vazia para permitir que o servidor gere um. |
log_level | number | Nível de log do SDK. Use um Constants.LogLevel valor: 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) ou 5 (NONE). |
save_log | boolean | Se deve salvar logs localmente. Se definido como true, defina debug_path em ticket. |
Constants.NuiResultCode.SUCCESS (0) indica sucesso.
sendStreamInputTts
startStreamInputTts. Este método não analisa tags SSML. Depois que todo o texto for enviado, chame stopStreamInputTts().
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | string | Texto a ser sintetizado. SSML não é suportado. As tags SSML são lidas como texto comum. |
stopStreamInputTts
true(padrão): Encerra de forma assíncrona e retorna imediatamente. AguardeSTREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEpara 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 porcomplete_waiting_ms.
| Parâmetro | Tipo | Descrição |
|---|---|---|
flag_async | boolean | Se 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. |
cancelStreamInputTts
cancelStreamInputTtsKeepConnection
playStreamInputTts
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
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
INativeStreamInputTtsCallback
onStreamInputTtsEventCallback
| Parâmetro | Tipo | Descrição |
|---|---|---|
event | StreamInputTtsEvent | Evento de síntese. |
task_id | string | ID da tarefa de síntese. |
session_id | string | ID da sessão. Um valor especificado pelo cliente é retornado inalterado. Caso contrário, o servidor gera um. |
ret_code | number | Código de erro. Válido apenas para um evento de falha de tarefa. |
error_msg | string | Mensagem de erro. Válida apenas para um evento de falha de tarefa. |
timestamp | string | Resultado do carimbo de data e hora. |
all_response | string | Resposta completa do servidor como uma string JSON. Analise-a para obter detalhes de uso, carimbo de data e hora e erros. |
onStreamInputTtsDataCallback
- Dados MP3 e Opus requerem um decodificador de streaming. Alternativamente, defina
enable_audio_decodercomotruepara 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
| Evento | Descrição |
|---|---|
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED | O 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_BEGIN | O servidor começou a sintetizar um enunciado. |
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS | Informações de progresso da síntese, incluindo informações de faturamento e carimbos de data e hora. |
STREAM_INPUT_TTS_EVENT_SENTENCE_END | O servidor concluiu a síntese de um enunciado. |
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE | O 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_FAILED | A síntese falhou. Recupere task_id, error_codee error_message de all_response, ou use os ret_code e error_msg argumentos de callback. |
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.
Qwen-Audio-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.
- Chame
playStreamInputTtsouasyncPlayStreamInputTtspara 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 chamestartStreamInputTtsprimeiro e não chame um método de parada depois. - Receba áudio em
onStreamInputTtsDataCallback. - A síntese termina quando
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEé recebido.
- Chame
startStreamInputTtspara abrir a conexão e configurar o callback e os parâmetros. - Chame
sendStreamInputTtspara enviar fragmentos de texto. - Receba áudio em
onStreamInputTtsDataCallback. - Depois que todo o texto for enviado, chame
stopStreamInputTts. - A síntese termina quando
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEé recebido.
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.
Recursos avançados
CosyVoice
Fluxos de chamada
CosyVoice suporta entrada única e entrada de streaming.
Entrada única é adequada para textos curtos ou cenários que exigem SSML.
- Chame
playStreamInputTtsouasyncPlayStreamInputTtspara 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 chamestartStreamInputTtsprimeiro e não chame um método de parada depois. - Receba áudio em
onStreamInputTtsDataCallback. - A síntese termina quando
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEé recebido.
- Chame
startStreamInputTtspara abrir a conexão e configurar o callback e os parâmetros. - Chame
sendStreamInputTtspara enviar fragmentos de texto. - Receba áudio em
onStreamInputTtsDataCallback. - Depois que todo o texto for enviado, chame
stopStreamInputTts. - A síntese termina quando
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEé recebido.
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 CosyVoice.