Este guia explica como usar o SDK HarmonyOS de reconhecimento de fala em tempo real Paraformer para converter fala em texto.
Substitua
Passe uma string JSON para o parâmetro
Passe uma string JSON para o parâmetro
Inicializa uma instância do SDK de reconhecimento de fala. Não inicialize a instância novamente antes de chamar release.
Esta interface bloqueia a thread chamadora. Chame-a a partir de uma thread que não seja de UI.
Define os parâmetros de efeito de reconhecimento de fala no formato JSON. Chame esta interface antes de startDialog.
Inicia o reconhecimento.
Interrompe o reconhecimento. Após chamar esta interface, o servidor retorna o resultado final do reconhecimento e encerra a tarefa.
Para o reconhecimento imediatamente sem esperar que o servidor retorne o resultado final do reconhecimento.
Libera todos os recursos internos do SDK. Após a chamada deste método, a instância do SDK torna-se indisponível. Para usá-la novamente, chame initialize para reinicializá-la.
Obtém as informações da versão atual do SDK.
Escuta eventos, estados de áudio, alterações de volume e logs durante o reconhecimento de fala em tempo real.
Escuta eventos de reconhecimento e obtém resultados de reconhecimento de fala.
O SDK usa este callback para indicar quando a gravação deve começar ou parar.
Monitora o volume dos dados de áudio gravados para exibição na UI.
Após o início do reconhecimento, este callback é acionado continuamente. Forneça os dados de áudio a serem reconhecidos no callback.
Este callback recebe logs internos detalhados do SDK para solução de problemas e depuração.
Os tipos de eventos do SDK HarmonyOS são definidos pela enumeração
Os valores de enumeração para o parâmetro
Diferente do Android, que usa
Declare a permissão de microfone em
{WorkspaceId} pelo seu ID do workspace real. O domínio existente permanece disponível.
Guia do usuário: Para introduções aos modelos e recomendações de seleção, consulte Reconhecimento de fala em tempo real - Fun-ASR e Paraformer.
Início rápido
-
Obter uma chave de API: Obter e configurar uma chave de API. Por segurança, recomendamos configurar a chave de API como uma variável de ambiente.
Para conceder acesso temporário a aplicativos ou usuários terceiros, ou para controlar estritamente operações de alto risco, como acessar ou excluir dados sensíveis, use uma chave de API temporária. Uma chave de API temporária é válida por 60 segundos por padrão. Obtenha uma nova após a expiração.
-
Baixe o SDK e execute o código de exemplo:
- Baixe o pacote SDK mais recente.
- Extraia o pacote TAR. Obtenha o SDK no formato HAR do diretório
neonuie adicione-o às dependências do seu projeto. Para integração C++, obtenha as bibliotecas dinâmicas e arquivos de cabeçalho denative/libsenative/includeno pacote TAR. - Abra o projeto no DevEco Studio. O código de exemplo está localizado em
DashParaformerSpeechTranscriberPage.ets. Substitua a chave de API para testar o recurso.
Etapas de invocação
- Inicialize o SDK.
- Configure os parâmetros com base nos requisitos do seu negócio: Use o parâmetro
parametersde initialize para definir parâmetros de conexão e controle e use setParams para definir parâmetros de efeito de reconhecimento de fala. - Chame startDialog para iniciar o reconhecimento.
- No callback onNuiAudioStateChanged, inicie o dispositivo de gravação com base no estado do áudio.
- No callback onNuiNeedAudioData, forneça continuamente dados de áudio gravados.
- No callback onNuiEventCallback, escute eventos e obtenha resultados de reconhecimento de fala.
- Chame stopDialog para parar o reconhecimento e ouça o evento
EVENT_TRANSCRIBER_COMPLETEpara confirmar que o reconhecimento terminou. - Quando o reconhecimento de fala não for mais necessário, chame release para liberar os recursos do SDK.
Parâmetros da solicitação
Parâmetros de conexão e controle
Passe uma string JSON para o parâmetro parameters de initialize para configurar os seguintes parâmetros. Exemplo: A seguinte string JSON é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:
- Descrições dos parâmetros
| Parâmetro | Tipo | Obrigatório | Descrição |
|---|---|---|---|
url | string | Sim | O endpoint. Isso é fixado em wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Substitua {WorkspaceId} pelo seu ID de workspace real. |
apikey | string | Sim | A chave de API. Recomendamos usar uma chave de API temporária mais segura, com curto período de validade, para reduzir o risco de vazamento de uma chave de longo prazo. |
service_mode | string | Sim | O modo de operação. Para reconhecimento de fala em tempo real, isso é fixado em "1". |
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. |
debug_path | string | Não | O caminho de armazenamento para arquivos de log. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Neste caso, você deve especificar um caminho de arquivo de log. Caso contrário, ocorrerá um erro. No máximo dois arquivos de log são retidos localmente. |
save_wav | string | Não | Especifica se deve salvar arquivos de áudio para depuração. Os arquivos de áudio são salvos em debug_path. Valor padrão: "false". Valores válidos: - "true": sim - "false": não. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Você também deve definir debug_path. |
max_log_file_size | number | Não | Define o tamanho máximo de um arquivo de log em bytes. Este parâmetro tem efeito apenas se você definir save_log como true ao chamar initialize. Valor padrão: 104857600 (100 * 1024 * 1024 bytes, ou 100 MiB). |
log_track_level | number | Não | Controla o nível de filtragem do conteúdo de log enviado externamente através do callback onNuiLogTrackCallback. Valor 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, que é definido através de initialize, determinam juntos quais logs são enviados ao callback. Um nível de log deve ser maior ou igual tanto a log_track_level quanto a level para acionar o callback. Por exemplo, se log_track_level for 2 (INFO) e level for 3 (WARNING), apenas logs no nível WARNING ou superior (valor >=3) acionam o callback. |
Parâmetros de efeito de reconhecimento de fala
Passe uma string JSON para o parâmetro params de setParams para configurar os seguintes parâmetros. Exemplo: A seguinte string JSON é um exemplo e não inclui todos os parâmetros. Adicione parâmetros conforme necessário:
- Descrições dos parâmetros
| Parâmetro de Nível-1 | Tipo | Obrigatório | Descrição |
|---|---|---|---|
service_type | int | Sim | O tipo de serviço de fala. Para reconhecimento de fala em tempo real, isso é fixado em 4. |
nls_config | object | Sim | O objeto de configuração principal de reconhecimento de fala, que contém parâmetros chave para seleção de modelo e controle de efeito de reconhecimento. |
nls_config.model | string | Sim | O modelo de reconhecimento de fala. |
nls_config.sr_format | string | Sim | O formato do áudio a ser reconhecido. Formatos suportados: pcm, wav e opus. |
nls_config.sample_rate | int | Sim | A taxa de amostragem do áudio a ser reconhecido, em Hz. Isso varia conforme o modelo: - paraformer-realtime-v2 suporta qualquer taxa de amostragem. - paraformer-realtime-8k-v2 suporta apenas 8000 Hz. |
nls_config.disfluency_removal_enabled | boolean | Não | Especifica se devem ser removidas disfluências, como palavras de preenchimento. Valor padrão: false. |
nls_config.language_hints | array[string] | Não | Especifica códigos de idioma para o áudio a ser reconhecido. Se o idioma não puder ser determinado antecipadamente, omita este parâmetro e o modelo detectará o idioma automaticamente. Códigos de idioma suportados: - zh: Chinês - en: Inglês - ja: Japonês - yue: Cantonês - ko: Coreano - de: Alemão - fr: Francês - ru: Russo. Este parâmetro tem efeito apenas para modelos que suportam vários idiomas. |
nls_config.semantic_punctuation_enabled | boolean | Não | Especifica o modo de segmentação de sentenças. Valor padrão: false. Valores válidos: - true: Habilita a segmentação semântica e desabilita a segmentação VAD. - false: Habilita a segmentação VAD e desabilita a segmentação semântica. A segmentação semântica é mais precisa e adequada para transcrição de reuniões. A segmentação VAD (Detecção de Atividade de Voz) tem menor latência e é adequada para interação em tempo real. Este parâmetro tem efeito apenas para modelos v2 e posteriores. |
nls_config.max_sentence_silence | int | Não | O limite de silêncio para segmentação de sentenças VAD (Detecção de Atividade de Voz), em milissegundos. Valor padrão: 800. Intervalo válido: [200, 6000]. Quando o silêncio após um segmento excede esse limite, o sistema determina que a sentença terminou. Este parâmetro tem efeito apenas quando semantic_punctuation_enabled é false e o modelo é v2 ou posterior. |
nls_config.multi_threshold_mode_enabled | boolean | Não | Especifica se deve habilitar o modo de prevenção de segmentos excessivamente longos. Este modo evita que os segmentos VAD se tornem muito longos. Valor padrão: false (desabilitado). Valores válidos: - true: habilita o modo - false: desabilita o modo. Este parâmetro tem efeito apenas quando semantic_punctuation_enabled é false e o modelo é v2 ou posterior. |
nls_config.punctuation_prediction_enabled | boolean | Não | Especifica se deve adicionar pontuação automaticamente aos resultados de reconhecimento. Valor padrão: true. Valores válidos: - true: sim - false: não. Este parâmetro tem efeito apenas para modelos v2 e posteriores. |
nls_config.heartbeat | boolean | Não | Especifica se deve manter uma conexão persistente com o servidor. Valor padrão: false. Valores válidos: - true: A conexão permanece ativa enquanto áudio silencioso é enviado continuamente. - false: Mesmo que áudio silencioso seja enviado continuamente, a conexão expira após um período de tempo. O tempo limite é um padrão do lado do servidor e não pode ser configurado no cliente. Este parâmetro tem efeito apenas para modelos v2 e posteriores. |
nls_config.inverse_text_normalization_enabled | boolean | Não | Especifica se deve habilitar a normalização inversa de texto (ITN). Quando habilitada, numerais chineses são convertidos para numerais arábicos. Valor padrão: true (habilitado). Valores válidos: - true: habilitado - false: desabilitado. Este parâmetro tem efeito apenas para modelos v2 e posteriores. |
nls_config.vocabulary_id | string | Não | O ID do vocabulário de palavras-chave, que melhora a precisão do reconhecimento de palavras específicas. Este parâmetro aplica-se a modelos v2 e posteriores. Para mais informações, consulte Palavras-chave personalizadas. |
Interfaces principais
NativeNui
initialize
Inicializa uma instância do SDK de reconhecimento de fala. Não inicialize a instância novamente antes de chamar release.
Esta interface bloqueia a thread chamadora. Chame-a a partir de uma thread que não seja de UI.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
callback | INativeNuiCallback | Uma implementação da interface de callback de eventos e dados. |
parameters | string | 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 | number | Controla o nível de log do SDK. Os valores válidos são definidos pela enumeração Constants.LogLevel. |
save_log | boolean | Especifica se deve salvar logs locais. Se este parâmetro for true, use debug_path em Parâmetros de conexão e controle para especificar um caminho. Você também pode usar max_log_file_size para definir o tamanho do arquivo. |
- Valor de retorno
setParams
Define os parâmetros de efeito de reconhecimento de fala no formato JSON. Chame esta interface antes de startDialog.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
params | string | Os parâmetros de efeito de reconhecimento de fala. |
- Valor de retorno
startDialog
Inicia o reconhecimento.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
vad_mode | Constants.VadMode | O modo VAD. Isso é fixado em Constants.VadMode.TYPE_P2T. |
dialog_params | string | Se a chave de API temporária especificada por apikey em Parâmetros de conexão e controle tiver expirado, atualize-a aqui. O valor está no formato JSON: typescript { "apikey": "st-****" } |
- Valor de retorno
stopDialog
Interrompe o reconhecimento. Após chamar esta interface, o servidor retorna o resultado final do reconhecimento e encerra a tarefa.
- Assinatura do método
- Valor de retorno
cancelDialog
Para o reconhecimento imediatamente sem esperar que o servidor retorne o resultado final do reconhecimento.
- Assinatura do método
- Valor de retorno
release
Libera todos os recursos internos do SDK. Após a chamada deste método, a instância do SDK torna-se indisponível. Para usá-la novamente, chame initialize para reinicializá-la.
- 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
INativeNuiCallback
Escuta eventos, estados de áudio, alterações de volume e logs durante o reconhecimento de fala em tempo real.
onNuiEventCallback
Escuta eventos de reconhecimento e obtém resultados de reconhecimento de fala.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
event | Constants.NuiEvent | O evento de callback. |
resultCode | number | Válido apenas quando o evento EVENT_ASR_ERROR ocorre. |
asrResult | AsrResult | O resultado do reconhecimento de fala. |
kwsResult | KwsResult | O recurso de despertar por voz. Você não precisa usar este parâmetro. |
arg2 | number | Um parâmetro reservado. |
onNuiAudioStateChanged
O SDK usa este callback para indicar quando a gravação deve começar ou parar.
- Assinatura do método
- Descrições do AudioState
| Estado | Descrição |
|---|---|
STATE_OPEN | A interação começa. Você pode iniciar o dispositivo de gravação. |
STATE_PAUSE | A interação está pausada. Você pode pausar a gravação. |
STATE_CLOSE | A interação para. Você pode parar completamente o dispositivo de gravação. |
onNuiAudioRMSChanged
Monitora o volume dos dados de áudio gravados para exibição na UI.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
val | number | O volume dos dados de áudio gravados. O intervalo de saída é geralmente [-160, 0]. |
onNuiNeedAudioData
Após o início do reconhecimento, este callback é acionado continuamente. Forneça os dados de áudio a serem reconhecidos no callback.
- Assinatura do método
- Descrições dos parâmetros
| Parâmetro | Tipo | Descrição |
|---|---|---|
buffer | ArrayBuffer | Os dados de áudio a serem fornecidos. O SDK usa buffer.byteLength como o número solicitado de bytes. |
- Valor de retorno
<=0 indica um erro ou ausência de dados.
onNuiLogTrackCallback
Este callback recebe logs internos detalhados do SDK para solução de problemas e depuração.
Constants.NuiEvent
Os tipos de eventos do SDK HarmonyOS são definidos pela enumeração Constants.NuiEvent. Os seguintes eventos se aplicam ao reconhecimento de fala em tempo real:
| Evento | Descrição |
|---|---|
EVENT_TRANSCRIBER_STARTED | A tarefa é iniciada com sucesso. |
EVENT_VAD_START | Este evento é acionado imediatamente após o início da tarefa. Ele não indica 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_RESULT | Um resultado completo de reconhecimento de fala. |
EVENT_ASR_ERROR | Ocorre um erro durante o reconhecimento de fala. |
EVENT_MIC_ERROR | Este evento é acionado quando nenhum dado de áudio é recebido por 2 segundos consecutivos. |
EVENT_SENTENCE_START | O início de uma frase é detectado. |
EVENT_SENTENCE_END | O fim de uma frase é detectado e um resultado completo de reconhecimento é retornado. |
EVENT_TRANSCRIBER_COMPLETE | O reconhecimento de fala termina. |
Tipos auxiliares
Constants.LogLevel
Os valores de enumeração para o parâmetro level são os seguintes:
| Valor | Descrição |
|---|---|
LOG_LEVEL_VERBOSE | Os logs mais detalhados. |
LOG_LEVEL_DEBUG | Logs de depuração. |
LOG_LEVEL_INFO | Logs informativos (padrão). |
LOG_LEVEL_WARNING | Logs de aviso. |
LOG_LEVEL_ERROR | Logs de erro. |
LOG_LEVEL_NONE | Desativa o registro de logs. |
Gerenciamento de dispositivos de áudio
Diferente do Android, que usa AudioRecord, o HarmonyOS usa AudioCapturer de @kit.AudioKit para capturar áudio. O exemplo do produto encapsula essa lógica na classe utilitária AudioRecorder.ets, que você pode reutilizar diretamente.
- Criação:
audio.createAudioCapturer(capturerOptions)cria o captador assincronamente com uma taxa de amostragem fixa de 16 kHz, profundidade de bits de 16 e um canal (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW). - Evento de dados:
capturer.on('readData', (buffer: ArrayBuffer) => void)obtém continuamente dados de áudio gravados. Armazene os dados em buffer em uma fila para que o callbackonNuiNeedAudioDatapossa recuperá-los conforme necessário. - Evento de estado:
capturer.on('stateChange', (state: audio.AudioState) => void).STATE_RUNNINGindica que a gravação foi iniciada eSTATE_STOPPEDindica que a gravação foi interrompida. - Controle:
start()inicia,stop()para erelease()libera o captador.
O HarmonyOS cria
AudioCapturer assincronamente. Chame start() somente após a conclusão da criação. Portanto, não crie e inicie imediatamente um gravador quando STATE_OPEN ocorrer. Crie-o primeiro e depois chame start() no callback STATE_OPEN. O exemplo cria o gravador durante doInit e o inicia durante onNuiAudioStateChanged. Quando STATE_CLOSE ocorrer, pare o gravador, mas mantenha a instância para reutilização. Libere-a em release.Declaração de permissão
Declare a permissão de microfone em module.json5 para usar a gravação: