Skip to main content

Qwen-Audio-TTS iOS SDK

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

NeoNui

Destaques da arquitetura:
  • Padrão Singleton: obtenha a instância global através de [StreamInputTts get_instance].
  • Orientado a callbacks: receba eventos e dados de áudio através do protocolo StreamInputTtsDelegate.
  • Configuração JSON: passe os parâmetros como strings JSON.

Fluxos de chamada

Qwen-Audio-TTS suporta dois modos de invocação: entrada única e entrada em streaming. Entrada única: ideal para síntese de texto curto ou quando você precisa de marcação SSML.
  1. playStreamInputTts() ou asyncPlayStreamInputTts() — Envia um texto completo e inicia a síntese. O primeiro é síncrono e retorna após a conclusão 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. TTS_EVENT_SYNTHESIS_COMPLETE — Síntese concluída.
Entrada em streaming: ideal para conversas em tempo real ou cenários de "falar enquanto sintetiza" de forma longa. Este modo não oferece suporte à marcação SSML.
  1. startStreamInputTts() — Inicializa o SDK e define o delegate de callback e os parâmetros de conexão.
  2. sendStreamInputTts() — Envia continuamente fragmentos de texto a serem sintetizados.
  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 a conclusão 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 em 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
ParâmetroTipoDescrição
ticketchar*String JSON que contém configurações de autenticação, conexão e depuração.
parameterschar*String JSON que contém as configurações de efeito de síntese de fala.
sessionIdchar*ID de sessão especificado pelo cliente. Se omitido, o servidor gera um.
logLevelNuiSdkLogLevelNível de impressão para os logs internos do SDK.
saveLogBOOLSe deve salvar logs localmente. Quando definido como YES, você deve especificar um caminho com debug_path e pode limitar o tamanho do arquivo com max_log_file_size.
Valor de retorno Retorna um código de erro. Exemplo de JSON de ticket: O exemplo a seguir não lista todos os campos. Adicione os outros conforme seu código exigir:
{
  "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
  "apikey": "st-****",
  "device_id": "my_device_id"
}
campos de ticket
CampoTipoObrigató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.
apikeystringSimChave de API. Para limitar a exposição caso uma chave de longa duração vaze, use uma chave de API de curta duração.
device_idstringSimIdentificador exclusivo para o usuário final. Defina isso como o ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. O ID é usado para rastreamento de logs e solução de problemas.
complete_waiting_msintNãoTempo limite, em milissegundos, para aguardar o evento de conclusão da síntese (TTS_EVENT_SYNTHESIS_COMPLETE) após chamar stopStreamInputTts.Padrão: 10000.
debug_pathstringNãoCaminho local onde os arquivos de log são armazenados.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts. Nesse caso, você deve definir este caminho; caso contrário, um erro é retornado.No máximo dois arquivos de log são mantidos localmente.
max_log_file_sizeintNãoTamanho máximo de um arquivo de log, em bytes.Este campo só entra em vigor quando saveLog é definido como YES em startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts.Padrão: 104857600 (100 × 1024 × 1024 bytes, ou seja, 100 MiB).
log_track_levelintNãoNível de filtro para logs 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 callback)
Nota: log_track_level e logLevel (definidos por meio de startStreamInputTts, playStreamInputTts ou asyncPlayStreamInputTts) juntos determinam quais logs chegam ao callback. Um log aciona o callback apenas quando seu nível está igual ou acima de ambos os limites. Por exemplo, se log_track_level for 2 (INFO) e logLevel for 3 (WARNING), apenas logs no nível WARNING ou superior (nível >= 3) são entregues.
Exemplo de 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
CampoTipoObrigatórioDescrição
modelstringSimO nome do modelo.
voicestringSimA voz usada para a síntese de fala.
  • Vozes do sistema: Consulte a lista de vozes do Qwen-Audio-TTS
  • 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_decoderBOOLNãoSe deve ativar o decodificador interno do SDK. Padrão: NO.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 clonadas são suportadas. Para as vozes do sistema compatíveis, consulte lista de vozes do Qwen-Audio-TTS.
