Skip to main content

CosyVoice Android SDK

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.
  1. playStreamInputTts() ou asyncPlayStreamInputTts() — 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.
  2. onStreamInputTtsDataCallback() — receber dados de áudio.
  3. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — a síntese está concluída.
Entrada em streaming é adequada para conversas em tempo real e cenários de "falar enquanto avança" de forma longa. O SSML não é suportado neste modo.
  1. startStreamInputTts() — inicialize o SDK e configure o callback e os parâmetros de conexão.
  2. sendStreamInputTts() — envie texto continuamente à medida que estiver disponível.
  3. onStreamInputTtsDataCallback() — receber dados de áudio.
  4. stopStreamInputTts() ou asyncStopStreamInputTts() — 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.
  5. 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:
public synchronized int startStreamInputTts(INativeStreamInputTtsCallback callback,
                                            String ticket,
                                            String parameters,
                                            String session_id,
                                            int log_level,
                                            boolean save_log)
Parâmetros:
ParâmetroTipoDescrição
callbackINativeStreamInputTtsCallbackSua implementação da interface de callback de eventos e dados.
ticketStringUma string JSON que contém configurações de autenticação, conexão e depuração. Consulte a referência do parâmetro ticket abaixo.
parametersStringUma string JSON que controla a saída da síntese de fala. Consulte a referência de parâmetros abaixo.
session_idStringUm ID de sessão especificado pelo cliente. Se omitido, o servidor gera um automaticamente.
log_levelintControla a verbosidade dos logs internos do SDK.Valores válidos:
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (desativa o log)
save_logbooleanSe 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.
Valor de retorno: Retorna um código de erro. exemplo de JSON do ticket:
{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id"
}
parâmetros do ticket:
ParâmetroTipoObrigatórioDescrição
urlStringSimEndereço do serviço:
  • wss://dashscope.aliyuncs.com/api-ws/v1/inference
  • China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference
Substitua {WorkspaceId} pelo seu ID do Workspace real.
apikeyStringSimSua 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_idStringSimUm 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_msintNãoDepois 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_pathStringNãoO 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_sizeintNãoO 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_levelintNãoNível de filtro para logs que são entregues através do callback de log (onStreamInputTtsLogTrackCallback).Padrão: 2.Valores válidos:
  • 0: LOG_LEVEL_VERBOSE
  • 1: LOG_LEVEL_DEBUG
  • 2: LOG_LEVEL_INFO
  • 3: LOG_LEVEL_WARNING
  • 4: LOG_LEVEL_ERROR
  • 5: LOG_LEVEL_NONE (desativa o log)
Nota: 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.
exemplo de JSON de parâmetros:
{
    "model": "cosyvoice-v3-plus",
    "voice": "longanyang",
    "format": "mp3",
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
}
referência de parâmetros:
ParâmetroTipoObrigatórioDescrição
modelStringSimO nome do modelo.
voiceStringSimA voz usada para a síntese de fala.
  • Vozes do sistema: Consulte a Lista de vozes do CosyVoice
  • Vozes clonadas: Vozes personalizadas criadas por meio de clonagem de voz
  • Vozes personalizadas: Vozes personalizadas criadas por meio de design de voz
formatStringNãoO formato de codificação de áudio.Valores válidos:
  • pcm
  • wav
  • mp3 (padrão)
  • opus
enable_audio_decoderbooleanNãoSe 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.
volumeintNãoO nível de volume.Valor padrão: 50.Valores válidos: [0, 100].
sample_rateintNãoA taxa de amostragem de áudio em Hz.Valores válidos: 8000, 16000, 22050 (padrão), 24000, 44100, 48000.
ratefloatNãoA velocidade da fala.Valor padrão: 1.0.Valores válidos: [0.5, 2.0].
pitchfloatNãoO tom.Valor padrão: 1.0.Valores válidos: [0.5, 2.0].
bit_rateintNãoA 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_ssmlbooleanNãoSe deve ativar o SSML.Padrão: false.
  • true: ativado.
  • false: desativado.
Para as restrições de uso do SSML (modelos, vozes e APIs suportados), consulte Limitações.
word_timestamp_enabledbooleanNãoEspecifica 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 INativeStreamInputTtsCallback.
seedintNãoUma 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_hintsString[]Não
  • Este parâmetro é um array, mas a versão atual processa apenas o primeiro elemento. Passe um único valor.
  • Este parâmetro especifica o idioma de destino para a síntese de fala. Não está relacionado ao idioma da amostra de áudio usada na clonagem de voz. Para definir o idioma de origem para uma tarefa de clonagem, consulte a referência da API de clonagem de voz.
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:
  • Pronúncia inesperada de dígitos: "hello, this is 110" é lido como "hello, this is one zero" em vez da pronúncia chinesa esperada
  • Pronúncia imprecisa de símbolos: "@" é lido como o equivalente em chinês em vez de "at"
  • Baixa qualidade de síntese em idiomas minoritários com resultados não naturais
  • 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
instructionStringNãoControla 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_tagbooleanNãoEspecifica 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_propagatorStringNãoDefine 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_idStringNãoDefine 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_fixobjectNãoConfiguraçã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.
Campos:
  • pronunciation: Especifica anotações de pinyin para palavras cuja pronúncia padrão precisa de correção.
  • replace: Substitui palavras especificadas antes da síntese. O texto de substituição é usado como a entrada real da síntese.
