Qwen-Audio-TTS/CosyVoice iOS SDK

Use o Qwen-Audio-TTS/CosyVoice iOS SDK para transformar texto em fala expressiva de alta qualidade em seus aplicativos iOS.

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.

##NeoNui

Destaques da arquitetura:

• Padrão Singleton: obtém a instância global [StreamInputTts get_instance].
• Orientado por retorno de chamada: receba eventos e dados de áudio por meio do StreamInputTtsDelegate protocolo.
• Configuração JSON: passe parâmetros como strings JSON.

Fluxos de chamadas

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

Entrada única: melhor para síntese de texto curto ou quando você precisar de SSML marcação.

1. playStreamInputTts() ou asyncPlayStreamInputTts() — Envie um texto completo e inicie 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 iniciar a síntese.
2. onStreamInputTtsDataCallback() — Recebe dados de áudio.
3. TTS_EVENT_SYNTHESIS_COMPLETE — Síntese concluída.

Entrada de streaming: ideal para conversas em tempo real ou cenários longos de "fala enquanto sintetiza". Este modo não suporta SSML marcação.

1. startStreamInputTts() — Inicialize o SDK e defina o delegado de retorno de chamada e os parâmetros de conexão.
2. sendStreamInputTts() — Envia continuamente fragmentos de texto para serem sintetizados.
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. TTS_EVENT_SYNTHESIS_COMPLETE — Síntese concluída.

startStreamInputTts

Inicia uma tarefa de síntese de fala de streaming e abre uma conexão com o servidor.

Assinatura do método:

- (int) startStreamInputTts:(const char *)ticket parameters:(const char *)parameters sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

Parâmetros:

Valor de retorno:

Retorna um código de erro.

exemplo JSON de ticket: O exemplo a seguir não lista todos os campos. Adicione os outros conforme seu código exigir:

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

campos do ticket:

Padrão: 10.000. | | debug_path | string | Não | Caminho local onde os arquivos de log são armazenados.

Este campo só entra em vigor quando saveLog está definido para YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, você deve definir esse caminho; caso contrário, um erro será retornado.

No máximo dois arquivos de log são mantidos localmente. | | max_log_file_size | int | Não | Tamanho máximo de um arquivo de log, em bytes.

Este campo só entra em vigor quando saveLog está definido para YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts.

Padrão: 104857600 (100 × 1024 × 1024 bytes, ou seja, 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 retorno de chamada).

Nota: log_track_level e logLevel (definido através de startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) juntos determinam quais logs alcançam o retorno de chamada. Um log dispara o retorno de chamada somente quando seu nível está igual ou acima de ambos os limites. Por exemplo, se log_track_level é 2 (INFO) e logLevel for 3 (WARNING), somente logs em WARNING ou superior (nível >= 3) serão entregues. |

exemplo JSON de parâmetros: O exemplo a seguir não lista todos os campos. Adicione os outros conforme seu código exigir:

{
    "model": "qwen-audio-3.0-tts-flash",
    "voice": "longanlingxi",
    "format": "mp3",
    "sample_rate": 24000,
    "volume": 50,
    "rate": 1,
    "pitch": 1,
    "language_hints": ["zh"],
    "enable_ssml": false
}

