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 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.
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.
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.
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. |
campos de parâmetros
| 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 | 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
|
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. |
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. |
Código de exemplo
- 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.
- 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:
- 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.
DashCosyVoiceStreamTtsPage.ets no pacote do SDK.
playStreamInputTts ou asyncPlayStreamInputTts:
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.