Qwen-Audio-TTS/CosyVoice SDK Android

Converta texto em fala expressiva e de alta qualidade em seu aplicativo Android com o Qwen-Audio-TTS/CosyVoice SDK de conversão de texto em fala (TTS).

Guia do usuário: Para obter visões gerais dos modelos e seleção de voz, consulte Modelos de conversão de texto em fala.

NativeNui

O SDK oferece suporte a várias instâncias NativeNui e usa retornos de chamada 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).
• Acionado por retorno de chamada: Receba eventos e dados de áudio por meio do INativeStreamInputTtsCallback interface.
• Tipos de eventos:
  • 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

Qwen-Audio-TTS/CosyVoice suporta dois modos de invocação: entrada única e entrada de streaming.

A entrada única é adequada para textos curtos e qualquer cenário que use marcação SSML.

1. playStreamInputTts() ou asyncPlayStreamInputTts() — enviar texto completo e iniciar 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 iniciar a síntese.
2. onStreamInputTtsDataCallback() — recebe dados de áudio.
3. STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE — a síntese está completa.

A entrada de streaming é adequada para conversas em tempo real e cenários longos do tipo "fale conforme você avança". SSML não é suportado neste modo.

1. startStreamInputTts() — inicialize o SDK e configure o retorno de chamada e os parâmetros de conexão.
2. sendStreamInputTts() — envia texto continuamente assim que estiver disponível.
3. onStreamInputTtsDataCallback() — recebe dados de áudio.
4. stopStreamInputTts() ou asyncStopStreamInputTts() — envie 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á completa.

startStreamInputTts

Inicia a síntese de streaming bidirecional, abre a conexão com o serviço e registra o retorno de chamada para eventos e dados de áudio.

Este método pode bloquear. Chame-o em um thread que não seja da 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:

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 registro em log). | | save_log | boolean | Se os logs devem ser gravados em um arquivo local. Se for verdade, defina debug_path no bilhete para especificar o destino e, opcionalmente, definir max_log_file_size para limitar o tamanho do arquivo. |

Valor de retorno:

Retorna um código de erro.

exemplo JSON de ticket:

{
    "url": "wss://maas.qwencloudapi.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id"
}

parâmetros do ticket:

Padrão: 10.000. | | debug_path | String | Não | O caminho local onde os arquivos de log são gravados.

Este parâmetro entra em vigor somente quando save_log é definido como verdadeiro para startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, o caminho é obrigatório; caso contrário, a chamada retornará 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 entra em vigor somente quando save_log é definido como verdadeiro 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 entregues por meio do retorno de chamada 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 registro em log).

Nota: log_track_level trabalha junto com log_level (definido em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) para decidir quais logs alcançam o retorno de chamada. Uma entrada de registro deve estar no mesmo nível ou acima de ambos log_track_level e log_level para ser entregue. Por exemplo, se log_track_level é 2 (INFO) e log_level for 3 (WARNING), apenas WARNING e acima (nível >= 3) alcançam o retorno de chamada. |

exemplo JSON de parâmetros:

{
    "model": "qwen-audio-3.0-tts-flash",
    "voice": "longanlingxi",
    "format": "mp3",
    "volume": 50,
    "rate": 1.0,
    "pitch": 1.0
}

referência de parâmetros:

<ul><li>Vozes do sistema: consulte Qwen-Audio-TTS lista de vozes, CosyVoice lista de vozes</li><li>Vozes clonadas: vozes personalizadas criadas por meio de clonagem de voz</li><li>Vozes personalizadas: vozes personalizadas criadas através do design de voz</li></ul> | | format | String | Não | O formato de codificação de áudio.

Valores válidos:

<ul><li>PCM</li><li>wav</li><li>mp3 (padrão)</li><li>obra</li></ul> | | enable_audio_decoder | boolean | Não | Se o decodificador interno do SDK deve ser habilitado. Padrão: falso.

Este parâmetro só entra em vigor quando o formato de codificação de áudio é opus ou mp3. Quando ativado, 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: 8.000, 16.000, 22.050 (padrão), 24.000, 44100, 48.000. | | 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 campo.

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: falso.

<ul><li>verdadeiro: habilitado.</li><li>falso: desativado.</li></ul> Para as restrições de uso de SSML (modelos, vozes e APIs compatíveis), consulte Limitações. | | word_timestamp_enabled | boolean | Não | Especifica se os carimbos de data/hora em nível de palavra devem ser ativados.

Valor padrão: falso.

Disponível apenas no modo de saída de streaming. Vozes suportadas: vozes clonadas de qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flashe cosyvoice-v3-pluse vozes do sistema marcadas como suportadas em Qwen-Audio-TTS lista de vozes, CosyVoice lista de vozes. Vozes clonadas de outros modelos não suportam esse recurso.