campos 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 | BOOL | Não | Se o decodificador interno do SDK deve ser habilitado. Padrão: NO.

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 são retornados em all_response de onStreamInputTtsEventCallback. | | 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 | array[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 | BOOL | 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: NO.

Valores válidos:

<ul><li>YES: habilite a filtragem Markdown.</li><li>NO: desative a filtragem Markdown.</li></ul> |

sendStreamInputTts

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

Depois de chamar startStreamInputTts, use este método para enviar texto continuamente.

Depois que todo o texto for enviado, chame stopStreamInputTts ou asyncStopStreamInputTts para sinalizar o fim da entrada.

Assinatura do método:

- (int) sendStreamInputTts:(const char *)text;

Parâmetros:

Valor de retorno:

Retorna um código de erro.

stopStreamInputTts

Método síncrono. Notifica o servidor de que todo o texto foi enviado e, em seguida, bloqueia até que cada pedaço de áudio seja sintetizado e TTS_EVENT_SYNTHESIS_COMPLETE é recebido.

O tempo limite do bloco é controlado por complete_waiting_ms.

Assinatura do método:

- (int) stopStreamInputTts;

Valor de retorno:

Retorna um código de erro.

asyncStopStreamInputTts

Método assíncrono. Notifica o servidor que todo o texto foi enviado e retorna imediatamente. A síntese continua em segundo plano.

Use TTS_EVENT_SYNTHESIS_COMPLETE para detectar quando a síntese termina.

Assinatura do método:

- (int) asyncStopStreamInputTts;

Valor de retorno:

Retorna um código de erro.

cancelarStreamInputTts

Interrompe imediatamente a conexão com o servidor e encerra a tarefa de síntese atual. Depois que esse método é chamado, nenhum outro retorno de chamada de dados de áudio é acionado.

Assinatura do método:

- (int) cancelStreamInputTts;

Valor de retorno:

Retorna um código de erro.

###playStreamInputTts

Método de síntese síncrona one-shot. Envia o texto e bloqueia enquanto todos os dados de áudio são recebidos e retorna após o término da síntese. Você não precisa chamar stopStreamInputTts depois.

Este método habilita SSML por padrão. Para desabilitar SSML, defina o enable_ssml campo em parameters para false.

Assinatura do método:

- (int) playStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

Parâmetros:

O ticket, parameterse outros parâmetros compartilhados usam as mesmas definições que startStreamInputTts.

Valor de retorno:

Retorna um código de erro.

asyncPlayStreamInputTts

Este método envia todo o texto para síntese de forma assíncrona. Ele retorna imediatamente sem esperar pelos dados de áudio. Você não precisa chamar stopStreamInputTts depois.

Este método habilita SSML por padrão. Para desabilitar SSML, defina o enable_ssml campo em parameters para false.

Assinatura do método:

- (int) asyncPlayStreamInputTts:(const char *)ticket parameters:(const char *)parameters text:(const char *)text sessionId:(const char *)sessionId logLevel:(NuiSdkLogLevel)logLevel saveLog:(BOOL)saveLog;

Parâmetros:

O ticket, parameterse outros parâmetros compartilhados usam as mesmas definições que startStreamInputTts.

Valor de retorno:

Retorna um código de erro.

StreamInputTtsDelegate

Protocolo de retorno de chamada para Qwen-Audio-TTS/CosyVoice streaming de síntese de fala. Implemente este protocolo para receber eventos de síntese, dados de áudio e logs.

onStreamInputTtsEventCallback: escuta eventos

Assinatura do método:

- (void)onStreamInputTtsEventCallback:(StreamInputTtsCallbackEvent)event taskId:(char*)taskid sessionId:(char*)sessionId ret_code:(int)ret_code error_msg:(char*)error_msg timestamp:(char*)timestamp all_response:(char*)all_response;

Parâmetros:

onStreamInputTtsDataCallback: ouça dados de áudio

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

Assinatura do método:

- (void)onStreamInputTtsDataCallback:(char*)buffer len:(int)len;

Parâmetros:

<ul><li>Monte um arquivo de áudio completo e reproduza-o.</li><li>Transmita os dados para um player que suporte reprodução de streaming.</li></ul> Nota:

<ul><li>Para os formatos compactados mp3 e opus, use um reprodutor de streaming. A reprodução de segmentos quadro a quadro pode causar falhas de decodificação.</li><li>Ao montar um arquivo completo, anexe cada segmento ao mesmo arquivo.</li><li>Para os formatos wav e mp3, apenas a primeira invocação onStreamInputTtsDataCallback inclui o cabeçalho do arquivo; invocações posteriores retornam dados de áudio brutos. Concatenar tudo buffer valores em ordem. Para o formato opus, cada quadro é uma página Ogg independente que você pode concatenar diretamente.</li></ul> | | len | int | Comprimento dos dados de áudio, em bytes. |

onStreamInputTtsLogTrackCallback: escuta logs de rastreamento

Esse retorno de chamada fornece logs internos do SDK detalhados para ajudar na solução de problemas e na depuração.

Assinatura do método:

- (void)onStreamInputTtsLogTrackCallback:(NuiSdkLogLevel)level
                              logMessage:(const char *)log;

Parâmetros:

StreamInputTtsCallbackEvent

Enum 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": {}
      }

