Skip to main content

Paraformer HarmonyOS SDK

Ce guide explique comment utiliser le SDK HarmonyOS de reconnaissance vocale en temps réel Paraformer pour convertir la parole en texte.

Alibaba Cloud Model Studio a introduit un domaine spécifique à l'espace de travail pour la région Chine (Pékin). Ce domaine offre des performances supérieures et une stabilité accrue pour les requêtes d'inférence. Nous vous recommandons de migrer de dashscope.aliyuncs.com vers {WorkspaceId}.cn-beijing.maas.aliyuncs.com.
Remplacez {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

  1. 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 neonui et 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 depuis native/libs et native/include dans 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

  1. Initialiser le SDK.
  2. Configurez les paramètres en fonction de vos besoins métier : Utilisez le paramètre parameters de 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.
  3. Appelez startDialog pour démarrer la reconnaissance.
  4. Dans le rappel onNuiAudioStateChanged, démarrez le périphérique d'enregistrement en fonction de l'état audio.
  5. Dans le rappel onNuiNeedAudioData, fournir continuellement des données audio enregistrées.
  6. Dans le rappel onNuiEventCallback, écouter les événements et obtenir les résultats de reconnaissance vocale.
  7. Appelez stopDialog pour arrêter la reconnaissance, et écoutez l'événement EVENT_TRANSCRIBER_COMPLETE pour confirmer que la reconnaissance est terminée.
  8. 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 :
{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "st-****",
    "device_id": "my_device_id",
    "service_mode": "1"
}
  • Descriptions des paramètres
ParamètreTypeObligatoireDescription
urlstringOuiLe 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.
apikeystringOuiLa 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_modestringOuiLe mode de fonctionnement. Pour la reconnaissance vocale en temps réel, ceci est fixé à "1".
device_idstringOuiUne 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_pathstringNonLe 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_wavstringNonSpé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_sizenumberNonDé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_levelnumberNonContrô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 :
{
    "service_type": 4,
    "nls_config": {
        "model": "paraformer-realtime-v2",
        "sr_format": "pcm",
        "sample_rate": "16000"
    }
}
  • Descriptions des paramètres
Paramètre de niveau 1TypeObligatoireDescription
service_typeintOuiLe type de service vocal. Pour la reconnaissance vocale en temps réel, ceci est fixé à 4.
nls_configobjectOuiL'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.modelstringOuiLe modèle de reconnaissance vocale.
nls_config.sr_formatstringOui

Le format de l'audio à reconnaître. Formats pris en charge : pcm, wav et opus.

  • opus : L'audio source doit être encodé en PCM. Le SDK l'encode en OPUS.
  • wav/pcm : L'audio doit être encodé en PCM.
nls_config.sample_rateintOuiLa 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_enabledbooleanNonSpécifie s'il faut supprimer les disfluences telles que les mots de remplissage. Valeur par défaut : false.
nls_config.language_hintsarray[string]NonSpé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_enabledbooleanNonSpé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_silenceintNonLe 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_enabledbooleanNonSpé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_enabledbooleanNonSpé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.heartbeatbooleanNonSpé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_enabledbooleanNonSpé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_idstringNonL'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
public initialize(callback: INativeNuiCallback,
                  parameters: string,
                  level: number,
                  save_log: boolean = false): number
  • Descriptions des paramètres
ParamètreTypeDescription
callbackINativeNuiCallbackUne implémentation de l'interface de rappel d'événements et de données.
parametersstringUne chaîne JSON contenant des paramètres d'authentification, de connexion et de débogage. Voir Paramètres de connexion et de contrôle.
levelnumberContrôle le niveau de journalisation du SDK. Les valeurs valides sont définies par l'énumération Constants.LogLevel.
save_logbooleanSpé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
public setParams(params: string): number
  • Descriptions des paramètres
ParamètreTypeDescription
paramsstringLes paramètres d'effet de reconnaissance vocale.
  • Valeur de retour

startDialog

Démarre la reconnaissance.
  • Signature de la méthode
public startDialog(vad_mode: Constants.VadMode, dialog_params: string): number
  • Descriptions des paramètres
ParamètreTypeDescription
vad_modeConstants.VadModeLe mode VAD. Ceci est fixé à Constants.VadMode.TYPE_P2T.
dialog_paramsstringSi 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
public stopDialog(): number
  • 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
public cancelDialog(): number
  • 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
public release(): number
  • Valeur de retour

GetVersion

Obtient les informations de version actuelles du SDK.
  • Signature de la méthode
public GetVersion(): string
  • Valeur de retour
Les informations de version actuelle du SDK.

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
onNuiEventCallback: (event: Constants.NuiEvent, resultCode: number, arg2: number,
                    kwsResult: KwsResult, asrResult: AsrResult) => void;
  • Descriptions des paramètres
ParamètreTypeDescription
eventConstants.NuiEventL'événement de rappel.
resultCodenumberValide uniquement lorsque l’événement EVENT_ASR_ERROR se produit.
asrResultAsrResultLe résultat de la reconnaissance vocale.
kwsResultKwsResultLa fonctionnalité de réveil vocal. Vous n'avez pas besoin d'utiliser ce paramètre.
arg2numberUn 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
onNuiAudioStateChanged: (state: Constants.AudioState) => void
  • Descriptions AudioState
ÉtatDescription
STATE_OPENL'interaction commence. Vous pouvez démarrer le périphérique d'enregistrement.
STATE_PAUSEL'interaction est en pause. Vous pouvez mettre l'enregistrement en pause.
STATE_CLOSEL'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
onNuiAudioRMSChanged: (val: number) => number
  • Descriptions des paramètres
ParamètreTypeDescription
valnumberLe 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
onNuiNeedAudioData: (buffer: ArrayBuffer) => number
  • Descriptions des paramètres
ParamètreTypeDescription
bufferArrayBufferLes données audio à fournir. Le SDK utilise buffer.byteLength comme nombre d'octets demandé.
  • Valeur de retour
Le nombre réel d'octets fournis. Une valeur de retour de <=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.
onNuiLogTrackCallback: (level: Constants.LogLevel, log: string) => void

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énementDescription
EVENT_TRANSCRIBER_STARTEDLa tâche démarre avec succès.
EVENT_VAD_STARTCet é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_ENDLa fin de la parole est détectée.
EVENT_ASR_PARTIAL_RESULTUn résultat intermédiaire de reconnaissance vocale.
EVENT_ASR_RESULTUn résultat de reconnaissance vocale complet.
EVENT_ASR_ERRORUne erreur s'est produite lors de la reconnaissance vocale.
EVENT_MIC_ERRORCet événement est déclenché lorsqu'aucune donnée audio n'est reçue pendant 2 secondes consécutives.
EVENT_SENTENCE_STARTLe début d'une phrase est détecté.
EVENT_SENTENCE_ENDLa fin d'une phrase est détectée et un résultat de reconnaissance complet est retourné.
EVENT_TRANSCRIBER_COMPLETELa reconnaissance vocale se termine.

Types auxiliaires

Constants.LogLevel

Les valeurs d'énumération pour le paramètre level sont les suivantes :
ValeurDescription
LOG_LEVEL_VERBOSELes journaux les plus détaillés.
LOG_LEVEL_DEBUGJournaux de débogage.
LOG_LEVEL_INFOJournaux d'information (par défaut).
LOG_LEVEL_WARNINGJournaux d'avertissement.
LOG_LEVEL_ERRORJournaux d'erreurs.
LOG_LEVEL_NONEDé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 rappel onNuiNeedAudioData puisse les récupérer selon les besoins.
  • Événement d'état : capturer.on('stateChange', (state: audio.AudioState) => void). STATE_RUNNING indique que l'enregistrement a commencé, et STATE_STOPPED indique que l'enregistrement s'est arrêté.
  • Contrôle : start() démarre, stop() arrête et release() 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 :
{
  "requestPermissions": [
    { "name": "ohos.permission.MICROPHONE" }
  ]
}