Os carimbos de data/hora são retornados em all_response de onStreamInputTtsEventCallback.
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_hintsarray[string]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
  • other: Outros idiomas (compatíveis com qwen-audio-3.1-tts-flash) búlgaro, holandês, húngaro, romeno, dinamarquês, croata, grego, tcheco, norueguês, sueco, hindi, eslovaco, finlandês, urdu, sérvio, espanhol (México), lituano, letão, turco, persa, hebraico, mongol, esloveno, azerbaijano, polonês, catalão, khmer, português (Brasil), laosiano, georgiano, africâner, nepalês, bielorrusso, malaiala, luxemburguês, albanês, tâmil, cingalês, télugo, estoniano, cebuano, bósnio, birmanês, armênio, latim, islandês, maltês, suaíli, cazaque, crioulo francês seichelense, ucraniano.
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.
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.
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.
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.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": [
    {"今天": "金天"}
  ]
}

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
ParâmetroTipoDescrição
textchar*Texto a ser sintetizado. SSML não é suportado. As tags SSML na entrada são lidas como texto simples em vez de serem analisadas.
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 bloco de áudio seja sintetizado e TTS_EVENT_SYNTHESIS_COMPLETE seja recebido. O tempo limite de bloqueio é 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 de 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.

cancelStreamInputTts

Encerra imediatamente a conexão com o servidor e finaliza a tarefa de síntese atual. Após a chamada deste método, nenhum outro callback 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 de uma única vez. Envia o texto e bloqueia enquanto todos os dados de áudio são recebidos, e então retorna após a conclusão da síntese. Você não precisa chamar stopStreamInputTts depois. Este método habilita SSML por padrão. Para desabilitar o SSML, defina o campo enable_ssml em parameters como 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 Os parâmetros ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
ParâmetroTipoDescrição
textchar*Texto a ser sintetizado. Suporta SSML.
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 o SSML, defina o campo enable_ssml em parameters como 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 Os parâmetros ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
ParâmetroTipoDescrição
textchar*Texto a ser sintetizado. Suporta SSML.
Valor de retorno Retorna um código de erro.

StreamInputTtsDelegate

Protocolo de callback para síntese de fala em streaming do Qwen-Audio-TTS. Implemente este protocolo para receber eventos de síntese, dados de áudio e logs.

onStreamInputTtsEventCallback: ouvir 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
ParâmetroTipoDescrição
eventStreamInputTtsCallbackEventEvento de callback.
taskidchar*ID da tarefa de síntese de fala.
sessionIdchar*ID da sessão. O valor fornecido pelo cliente é retornado como está. Se none for fornecido, o servidor gera um.
ret_codeintCódigo de erro. Válido apenas para o evento TTS_EVENT_TASK_FAILED. Consulte os códigos de erro.
error_msgchar*Mensagem de erro. Válida apenas para o evento TTS_EVENT_TASK_FAILED.
timestampchar*Informações de timestamp para o resultado da síntese.
all_responsechar*Resposta JSON completa. Analise esta string para extrair os campos necessários.

onStreamInputTtsDataCallback: ouvir dados de áudio

O SDK aciona este callback repetidamente durante a síntese. Leia os dados de áudio do callback. Assinatura do método
- (void)onStreamInputTtsDataCallback:(char*)buffer len:(int)len;
Parâmetros
ParâmetroTipoDescrição
bufferchar*Dados de áudio para o segmento atual. Use estes dados para:
  • Monte um arquivo de áudio completo e reproduza-o.
  • Transmita os dados para um player que suporte reprodução em streaming.
Nota:
  • Para os formatos mp3 e opus compactados, use um player de streaming. Reproduzir segmentos quadro a quadro pode causar falhas de decodificação.
  • Ao montar um arquivo completo, anexe cada segmento ao mesmo arquivo.
  • Para os formatos wav e mp3, apenas a primeira invocação de onStreamInputTtsDataCallback inclui o cabeçalho do arquivo; as invocações subsequentes retornam dados de áudio brutos. Concatene todos os valores de buffer em ordem. Para o formato opus, cada quadro é uma página Ogg autônoma que você pode concatenar diretamente.
lenintComprimento dos dados de áudio, em bytes.

onStreamInputTtsLogTrackCallback: ouvir logs de rastreamento

Este callback entrega logs internos detalhados do SDK para ajudar na solução de problemas e depuração. Assinatura do método
- (void)onStreamInputTtsLogTrackCallback:(NuiSdkLogLevel)level
                            logMessage:(const char *)log;