Nota: Os carimbos de data e hora do Word são retornados no campo all_response de INativeStreamInputTtsCallback. | | 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, o texto, a voz e outros parâmetros permanecem inalterados, o uso da 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 síntese de fala para melhorar a qualidade da saída.

Nota: 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 alvo para 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.

Quando a pronúncia de dígitos, a expansão de abreviações, a leitura de símbolos ou a síntese de idiomas minoritários não atenderem às expectativas, use este parâmetro. Por exemplo:

<ul><li>Pronúncia inesperada de dígitos: "olá, aqui é 110" é lida como "olá, aqui é um zero" em vez da pronúncia chinesa esperada</li><li>Pronúncia imprecisa do símbolo: "@" é lido como o equivalente chinês em vez de "at"</li><li>Baixa qualidade de síntese de linguagem secundária com resultados não naturais</li></ul> Valores válidos: 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). | | instruction | String | Não | Controla características de síntese, como dialeto, emoção ou estilo de fala.

Para obter detalhes de uso, consulte Controle de instruções. | | enable_aigc_tag | boolean | Não | Especifica se uma marca d'água AIGC deve ser incorporada no áudio gerado. Quando definida como verdadeira, a marca d'água é incorporada em arquivos de áudio de formatos suportados (wav/mp3/opus).

Valor padrão: falso.

Somente qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flashe cosyvoice-v3-plus suporte a esse recurso. | | aigc_propagator | String | Não | Define o ContentPropagator campo na marca d’água AIGC, identificando o propagador do conteúdo. Só entra em vigor quando enable_aigc_tag é true.

Valor padrão: UID.

Somente qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flashe cosyvoice-v3-plus suporte a esse recurso. | | aigc_propagate_id | String | Não | Define o PropagateID campo na marca d'água AIGC, identificando exclusivamente uma ação de propagação específica. Só entra em vigor quando enable_aigc_tag é true.

Valor padrão: O ID da solicitação de síntese de fala atual.

Somente qwen-audio-3.0-tts-plus, qwen-audio-3.0-tts-flash, cosyvoice-v3-flashe cosyvoice-v3-plus suporte a esse recurso. | | hot_fix | object | Não | Configuração de hot-fix de texto para personalizar a pronúncia de palavras específicas ou substituir texto antes da síntese.

Campos:

<ul><li>pronúncia: especifica anotações pinyin para palavras cuja pronúncia padrão precisa de correção.</li><li>substituir: Substitui palavras especificadas antes da síntese. O texto de substituição é usado como entrada de síntese real.</li></ul> Exemplo: {"hot_fix": {"pronunciation": [{"天气": "tian1 qi4"}], "replace": [{"今天": "金天"}]}} | | enable_markdown_filter | boolean | Não | Se a marcação Markdown deve ser filtrada do texto de entrada antes da síntese, para que a marcação não seja falada em voz alta.

Nota: Apenas vozes clonadas de cosyvoice-v3-flash suporte a esse recurso.

Padrão: falso.

Valores válidos:

<ul><li>true: Habilite a filtragem Markdown.</li><li>false: Desativa a filtragem Markdown.</li></ul> |

sendStreamInputTts

Envia texto para ser sintetizado. Use este método junto com startStreamInputTts.

Depois de chamar startStreamInputTts, chame esse método para enviar texto continuamente.

Depois de enviar todo o texto, chame stopStreamInputTts ou asyncStopStreamInputTts para finalizar a entrada.

Assinatura do método:

public synchronized int sendStreamInputTts(String text)

Parâmetros:

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 STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE o evento é 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 STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE evento para detectar quando a síntese é concluída.

Assinatura do método:

public synchronized int asyncStopStreamInputTts()

Valor de retorno:

Retorna um código de erro.

cancelarStreamInputTts

Fecha imediatamente a conexão com o servidor e aborta a tarefa de síntese atual. Nenhum outro retorno de chamada de áudio será 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 síncrona one-shot. A chamada envia o texto, bloqueia enquanto o áudio é recebido e retorna somente após a síntese ser concluída. Você não precisa chamar o método stop depois.

SSML está habilitado por padrão para este método. Para substituir, defina enable_ssml explicitamente.

Chame esse método em um thread que não seja da 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 retorno de chamada, ticket e outros parâmetros compartilhados têm o mesmo significado que em startStreamInputTts.

Valor de retorno:

Retorna um código de erro.

asyncPlayStreamInputTts

Método de síntese assíncrona one-shot. A chamada retorna imediatamente, a síntese é executada em segundo plano e os resultados são entregues por meio do retorno de chamada. Você não precisa chamar o método stop depois.

