Alibaba Cloud Model Studio:Fun-ASR-Realtime Android SDK

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

1. Obter uma chave de API

2. 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++, use android_libs e android_include do 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

1. Inicialize o SDK.
2. Defina os parâmetros para o seu caso de uso. Use o argumento parameters do método initialize para definir os Parâmetros de conexão e controle e use o método setParams para definir os Parâmetros de reconhecimento de fala.
3. Chame startDialog para iniciar o reconhecimento.
4. No callback onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
5. Forneça continuamente dados de gravação no callback onNuiNeedAudioData ou envie ativamente dados de gravação chamando updateAudio.
6. No callback onNuiEventCallback, ouça eventos e obtenha os resultados do reconhecimento de fala.
7. Chame stopDialog para parar o reconhecimento e ouça o evento EVENT_TRANSCRIBER_COMPLETE para confirmar que o reconhecimento terminou.
8. Quando você não precisar mais do reconhecimento, chame release para 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:

{
    "url": "wss://dashscope.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}

• Parâmetros

  Parâmetro	Tipo	Obrigatório	Descrição
  url	String	Sim	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 Substitua {WorkspaceId} pelo seu ID do Workspace real.
  apikey	String	Sim	A chave de API.
  service_mode	String	Sim	O modo de execução. Fixo em "1" para reconhecimento de fala em tempo real.
  device_id	String	Sim	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_manually	String	Nã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.
  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	O caminho de armazenamento para arquivos de log.Este parâmetro entra em vigor somente quando save_log é definido como true no método initialize. 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_wav	String	Nã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. Este parâmetro tem efeito apenas quando save_log está definido como true no método initialize. Além disso, debug_path também deve ser definido.
  max_log_file_size	int	Não	O tamanho máximo de um arquivo de log, em bytes.Este parâmetro tem efeito apenas quando save_log está definido como true no método initialize.Padrão: 104857600 (100 * 1024 * 1024 bytes, ou seja, 100 MiB).
  log_track_level	int	Nã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) Nota: log_track_level e level (definidos através do método initialize) 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 a log_track_level quanto a level. Por exemplo, se log_track_level for definido como 2 (INFO) e level for definido como 3 (WARNING), então apenas logs de nível WARNING ou superior (valor >= 3) serão enviados ao callback.
  enable_reconnection	String	Não	Se deve retomar a transmissão após a reconexão da rede. Padrão: "false".
  aec_params	object	Nã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_manually está definido como "true".
  aec_params.enable_aec	boolean	Não	Se deve habilitar o AEC no dispositivo. Se audio_update_manually estiver definido como "true" e a versão do SDK suportar AEC no dispositivo, essa capacidade será habilitada por padrão.
  aec_params.save_audio	boolean	Não	Se deve salvar o áudio processado pelo módulo AEC no dispositivo. Se save_wav for definido como "true" e debug_path for especificado, esse recurso será habilitado por padrão e os dados de áudio do AEC serão salvos em debug_path.
  aec_params.enable_aec_data_callback	boolean	Nã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_DATA em onNuiAssistEventCallback.
  vad_params	object	Nã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_manually está definido como "true".
  vad_params.enable_aec	boolean	Não	Se deve habilitar o VAD no dispositivo. Se audio_update_manually estiver definido como "true" e a versão do SDK suportar VAD no dispositivo, essa capacidade será habilitada por padrão.
  vad_params.save_audio	boolean	Não	Se deve salvar o áudio processado pelo módulo VAD no dispositivo. Se save_wav for definido como "true" e debug_path for especificado, esse recurso será habilitado por padrão e os dados de áudio do VAD serão salvos em debug_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:

