Este guia mostra como usar o SDK Android para reconhecimento de fala em tempo real Fun-ASR-Realtime para converter fala em texto.
Início rápido
- Obter uma chave de API
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote SDK mais recente.
- Extraia o pacote ZIP. O SDK no formato AAR está no diretório
app/libs. Adicione-o às dependências do seu projeto. Para integração com Android C++, useandroid_libseandroid_includedo pacote ZIP para obter as bibliotecas dinâmicas e arquivos de cabeçalho. - Abra o projeto no Android Studio. O código de exemplo está em
DashFunAsrSpeechTranscriberActivity.java. Substitua a chave de API para testar o recurso.
Procedimento de chamada
- Inicialize o SDK.
- Defina os parâmetros para o seu caso de uso. Use o argumento
parametersdo métodoinitializepara definir os Parâmetros de conexão e controle e use o métodosetParamspara definir os Parâmetros de reconhecimento de fala. - Chame
startDialogpara iniciar o reconhecimento. - No callback
onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio. - Forneça continuamente dados de gravação no callback
onNuiNeedAudioDataou envie ativamente dados de gravação chamandoupdateAudio. - No callback
onNuiEventCallback, ouça eventos e obtenha os resultados do reconhecimento de fala. - Chame
stopDialogpara parar o reconhecimento e ouça o evento EVENT_TRANSCRIBER_COMPLETE para confirmar que o reconhecimento terminou. - Quando você não precisar mais do reconhecimento, chame
releasepara liberar os recursos do SDK.
Parâmetros da solicitação
Parâmetros de conexão e controle
Para configurar esses parâmetros, passe uma string JSON no argumento parameters do método initialize.
- Exemplo: A seguir está um exemplo de string JSON. Nem todos os parâmetros estão listados. Adicione outros conforme necessário ao escrever seu código:
-
Parâmetros
Parâmetro Tipo Obrigatório Descrição urlStringSim Endereç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
{WorkspaceId}pelo seu ID do Workspace real.apikeyStringSim A chave de API. service_modeStringSim O modo de execução. Fixo em "1"para reconhecimento de fala em tempo real.device_idStringSim Uma string única que identifica o usuário final. Você pode defini-la como um ID de usuário no aplicativo ou um identificador de dispositivo único gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas. audio_update_manuallyStringNão Se deve habilitar o envio ativo de dados de áudio. Padrão: "false".Se definido como"true"e a versão do SDK suportar capacidades de processamento de áudio no dispositivo, como AEC e VAD, essas capacidades serão habilitadas por padrão.workspaceStringNão O caminho onde os arquivos de recursos no dispositivo são armazenados. Este parâmetro é obrigatório quando audio_update_manuallyestá definido como"true"e uma capacidade de processamento de áudio no dispositivo, como AEC ou VAD, está habilitada.debug_pathStringNão O caminho de armazenamento para arquivos de log.Este parâmetro entra em vigor somente quando save_logé definido como true no métodoinitialize. Nesse caso, você deve definir o caminho do arquivo de log, caso contrário, ocorrerá um erro.No máximo dois arquivos de log são mantidos localmente.save_wavStringNão Se deve salvar o arquivo de áudio de depuração. O arquivo de áudio é salvo em debug_path.Padrão: "false".Valores válidos:- "true": salvar o arquivo.
- "false": não salvar o arquivo.
save_logestá definido como true no métodoinitialize. Além disso,debug_pathtambém deve ser definido.max_log_file_sizeintNão O tamanho máximo de um arquivo de log, em bytes.Este parâmetro tem efeito apenas quando save_logestá definido como true no métodoinitialize.Padrão: 104857600 (100 * 1024 * 1024 bytes, ou seja, 100 MiB).log_track_levelintNão O nível de filtro para o conteúdo de log enviado através do callback de log ( onNuiLogTrackCallback).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 (desabilita este recurso)
log_track_levelelevel(definidos através do métodoinitialize) determinam juntos quais logs são finalmente enviados ao callback. Um log é enviado ao callback somente quando seu valor de nível é maior ou igual tanto alog_track_levelquanto alevel. Por exemplo, selog_track_levelfor definido como 2 (INFO) elevelfor definido como 3 (WARNING), então apenas logs de nível WARNING ou superior (valor >= 3) serão enviados ao callback.enable_reconnectionStringNão Se deve retomar a transmissão após a reconexão da rede. Padrão: "false".aec_paramsobjectNão O objeto de configuração avançada para cancelamento de eco acústico (AEC) no dispositivo. Este objeto tem efeito apenas quando audio_update_manuallyestá definido como"true".aec_params.enable_aecbooleanNão Se deve habilitar o AEC no dispositivo. Se audio_update_manuallyestiver definido como"true"e a versão do SDK suportar AEC no dispositivo, essa capacidade será habilitada por padrão.aec_params.save_audiobooleanNão Se deve salvar o áudio processado pelo módulo AEC no dispositivo. Se save_wavfor definido como"true"edebug_pathfor especificado, esse recurso será habilitado por padrão e os dados de áudio do AEC serão salvos emdebug_path.aec_params.enable_aec_data_callbackbooleanNão Se deve retornar os dados processados por AEC para o seu aplicativo. Padrão: false. Se habilitado, receba os dados do evento EVENT_AEC_DATAemonNuiAssistEventCallback.vad_paramsobjectNão O objeto de configuração avançada para detecção de atividade de voz (VAD) no dispositivo. Este objeto tem efeito apenas quando audio_update_manuallyestá definido como"true".vad_params.enable_aecbooleanNão Se deve habilitar o VAD no dispositivo. Se audio_update_manuallyestiver definido como"true"e a versão do SDK suportar VAD no dispositivo, essa capacidade será habilitada por padrão.vad_params.save_audiobooleanNão Se deve salvar o áudio processado pelo módulo VAD no dispositivo. Se save_wavfor definido como"true"edebug_pathfor especificado, esse recurso será habilitado por padrão e os dados de áudio do VAD serão salvos emdebug_path.
Parâmetros de reconhecimento de fala
Para configurar esses parâmetros, passe uma string JSON no argumento params do método setParams.
- Exemplo: A seguir está um exemplo de string JSON. Nem todos os parâmetros estão listados. Adicione outros conforme necessário ao escrever seu código:
-
Parâmetros
Parâmetro de nível superior Tipo Obrigatório Descrição service_typeintSim O tipo de serviço de fala. Fixo em 4para reconhecimento de fala em tempo real.nls_configobjectSim O objeto de configuração principal para reconhecimento de fala. Ele contém parâmetros-chave como seleção de modelo e controles de qualidade de reconhecimento. nls_config.modelstringSim O modelo usado no exemplo. Para informações sobre o modelo, consulte Modelos e regiões suportados. nls_config.sr_formatstringSim O formato de áudio.Valores válidos: pcmopus
nls_config.sample_rateintSim A taxa de amostragem, em Hz.Valores válidos: modelos de 8 kHz suportam apenas 8000 Hz; outros modelos suportam qualquer taxa de amostragem. nls_config.max_sentence_silenceintNã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_enabledbooleanNão Se deve habilitar o modo de múltiplos limites. Quando habilitado, isso evita que os segmentos VAD fiquem muito longos.Valor padrão: false. nls_config.heartbeatbooleanNão Se deve habilitar pacotes de heartbeat.Valor padrão: false. - true: Mantém a conexão com o servidor ativa mesmo quando áudio silencioso é enviado continuamente.
- false (padrão): Mesmo quando áudio silencioso é enviado continuamente, a conexão expira e fecha após um período de tempo.
nls_config.vocabulary_idstringNão O ID de uma lista de palavras-chave pré-compilada.Gere este ID antecipadamente chamando a API de criação de lista de hotwords. Passe o ID durante o reconhecimento para usar as hotwords da lista.Adequado para cenários onde o vocabulário é conhecido e relativamente estável, e onde você precisa reutilizar a mesma lista de palavras entre solicitações.Para detalhes de uso, consulte Hotwords pré-compiladas. nls_config.language_hintsarray[string]Não O idioma do áudio a ser reconhecido. Não há valor padrão; se não definido, o modelo detecta o idioma automaticamente.Você pode definir 1 valor. Se definir mais, somente o primeiro terá efeito. Clique para ver os códigos de idioma suportados
-
fun-asr-realtime:
- zh: Chinês
- en: Inglês
- ja: Japonês
- ko: Coreano
- vi: Vietnamita
- th: Tailandês
- id: Indonésio
- ms: Malaio
- tl: Filipino
- hi: Hindi
- ar: Árabe
- fr: Francês
- de: Alemão
- es: Espanhol
- pt: Português
- ru: Russo
- it: Italiano
- nl: Holandês
- sv: Sueco
- da: Dinamarquês
- fi: Finlandês
- no: Norueguês
- el: Grego
- pl: Polonês
- cs: Tcheco
- hu: Húngaro
- ro: Romeno
- bg: Búlgaro
- hr: Croata
- sk: Eslovaco
-
fun-asr-realtime-2026-02-28:
- zh: Chinês
- en: Inglês
- ja: Japonês
-
fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28:
- zh: Chinês
-
fun-asr-mtl-realtime-2025-12-10:
- zh: Chinês
- en: Inglês
- ja: Japonês
- ko: Coreano
- vi: Vietnamita
- id: Indonésio
- th: Tailandês
nls_config.speech_noise_thresholdfloatNã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: - Quanto mais próximo o valor estiver de -1: O limite de ruído diminui, então o ruído tem maior probabilidade de ser reconhecido como fala, o que pode causar a transcrição de mais ruído.
- Quanto mais próximo o valor estiver de +1: O limite de ruído aumenta, então a fala tem maior probabilidade de ser erroneamente julgada como ruído, o que pode fazer com que parte da fala seja filtrada.
- Teste e verifique minuciosamente os resultados antes de ajustar.
- Ajuste em pequenos incrementos com base no ambiente de áudio real (recomenda-se um passo de 0.1).
nls_config.special_word_filterobjectNã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_checkbooleanNão Se deve detectar rapidamente interrupções de rede e relatá-las o mais rápido possível. Padrão: false.
Interfaces principais
NativeNui
initialize
Inicializa uma instância do SDK de reconhecimento de fala. O SDK é um singleton. Não o inicialize mais de uma vez antes de chamar release.
Este método é bloqueante, portanto, chame-o em uma thread que não seja de UI.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição callbackINativeNuiCallbackA implementação da interface de callback de eventos e dados. parametersStringUma string JSON que contém os parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle. levelConstants.LogLevelControla o nível de impressão dos logs do próprio SDK. save_logbooleanSe deve salvar logs locais. Se definido como true, especifique o caminho através dedebug_pathnos Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo através demax_log_file_size. - Valor de retorno
setParams
Define os Parâmetros de reconhecimento de fala no formato JSON. Chame este método antes de startDialog.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição paramsStringParâmetros de reconhecimento de fala. - Valor de retorno
startDialog
Inicia o reconhecimento.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição vad_modeVadModeO modo VAD. Fixado em VadMode.TYPE_P2T.dialog_paramsStringSe o parâmetro apikeyem Parâmetros de conexão e controle usar uma chave de API temporária, você poderá atualizá-la aqui quando ela expirar.Para melhorar a precisão do reconhecimento usando contexto, atualize o contexto aqui.O conteúdo está no formato JSON: - Valor de retorno
stopDialog
Encerra o reconhecimento. Após chamar este método, o servidor retorna o resultado final do reconhecimento e encerra a tarefa.
- Assinatura do método
- Valor de retorno
cancelDialog
Encerra o reconhecimento imediatamente. Após chamar este método, a tarefa termina de uma vez sem esperar que o servidor retorne o resultado final do reconhecimento.
- Assinatura do método
- Valor de retorno
updateAction
Envia uma ação em tempo de execução para informar ao AEC no dispositivo o estado da reprodução.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição paramsStringUma string JSON que contém a ação em tempo de execução. params.typeStringDefina como "action".params.commandStringplay_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. - Valor de retorno
updateAudio
Quando audio_update_manually está definido como "true", chame este método para enviar ativamente dados de gravação em vez de fornecer os dados através de onNuiNeedAudioData.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição databyte[]Os dados de áudio a serem enviados. lenintO número de bytes de dados de áudio a serem enviados. first_packbooleanIgnore este parâmetro. - Valor de retorno
updateRefAudio
Quando audio_update_manually está definido como "true" e o AEC no dispositivo está habilitado, chame este método para enviar o áudio reproduzido pelo player como sinal de referência.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição databyte[]Os dados de áudio a serem enviados. lenintO número de bytes de dados de áudio a serem enviados. first_packbooleanIgnore este parâmetro. - Valor de retorno
release
Libera todos os recursos internos do SDK. Após chamar este método, a instância do SDK torna-se indisponível. Para usá-la novamente, você deve reinicializá-la chamando initialize.
- Assinatura do método
- Valor de retorno
GetVersion
Obtém as informações da versão atual do SDK.
- Assinatura do método
- Valor de retorno As informações da versão atual do SDK.
INativeNuiCallback: callbacks de listener
onNuiEventCallback: ouvir eventos e resultados de reconhecimento de fala
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição eventNuiEventO evento de callback. resultCodeintVálido apenas quando o evento EVENT_ASR_ERRORocorre.arg2intUm parâmetro reservado. asrResultAsrResultO resultado do reconhecimento de fala. kwsResultKwsResultO recurso de despertar por voz. Você não precisa usar este parâmetro.
onNuiAudioStateChanged: ouvir o estado do áudio
O SDK usa este callback para notificá-lo quando iniciar ou parar a gravação.
- Assinatura do método
-
Estados AudioState
Estado Descrição STATE_OPENA interação foi iniciada. Você pode abrir o dispositivo de gravação e começar a gravar. STATE_PAUSEA interação foi interrompida. Você pode parar a gravação. STATE_CLOSEA instância do SDK foi liberada. Você pode fechar completamente o dispositivo de gravação.
onNuiNeedAudioData: fornecer os dados de áudio para reconhecer
Após o início do reconhecimento, este callback é acionado continuamente. Forneça os dados de áudio a serem reconhecidos neste callback.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição bufferbyte[]Os dados de áudio a serem preenchidos. lenintO número de bytes de dados de áudio a serem preenchidos. - Valor de retorno O número de bytes realmente preenchidos.
onNuiAssistEventCallback: receber eventos e dados auxiliares
Este callback recebe eventos auxiliares e dados relacionados do SDK.
- Assinatura do método
-
Parâmetros
Parâmetro Tipo Descrição eventintUm evento NuiEvent.infoStringIgnore este parâmetro. info_lenintIgnore este parâmetro. databyte[]Dados auxiliares, como dados de áudio processados por AEC.
onNuiLogTrackCallback: ouvir logs de rastreamento
Este callback recebe logs internos detalhados do SDK para ajudar na solução de problemas e depuração.
NuiEvent: 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. Isso 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_WARN | Ocorreu um aviso que não interrompe o reconhecimento de fala, como uma interrupção de rede quando a reconexão está habilitada. |
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 é detectado. Um resultado completo de reconhecimento para a frase é retornado. |
EVENT_TRANSCRIBER_COMPLETE | O reconhecimento de fala terminou. |
EVENT_AEC_DATA | Dados de áudio processados por AEC. |