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

Ce guide vous montre comment utiliser le SDK Android pour la reconnaissance vocale en temps réel Fun-ASR-Realtime afin de convertir la parole en texte.

Démarrage rapide

1. Obtenir une clé API

2. Télécharger le SDK et exécuter l'exemple de code :
   • Télécharger le dernier package SDK.
   • Extrayez le package ZIP. Le SDK au format AAR se trouve dans le répertoire app/libs. Ajoutez-le aux dépendances de votre projet. Pour l'intégration C++ Android, utilisez android_libs et android_include du package ZIP pour obtenir les bibliothèques dynamiques et les fichiers d'en-tête.
   • Ouvrez le projet dans Android Studio. L'exemple de code se trouve dans DashFunAsrSpeechTranscriberActivity.java. Remplacez la clé API pour tester la fonctionnalité.

Procédure d'appel

1. Initialiser le SDK.
2. Définissez les paramètres pour votre cas d'utilisation. Utilisez l'argument parameters de la méthode initialize pour définir les Paramètres de connexion et de contrôle, et utilisez la méthode setParams pour définir les Paramètres 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. Fournissez continuellement des données d'enregistrement dans le rappel onNuiNeedAudioData, ou envoyez activement des données d'enregistrement en appelant updateAudio.
6. Dans le rappel onNuiEventCallback, écoutez les événements et obtenez les résultats de la 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 vous n'avez plus besoin de la reconnaissance, appelez release pour libérer les ressources du SDK.

Paramètres de la requête

Paramètres de connexion et de contrôle

Pour configurer ces paramètres, passez une chaîne JSON dans l'argument parameters de la méthode initialize.

• Exemple : Voici un exemple de chaîne JSON. Tous les paramètres ne sont pas listés. Ajoutez-en d'autres selon vos besoins lors de l'écriture de votre code :

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

• Paramètres

  Paramètre	Type	Obligatoire	Description
  url	String	Oui	Adresse du service : wss://dashscope.aliyuncs.com/api-ws/v1/inference Chine (Pékin) : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference Singapour : wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference Remplacez {WorkspaceId} par votre véritable ID d'espace de travail.
  apikey	String	Oui	La clé API.
  service_mode	String	Oui	Le mode d'exécution. Fixé à "1" pour la reconnaissance vocale en temps réel.
  device_id	String	Oui	Une chaîne unique qui identifie 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 traçage des journaux et le dépannage.
  audio_update_manually	String	Non	Indique s'il faut activer la poussée active des données audio. Par défaut : "false".Si défini sur "true" et que la version du SDK prend en charge les capacités de traitement audio sur appareil telles que AEC et VAD, ces capacités sont activées par défaut.
  workspace	String	Non	Le chemin où sont stockés les fichiers de ressources sur appareil. Ce paramètre est requis lorsque audio_update_manually est défini sur "true" et qu'une capacité de traitement audio sur appareil telle que AEC ou VAD est activée.
  debug_path	String	Non	Le chemin de stockage des fichiers journaux.Ce paramètre prend effet uniquement lorsque save_log est défini sur true dans la méthode initialize. Dans ce cas, vous devez définir le chemin du fichier journal, sinon une erreur se produit.Un maximum de deux fichiers journaux sont conservés localement.
  save_wav	String	Non	Indique s'il faut sauvegarder le fichier audio de débogage. Le fichier audio est sauvegardé sous debug_path.Par défaut : "false".Valeurs valides : "true" : enregistrer le fichier. "false" : ne pas enregistrer le fichier. Ce paramètre prend effet uniquement lorsque save_log est défini sur true dans la méthode initialize. De plus, debug_path doit également être défini.
  max_log_file_size	int	Non	La taille maximale d'un fichier journal, en octets.Ce paramètre prend effet uniquement lorsque save_log est défini sur true dans la méthode initialize.Par défaut : 104857600 (100 * 1024 * 1024 octets, soit 100 Mio).
  log_track_level	int	Non	Le niveau de filtrage pour le contenu des journaux envoyé via le rappel de journalisation (onNuiLogTrackCallback).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 (définis via la méthode initialize) déterminent ensemble quels journaux sont finalement envoyés au rappel. Un journal est envoyé au rappel uniquement lorsque sa valeur de niveau est supérieure ou égale à la fois à log_track_level et level. Par exemple, si log_track_level est défini sur 2 (INFO) et level sur 3 (WARNING), alors seuls les journaux de niveau WARNING ou supérieur (valeur >= 3) sont envoyés au rappel.
  enable_reconnection	String	Non	Indique s'il faut reprendre la transmission après la reconnexion du réseau. Par défaut : "false".
  aec_params	object	Non	L'objet de configuration avancé pour l'annulation d'écho acoustique (AEC) sur appareil. Cet objet prend effet uniquement lorsque audio_update_manually est défini sur "true".
  aec_params.enable_aec	boolean	Non	Indique s'il faut activer l'AEC sur appareil. Si audio_update_manually est défini sur "true" et que la version du SDK prend en charge l'AEC sur appareil, cette capacité est activée par défaut.
  aec_params.save_audio	boolean	Non	Indique s'il faut sauvegarder l'audio traité par le module AEC sur appareil. Si save_wav est défini sur "true" et que debug_path est spécifié, cette fonctionnalité est activée par défaut et les données audio AEC sont sauvegardées dans debug_path.
  aec_params.enable_aec_data_callback	boolean	Non	Indique s'il faut retourner les données traitées par AEC à votre application. Par défaut : false. Si activé, recevez les données de l'événement EVENT_AEC_DATA dans onNuiAssistEventCallback.
  vad_params	object	Non	L'objet de configuration avancé pour la détection d'activité vocale (VAD) sur appareil. Cet objet prend effet uniquement lorsque audio_update_manually est défini sur "true".
  vad_params.enable_aec	boolean	Non	Indique s'il faut activer le VAD sur appareil. Si audio_update_manually est défini sur "true" et que la version du SDK prend en charge le VAD sur appareil, cette capacité est activée par défaut.
  vad_params.save_audio	boolean	Non	Indique s'il faut sauvegarder l'audio traité par le module VAD sur appareil. Si save_wav est défini sur "true" et que debug_path est spécifié, cette fonctionnalité est activée par défaut et les données audio VAD sont sauvegardées dans debug_path.

