Alibaba Cloud Model Studio:SDK HarmonyOS de synthèse vocale Sambert

Ce guide explique comment utiliser le SDK HarmonyOS de synthèse vocale Sambert pour convertir du texte en parole expressive de haute qualité.

Guide d'utilisation : Pour les présentations des modèles et les recommandations de sélection, consultez Synthèse vocale - Sambert.

Expérience en ligne **** : Non prise en charge.

Remplacez {WorkspaceId} par votre véritable ID d'espace de travail. Le domaine existant reste disponible.

NativeNui

Ce SDK est basé sur l'architecture NativeNui et utilise des rappels pour traiter les événements de synthèse vocale.

Caractéristiques de l'architecture **** :

• Mode instance : Créez une instance de synthèse vocale en utilisant new NativeNui(Constants.ModeType.MODE_TTS).
• Piloté par rappels : Recevez des événements et des données via l'interface NuiTtsSdkListener.
• Types d'événements :
  • NuiSdkTtsEvent : La tâche de synthèse démarre.
  • onTtsDataCallback : Des données audio sont renvoyées.
  • NuiSdkTtsEvent : La tâche de synthèse se termine.
  • NuiSdkTtsEvent : Une erreur de synthèse survient.

Procédure

1. tts_initialize - Initialiser le SDK et configurer l'interface de rappel ainsi que les paramètres de connexion.
2. setParamTts - Configurer les paramètres d'effet de synthèse vocale tels que le modèle, la voix et le volume.
3. startTts - Démarrer une tâche de synthèse vocale.
4. onTtsDataCallback - Recevoir des données audio.
5. tts_release - Libérer les ressources du SDK.

Méthodes Sambert

tts_initialize

Initialise une instance SDK de synthèse vocale. Créez une instance en utilisant new NativeNui(Constants.ModeType.MODE_TTS). Chaque instance correspond à un canal de synthèse vocale. N'initialisez pas la même instance à nouveau avant d'avoir appelé tts_release. Pour traiter plusieurs tâches simultanément, créez plusieurs instances.

Cette interface bloque le thread appelant. Appelez-la depuis un thread non UI.

Signature de la méthode :

public tts_initialize(callback: NuiTtsSdkListener,
                      ticket: string,
                      level: number,
                      save_log: boolean): number

Descriptions des paramètres **** :

Paramètre	Type	Description
callback	NuiTtsSdkListener	Une implémentation de l'interface de rappel d'événements et de données.
ticket	string	Une chaîne JSON contenant des paramètres d'authentification, de connexion et de débogage. Consultez les descriptions des paramètres du ticket ci-dessous.
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 les paramètres du ticket pour spécifier un chemin. Vous pouvez également utiliser max_log_file_size pour définir la taille du fichier.

Exemple JSON de ticket **** :

{
    "url": "wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inference",
    "apikey": "sk-****",
    "device_id": "my_device_id",
    "mode_type": "2"
}

Descriptions des paramètres du ticket **** :

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.
mode_type	string	Oui	Le type de mode. Celui-ci doit être défini sur la chaîne "2", qui indique le mode de synthèse vocale en ligne et correspond à Constants.TtsModeTypeCloud.
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 tts_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.
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 tts_initialize. Valeur par défaut : 104857600 (100 * 1024 * 1024 octets, soit 100 Mio).

setParamTts

Définit les paramètres d'effet de synthèse vocale sous forme de paires clé-valeur. Appelez cette méthode avant startTts.

Signature de la méthode :

public setParamTts(param: string, value: string): number

Descriptions des paramètres **** :

Paramètre	Type	Description
param	string	Le nom du paramètre.
value	string	La valeur du paramètre.

Paramètres disponibles **** :

