Conheça os parâmetros, as interfaces, os callbacks e o uso do SDK iOS para Fun-ASR-Realtime.
Início rápido
- Obter uma chave de API: Obter uma chave de API
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote mais recente do SDK.
- Extraia o pacote ZIP e adicione o arquivo
nuisdk.xcframeworkincluído ao projeto. - Em Build Phases → Link Binary With Libraries, adicione
nuisdk.xcframework. - Em General → Frameworks, Libraries, and Embedded Content, defina
nuisdk.xcframeworkcomo Embed & Sign. - Abra o projeto de exemplo no Xcode. O código está em
DashFunAsrSpeechTranscriberViewController.m. Substitua a chave de API pela sua para testar o recurso.
Sequência de chamadas
- Inicialize o SDK.
- Configure os parâmetros conforme seu caso de uso: use
nui_initializepara os parâmetros de conexão e controle, enui_set_paramspara os parâmetros de qualidade do reconhecimento. - Chame
nui_dialog_startpara iniciar o reconhecimento. - No callback
onNuiAudioStateChanged, abra o dispositivo de gravação conforme o estado do áudio. - Forneça continuamente os dados gravados em
onNuiNeedAudioDataou chamenui_update_audio_datapara enviá-los ativamente. - Em
onNuiEventCallback, monitore os eventos e obtenha os resultados de reconhecimento de fala. - Chame
nui_dialog_cancelpara interromper o reconhecimento e confirme sua conclusão pelo eventoEVENT_TRANSCRIBER_COMPLETE. - Quando o reconhecimento não for mais necessário, chame
nui_releasepara liberar os recursos do SDK.
Parâmetros da solicitação
Parâmetros de conexão e controle
Configure esses parâmetros passando uma string JSON no argumento parameters de nui_initialize.
Exemplo de parâmetros: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever o código.
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | String | Sim | Endereço do serviço:
{WorkspaceId} pelo seu ID do Workspace real. |
apikey | String | Sim | API key. |
service_mode | String | Sim | Modo de execução. Fixo em "1" para reconhecimento de fala em tempo real. |
device_id | String | Sim | String exclusiva que identifica o usuário final. Você pode usar um ID de usuário do aplicativo ou um identificador de dispositivo gerado no cliente. Esse ID é usado principalmente para rastrear logs e solucionar problemas. |
audio_update_manually | String | Não | Define se o envio ativo de áudio está habilitado. Padrão: "false". Se definido como "true" e a versão do SDK suportar processamento de áudio no dispositivo, como AEC ou VAD, essas capacidades serão habilitadas por padrão. |
workspace | String | Não | O caminho onde os arquivos de recursos no dispositivo são armazenados. Este parâmetro é obrigatório quando audio_update_manually está definido como "true" e uma capacidade de processamento de áudio no dispositivo, como AEC ou VAD, está habilitada. |
debug_path | String | Não | Caminho de armazenamento dos logs. Só tem efeito quando save_log é YES em nui_initialize. Nesse caso, o caminho é obrigatório; caso contrário, ocorre um erro. São mantidos no máximo dois arquivos de log locais. |
save_wav | String | Não | Define se o áudio de depuração será salvo em debug_path. Padrão: "false". "true" salva o arquivo; "false" não o salva. Só tem efeito quando save_log é true em nui_initialize. Também é necessário definir debug_path. |
max_log_file_size | int | Não | Tamanho máximo do arquivo de log em bytes. Só tem efeito quando save_log é YES em nui_initialize. Padrão: 104857600 (100 × 1024 × 1024 bytes, ou 100 MiB). |
log_track_level | int | Não | Nível de filtragem dos logs retornados por onNuiLogTrackCallback. Padrão: 2. Valores: 0 (LOG_LEVEL_VERBOSE), 1 (LOG_LEVEL_DEBUG), 2 (LOG_LEVEL_INFO), 3 (LOG_LEVEL_WARNING), 4 (LOG_LEVEL_ERROR), 5 (LOG_LEVEL_NONE, desativado). Um log só é retornado se seu nível for maior ou igual a log_track_level e ao level de nui_initialize. Por exemplo, com 2 (INFO) e 3 (WARNING), só são retornados logs WARNING ou superiores (valor ≥ 3). |
Parâmetros de qualidade do reconhecimento
Configure esses parâmetros passando uma string JSON no argumento params de nui_set_params.
Exemplo de parâmetros: A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever o código.
| Parâmetro de nível superior | Tipo | Obrigatório | Descrição |
|---|---|---|---|
service_type | int | Sim | Tipo de serviço de voz. Fixo em 4 para reconhecimento de fala em tempo real. |
nls_config | object | Sim | Objeto principal de configuração do reconhecimento. Contém parâmetros como seleção do modelo e controles de qualidade do reconhecimento. |
nls_config.model | string | Sim | O nome do modelo. |
nls_config.sr_format | string | Sim | O formato do áudio.Valores válidos:
|
nls_config.sample_rate | int | Sim | A taxa de amostragem em Hz.Os modelos de 8 kHz suportam apenas 8000 Hz; os demais suportam qualquer taxa de amostragem. |
nls_config.max_sentence_silence | int | Não | O limite de silêncio do VAD para segmentação, em ms. Quando o silêncio após um segmento de fala excede esse limite, o sistema determina que a frase terminou.Valor padrão: 1300.Valores válidos: [200, 6000]. |
nls_config.multi_threshold_mode_enabled | boolean | Não | Define se o modo de múltiplos limiares está habilitado. Quando habilitado, evita segmentos VAD excessivamente longos.Valor padrão: false. |
nls_config.heartbeat | boolean | Não | Se deve habilitar pacotes de heartbeat.Valor padrão: false.
|
nls_config.vocabulary_id | string | Não | O ID de uma lista de palavras-chave pré-compilada.Gere este ID antecipadamente chamando a API de criação de lista de palavras-chave. Passe o ID durante o reconhecimento para usar as palavras-chave na lista.Adequado para cenários onde o vocabulário é conhecido e relativamente estável, e onde você precisa reutilizar a mesma lista de palavras em várias solicitações.Para detalhes de uso, consulte Palavras-chave pré-compiladas. |
nls_config.language_hints | array[string] | Não | O idioma do áudio a reconhecer. Não há valor padrão; se não for definido, o modelo detectará o idioma automaticamente.Você pode definir 1 valor. Se definir mais, somente o primeiro terá efeito.
Click to view the supported language codes
|
nls_config.speech_noise_threshold | float | Não | O limite para distinguir fala de ruído, usado para ajustar a sensibilidade da Detecção de Atividade de Voz (VAD).Valores válidos: [-1.0, 1.0].Descrições dos valores:
|
nls_config.special_word_filter | object | Não | Especifica as palavras sensíveis a serem processadas durante o reconhecimento de fala e permite definir diferentes métodos de processamento para diferentes palavras sensíveis. Para obter detalhes, consulte Filtragem de palavras sensíveis. |
nls_config.enable_connection_fast_check | BOOL | Não | Define se a verificação rápida de rede está habilitada para informar desconexões o mais cedo possível. Padrão: NO. |
APIs principais
NeoNui
nui_initialize
Inicializa a instância do SDK de reconhecimento de fala. O SDK é um singleton. Não o reinicialize antes de chamar nui_release.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
parameters | char* | Uma string JSON que contém parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle. |
level | NuiSdkLogLevel | Nível de impressão para os próprios logs do SDK. |
save_log | BOOL | Se deve salvar logs localmente. Se definido como YES, especifique um caminho com debug_path em Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo com max_log_file_size. |
nui_set_params
Define os parâmetros de qualidade do reconhecimento em JSON. Chame antes de nui_dialog_start.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | char* | Parâmetros de qualidade do reconhecimento. |
nui_dialog_start
Inicia o reconhecimento.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
vad_mode | NuiVadMode | Modo VAD. Fixado como MODE_P2T. |
dialog_params | char* | Se apikey nos parâmetros de conexão e controle for uma chave de API temporária, você poderá atualizá-la aqui quando expirar. Também é possível fornecer contexto para melhorar a precisão por enriquecimento de contexto.O conteúdo está em formato JSON: |
nui_dialog_cancel
Encerra o reconhecimento ou cancela imediatamente a interação atual.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
force | BOOL | Define se o encerramento será forçado e o resultado final descartado. YES: encerra imediatamente sem esperar o resultado final do servidor. NO: encerra a tarefa, mas espera o resultado completo. |
nui_dialog_action
Envia uma ação em tempo de execução para informar ao AEC no dispositivo o estado da reprodução.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
action_params | char* | Uma string JSON que contém a ação em tempo de execução. |
action_params.type | String | Fixo em "action". |
action_params.command | String | play_start: Quando o AEC no dispositivo é usado, informa ao SDK que o player começou a reproduzir áudio.play_over: Quando o AEC no dispositivo é usado, informa ao SDK que o player terminou de reproduzir áudio. |
nui_update_audio_data
Quando audio_update_manually é "true", os dados gravados deixam de ser fornecidos por onNuiNeedAudioData. Use este método para enviá-los ativamente.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | const char * | Os dados de áudio a serem enviados. |
length | int | O comprimento dos dados de áudio, em bytes. |
first_pack | BOOL | Você não precisa usar este parâmetro. |
nui_push_reference_data
Quando audio_update_manually é "true" e o AEC no dispositivo está habilitado, use este método para enviar o áudio reproduzido como sinal de referência.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
data | const char * | Os dados de áudio a serem enviados. |
length | int | O comprimento dos dados de áudio, em bytes. |
first_pack | BOOL | Você não precisa usar este parâmetro. |
nui_release
Libera todos os recursos internos do SDK e encerra forçadamente todas as tarefas em execução. A instância fica indisponível. Para reutilizá-la, inicialize-a novamente com nui_initialize.
Method signature
nui_get_version
Obtém a versão atual do SDK. Só retorna um valor após a chamada de nui_initialize.
Method signature
nui_get_all_response
Obtém as informações completas do callback do evento atual.
Method signature
NeoNuiSdkDelegate: listeners de callback
onNuiEventCallback: receber eventos e resultados de reconhecimento de fala
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
nuiEvent | NuiCallbackEvent | Evento de callback. |
dialog | long | ID da sessão. Você não precisa usar este parâmetro. |
wuw | char* | Despertar por voz. Você não precisa usar este parâmetro. |
asr_result | char* | Resultado do reconhecimento de fala. |
finish | BOOL | Se a rodada de reconhecimento atual foi concluída. |
code | int | Válido apenas quando o evento EVENT_ASR_ERROR ocorre. |
onNuiAudioStateChanged: monitorar o estado do áudio
O SDK usa este callback para informar quando iniciar ou parar a gravação.
Method signature
| Parâmetro | Descrição |
|---|---|
STATE_OPEN | A interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar. |
STATE_PAUSE | A interação parou. Você pode parar a gravação. |
STATE_CLOSE | A instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação. |
onNuiNeedAudioData: fornecer áudio para reconhecimento
Após o início do reconhecimento, este callback é acionado continuamente. Forneça nele os dados de áudio a reconhecer.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
audioData | char* | Os dados de áudio a serem fornecidos. |
len | int | O tamanho dos dados de áudio fornecidos em bytes. |
onNuiAssistEventCallback: receber dados e informações auxiliares
Recebe eventos auxiliares e dados relacionados do SDK.
Method signature
| Parâmetro | Tipo | Descrição |
|---|---|---|
nuiEvent | NuiCallbackEvent | O evento de callback. |
info | char* | Você não precisa usar este parâmetro. |
info_len | int | Você não precisa usar este parâmetro. |
buffer | char* | Dados auxiliares, como áudio após o processamento AEC. |
len | int | O comprimento dos dados auxiliares, em bytes. |
onNuiLogTrackCallback: receber logs de rastreamento
Este callback recebe os logs internos detalhados do SDK para ajudar a localizar e depurar problemas.
NuiCallbackEvent: tipos de evento
| Evento | Descrição |
|---|---|
EVENT_TRANSCRIBER_STARTED | A tarefa foi iniciada com sucesso. |
EVENT_VAD_START | Acionado logo após o início da tarefa. Não significa que o início da fala foi detectado. |
EVENT_VAD_END | O fim da fala foi detectado. |
EVENT_ASR_PARTIAL_RESULT | Um resultado intermediário de reconhecimento de fala. |
| EVENT_ASR_ERROR | Ocorreu um erro durante o reconhecimento de fala. |
EVENT_MIC_ERROR | Acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos. |
EVENT_SENTENCE_END | O fim de uma frase foi detectado. O resultado completo de reconhecimento da frase é retornado. |
EVENT_TRANSCRIBER_COMPLETE | O reconhecimento de fala foi concluído. |
EVENT_AEC_DATA | Dados de áudio após o cancelamento de eco acústico (AEC). |