Paramètres de reconnaissance vocale

Pour configurer ces paramètres, passez une chaîne JSON dans l'argument params de la méthode setParams.

• Exemple : Voici un exemple de chaîne JSON. Tous les paramètres ne sont pas listés. Ajoutez-en d'autres selon vos besoins lors de l'écriture de votre code :

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

• Paramètres

  Paramètre de niveau supérieur	Type	Obligatoire	Description
  service_type	int	Oui	Le type de service vocal. Fixé à 4 pour la reconnaissance vocale en temps réel.
  nls_config	object	Oui	L'objet de configuration principal pour la reconnaissance vocale. Il contient des paramètres clés tels que la sélection du modèle et les contrôles de qualité de reconnaissance.
  nls_config.model	string	Oui	Le modèle utilisé dans l'exemple. Pour les informations sur les modèles, voir Modèles et régions pris en charge.
  nls_config.sr_format	string	Oui	Le format audio. Valeurs valides : pcm opus ImportantPour l'audio Opus, transmettez l'audio PCM au SDK. Le SDK l'encode en Opus en interne.
  nls_config.sample_rate	int	Oui	Le taux d'échantillonnage, en Hz. Valeurs valides : les modèles 8 kHz prennent en charge uniquement 8000 Hz ; les autres modèles prennent en charge n'importe quel taux d'échantillonnage. Important8000 Hz n'est pas pris en charge lorsqu'une capacité de traitement audio sur appareil telle que AEC ou VAD est activée.
  nls_config.semantic_punctuation_enabled	boolean	Non	Indique s'il faut activer la segmentation sémantique. Valeur par défaut : false. true : Active la segmentation sémantique et désactive la segmentation VAD. false (par défaut) : Active la segmentation VAD et désactive la segmentation sémantique. La segmentation sémantique est plus précise et convient mieux aux scénarios de transcription. La segmentation VAD (détection d'activité vocale) a une latence plus faible et convient mieux aux scénarios interactifs.
  nls_config.max_sentence_silence	int	Non	Le seuil de silence VAD pour la segmentation, en ms. Lorsque le silence suivant un segment de parole dépasse ce seuil, le système détermine que la phrase est terminée. Lorsque semantic_punctuation_enabled est défini sur true, ce paramètre n'est pas utilisé comme critère pour retourner sentence_end, mais le définir trop bas peut affecter les performances de reconnaissance. Valeur par défaut : 1300. Valeurs valides : [200, 6000].
  nls_config.multi_threshold_mode_enabled	boolean	Non	ImportantPrend effet uniquement lorsque semantic_punctuation_enabled est false. Indique s'il faut activer le mode multi-seuil. Lorsqu'il est activé, cela empêche les segments VAD de devenir trop longs. Valeur par défaut : false.
  nls_config.heartbeat	boolean	Non	Indique s'il faut activer les paquets de battement de cœur. Valeur par défaut : false. true : Maintient la connexion au serveur active même lorsque de l'audio silencieux est envoyé en continu. false (par défaut) : Même lorsque de l'audio silencieux est envoyé en continu, la connexion expire et se ferme après un certain temps. L'audio silencieux désigne le contenu d'un fichier audio ou d'un flux de données qui ne contient aucun signal sonore. Vous pouvez générer de l'audio silencieux de plusieurs manières, par exemple en utilisant un logiciel d'édition audio comme Audacity ou Adobe Audition, ou en utilisant un outil en ligne de commande comme FFmpeg.
  nls_config.vocabulary_id	string	Non	L'identifiant d'une liste de mots-clés précompilée. Générez cet ID à l'avance en appelant l'API de création de liste de mots chauds. Transmettez l'ID lors de la reconnaissance pour utiliser les mots chauds de la liste. Convient aux scénarios où le vocabulaire est connu et relativement stable, et où vous devez réutiliser la même liste de mots entre les requêtes. Pour plus de détails sur l'utilisation, voir Mots chauds précompilés.
  nls_config.language_hints	array[string]	Non	La langue de l'audio à reconnaître. Il n'y a pas de valeur par défaut ; si elle n'est pas définie, le modèle détecte automatiquement la langue. Vous pouvez définir une seule valeur. Si vous en définissez plusieurs, seule la première prend effet. Cliquez pour afficher les codes de langue pris en charge fun-asr-realtime: zh : Chinois en : Anglais ja : Japonais ko : Coréen vi : Vietnamien th : Thaï id : Indonésien ms : Malais tl : Filipino hi : Hindi ar : Arabe fr : Français de : Allemand es : Espagnol pt : Portugais ru : Russe it : Italien nl : Néerlandais sv : Suédois da : Danois fi : Finnois no : Norvégien el : Grec pl : Polonais cs : Tchèque hu : Hongrois ro : Roumain bg : Bulgare hr : Croate sk : Slovaque fun-asr-realtime-2026-02-28: zh : Chinois en : Anglais ja : Japonais fun-asr-flash-8k-realtime, fun-asr-flash-8k-realtime-2026-01-28: zh : Chinois fun-asr-mtl-realtime-2025-12-10: zh : Chinois en : Anglais ja : Japonais ko : Coréen vi : Vietnamien id : Indonésien th : Thaï
  nls_config.speech_noise_threshold	float	Non	Le seuil pour distinguer la parole du bruit, utilisé pour ajuster la sensibilité de la détection d'activité vocale (VAD). Valeurs valides : [-1.0, 1.0]. Descriptions des valeurs : Plus la valeur est proche de -1 : Le seuil de bruit diminue, donc le bruit est plus susceptible d'être reconnu comme de la parole, ce qui peut entraîner la transcription de davantage de bruit. Plus la valeur est proche de +1 : Le seuil de bruit augmente, donc la parole est plus susceptible d'être jugée à tort comme du bruit, ce qui peut entraîner le filtrage de certaines paroles. Il s'agit d'un paramètre de configuration avancé. Son ajustement peut affecter considérablement les résultats de la reconnaissance. Recommandations : Effectuer des tests et vérifier minutieusement les résultats avant tout ajustement. Ajustez par petits incréments en fonction de l'environnement audio réel (un pas de 0.1 est recommandé).
  nls_config.special_word_filter	object	Non	Spécifie les mots sensibles à traiter lors de la reconnaissance vocale et permet de définir différentes méthodes de traitement pour différents mots sensibles. Pour plus de détails, voir Filtrage des mots sensibles.
  nls_config.enable_connection_fast_check	boolean	Non	Indique s'il faut détecter rapidement les pannes réseau et les signaler dès que possible. Par défaut : false.