Paramètre	Type	Obligatoire	Description
model	string	Oui	Le nom du modèle, tel que sambert-zhinan-v1.
format	string	Non	Le format d'encodage audio. Valeurs valides : - pcm - wav - mp3 (par défaut).
volume	string	Non	Le volume. Valeur par défaut : 50. Plage valide : [0, 100].
sample_rate	string	Non	Le taux d'échantillonnage audio en Hz. Valeurs valides : 8000, 16000, 22050, 24000 et 48000. Le taux d'échantillonnage par défaut pour la plupart des modèles vocaux Sambert est 48000. Configurez le lecteur pour utiliser le taux d'échantillonnage correspondant.
rate	string	Non	La vitesse de parole. Valeur par défaut : 1.0. Plage valide : [0.5, 2.0].
pitch	string	Non	La hauteur. Valeur par défaut : 1.0. Plage valide : [0.5, 2.0].
word_timestamp_enabled	string	Non	Spécifie s'il faut activer les horodatages au niveau des mots. Valeur par défaut : false. Ce paramètre s'applique à tous les modèles Sambert.
phoneme_timestamp_enabled	string	Non	Spécifie s'il faut activer les horodatages au niveau des phonèmes. Valeur par défaut : false. Activez d'abord word_timestamp_enabled.
enable_audio_decoder	string	Non	Spécifie s'il faut activer le décodeur audio intégré. Valeur par défaut : 0. Valeurs valides : - 1 : activé. Lorsque format est mp3, définissez ce paramètre sur "1" pour activer le décodeur intégré du SDK. onTtsDataCallback renvoie alors des données PCM décodées. - 0 : désactivé.
enable_callback_vol	string	Non	Spécifie s'il faut activer le rappel de volume. Définissez-le sur "1" pour activer onTtsVolCallback.
apikey	string	Non	Actualise une clé API temporaire pendant l'exécution. Avant le démarrage d'une tâche de synthèse, injectez la dernière clé temporaire en utilisant setParamTts('apikey', ...).

getparamTts

Obtient une valeur de paramètre. Cette méthode est principalement utilisée pour le dépannage.

Signature de la méthode :

public getparamTts(param: string): string

Descriptions des paramètres **** :

Paramètre	Type	Description
param	string	Le nom du paramètre. Actuellement, seul "error_msg" est pris en charge.

Valeur de retour :

La valeur du paramètre.

startTts

Démarre une tâche de synthèse vocale. Le résultat de la synthèse est renvoyé via des rappels.

Signature de la méthode :

public startTts(priority: string, taskid: string, text: string): number

Descriptions des paramètres **** :

Paramètre	Type	Description
priority	string	La priorité de la tâche. Définissez ce paramètre sur 1.
taskid	string	L'ID de la tâche. Si une chaîne vide '' est transmise, le SDK génère automatiquement un ID.
text	string	Le texte à synthétiser.

pauseTts

Met en pause la tâche de synthèse vocale en cours. Une fois la tâche mise en pause, appelez resumeTts pour la reprendre ou cancelTts pour l'annuler. Le SDK ne peut pas démarrer une nouvelle tâche de synthèse tant qu'une tâche est en pause.

Remarque : Cette opération met uniquement en pause la récupération des données depuis le serveur. Les données audio déjà mises en mémoire tampon dans le lecteur continuent d'être lues.

Signature de la méthode :

public pauseTts(): number

resumeTts

Reprend une tâche de synthèse vocale en pause.

Signature de la méthode :

public resumeTts(): number

cancelTts

Annule une tâche de synthèse.

Remarque : Cette opération annule uniquement la récupération des données depuis le serveur. Les données audio déjà mises en mémoire tampon dans le lecteur continuent d'être lues.

Signature de la méthode :

public cancelTts(taskid: string): number

Descriptions des paramètres **** :

Paramètre	Type	Description
taskid	string	L'ID de la tâche à annuler. Si une chaîne vide '' est transmise, toutes les tâches de synthèse en pause ou actives sont annulées.

tts_release

Libère toutes les ressources internes du SDK et termine de force toutes les tâches de synthèse actives. Après l'appel de cette méthode, l'instance du SDK devient indisponible. Pour l'utiliser à nouveau, appelez tts_initialize pour la réinitialiser.

Signature de la méthode :

public tts_release(): number

NuiTtsSdkListener

L'interface de rappel de synthèse vocale Sambert reçoit les événements de synthèse et les données audio. Dans le SDK HarmonyOS, les rappels sont définis comme des fonctions fléchées ArkTS.

onTtsEventCallback

Écoute les événements de démarrage, de fin, d'annulation, de pause, de reprise et d'erreur de la tâche de synthèse vocale.

Signature de la méthode :

onTtsEventCallback: (event: NuiSdkTtsEvent, taskid: string, ret_code: number) => void;

Descriptions des paramètres **** :

Paramètre	Type	Description
event	NuiSdkTtsEvent	L'événement de rappel.
taskid	string	L'ID de la tâche de synthèse vocale.
ret_code	number	Valide uniquement lorsque l’événement TTS_EVENT_ERROR se produit.

onTtsDataCallback

Pendant la synthèse, le SDK déclenche continuellement ce rappel. Obtenez les données audio à partir du rappel.

Signature de la méthode :

onTtsDataCallback: (info: string, info_len: number, buffer: ArrayBuffer | null) => void;