{
    "service_type": 4,
    "nls_config": {
        "model": "fun-asr-realtime",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}

• Parâmetros

  Parâmetro de nível superior	Tipo	Obrigatório	Descrição
  service_type	int	Sim	O tipo de serviço de fala. Fixo em 4 para reconhecimento de fala em tempo real.
  nls_config	object	Sim	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.model	string	Sim	O modelo usado no exemplo. Para informações sobre o modelo, consulte Modelos e regiões suportados.
  nls_config.sr_format	string	Sim	O formato de áudio. Valores válidos: pcm opus ImportantePara áudio Opus, passe áudio PCM para o SDK. O SDK o codifica como Opus internamente.
  nls_config.sample_rate	int	Sim	A taxa de amostragem, em Hz. Valores válidos: modelos de 8 kHz suportam apenas 8000 Hz; outros modelos suportam qualquer taxa de amostragem. Importante8000 Hz não é suportado quando uma capacidade de processamento de áudio no dispositivo, como AEC ou VAD, está habilitada.
  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	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.heartbeat	boolean	Nã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. Áudio silencioso refere-se a conteúdo em um arquivo de áudio ou fluxo de dados que não contém sinal sonoro. Você pode gerar áudio silencioso de várias maneiras, como usando software de edição de áudio como Audacity ou Adobe Audition, ou usando uma ferramenta de linha de comando como FFmpeg.
  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 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_hints	array[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_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: 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. Este é um parâmetro de configuração avançado. Ajustá-lo pode afetar significativamente os resultados do reconhecimento. Recomendações: 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_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	boolean	Nã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

public synchronized int initialize(final INativeNuiCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)

• Parâmetros

  Parâmetro	Tipo	Descrição
  callback	INativeNuiCallback	A implementação da interface de callback de eventos e dados.
  parameters	String	Uma string JSON que contém os parâmetros de autenticação, conexão e depuração. Consulte Parâmetros de conexão e controle.
  level	Constants.LogLevel	Controla o nível de impressão dos logs do próprio SDK.
  save_log	boolean	Se deve salvar logs locais. Se definido como true, especifique o caminho através de debug_path nos Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo através de max_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

public synchronized int setParams(String params)

• Parâmetros

  Parâmetro	Tipo	Descrição
  params	String	Parâmetros de reconhecimento de fala.

• Valor de retorno

startDialog

Inicia o reconhecimento.

• Assinatura do método

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

• Parâmetros

  Parâmetro	Tipo	Descrição
  vad_mode	VadMode	O modo VAD. Fixado em VadMode.TYPE_P2T.
  dialog_params	String	Se o parâmetro apikey em 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: { "apikey": "st-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }

• 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

public synchronized int stopDialog();

• 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

public synchronized int cancelDialog();

• 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

public synchronized int updateAction(String params);

• Parâmetros

  Parâmetro	Tipo	Descrição
  params	String	Uma string JSON que contém a ação em tempo de execução.
  params.type	String	Defina como "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.

• 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

public synchronized int updateAudio(byte[] data, int len,
                                    boolean first_pack);

• Parâmetros

  Parâmetro	Tipo	Descrição
  data	byte[]	Os dados de áudio a serem enviados.
  len	int	O número de bytes de dados de áudio a serem enviados.
  first_pack	boolean	Ignore 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

public synchronized int updateRefAudio(byte[] data, int len,
                                       boolean first_pack);

• Parâmetros

  Parâmetro	Tipo	Descrição
  data	byte[]	Os dados de áudio a serem enviados.
  len	int	O número de bytes de dados de áudio a serem enviados.
  first_pack	boolean	Ignore 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

public synchronized int release();

• Valor de retorno

GetVersion

Obtém as informações da versão atual do SDK.

• Assinatura do método

public synchronized String GetVersion();

• 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

void onNuiEventCallback(NuiEvent event, final int resultCode, final int arg2, KwsResult kwsResult, AsrResult asrResult);

• Parâmetros

  Parâmetro	Tipo	Descrição
  event	NuiEvent	O evento de callback.
  resultCode	int	Válido apenas quando o evento EVENT_ASR_ERROR ocorre.
  arg2	int	Um parâmetro reservado.
  asrResult	AsrResult	O resultado do reconhecimento de fala.
  kwsResult	KwsResult	O 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

void onNuiAudioStateChanged(AudioState state);

• Estados AudioState

  Estado	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 foi interrompida. 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 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

int onNuiNeedAudioData(byte[] buffer, int len);

• Parâmetros

  Parâmetro	Tipo	Descrição
  buffer	byte[]	Os dados de áudio a serem preenchidos.
  len	int	O 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

void onNuiAssistEventCallback_(int event, byte[] info, int info_len,
                               byte[] data);

• Parâmetros

  Parâmetro	Tipo	Descrição
  event	int	Um evento NuiEvent.
  info	String	Ignore este parâmetro.
  info_len	int	Ignore este parâmetro.
  data	byte[]	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.

default void onNuiLogTrackCallback(Constants.LogLevel level, String log)

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.