Interfaces clés

NativeNui

initialize

Initialise une instance SDK de reconnaissance vocale. Le SDK est un singleton. Ne l'initialisez pas plus d'une fois avant d'appeler release.

Cette méthode est bloquante, appelez-la donc sur un thread non UI.

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  callback	INativeNuiCallback	L'implémentation de l'interface de rappel des événements et des données.
  parameters	String	Une chaîne JSON contenant les paramètres d'authentification, de connexion et de débogage. Voir Paramètres de connexion et de contrôle.
  level	Constants.LogLevel	Contrôle le niveau d'impression des propres journaux du SDK.
  save_log	boolean	Indique s'il faut sauvegarder les journaux locaux. Si défini sur true, spécifiez le chemin via debug_path dans les Paramètres de connexion et de contrôle, et définissez éventuellement la taille du fichier via max_log_file_size.

• Valeur de retour

setParams

Définit les Paramètres de reconnaissance vocale au format JSON. Appelez cette méthode avant startDialog.

• Signature de la méthode

public synchronized int setParams(String params)

• Paramètres

  Paramètre	Type	Description
  params	String	Paramètres de reconnaissance vocale.

• Valeur de retour

startDialog

Démarre la reconnaissance.

• Signature de la méthode

public synchronized int startDialog(VadMode vad_mode, String dialog_params)