Parâmetros
ParâmetroTipoDescrição
levelNuiSdkLogLevelNível de log.
logchar*Conteúdo do log.

StreamInputTtsCallbackEvent

Enumeração de tipo de evento para síntese de fala em streaming do Qwen-Audio-TTS.
EventoDescrição
TTS_EVENT_SYNTHESIS_STARTEDO servidor aceitou a solicitação e iniciou o processamento. onStreamInputTtsDataCallback normalmente entrega o primeiro segmento de áudio logo após este evento.
TTS_EVENT_SENTENCE_SYNTHESISInformações de progresso emitidas durante a síntese, incluindo dados de faturamento.
TTS_EVENT_SYNTHESIS_COMPLETEO servidor terminou de enviar todos os dados de áudio. onStreamInputTtsDataCallback não é chamado novamente. Este evento é o sinal definitivo de fim de stream.
TTS_EVENT_TASK_FAILEDA tarefa falhou. Leia task_id, error_code e error_message de all_response em onStreamInputTtsEventCallback para diagnosticar a falha.
{
        "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

Enumeração de nível de log do SDK que controla a saída de log.
NívelDescrição
0: LOG_LEVEL_VERBOSENível de log mais detalhado. Inclui todas as informações de depuração.
1: LOG_LEVEL_DEBUGLogs de nível de depuração.
2: LOG_LEVEL_INFOLogs informativos gerais (padrão).
3: LOG_LEVEL_WARNINGLogs de nível de aviso.
4: LOG_LEVEL_ERRORLogs de nível de erro.
5: LOG_LEVEL_NONEDesativa a saída de log.

Código de exemplo

  1. Obtenha sua chave de API: Obter uma chave de API.
Para aplicativos de terceiros ou usuários finais que precisam de acesso temporário, ou quando você want controle rigoroso sobre operações sensíveis, como acesso e exclusão de dados, use uma chave de API temporária. Uma chave de API temporária é válida por 60 segundos fixos e deve ser regenerada após a expiração.
  1. Baixe o SDK e execute o código de exemplo:
    • Baixe o pacote mais recente do SDK.
    • Extraia o arquivo ZIP e adicione nuisdk.framework ao seu projeto Xcode.
    • Em Build Phases > Link Binary With Libraries, adicione nuisdk.framework.
    • Em General > Frameworks, Libraries, and Embedded Content, defina nuisdk.framework como Embed & Sign.
    • Abra o projeto de exemplo no Xcode. O código de exemplo está em DashQwen-Audio-TTSStreamInputTTSViewController.m. Substitua a chave de API de espaço reservado pela sua própria e execute o aplicativo para testá-lo.

Modos de chamada

Modo de chamadaDescrição
Entrada únicaEtapas:
  1. Inicialize o SDK e o componente 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. Aguarde o callback TTS_EVENT_SYNTHESIS_COMPLETE, que sinaliza que a síntese foi concluída.
Casos de uso:
  • Síntese de texto curto.
  • Cenários que requerem marcação SSML.
Entrada em streamingEtapas:
  1. Inicialize o SDK e o componente 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 repetidamente para enviar texto em partes.
  5. Leia os dados de áudio binários de onStreamInputTtsDataCallback.
  6. Chame stopStreamInputTts ou asyncStopStreamInputTts para parar de enviar texto e aguardar o término da síntese.
  7. Aguarde o callback TTS_EVENT_SYNTHESIS_COMPLETE, que sinaliza que a síntese foi concluída.
Casos de uso:
  • Conversa em tempo real ou cenários de formato longo "fale enquanto sintetiza".
  • Este modo não suporta marcação SSML.

Recursos avançados

Marcação SSML

Objetivo: Incorporar tags XML no texto de entrada para controlar com precisão a pronúncia, a taxa de fala, as pausas e outros detalhes de prosódia. Limitações: O SSML é suportado apenas com Entrada única (os métodos playStreamInputTts e asyncPlayStreamInputTts). Não é suportado com Entrada em streaming (o método sendStreamInputTts). Como usar: Ao chamar playStreamInputTts ou asyncPlayStreamInputTts, o SDK habilita o SSML automaticamente. Passe o texto que contém tags SSML diretamente no parâmetro text. Para 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 parâmetro text. Para mais detalhes, consulte Converter fórmulas LaTeX em fala (apenas idioma chinês).