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.
playStreamInputTts()ouasyncPlayStreamInputTts()— 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.onStreamInputTtsDataCallback()— Receber dados de áudio.TTS_EVENT_SYNTHESIS_COMPLETE— Síntese concluída.
startStreamInputTts()— Inicializa o SDK e define o delegate de callback e os parâmetros de conexão.sendStreamInputTts()— Envia continuamente fragmentos de texto a serem sintetizados.onStreamInputTtsDataCallback()— Receber dados de áudio.stopStreamInputTts()ouasyncStopStreamInputTts()— 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.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
| Parâmetro | Tipo | Descrição |
|---|---|---|
ticket | char* | String JSON que contém configurações de autenticação, conexão e depuração. |
parameters | char* | String JSON que contém as configurações de efeito de síntese de fala. |
sessionId | char* | ID de sessão especificado pelo cliente. Se omitido, o servidor gera um. |
logLevel | NuiSdkLogLevel | Nível de impressão para os logs internos do SDK. |
saveLog | BOOL | Se 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. |
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | string | Sim | Chave 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_id | string | Sim | Identificador 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_ms | int | Não | Tempo 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_path | string | Não | Caminho 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_size | int | Não | Tamanho 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_level | int | Não | Nível de filtro para logs entregues através do callback de log (onStreamInputTtsLogTrackCallback).Padrão: 2.Valores válidos:
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. |
| Campo | 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 | BOOL | Não | Se 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. |
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 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 |
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 | array[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. |
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. |
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. |
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.Campos:
|
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. SSML não é suportado. As tags SSML na entrada são lidas como texto simples em vez de serem analisadas. |
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
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
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
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
ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. Suporta SSML. |
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
ticket, parameters e outros parâmetros compartilhados usam as mesmas definições de startStreamInputTts.
| Parâmetro | Tipo | Descrição |
|---|---|---|
text | char* | Texto a ser sintetizado. Suporta SSML. |
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
| Parâmetro | Tipo | Descrição |
|---|---|---|
event | StreamInputTtsCallbackEvent | Evento de callback. |
taskid | char* | ID da tarefa de síntese de fala. |
sessionId | char* | ID da sessão. O valor fornecido pelo cliente é retornado como está. Se none for fornecido, o servidor gera um. |
ret_code | int | Código de erro. Válido apenas para o evento TTS_EVENT_TASK_FAILED. Consulte os códigos de erro. |
error_msg | char* | Mensagem de erro. Válida apenas para o evento TTS_EVENT_TASK_FAILED. |
timestamp | char* | Informações de timestamp para o resultado da síntese. |
all_response | char* | 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
buffer | char* | Dados de áudio para o segmento atual. Use estes dados para:
|
len | int | Comprimento 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
| Parâmetro | Tipo | Descrição |
|---|---|---|
level | NuiSdkLogLevel | Nível de log. |
log | char* | Conteúdo do log. |
StreamInputTtsCallbackEvent
Enumeração de tipo de evento para síntese de fala em streaming do Qwen-Audio-TTS.
| Evento | Descrição |
|---|---|
TTS_EVENT_SYNTHESIS_STARTED | O 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_SYNTHESIS | Informações de progresso emitidas durante a síntese, incluindo dados de faturamento. |
TTS_EVENT_SYNTHESIS_COMPLETE | O 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_FAILED | A tarefa falhou. Leia task_id, error_code e error_message de all_response em onStreamInputTtsEventCallback para diagnosticar a falha. |
NuiSdkLogLevel
Enumeração de nível de log do SDK que controla a saída de log.
| Nível | Descrição |
|---|---|
| 0: LOG_LEVEL_VERBOSE | Nível de log mais detalhado. Inclui todas as informações de depuração. |
| 1: LOG_LEVEL_DEBUG | Logs de nível de depuração. |
| 2: LOG_LEVEL_INFO | Logs informativos gerais (padrão). |
| 3: LOG_LEVEL_WARNING | Logs de nível de aviso. |
| 4: LOG_LEVEL_ERROR | Logs de nível de erro. |
| 5: LOG_LEVEL_NONE | Desativa a saída de log. |
Código de exemplo
- 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.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- Extraia o arquivo ZIP e adicione
nuisdk.frameworkao seu projeto Xcode. - Em Build Phases > Link Binary With Libraries, adicione
nuisdk.framework. - Em General > Frameworks, Libraries, and Embedded Content, defina
nuisdk.frameworkcomo 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 chamada | Descrição |
|---|---|
| Entrada única | Etapas:
|
Entrada em streaming | Etapas:
|
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).