• Paramètres

  Paramètre	Type	Description
  vad_mode	VadMode	Le mode VAD. Fixé à VadMode.TYPE_P2T.
  dialog_params	String	Si le paramètre apikey dans Paramètres de connexion et de contrôle utilise une clé API temporaire, vous pouvez la mettre à jour ici lorsqu'elle expire. Pour améliorer la précision de la reconnaissance en utilisant le contexte, mettez à jour le contexte ici. Le contenu est au format JSON : { "apikey": "st-****", "input_context": [ { "role": "user", "content": [ { "text": "xxxxx", "type": "input_text" } ] } ] }

• Valeur de retour

stopDialog

Termine la reconnaissance. Après avoir appelé cette méthode, le serveur retourne le résultat final de reconnaissance et termine la tâche.

• Signature de la méthode

public synchronized int stopDialog();

• Valeur de retour

cancelDialog

Arrête la reconnaissance immédiatement. Après avoir appelé cette méthode, la tâche se termine aussitôt sans attendre que le serveur retourne le résultat final de reconnaissance.

• Signature de la méthode

public synchronized int cancelDialog();

• Valeur de retour

updateAction

Envoie une commande d'action pendant une interaction pour mettre à jour le comportement d'exécution, tel que le contexte de reconnaissance.

• Signature de la méthode

public synchronized int updateAction(String params);

• Paramètres

  Paramètre	Type	Description
  params	String	Une chaîne JSON utilisée pour mettre à jour le comportement d'exécution, tel que le contexte de reconnaissance.
  params.type	String	Définir sur "action".
  params.command	String	La commande d'exécution. Valeurs valides : context : Met à jour immédiatement le contexte pour améliorer la précision de la reconnaissance. play_start : Lorsque l'AEC sur appareil est utilisé, notifie au SDK que le lecteur a commencé à lire l'audio. play_over : Lorsque l'AEC sur appareil est utilisé, notifie au SDK que le lecteur a terminé la lecture de l'audio.
  params.context	String	Lorsque command est défini sur context, met à jour immédiatement le contexte pour améliorer la précision de la reconnaissance. La valeur est une chaîne JSON, comme illustré dans l'exemple suivant.

{
  "context": [
    {
      "role": "user",
      "content": [
        {
          "text": "xxx",
          "type": "input_text"
        }
      ]
    }
  ]
}

• Valeur de retour

updateAudio

