Skip to main content

SDK Android de reconhecimento de fala não em tempo real Fun-ASR

Este guia mostra como converter fala em texto com o SDK Android de reconhecimento de fala não em tempo real Fun-ASR.

Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Especificações de áudio.

Início rápido

  1. Obtenha uma chave de API: Obter uma chave de API. Para maior segurança, armazene a chave de API em uma variável de ambiente.
  2. Baixe o SDK e execute o código de exemplo:
    • Baixe o pacote mais recente do SDK.
    • Extraia o pacote ZIP. Encontre o SDK no formato AAR no diretório app/libs e adicione-o às dependências do seu projeto. Para integração com Android C++, use android_libs e android_include no pacote ZIP para obter as bibliotecas dinâmicas e os arquivos de cabeçalho.
    • Abra o projeto no Android Studio. O código de exemplo está em DashFunAsrFileTranscriberActivity.java. Substitua a chave de API e, em seguida, teste o recurso.

Procedimento de chamada

  • Modo síncrono
  • Modo assíncrono
  1. Inicialize o SDK.
  2. Configure os parâmetros que o seu negócio requer.
  3. Defina async_request como false e chame startFileTranscriber para enviar uma solicitação de reconhecimento de fala não em tempo real e aguardar o resultado.
  4. Monitore o evento EVENT_FILE_TRANS_RESULT na interface onFileTransEventCallback para obter o resultado final do reconhecimento.
  5. Chame release para liberar os recursos do SDK.

Parâmetros de solicitação

Parâmetros de conexão e controle

Configure esses parâmetros passando uma string JSON no argumento parameters da interface initialize. Exemplo de parâmetro A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever seu código:
{
    "url": "wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
Descrição do parâmetro
ParâmetroTipoObrigatórioDescrição
urlStringSimEndpoints de serviço:
  • wss://dashscope.aliyuncs.com/api/v1/services/audio/asr/transcription
  • China (Pequim): wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
  • Singapura: wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/audio/asr/transcription
Substitua {WorkspaceId} pelo seu ID do Workspace real.
apikeyStringSimA chave de API.
service_modeStringSimO modo de execução. Fixado em "1" para reconhecimento de fala gravada.
device_idStringSimUma string exclusiva que identifica o usuário final. Defina-a como um ID de usuário no aplicativo ou um identificador de dispositivo gerado pelo cliente. Este ID é usado principalmente para rastreamento de logs e solução de problemas.
debug_pathStringNãoO caminho de armazenamento para o arquivo de log.Este parâmetro só entra em vigor quando save_log é definido como true na interface initialize. Nesse caso, você deve definir o caminho do arquivo de log, caso contrário, um erro será relatado.No máximo dois arquivos de log são mantidos localmente.
max_log_file_sizeintNãoO tamanho máximo do arquivo de log, em bytes.Este parâmetro só entra em vigor quando save_log é definido como true na interface initialize.Padrão: 104857600 (100 * 1024 * 1024 bytes, ou seja, 100 MiB).
log_track_levelintNãoO nível de filtro para o conteúdo de log enviado através do callback de log (onFileTransLogTrackCallback).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 este recurso)
Nota: log_track_level e level (definidos por meio da interface initialize) juntos determinam quais logs são finalmente enviados para o callback. Um log é enviado para o callback apenas quando seu valor de nível é maior ou igual a log_track_level e level. Por exemplo, se log_track_level estiver definido como 2 (INFO) e level estiver definido como 3 (WARNING), apenas logs no nível WARNING ou superior (valor >= 3) serão enviados para o callback.

Parâmetros de reconhecimento de fala