Descriptions des paramètres **** :

Paramètre	Type	Description
info	string	Un résultat d'horodatage au format JSON. Ce paramètre prend effet lorsque word_timestamp_enabled est défini sur "1".
info_len	number	La longueur des données du champ info. Vous pouvez ignorer ce paramètre.
buffer	ArrayBuffer | null	Les données audio pour le segment actuel. Ce paramètre peut être null. Vérifiez la présence de null dans le rappel.

onTtsVolCallback

Une fois enable_callback_vol activé, ce rappel renvoie le volume des données de synthèse venant d'être reçues par le SDK. Il ne s'agit pas du volume actuellement en cours de lecture.

Signature de la méthode :

onTtsVolCallback: (vol: number) => void;

Descriptions des paramètres **** :

Paramètre	Type	Description
vol	number	Le volume des données de synthèse.

NuiSdkTtsEvent

L'énumération des types d'événements de synthèse vocale Sambert.

Événement	Description
TTS_EVENT_START	La tâche de synthèse démarre. Des données audio sont sur le point d'être renvoyées.
TTS_EVENT_END	La tâche de synthèse se termine normalement. Toutes les données audio ont été renvoyées via le rappel.
TTS_EVENT_CANCEL	La tâche de synthèse est annulée.
TTS_EVENT_PAUSE	La tâche de synthèse est en pause.
TTS_EVENT_RESUME	La tâche de synthèse reprend.
TTS_EVENT_ERROR	Une erreur survient pendant la synthèse. Appelez getparamTts("error_msg") pour obtenir les détails. { "header": { "task_id": "xxxxxxxxx", "event": "task-failed", "error_code": "InvalidParameter", "error_message": "Please ensure input text is valid.", "attributes": {} }, "payload": {} }

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.

Exemple de code

1. Obtenir une clé API : Obtenir et configurer une clé API. Pour des raisons de sécurité, nous vous recommandons de configurer la clé API en tant que variable d'environnement.

   RemarquePour accorder un accès temporaire à des applications tierces ou à des utilisateurs, ou pour contrôler strictement des opérations à haut risque telles que l'accès ou la suppression de données sensibles, utilisez une clé API temporaire. Une clé API temporaire est valide pendant 60 secondes par défaut. Obtenez-en une nouvelle après son expiration.

2. Télécharger le SDK et exécuter l'exemple de code :

   • 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.
   • Ouvrez le projet dans DevEco Studio. L'exemple de code se trouve dans DashSambertTtsPage.ets. Remplacez la clé API pour tester la fonctionnalité.

Étapes d'appel

1. Initialiser le SDK : Appelez tts_initialize et passez le rappel NuiTtsSdkListener ainsi que les paramètres ticket.
2. Configurez les paramètres en fonction de vos besoins métier : Utilisez setParamTts pour configurer les paramètres d'effet de synthèse vocale tels que le modèle, le format, le taux d'échantillonnage, la voix et le volume. Nous recommandons de les configurer immédiatement après la réussite de l'initialisation.
3. Appelez startTts pour démarrer la synthèse vocale.
4. Obtenez les données audio depuis le rappel onTtsDataCallback. Nous recommandons une lecture en flux continu comme décrit dans la section Lecture audio ci-dessous. Pour enregistrer l'audio localement, ajoutez les données audio au même fichier jusqu'à la fin de la synthèse.
5. Une fois la tâche terminée, appelez tts_release pour libérer les ressources du SDK.

Lecture audio

HarmonyOS utilise AudioRenderer de @kit.AudioKit pour lire l'audio synthétisé. Le taux d'échantillonnage par défaut de l'audio synthétisé par Sambert est de 48 kHz ; configurez donc le taux d'échantillonnage du lecteur sur 48000.

L'exemple de produit encapsule la logique dans la classe utilitaire AudioPlayer.ets. Spécifiez le taux d'échantillonnage dans le constructeur :

// Play Sambert audio at the default sample rate of 48000. The default for AudioPlayer is 16000.
this.mAudioPlayer = new AudioPlayer(this, 48000);

Le lecteur utilise le rappel writeData pour récupérer les données audio d'une file d'attente et renvoie AudioDataCallbackResult.VALID ou AudioDataCallbackResult.INVALID. Lorsque onTtsEventCallback reçoit TTS_EVENT_END, le SDK a terminé la synthèse et renvoyé toutes les données via les rappels. Marquez la file d'attente de lecture comme terminée afin que le lecteur s'arrête automatiquement après avoir lu les données restantes.