Exemplo:
"hot_fix": {
  "pronunciation": [
    {"天气": "tian1 qi4"}
  ],
  "replace": [
    {"今天": "金天"}
  ]
}
enable_markdown_filterbooleanNão
Apenas as vozes clonadas do cosyvoice-v3-flash suportam este recurso.
Se deve filtrar a marcação Markdown do texto de entrada antes da síntese para que a marcação não seja lida em voz alta.Padrão: false.Valores válidos:
  • true: Ativar filtragem de Markdown.
  • false: Desativar filtragem de Markdown.

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:
public synchronized int sendStreamInputTts(String text)
Parâmetros:
ParâmetroTipoDescrição
textStringTexto 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.
Valor de retorno: Retorna um código de erro.

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:
public synchronized int stopStreamInputTts()
Valor de retorno: Retorna um código de erro.

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:
public synchronized int asyncStopStreamInputTts()
Valor de retorno: Retorna um código de erro.

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:
public synchronized int cancelStreamInputTts()
Valor de retorno: Retorna um código de erro.

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:
public synchronized int playStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
Parâmetros: O callback, ticket e outros parâmetros compartilhados têm o mesmo significado que em startStreamInputTts.
ParâmetroTipoDescrição
textStringTexto a ser sintetizado. Suporta SSML.
Valor de retorno: Retorna um código de erro.

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:
public synchronized int asyncPlayStreamInputTts(INativeStreamInputTtsCallback callback,
                                           String ticket,
                                           String parameters,
                                           String text,
                                           String session_id,
                                           int log_level,
                                           boolean save_log)
Parâmetros: O callback, ticket e outros parâmetros compartilhados têm o mesmo significado que em startStreamInputTts.
ParâmetroTipoDescrição
textStringTexto a ser sintetizado. Suporta SSML.
Valor de retorno: Retorna um código de erro.

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:
void onStreamInputTtsEventCallback(StreamInputTtsEvent event,
                                   String task_id,
                                   String session_id,
                                   int ret_code,
                                   String error_msg,
                                   String timestamp,
                                   String all_response);
Parâmetros:
ParâmetroTipoDescrição
eventStreamInputTtsEventO evento entregue.
task_idStringO ID da tarefa de síntese.
session_idStringO ID da sessão. Retornado conforme fornecido pelo cliente; gerado pelo servidor se omitido.
ret_codeintCódigo de erro. Válido apenas com o evento STREAM_INPUT_TTS_EVENT_TASK_FAILED.
error_msgStringMensagem de erro. Válido apenas com o evento STREAM_INPUT_TTS_EVENT_TASK_FAILED.
timestampStringInformações de timestamp para o resultado da síntese.
all_responseStringA 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:
void onStreamInputTtsDataCallback(byte[] data);
Parâmetros:
ParâmetroTipoDescrição
databyte[]Dados de áudio para o segmento atual. Use-os para:
  • Monte um arquivo de áudio completo e reproduza-o.
  • Reproduza-o em tempo real com um player compatível com streaming.
Observações:
  • Para formatos compactados como mp3 e opus, a reprodução segmentada requer um player de streaming. A decodificação pode falhar se você reproduzir os segmentos quadro a quadro.
  • Para montar um arquivo completo, abra-o no modo de anexar e grave cada segmento em ordem.
  • Para wav e mp3, apenas a primeira invocação de onStreamInputTtsDataCallback contém o cabeçalho do arquivo. As invocações subsequentes contêm áudio bruto. Concatene todos os blocos buffer em ordem. Para opus, cada quadro é uma página Ogg autônoma e pode ser concatenada diretamente.

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:
default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent

Enumeração de tipos de evento para a síntese de fala em streaming do CosyVoice.
EventoDescrição
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDO 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_SYNTHESISInformações de tempo de execução sobre a síntese, incluindo dados de faturamento.
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEO 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_FAILEDA tarefa falhou. Leia o campo all_response de INativeStreamInputTtsCallback para task_id, error_code e error_message para identificar a causa.
{
    "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. 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.
  2. 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 de android_libs e os cabeçalhos de android_include dentro 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

ModoDescrição
Entrada de texto únicaEtapas:
  1. Inicialize o SDK e os componentes do player.
  2. Configure os parâmetros para o seu cenário.
  3. Chame playStreamInputTts ou asyncPlayStreamInputTts para enviar o texto e iniciar a síntese.
  4. Receba o evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — a síntese está concluída.
Casos de uso:
  • Síntese de texto curto
  • Cenários que requerem marcação SSML
Entrada de texto em streamingEtapas:
  1. Inicialize o SDK e os componentes do player.
  2. Configure os parâmetros para o seu cenário.
  3. Chame startStreamInputTts para iniciar a síntese em streaming.
  4. Chame sendStreamInputTts para enviar texto continuamente à medida que estiver disponível.
  5. Receba dados de áudio binários em onStreamInputTtsDataCallback.
  6. Chame stopStreamInputTts ou asyncStopStreamInputTts para encerrar a entrada e aguardar a conclusão da síntese.
  7. Receba o evento STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — a síntese está concluída.
Casos de uso:
  • Conversação em tempo real e cenários de formato longo "fale enquanto avança"
  • A marcação SSML não é suportada neste modo

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).