SSML está 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 retorno de chamada, ticket e outros parâmetros compartilhados têm o mesmo significado que em startStreamInputTts.

Valor de retorno:

Retorna um código de erro.

INativeStreamInputTtsCallback

O Qwen-Audio-TTS/CosyVoice a interface de retorno de chamada TTS de streaming fornece eventos de síntese, dados de áudio e registros.

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:

onStreamInputTtsDataCallback: recebe dados de áudio

O SDK invoca esse retorno de chamada repetidamente durante a síntese. Leia os dados de áudio do retorno de chamada.

Assinatura do método:

void onStreamInputTtsDataCallback(byte[] data);

Parâmetros:

<ul><li>Monte um arquivo de áudio completo e reproduza-o.</li><li>Jogue em tempo real com um player compatível com streaming.</li></ul> Notas:

<ul><li>Para formatos compactados como mp3 e opus, a reprodução segmentada requer um reprodutor de streaming. A decodificação poderá falhar se você reproduzir os segmentos quadro a quadro.</li><li>Para montar um arquivo completo, abra-o no modo anexar e escreva cada segmento em ordem.</li><li>Para wav e mp3, apenas a primeira invocação onStreamInputTtsDataCallback contém o cabeçalho do arquivo. As invocações subsequentes carregam áudio bruto. Concatene todos os buffer pedaços em ordem. Para opus, cada quadro é uma página Ogg independente e pode ser concatenada diretamente.</li></ul> |

onStreamInputTtsLogTrackCallback: recebe logs de rastreamento

Use esse retorno de chamada para receber logs internos detalhados do SDK, o que ajuda na solução de problemas e na depuração.

Assinatura do método:

default void onStreamInputTtsLogTrackCallback(Constants.LogLevel level, String log)

StreamInputTtsEvent

Enumeração de tipo de evento para Qwen-Audio-TTS/CosyVoice streaming de síntese de fala.

Exemplo de resposta com 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. Obter uma chave de API: Obter uma chave de API. Por segurança, armazene a chave de API em uma variável de ambiente.

   Use uma chave de API temporária quando você precisar conceder acesso temporário a um aplicativo ou usuário de terceiros ou quando você want para controlar rigorosamente operações de alto risco, como acesso ou exclusão de 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 SDK mais recente.
   • Descompacte o pacote. O SDK em formato AAR está em app/libs - adicione-o às dependências do seu projeto. Para integração com Android C++, obtenha as bibliotecas compartilhadas em 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 DashQwen-Audio-TTS/CosyVoiceStreamTtsActivity.java — substitua a chave API pela sua própria para experimentar o recurso.

Modos de invocação

<ol><li>Inicialize o SDK e os componentes do player.</li><li>Configure os parâmetros para o seu cenário.</li><li>Chame playStreamInputTts ou asyncPlayStreamInputTts submeter o texto e iniciar a síntese.</li><li>Receba o STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE evento – a síntese está completa.</li></ol> Casos de uso:

<ul><li>Síntese de texto curto</li><li>Cenários que exigem marcação SSML</li></ul> | | Entrada de texto por streaming | Etapas:

<ol><li>Inicialize o SDK e os componentes do player.</li><li>Configure os parâmetros para o seu cenário.</li><li>Ligar startStreamInputTts para iniciar a síntese de streaming.</li><li>Ligar sendStreamInputTts para enviar texto continuamente à medida que estiver disponível.</li><li>Receba dados de áudio binários em onStreamInputTtsDataCallback.</li><li>Ligar stopStreamInputTts ou asyncStopStreamInputTts para finalizar a entrada e aguardar o término da síntese.</li><li>Receba o STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE evento – a síntese está completa.</li></ol> Casos de uso:

<ul><li>Conversa em tempo real e cenários longos do tipo "fale conforme você avança"</li><li>A marcação SSML não é suportada neste modo</li></ul> |

Recursos avançados

Marcação SSML

Objetivo: Incorpore tags XML no texto para ajustar a pronúncia, a velocidade de fala, as pausas e outros detalhes prosódicos.

Limitações: SSML é compatível apenas com entrada de texto única (o playStreamInputTts ou asyncPlayStreamInputTts métodos). Streaming de entrada de texto (o sendStreamInputTts método) não oferece suporte a SSML.

Uso: Quando você chama playStreamInputTts ou asyncPlayStreamInputTts, o SDK ativa o SSML automaticamente. Passe o texto que contém tags SSML através do text parâmetro.

Para obter mais informações, consulte SSML.

Expressões matemáticas

Objetivo: 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 text parâmetro. Para obter mais informações, consulte Converter fórmulas LaTeX em fala (apenas idioma chinês).