NuiSdkLogLevel

Enum de nível de log do SDK que controla a saída do log.

Código de exemplo

1. Obtenha sua chave de API: Obtenha uma chave de API.

   Para aplicativos de terceiros ou usuários finais que precisam de acesso temporário ou quando você want controle rígido sobre operações confidenciais, como acesso e exclusão de dados, use uma chave de API temporária em vez disso. Uma chave de API temporária é válida por um período fixo de 60 segundos e deve ser regenerada após expirar.

2. Baixe o SDK e execute o código de exemplo:

   • Baixe o pacote SDK mais recente.
   • Extraia o arquivo ZIP e adicione nuisdk.framework ao seu projeto Xcode.
   • Em Fases de construção > Vincular binário a bibliotecas, adicione nuisdk.framework.
   • Em Geral > Frameworks, Bibliotecas e Conteúdo Incorporado, defina nuisdk.framework para Incorporar e assinar.
   • Abra o projeto de amostra no Xcode. O código de exemplo está em DashQwen-Audio-TTS/CosyVoiceStreamInputTTSViewController.m. Substitua a chave de API do espaço reservado pela sua e execute o aplicativo para testá-lo.

Modos de chamada

<ol><li>Inicialize o SDK e o componente do player.</li><li>Configure os parâmetros para o seu cenário.</li><li>Ligar playStreamInputTts ou asyncPlayStreamInputTts para enviar o texto e iniciar a síntese.</li><li>Espere pelo TTS_EVENT_SYNTHESIS_COMPLETE retorno de chamada, que sinaliza que a síntese foi concluída.</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 streaming | Etapas:

<ol><li>Inicialize o SDK e o componente 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 repetidamente para enviar texto em pedaços.</li><li>Leia os dados binários de áudio de onStreamInputTtsDataCallback.</li><li>Ligar stopStreamInputTts ou asyncStopStreamInputTts para parar de enviar texto e aguardar o término da síntese.</li><li>Espere pelo TTS_EVENT_SYNTHESIS_COMPLETE retorno de chamada, que sinaliza que a síntese foi concluída.</li></ol> Casos de uso:

<ul><li>Conversa em tempo real ou cenários longos do tipo "fale enquanto sintetiza".</li><li>Este modo não oferece suporte à marcação SSML.</li></ul> |

Recursos avançados

Marcação SSML

Objetivo: Incorpore tags XML no texto de entrada para controlar com precisão a pronúncia, a velocidade da fala, as pausas e outros detalhes da prosódia.

Limitações: SSML é compatível apenas com entrada única (o playStreamInputTts e asyncPlayStreamInputTts métodos). Não é compatível com entrada de streaming (o sendStreamInputTts método).

Como usar: Quando você chama playStreamInputTts ou asyncPlayStreamInputTts, o SDK ativa o SSML automaticamente. Passe o texto que contém tags SSML diretamente no text parâmetro.

Para obter mais detalhes, consulte SSML.

Expressões matemáticas

Objetivo: Fazer com que o modelo leia fórmulas e expressões matemáticas comuns corretamente.

Como usar: Passe o texto que contém expressões matemáticas no formato LaTeX diretamente no text parâmetro. Para obter mais detalhes, consulte Converter fórmulas LaTeX em fala (apenas idioma chinês).