Configure todos os parâmetros de reconhecimento de fala por meio da interface startFileTranscriber. Exemplo de parâmetro A string JSON a seguir é um exemplo e não lista todos os parâmetros. Adicione os parâmetros necessários ao escrever seu código:
{
    "apikey": "st-****",
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}
Descrição do parâmetro
ParâmetroTipoObrigatórioDescrição
file_urlsarray[string]SimUma lista de URLs dos arquivos de áudio ou vídeo a serem transcritos. HTTP e HTTPS são suportados. Uma única solicitação suporta apenas uma URL. Para requisitos de entrada, como formatos de áudio suportados, limites de tamanho de arquivo e limites de duração, consulte Especificações de áudio.Se a gravação estiver armazenada no Alibaba Cloud OSS, a API RESTful suporta URLs temporárias com o prefixo oss://, enquanto o SDK não suporta URLs temporárias com o prefixo oss://.
  • Uma URL temporária é válida por 48 horas e não pode ser usada após a expiração. Não a use em produção.
  • A interface de credencial de upload tem limite de taxa de 100 QPS e não pode ser escalada. Não a use em cenários de produção, alta simultaneidade ou teste de carga.
  • Para produção, use armazenamento estável, como o Alibaba Cloud OSS, para manter os arquivos disponíveis a longo prazo e evitar limitações de taxa.
  • Se uma URL de arquivo de áudio definida como uma URL pública temporária do OSS estiver inacessível, defina X-DashScope-OssResourceResolve como enable no cabeçalho da solicitação (não recomendado). O SDK não suporta a configuração de cabeçalhos de solicitação.
async_requestbooleanNãoSe a solicitação de reconhecimento é assíncrona.Padrão: false.Valores válidos:
  • true: solicitação assíncrona
  • false: solicitação síncrona
apikeystringNãoSe a apikey em Parâmetros de conexão e controle for uma chave de API temporária, você poderá atualizá-la aqui para evitar a expiração.
nls_configobjectSimO objeto de configuração principal para reconhecimento de fala. Ele contém parâmetros chave, como seleção de modelo e controle de reconhecimento.
nls_config.modelstringSimO nome do modelo.
nls_config.special_word_filterobjectNãoAs palavras sensíveis a serem processadas durante o reconhecimento de fala. Você pode definir um método de tratamento diferente para cada palavra sensível. Para obter detalhes, consulte Filtragem de palavras sensíveis.
nls_config.channel_idarray[integer]NãoO índice das faixas de áudio a serem reconhecidas em um arquivo de áudio com várias faixas. O índice começa em 0. Por exemplo, [0] reconhece a primeira faixa, e [0, 1] reconhece a primeira e a segunda faixas ao mesmo tempo. Se você omitir este parâmetro, apenas a primeira faixa será processada.
Cada faixa especificada é cobrada de forma independente. Por exemplo, solicitar [0, 1] para um único arquivo incorre em duas cobranças separadas.
Valor padrão: [0].
nls_config.diarization_enabledbooleanNãoSe deve ativar a diarização de falantes. Desativado por padrão.Aplica-se apenas a áudio mono. Áudio multicanal não suporta diarização de falantes.Quando ativado, o resultado do reconhecimento inclui um campo speaker_id que distingue diferentes falantes.
Quando a diarização de falantes está ativada, mantenha a duração do áudio dentro de 2 horas. Caso contrário, o reconhecimento pode falhar ou atingir o tempo limite.
Padrão: false.Para um exemplo de speaker_id, consulte Descrição do resultado do reconhecimento.
nls_config.speaker_countintegerNão
Entra em vigor apenas quando a diarização de falantes está ativada (diarization_enabled está definido como true).
Um valor de referência para o número de falantes. O intervalo válido é um número inteiro de 2 a 100 (inclusivo).Por padrão, o número de falantes é detectado automaticamente. Se você definir este valor, ele apenas orientará o algoritmo a gerar a contagem especificada quando possível, e não garante essa contagem exata.Sem valor padrão.
nls_config.vocabulary_idstringNãoO 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.instant_vocabularyobjectNãoHotwords instantâneas. Passe pares de chave-valor em que as chaves são os textos das hotwords (string) e os valores são pesos inteiros (integer). Não é necessário criar uma lista pré-compilada.Para saber como usar, consulte Hotwords instantâneas.
{
  "张三": 5,
  "李四": 5
}
nls_config.language_hintsarray[string]NãoOs códigos de idioma a serem reconhecidos. Se você não puder determinar o idioma com antecedência, deixe-o indefinido e o modelo detectará o idioma automaticamente.Você pode definir até 1 valor. Se definir mais, apenas os 1 primeiros serão usados.
  • 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

Interfaces principais

NativeNui

initialize

Inicializa a instância do SDK de reconhecimento de fala. O SDK é um singleton. Não o inicialize novamente antes de chamar release. Esta interface bloqueia, portanto, chame-a em uma thread que não seja de UI. Assinatura do método
public synchronized int initialize(final INativeFileTransCallback callback,
                                   String parameters,
                                   final Constants.LogLevel level,
                                   final boolean save_log)
