Converta texto em fala expressiva e de alta qualidade em seu aplicativo Android com o SDK de conversão de texto em fala (TTS) CosyVoice.
NativeNui
O SDK suporta várias instâncias NativeNui e usa callbacks para entregar eventos de síntese.
Destaques da arquitetura:
-
Múltiplas instâncias: Crie uma instância chamando
new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS). -
Orientado por callback: Receba eventos e dados de áudio através da interface
INativeStreamInputTtsCallback. -
Tipos de evento:
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED: A tarefa de síntese foi iniciada.onStreamInputTtsDataCallback: Os dados de áudio são entregues.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE: A tarefa de síntese foi concluída.STREAM_INPUT_TTS_EVENT_TASK_FAILED: A tarefa de síntese falhou.
Fluxo de uso
CosyVoice suporta dois modos de invocação: entrada única e entrada em streaming.
Entrada única é adequada para textos curtos e qualquer cenário que use marcação SSML.
playStreamInputTts()ouasyncPlayStreamInputTts()— envia um texto completo e inicia a síntese. O primeiro é síncrono e retorna após o término da síntese; o último é assíncrono e retorna imediatamente após o início da síntese.onStreamInputTtsDataCallback()— receber dados de áudio.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE— a síntese está concluída.
startStreamInputTts()— inicialize o SDK e configure o callback e os parâmetros de conexão.sendStreamInputTts()— envie texto continuamente à medida que estiver disponível.onStreamInputTtsDataCallback()— receber dados de áudio.stopStreamInputTts()ouasyncStopStreamInputTts()— envia a solicitação de fim de síntese. O primeiro é síncrono e retorna após o término da síntese; o último é assíncrono e retorna imediatamente após o envio da solicitação.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE— a síntese está concluída.
startStreamInputTts
Inicia a síntese de streaming bidirecional, abre a conexão com o serviço e registra o callback para eventos e dados de áudio.
Este método pode bloquear. Chame-o em uma thread que não seja de UI.
Assinatura do método:
| Parâmetro | Tipo | Descrição |
|---|---|---|
callback | INativeStreamInputTtsCallback | Sua implementação da interface de callback de eventos e dados. |
ticket | String | Uma string JSON que contém configurações de autenticação, conexão e depuração. Consulte a referência do parâmetro ticket abaixo. |
parameters | String | Uma string JSON que controla a saída da síntese de fala. Consulte a referência de parâmetros abaixo. |
session_id | String | Um ID de sessão especificado pelo cliente. Se omitido, o servidor gera um automaticamente. |
log_level | int | Controla a verbosidade dos logs internos do SDK.Valores válidos:
|
save_log | boolean | Se deve gravar logs em um arquivo local. Se true, defina debug_path no ticket para especificar o destino e, opcionalmente, defina max_log_file_size para limitar o tamanho do arquivo. |
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | String | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | String | Sim | Sua chave de API. Para limitar o raio de impacto caso uma chave de longa duração seja exposta, use uma chave de API temporária de curta duração. |
device_id | String | Sim | Um identificador exclusivo para o usuário final. Defina-o como o ID de usuário no seu aplicativo ou como um identificador de dispositivo gerado pelo cliente. Este ID é usado principalmente para correlação de logs e solução de problemas. |
complete_waiting_ms | int | Não | Depois de chamar o método stop, o tempo em milissegundos para aguardar o evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE antes de atingir o tempo limite.Padrão: 10000. |
debug_path | String | Não | O caminho local onde os arquivos de log são gravados.Este parâmetro só entra em vigor quando save_log é definido como true para startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, o caminho é obrigatório; caso contrário, a chamada retorna um erro.No máximo dois arquivos de log são mantidos no dispositivo. |
max_log_file_size | int | Não | O tamanho máximo do arquivo de log em bytes.Este parâmetro só entra em vigor quando save_log é definido como true para startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts.Padrão: 104857600 (100 × 1024 × 1024 bytes, ou 100 MiB). |
log_track_level | int | Não | Nível de filtro para logs que são entregues através do callback de log (onStreamInputTtsLogTrackCallback).Padrão: 2.Valores válidos:
log_track_level funciona em conjunto com log_level (definido em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) para decidir quais logs chegam ao callback. Uma entrada de log deve estar no nível ou acima de ambos log_track_level e log_level para ser entregue. Por exemplo, se log_track_level for 2 (INFO) e log_level for 3 (WARNING), apenas WARNING e acima (nível >= 3) chegam ao callback. |
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
model | String | Sim | O nome do modelo. |
voice | String | Sim | A voz usada para a síntese de fala.
|
format | String | Não | O formato de codificação de áudio.Valores válidos:
|
enable_audio_decoder | boolean | Não | Se deve ativar o decodificador interno do SDK. Padrão: false.Este parâmetro entra em vigor apenas quando o formato de codificação de áudio é opus ou mp3. Quando habilitado, o SDK decodifica dados de áudio opus ou mp3 em dados PCM antes de retorná-los. |
volume | int | Não | O nível de volume.Valor padrão: 50.Valores válidos: [0, 100]. |
sample_rate | int | Não | A taxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000. |
rate | float | Não | A velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
pitch | float | Não | O tom.Valor padrão: 1.0.Valores válidos: [0.5, 2.0]. |
bit_rate | int | Não | A taxa de bits de áudio em kbps. Quando o formato de áudio for mp3 ou opus, use bit_rate para ajustar a taxa de bits.Valor padrão: 32.Valores válidos: [6, 510]. |
enable_ssml | boolean | Não | Se deve ativar o SSML.Padrão: false.
|
word_timestamp_enabled | boolean | Não | Especifica se deve ativar os timestamps no nível da palavra.Valor padrão: false.Disponível apenas no modo de saída em streaming. Vozes suportadas: 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 suportam este recurso.
Os carimbos de data e hora de palavras são retornados no campo all_response de |
seed | int | Não | Uma semente aleatória para controlar a variação na saída da síntese. Quando a versão do modelo, texto, voz e outros parâmetros permanecem inalterados, usar a mesma semente produz resultados idênticos.Valor padrão: 0.Valores válidos: [0, 65535]. |
language_hints | String[] | Não | Especifica o idioma de destino para a síntese de fala para melhorar a qualidade da saída.Quando a pronúncia de dígitos, expansão de abreviações, leitura de símbolos ou síntese em idiomas minoritários não atender às expectativas, use este parâmetro. Por exemplo:
Valores válidos
|
instruction | String | Não | Controla as características da síntese, como dialeto, emoção ou estilo de fala.Para detalhes de uso, consulte Controle de instrução. |
enable_aigc_tag | boolean | Não | Especifica se deve incorporar uma marca d'água AIGC no áudio gerado. Quando definido como true, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).Valor padrão: false. Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
aigc_propagator | String | Não | Define o campo ContentPropagator na marca d'água AIGC, identificando o propagador de conteúdo. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: UID da Alibaba Cloud.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
aigc_propagate_id | String | Não | Define o campo PropagateID na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Entra em vigor apenas quando enable_aigc_tag é true.Valor padrão: O ID da solicitação de síntese de fala atual.Apenas cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2 suportam este recurso. |
hot_fix | object | Não | Configuração de correção rápida de texto para personalizar a pronúncia de palavras especificadas ou substituir texto antes da síntese. cosyvoice-v2 não suporta este recurso.
|
enable_markdown_filter | boolean | Não | Apenas as vozes clonadas do cosyvoice-v3-flash suportam este recurso.
|
sendStreamInputTts
Envia texto para ser sintetizado. Use este método junto com startStreamInputTts.
Depois de chamar startStreamInputTts, chame este método para enviar texto continuamente.
Quando você tiver enviado todo o texto, chame stopStreamInputTts ou asyncStopStreamInputTts para encerrar a entrada.
Assinatura do método:
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | String | Texto a ser sintetizado. SSML não é suportado. As tags SSML na entrada são lidas em voz alta como texto simples, em vez de serem analisadas. |
stopStreamInputTts
Método síncrono que informa ao servidor que todo o texto foi enviado e bloqueia até que todo o áudio tenha sido sintetizado e o evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE seja recebido.
O tempo limite de espera é controlado por complete_waiting_ms.
Assinatura do método:
asyncStopStreamInputTts
Método assíncrono que informa ao servidor que todo o texto foi enviado. A chamada retorna imediatamente e a síntese continua em segundo plano.
Use o evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE para detectar quando a síntese for concluída.
Assinatura do método:
cancelStreamInputTts
Fecha imediatamente a conexão com o servidor e aborta a tarefa de síntese atual. Nenhum callback de áudio adicional é entregue após esta chamada.
Assinatura do método:
playStreamInputTts
Método de síntese única síncrono. A chamada envia o texto, bloqueia enquanto o áudio é recebido e retorna apenas após a conclusão da síntese. Você não precisa chamar o método stop depois.
O SSML é habilitado por padrão para este método. Para substituir, defina enable_ssml explicitamente.
Chame este método em uma thread que não seja de UI.
Assinatura do método:
startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | String | Texto a ser sintetizado. Suporta SSML. |
asyncPlayStreamInputTts
Método de síntese única assíncrono. A chamada retorna imediatamente, a síntese é executada em segundo plano e os resultados são entregues através do callback. Você não precisa chamar o método stop depois.
O SSML é habilitado por padrão para este método. Para substituir, defina enable_ssml explicitamente.
Assinatura do método:
startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | String | Texto a ser sintetizado. Suporta SSML. |
INativeStreamInputTtsCallback
A interface de callback de TTS em streaming do CosyVoice entrega eventos de síntese, dados de áudio e logs.
onStreamInputTtsEventCallback: receber eventos
Assinatura do método:
| Parâmetro | Tipo | Descrição |
|---|---|---|
event | StreamInputTtsEvent | O evento entregue. |
task_id | String | O ID da tarefa de síntese. |
session_id | String | O ID da sessão. Retornado conforme fornecido pelo cliente; gerado pelo servidor se omitido. |
ret_code | int | Código de erro. Válido apenas com o evento STREAM_INPUT_TTS_EVENT_TASK_FAILED. |
error_msg | String | Mensagem de erro. Válido apenas com o evento STREAM_INPUT_TTS_EVENT_TASK_FAILED. |
timestamp | String | Informações de timestamp para o resultado da síntese. |
all_response | String | A resposta JSON completa. Analise-a para extrair quaisquer dados adicionais necessários. |
onStreamInputTtsDataCallback: receber dados de áudio
O SDK invoca este callback repetidamente durante a síntese. Leia os dados de áudio a partir do callback.
Assinatura do método:
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | byte[] | Dados de áudio para o segmento atual. Use-os para:
|
onStreamInputTtsLogTrackCallback: receber logs de rastreamento
Use este callback para receber logs internos detalhados do SDK, o que ajuda na solução de problemas e depuração.
Assinatura do método:
StreamInputTtsEvent
Enumeração de tipos de evento para a síntese de fala em streaming do CosyVoice.
| Evento | Descrição |
|---|---|
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED | O servidor aceitou a solicitação e iniciou o processamento. Logo após este evento, onStreamInputTtsDataCallback começa a retornar os primeiros dados de áudio. |
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS | Informações de tempo de execução sobre a síntese, incluindo dados de faturamento. |
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE | O servidor enviou todos os dados de áudio e onStreamInputTtsEventCallback não será chamado novamente. Este evento é o sinal explícito de que o fluxo de áudio terminou. |
STREAM_INPUT_TTS_EVENT_TASK_FAILED | A tarefa falhou. Leia o campo all_response de INativeStreamInputTtsCallback para task_id, error_code e error_message para identificar a causa. |
Código de exemplo
-
Obter uma chave de API: Obtenha uma chave de API. Para segurança, armazene a chave de API em uma variável de ambiente.
Use uma chave de API temporária quando precisar conceder acesso temporário a um aplicativo ou usuário de terceiros, ou quando você want controlar rigorosamente operações de alto risco, como acessar ou excluir dados confidenciais. Uma chave de API temporária é válida por 60 segundos, após os quais você deve solicitar uma nova.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- Descompacte o pacote. O SDK no formato AAR está em
app/libs— adicione-o às dependências do seu projeto. Para integração com C++ no Android, obtenha as bibliotecas compartilhadas deandroid_libse os cabeçalhos deandroid_includedentro do ZIP. - Abra o projeto no Android Studio. O código de exemplo está em
DashCosyVoiceStreamTtsActivity.java— substitua a chave de API pela sua própria para testar o recurso.
Modos de invocação
| Modo | Descrição |
|---|---|
| Entrada de texto única | Etapas:
|
Entrada de texto em streaming | Etapas:
|
Recursos avançados
Marcação SSML
Propósito: Incorpore tags XML no texto para ajustar a pronúncia, a taxa de fala, as pausas e outros detalhes prosódicos.
Limitações: O SSML é suportado apenas com Entrada de texto única (os métodos playStreamInputTts ou asyncPlayStreamInputTts). A Entrada de texto em streaming (o método sendStreamInputTts) não suporta SSML.
Uso: Quando você chama playStreamInputTts ou asyncPlayStreamInputTts, o SDK habilita o SSML automaticamente. Passe o texto que contém tags SSML através do parâmetro text.
Para mais informações, consulte SSML.
Expressões matemáticas
Propósito: Permitir que o modelo leia fórmulas e expressões matemáticas comuns em voz alta corretamente.
Uso: Passe o texto que contém expressões matemáticas formatadas em LaTeX através do parâmetro text. Para mais informações, consulte Converter fórmulas LaTeX em fala (apenas idioma chinês).