Lorsque audio_update_manually est défini sur "true", appelez cette méthode pour pousser activement les données d'enregistrement au lieu de fournir les données via onNuiNeedAudioData.

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  data	byte[]	Les données audio à transmettre.
  len	int	Le nombre d'octets de données audio à transmettre.
  first_pack	boolean	Ignorer ce paramètre.

• Valeur de retour

updateRefAudio

Lorsque audio_update_manually est défini sur "true" et que l'AEC sur appareil est activé, appelez cette méthode pour pousser l'audio lu par le lecteur comme signal de référence.

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  data	byte[]	Les données audio à transmettre.
  len	int	Le nombre d'octets de données audio à transmettre.
  first_pack	boolean	Ignorer ce paramètre.

• Valeur de retour

release

Libère toutes les ressources internes du SDK. Après avoir appelé cette méthode, l'instance SDK devient indisponible. Pour l'utiliser à nouveau, vous devez la réinitialiser en appelant initialize.

• Signature de la méthode

public synchronized int release();

• Valeur de retour

GetVersion

Obtient les informations de version actuelle du SDK.

• Signature de la méthode

public synchronized String GetVersion();

• Valeur de retour

  Les informations de version actuelle du SDK.

INativeNuiCallback : rappels d'écoute

onNuiEventCallback : écouter les événements et les résultats de reconnaissance vocale

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  event	NuiEvent	L'événement de rappel.
  resultCode	int	Valide uniquement lorsque l’événement EVENT_ASR_ERROR se produit.
  arg2	int	Un paramètre réservé.
  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.

onNuiAudioStateChanged : écouter l'état audio

Le SDK utilise ce rappel pour vous notifier quand démarrer ou arrêter l'enregistrement.

• Signature de la méthode

void onNuiAudioStateChanged(AudioState state);

• États AudioState

  État	Description
  STATE_OPEN	L'interaction a commencé. Vous pouvez ouvrir le périphérique d'enregistrement et commencer l'enregistrement.
  STATE_PAUSE	L'interaction s'est arrêtée. Vous pouvez arrêter l'enregistrement.
  STATE_CLOSE	L'instance du SDK a été libérée. Vous pouvez fermer complètement le périphérique d'enregistrement.

onNuiNeedAudioData : fournir les données audio à reconnaître

Après le début de la reconnaissance, ce rappel est déclenché en continu. Fournissez les données audio à reconnaître dans ce rappel.

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  buffer	byte[]	Les données audio à remplir.
  len	int	Le nombre d'octets de données audio à remplir.

• Valeur de retour

  Le nombre d'octets effectivement remplis.

onNuiAssistEventCallback : recevoir les événements et données auxiliaires

Ce rappel reçoit les événements auxiliaires et les données associées du SDK.

• Signature de la méthode

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

• Paramètres

  Paramètre	Type	Description
  event	int	Un événement NuiEvent.
  info	String	Ignorer ce paramètre.
  info_len	int	Ignorer ce paramètre.
  data	byte[]	Données auxiliaires, telles que les données audio traitées par l'AEC.

onNuiLogTrackCallback : écouter les journaux de trace

Ce rappel reçoit les journaux internes détaillés du SDK pour aider au dépannage et au débogage.

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

NuiEvent : types d'événements

Événement	Description
EVENT_TRANSCRIBER_STARTED	La tâche a démarré avec succès.
EVENT_VAD_START	Déclenché juste après le début de la tâche. Cela ne signifie pas que le début de la parole est 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_WARN	Un avertissement qui n'interrompt pas la reconnaissance vocale s'est produit, comme une panne réseau lorsque la reconnexion est activée.
EVENT_ASR_ERROR	Une erreur s'est produite lors de la reconnaissance vocale.
EVENT_MIC_ERROR	Déclenché lorsqu'aucune donnée audio n'est reçue pendant 2 secondes consécutives.
EVENT_SENTENCE_END	La fin d'une phrase est détectée. Un résultat de reconnaissance complet pour la phrase est retourné.
EVENT_TRANSCRIBER_COMPLETE	La reconnaissance vocale est terminée.
EVENT_AEC_DATA	Données audio traitées par l'AEC.