Descrição do parâmetro
ParâmetroTipoDescrição
callbackINativeFileTransCallbackA 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 próprios logs do SDK.
save_logbooleanSe deve salvar logs localmente. Se true, especifique o caminho com debug_path em Parâmetros de conexão e controle e, opcionalmente, defina o tamanho do arquivo com max_log_file_size.

setParams

Use esta interface para definir ou atualizar os parâmetros nls_config separadamente. Se você fornecer todos os parâmetros de uma vez em startFileTranscriber, não precisará chamar este método. Assinatura do método
public synchronized int setParams(String params);
Descrição do parâmetro
ParâmetroTipoDescrição
paramsStringO parâmetro nls_config em Parâmetros de reconhecimento de fala. Parâmetros diferentes de nls_config não podem ser definidos por meio deste método.Exemplo:
{
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}

startFileTranscriber

Inicia o reconhecimento. Assinatura do método
public synchronized int startFileTranscriber(String params, byte[] task_id)
Descrição do parâmetro
ParâmetroTipoDescrição
paramsStringParâmetros de reconhecimento de fala.Exemplo:
{
    "file_urls": [
        "{YOUR_AUDIO_URL}"
    ],
    "async_request": false,
    "nls_config": {
        "model":"fun-asr",
        "diarization_enabled": false
    }
}
task_idbyte[]O ID da tarefa. O SDK gera uma string aleatória internamente. Você obtém o task_id após esta interface retornar com sucesso.

queryFileTranscriber

Use esta interface para consultar o status atual e o resultado de uma tarefa assíncrona. Após a chamada ser bem-sucedida, o resultado é retornado por meio do evento EVENT_FILE_TRANS_QUERY_RESULT no callback onFileTransEventCallback.
Obtenha o task_id passado para este método a partir do evento EVENT_FILE_TRANS_UPLOADED.
Assinatura do método
public synchronized int queryFileTranscriber(String task_id)
Descrição do parâmetro
ParâmetroTipoDescrição
task_idStringO ID da tarefa a ser consultada, obtido a partir do evento EVENT_FILE_TRANS_UPLOADED.

cancelFileTranscriber

Cancela a tarefa atual imediatamente. Assinatura do método
public synchronized int cancelFileTranscriber(String task_id)
Descrição do parâmetro
ParâmetroTipoDescrição
task_idStringO ID da tarefa a ser cancelada, obtido a partir do evento EVENT_FILE_TRANS_UPLOADED.

release

Libera todos os recursos internos do SDK. Depois de chamar este método, a instância do SDK torna-se inutilizável. Para usá-la novamente, você deve chamar initialize para inicializá-la novamente. Assinatura do método
public synchronized int release();

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.

INativeFileTransCallback: callbacks do listener

onFileTransEventCallback: ouvir eventos e resultados de reconhecimento

Assinatura do método
void onFileTransEventCallback(NuiEvent event, final int resultCode, final int arg2, AsrResult asrResult, String taskId);
Descrição do parâmetro
ParâmetroTipoDescrição
eventNuiEventO evento de callback.
resultCodeintVálido apenas quando o evento EVENT_ASR_ERROR ocorre.
asrResultAsrResultO resultado do reconhecimento de fala.
taskIdStringO ID da tarefa.
arg2intUm parâmetro reservado.

onFileTransLogTrackCallback: ouvir logs de rastreamento

Este callback recebe os logs internos detalhados do SDK para diagnóstico e depuração de problemas.
default void onFileTransLogTrackCallback(Constants.LogLevel level, String log)

NuiEvent: tipos de evento

EventoDescrição
EVENT_FILE_TRANS_CONNECTEDA conexão do serviço foi bem-sucedida.
EVENT_FILE_TRANS_UPLOADEDO arquivo de áudio a ser reconhecido foi carregado com sucesso. Agora você pode obter o task_id da tarefa atual.
EVENT_FILE_TRANS_QUERY_RESULTUma consulta de resultado de tarefa.
EVENT_FILE_TRANS_RESULTO resultado final do reconhecimento.
EVENT_ASR_ERROROcorreu um erro durante o reconhecimento de fala.