Ce guide explique comment utiliser le SDK HarmonyOS de reconnaissance vocale en temps réel Paraformer pour convertir la parole en texte.
Remplacez
Ouvrez le projet dans DevEco Studio. L'exemple de code se trouve dans
Transmettez une chaîne JSON au paramètre
Transmettez une chaîne JSON au paramètre
Initialise une instance du SDK de reconnaissance vocale. N'initialisez pas l'instance à nouveau avant d'avoir appelé release.
Cette interface bloque le thread appelant. Appelez-la depuis un thread non UI.
Définit les paramètres d'effet de reconnaissance vocale au format JSON. Appelez cette interface avant startDialog.
Démarre la reconnaissance.
Arrête la reconnaissance. Après l'appel de cette interface, le serveur renvoie le résultat final de la reconnaissance et termine la tâche.
Arrête immédiatement la reconnaissance sans attendre que le serveur retourne le résultat final de reconnaissance.
Libère toutes les ressources internes du SDK. Après l'appel de cette méthode, l'instance du SDK devient indisponible. Pour la réutiliser, appelez initialize afin de la réinitialiser.
Obtient les informations de version actuelles du SDK.
Écoute les événements, les états audio, les changements de volume et les journaux pendant la reconnaissance vocale en temps réel.
Écoute les événements de reconnaissance et obtient les résultats de reconnaissance vocale.
Le SDK utilise ce rappel pour indiquer quand l'enregistrement doit commencer ou s'arrêter.
Surveille le volume des données audio enregistrées pour l'affichage de l'interface utilisateur.
Une fois la reconnaissance démarrée, ce rappel est déclenché en continu. Fournissez les données audio à reconnaître dans le rappel.
Ce callback reçoit les journaux internes détaillés du SDK pour le dépannage et le débogage.
Les types d'événements du SDK HarmonyOS sont définis par l'énumération
Les valeurs d'énumération pour le paramètre
Contrairement à Android, qui utilise
Déclarer l'autorisation du microphone dans
{WorkspaceId} par votre véritable ID d'espace de travail. Le domaine existant reste disponible.
Guide d'utilisation : Pour les présentations des modèles et les recommandations de sélection, consultez Reconnaissance vocale en temps réel - Fun-ASR et Paraformer.
Prérequis
- Obtenez et configurez une clé API. Ne codez pas en dur de clé API de longue durée dans votre application mobile. Nous vous recommandons de générer une clé API temporaire sur votre serveur d’application et de la transmettre au client.
Installer le SDK
- Télécharger le dernier package SDK.
- Extrayez le package TAR. Obtenez le SDK au format HAR depuis le répertoire
neonuiet ajoutez-le aux dépendances de votre projet. Pour l'intégration C++, obtenez les bibliothèques dynamiques et les fichiers d'en-tête depuisnative/libsetnative/includedans le package TAR.
Démarrage rapide
Ouvrez le projet dans DevEco Studio. L'exemple de code se trouve dans DashParaformerSpeechTranscriberPage.ets. Remplacez la clé API pour tester la fonctionnalité.
Étapes d'appel
- Initialiser le SDK.
- Configurez les paramètres en fonction de vos besoins métier : Utilisez le paramètre
parametersde initialize pour définir les paramètres de connexion et de contrôle, et utilisez setParams pour définir les paramètres d'effet de reconnaissance vocale. - Appelez startDialog pour démarrer la reconnaissance.
- Dans le rappel onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
- Dans le rappel onNuiNeedAudioData, fournir continuellement des données audio enregistrées.
- Dans le rappel onNuiEventCallback, écouter les événements et obtenir les résultats de reconnaissance vocale.
- Appelez stopDialog pour arrêter la reconnaissance, et écoutez l'événement
EVENT_TRANSCRIBER_COMPLETEpour confirmer que la reconnaissance est terminée. - Lorsque la reconnaissance vocale n'est plus nécessaire, appeler release pour libérer les ressources du SDK.
Paramètres de requête
Paramètres de connexion et de contrôle
Transmettez une chaîne JSON au paramètre parameters de initialize pour configurer les paramètres suivants. Exemple : La chaîne JSON suivante est un exemple et n'inclut pas tous les paramètres. Ajoutez les paramètres selon vos besoins :
- Descriptions des paramètres
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
url | string | Oui | Le point de terminaison. Celui-ci est fixé à wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference. Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. |
apikey | string | Oui | La clé API. Nous recommandons d'utiliser une clé API temporaire plus sécurisée avec une courte période de validité afin de réduire le risque de fuite d'une clé à long terme. |
service_mode | string | Oui | Le mode de fonctionnement. Pour la reconnaissance vocale en temps réel, ceci est fixé à "1". |
device_id | string | Oui | Une chaîne unique identifiant l'utilisateur final. Vous pouvez la définir sur un ID utilisateur in-app ou un identifiant d'appareil unique généré par le client. Cet ID est principalement utilisé pour le suivi des journaux et le dépannage. |
debug_path | string | Non | Le chemin de stockage des fichiers journaux. Ce paramètre prend effet uniquement si vous définissez save_log sur true lors de l'appel de initialize. Dans ce cas, vous devez spécifier un chemin de fichier journal. Sinon, une erreur se produit. Un maximum de deux fichiers journaux sont conservés localement. |
save_wav | string | Non | Spécifie s'il faut enregistrer des fichiers audio pour le débogage. Les fichiers audio sont enregistrés sous debug_path. Valeur par défaut : "false". Valeurs valides : - "true" : oui - "false" : non. Ce paramètre prend effet uniquement si vous définissez save_log sur true lors de l'appel de initialize. Vous devez également définir debug_path. |
max_log_file_size | number | Non | Définit la taille maximale d'un fichier journal en octets. Ce paramètre prend effet uniquement si vous définissez save_log sur true lors de l'appel de initialize. Valeur par défaut : 104857600 (100 * 1024 * 1024 octets, soit 100 Mio). |
log_track_level | number | Non | Contrôle le niveau de filtrage du contenu des journaux envoyé à l'extérieur via le rappel onNuiLogTrackCallback. Valeur par défaut : 2. Valeurs valides : - 0 : LOG_LEVEL_VERBOSE - 1 : LOG_LEVEL_DEBUG - 2 : LOG_LEVEL_INFO - 3 : LOG_LEVEL_WARNING - 4 : LOG_LEVEL_ERROR - 5 : LOG_LEVEL_NONE (désactive cette fonctionnalité). Remarque : log_track_level et level, qui est défini via initialize, déterminent ensemble quels journaux sont envoyés au rappel. Un niveau de journal doit être supérieur ou égal à la fois à log_track_level et à level pour déclencher le rappel. Par exemple, si log_track_level est 2 (INFO) et que level est 3 (WARNING), seuls les journaux au niveau WARNING ou supérieur (valeur >=3) déclenchent le rappel. |
Paramètres d'effet de reconnaissance vocale
Transmettez une chaîne JSON au paramètre params de setParams pour configurer les paramètres suivants. Exemple : La chaîne JSON suivante est un exemple et n'inclut pas tous les paramètres. Ajoutez les paramètres selon vos besoins :
- Descriptions des paramètres
| Paramètre de niveau 1 | Type | Obligatoire | Description |
|---|---|---|---|
service_type | int | Oui | Le type de service vocal. Pour la reconnaissance vocale en temps réel, ceci est fixé à 4. |
nls_config | object | Oui | L'objet de configuration principal de la reconnaissance vocale, qui contient les paramètres clés pour la sélection du modèle et le contrôle de l'effet de reconnaissance. |
nls_config.model | string | Oui | Le modèle de reconnaissance vocale. |
nls_config.sr_format | string | Oui | Le format de l'audio à reconnaître. Formats pris en charge : pcm, wav et opus. |
nls_config.sample_rate | int | Oui | La fréquence d'échantillonnage de l'audio à reconnaître, en Hz. Elle varie selon le modèle : - paraformer-realtime-v2 prend en charge n'importe quelle fréquence d'échantillonnage. - paraformer-realtime-8k-v2 prend en charge uniquement 8000 Hz. |
nls_config.disfluency_removal_enabled | boolean | Non | Spécifie s'il faut supprimer les disfluences telles que les mots de remplissage. Valeur par défaut : false. |
nls_config.language_hints | array[string] | Non | Spécifie les codes de langue pour l'audio à reconnaître. Si la langue ne peut pas être déterminée à l'avance, omettez ce paramètre et le modèle détecte automatiquement la langue. Codes de langue pris en charge : - zh : Chinois - en : Anglais - ja : Japonais - yue : Cantonais - ko : Coréen - de : Allemand - fr : Français - ru : Russe. Ce paramètre prend effet uniquement pour les modèles qui prennent en charge plusieurs langues. |
nls_config.semantic_punctuation_enabled | boolean | Non | Spécifie le mode de segmentation des phrases. Valeur par défaut : false. Valeurs valides : - true : Active la segmentation sémantique et désactive la segmentation VAD. - false : Active la segmentation VAD et désactive la segmentation sémantique. La segmentation sémantique est plus précise et convient à la transcription de réunions. La segmentation VAD (détection d'activité vocale) a une latence plus faible et convient à l'interaction en temps réel. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs. |
nls_config.max_sentence_silence | int | Non | Le seuil de silence pour la segmentation des phrases par VAD (détection d'activité vocale), en millisecondes. Valeur par défaut : 800. Plage valide : [200, 6000]. Lorsque le silence après un segment dépasse ce seuil, le système détermine que la phrase est terminée. Ce paramètre prend effet uniquement lorsque semantic_punctuation_enabled est false et que le modèle est v2 ou ultérieur. |
nls_config.multi_threshold_mode_enabled | boolean | Non | Spécifie s'il faut activer le mode de prévention des segments trop longs. Ce mode empêche les segments VAD de devenir trop longs. Valeur par défaut : false (désactivé). Valeurs valides : - true : active le mode - false : désactive le mode. Ce paramètre prend effet uniquement lorsque semantic_punctuation_enabled est false et que le modèle est v2 ou ultérieur. |
nls_config.punctuation_prediction_enabled | boolean | Non | Spécifie s'il faut ajouter automatiquement la ponctuation aux résultats de reconnaissance. Valeur par défaut : true. Valeurs valides : - true : oui - false : non. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs. |
nls_config.heartbeat | boolean | Non | Spécifie s'il faut maintenir une connexion persistante au serveur. Valeur par défaut : false. Valeurs valides : - true : La connexion reste active tant que de l'audio silencieux est envoyé en continu. - false : Même si de l'audio silencieux est envoyé en continu, la connexion expire après un certain temps. Le délai d'expiration est une valeur par défaut côté serveur et ne peut pas être configuré sur le client. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs. |
nls_config.inverse_text_normalization_enabled | boolean | Non | Spécifie s'il faut activer la normalisation inverse du texte (ITN). Lorsqu'elle est activée, les chiffres chinois sont convertis en chiffres arabes. Valeur par défaut : true (activée). Valeurs valides : - true : activée - false : désactivée. Ce paramètre prend effet uniquement pour les modèles v2 et ultérieurs. |
nls_config.vocabulary_id | string | Non | L'ID du vocabulaire de mots clés, qui améliore la précision de reconnaissance de mots spécifiques. Ce paramètre s'applique aux modèles v2 et ultérieurs. Pour plus d'informations, consultez Mots clés personnalisés. |
Référence de l’API
NativeNui
initialize
Initialise une instance du SDK de reconnaissance vocale. N'initialisez pas l'instance à nouveau avant d'avoir appelé release.
Cette interface bloque le thread appelant. Appelez-la depuis un thread non UI.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
callback | INativeNuiCallback | Une implémentation de l'interface de rappel d'événements et de données. |
parameters | string | Une chaîne JSON contenant des paramètres d'authentification, de connexion et de débogage. Voir Paramètres de connexion et de contrôle. |
level | number | Contrôle le niveau de journalisation du SDK. Les valeurs valides sont définies par l'énumération Constants.LogLevel. |
save_log | boolean | Spécifie s'il faut enregistrer les journaux locaux. Si ce paramètre est true, utilisez debug_path dans Paramètres de connexion et de contrôle pour spécifier un chemin. Vous pouvez également utiliser max_log_file_size pour définir la taille du fichier. |
- Valeur de retour
setParams
Définit les paramètres d'effet de reconnaissance vocale au format JSON. Appelez cette interface avant startDialog.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
params | string | Les paramètres d'effet de reconnaissance vocale. |
- Valeur de retour
startDialog
Démarre la reconnaissance.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
vad_mode | Constants.VadMode | Le mode VAD. Ceci est fixé à Constants.VadMode.TYPE_P2T. |
dialog_params | string | Si la clé API temporaire spécifiée par apikey dans Paramètres de connexion et de contrôle a expiré, mettez-la à jour ici. La valeur est au format JSON : typescript { "apikey": "st-****" } |
- Valeur de retour
stopDialog
Arrête la reconnaissance. Après l'appel de cette interface, le serveur renvoie le résultat final de la reconnaissance et termine la tâche.
- Signature de la méthode
- Valeur de retour
cancelDialog
Arrête immédiatement la reconnaissance sans attendre que le serveur retourne le résultat final de reconnaissance.
- Signature de la méthode
- Valeur de retour
release
Libère toutes les ressources internes du SDK. Après l'appel de cette méthode, l'instance du SDK devient indisponible. Pour la réutiliser, appelez initialize afin de la réinitialiser.
- Signature de la méthode
- Valeur de retour
GetVersion
Obtient les informations de version actuelles du SDK.
- Signature de la méthode
- Valeur de retour
INativeNuiCallback
Écoute les événements, les états audio, les changements de volume et les journaux pendant la reconnaissance vocale en temps réel.
onNuiEventCallback
Écoute les événements de reconnaissance et obtient les résultats de reconnaissance vocale.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
event | Constants.NuiEvent | L'événement de rappel. |
resultCode | number | Valide uniquement lorsque l’événement EVENT_ASR_ERROR se produit. |
asrResult | AsrResult | Le résultat de la reconnaissance vocale. |
kwsResult | KwsResult | La fonctionnalité de réveil vocal. Vous n'avez pas besoin d'utiliser ce paramètre. |
arg2 | number | Un paramètre réservé. |
onNuiAudioStateChanged
Le SDK utilise ce rappel pour indiquer quand l'enregistrement doit commencer ou s'arrêter.
- Signature de la méthode
- Descriptions AudioState
| État | Description |
|---|---|
STATE_OPEN | L'interaction commence. Vous pouvez démarrer le périphérique d'enregistrement. |
STATE_PAUSE | L'interaction est en pause. Vous pouvez mettre l'enregistrement en pause. |
STATE_CLOSE | L'interaction s'arrête. Vous pouvez arrêter complètement le périphérique d'enregistrement. |
onNuiAudioRMSChanged
Surveille le volume des données audio enregistrées pour l'affichage de l'interface utilisateur.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
val | number | Le volume des données audio enregistrées. La plage de sortie est généralement [-160, 0]. |
onNuiNeedAudioData
Une fois la reconnaissance démarrée, ce rappel est déclenché en continu. Fournissez les données audio à reconnaître dans le rappel.
- Signature de la méthode
- Descriptions des paramètres
| Paramètre | Type | Description |
|---|---|---|
buffer | ArrayBuffer | Les données audio à fournir. Le SDK utilise buffer.byteLength comme nombre d'octets demandé. |
- Valeur de retour
<=0 indique une erreur ou une absence de données.
onNuiLogTrackCallback
Ce callback reçoit les journaux internes détaillés du SDK pour le dépannage et le débogage.
Constants.NuiEvent
Les types d'événements du SDK HarmonyOS sont définis par l'énumération Constants.NuiEvent. Les événements suivants s'appliquent à la reconnaissance vocale en temps réel :
| Événement | Description |
|---|---|
EVENT_TRANSCRIBER_STARTED | La tâche démarre avec succès. |
EVENT_VAD_START | Cet événement est déclenché immédiatement après le démarrage de la tâche. Il n'indique pas que le début de la parole a été détecté. |
EVENT_VAD_END | La fin de la parole est détectée. |
EVENT_ASR_PARTIAL_RESULT | Un résultat intermédiaire de reconnaissance vocale. |
EVENT_ASR_RESULT | Un résultat de reconnaissance vocale complet. |
EVENT_ASR_ERROR | Une erreur s'est produite lors de la reconnaissance vocale. |
EVENT_MIC_ERROR | Cet événement est déclenché lorsqu'aucune donnée audio n'est reçue pendant 2 secondes consécutives. |
EVENT_SENTENCE_START | Le début d'une phrase est détecté. |
EVENT_SENTENCE_END | La fin d'une phrase est détectée et un résultat de reconnaissance complet est retourné. |
EVENT_TRANSCRIBER_COMPLETE | La reconnaissance vocale se termine. |
Types auxiliaires
Constants.LogLevel
Les valeurs d'énumération pour le paramètre level sont les suivantes :
| Valeur | Description |
|---|---|
LOG_LEVEL_VERBOSE | Les journaux les plus détaillés. |
LOG_LEVEL_DEBUG | Journaux de débogage. |
LOG_LEVEL_INFO | Journaux d'information (par défaut). |
LOG_LEVEL_WARNING | Journaux d'avertissement. |
LOG_LEVEL_ERROR | Journaux d'erreurs. |
LOG_LEVEL_NONE | Désactive la journalisation. |
Gestion des périphériques audio
Contrairement à Android, qui utilise AudioRecord, HarmonyOS utilise AudioCapturer de @kit.AudioKit pour capturer l'audio. L'exemple de produit encapsule cette logique dans la classe utilitaire AudioRecorder.ets, que vous pouvez réutiliser directement.
- Création :
audio.createAudioCapturer(capturerOptions)crée de manière asynchrone le capteur avec une fréquence d'échantillonnage fixe de 16 kHz, une profondeur de 16 bits et un canal (SAMPLE_RATE_16000/CHANNEL_1/SAMPLE_FORMAT_S16LE/ENCODING_TYPE_RAW). - Événement de données :
capturer.on('readData', (buffer: ArrayBuffer) => void)obtient en continu les données audio enregistrées. Mettez les données en mémoire tampon dans une file d'attente afin que le rappelonNuiNeedAudioDatapuisse les récupérer selon les besoins. - Événement d'état :
capturer.on('stateChange', (state: audio.AudioState) => void).STATE_RUNNINGindique que l'enregistrement a commencé, etSTATE_STOPPEDindique que l'enregistrement s'est arrêté. - Contrôle :
start()démarre,stop()arrête etrelease()libère le capteur.
HarmonyOS crée
AudioCapturer de manière asynchrone. Appelez start() uniquement après la fin de la création. Par conséquent, ne créez pas et ne démarrez pas immédiatement un enregistreur lorsque STATE_OPEN se produit. Créez-le d'abord, puis appelez start() dans le rappel STATE_OPEN. L'exemple crée l'enregistreur pendant doInit et le démarre pendant onNuiAudioStateChanged. Lorsque STATE_CLOSE se produit, arrêtez l'enregistreur mais conservez l'instance pour la réutiliser. Libérez-la dans release.Déclaration d'autorisation
Déclarer l'autorisation du microphone dans module.json5 pour utiliser l'enregistrement :