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.
-
Téléchargez le dernier package SDK. Extrayez le package, copiez
entry/libs/neonui.hardans le répertoireentry/libsde votre application, et ajoutez la dépendance àentry/oh-package.json5:
Démarrage rapide
Qwen-Audio-TTS / CosyVoice
Ouvrez le projet d'exemple du package SDK dans DevEco Studio. La page d'exemple est entry/src/main/ets/pages/dashscope/DashCosyVoiceStreamTtsPage.ets. Configurez une clé API et exécutez le projet.
Le code suivant illustre le flux principal d'entrée en streaming. Pour la lecture audio complète, la sélection des paramètres et la gestion de l'état des tâches, consultez DashCosyVoiceStreamTtsPage.ets dans le package SDK.
Pour exécuter cet exemple avec CosyVoice, définissez model sur cosyvoice-v3-plus et voice sur longanyang.
playStreamInputTts ou asyncPlayStreamInputTts :
Paramètres de requête
champs ticket
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
url | string | Oui | Point de terminaison du service. Utilisez le point de terminaison public wss://dashscope.aliyuncs.com/api-ws/v1/inference, ou un point de terminaison spécifique à l'espace de travail : wss://{WorkspaceId}.cn-beijing.maas.aliyuncs.com/api-ws/v1/inferencepour Pékin ou wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inferencepour Singapour. Remplacez {WorkspaceId} par votre ID d'espace de travail. |
apikey | string | Oui | Clé API. Utilisez une clé API temporaire pour réduire le risque d'exposer une clé à longue durée de vie. |
device_id | string | Oui | Un identifiant unique de l'utilisateur final, tel qu'un ID d'utilisateur dans l'application ou un ID d'appareil généré par le client. Il est principalement utilisé pour le suivi des journaux et le dépannage. |
complete_waiting_ms | number | Non | Temps en millisecondes à attendre pour l'événement de fin de synthèse après stopStreamInputTts(false). Valeur par défaut : 10000. |
debug_path | string | Non | Répertoire des journaux. Ce champ est requis lorsque save_log est true. Le SDK conserve au maximum deux fichiers journaux. |
max_log_file_size | number | Non | Taille maximale d'un seul fichier journal en octets. Valeur par défaut : 104857600 (100 Mio). Ce champ prend effet uniquement lorsque save_log est true. |
log_track_level | number | Non | Niveau de filtre des journaux de trace internes. Par défaut : 2. Les valeurs valides sont les mêmes que log_level. L'interface de rappel HarmonyOS n'expose pas actuellement de rappel de journal TTS en streaming, de sorte que les journaux filtrés sont écrits uniquement par le SDK. |
Qwen-Audio-TTS
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
model | string | Oui | Nom du modèle. Consultez Modèles de synthèse vocale. |
voice | string | Oui | Voix. Pour les voix système, consultez voix Qwen-Audio-TTS. Vous pouvez également utiliser une voix créée par clonage de voix ou Voice Design. |
format | string | Non | Format d'encodage audio : pcm, wav, mp3 (par défaut), ou opus. |
enable_audio_decoder | boolean | Non | Indique s'il faut activer le décodeur du SDK. Par défaut : false. Pour MP3 ou Opus, définissez ceci sur true pour décoder l'audio en PCM avant qu'il ne soit retourné via le rappel de données. |
volume | number | Non | Volume. Par défaut : 50. Plage valide : [0, 100]. |
sample_rate | number | Non | Taux d'échantillonnage en Hz. Valeurs valides : 8000, 16000, 22050 (par défaut), 24000, 44100, et 48000. |
rate | number | Non | Débit de parole. Par défaut : 1.0. Plage valide : [0.5, 2.0]. |
pitch | number | Non | Hauteur. Par défaut : 1.0. Plage valide : [0.5, 2.0]. |
bit_rate | number | Non | Débit binaire MP3 ou Opus en kbit/s. Par défaut : 32. Plage valide : [6, 510]. |
enable_ssml | boolean | Non | Indique s'il faut activer le SSML. Par défaut : false. Consultez Limites du SSML. |
word_timestamp_enabled | boolean | Non | Indique s'il faut retourner les horodatages au niveau des mots. Par défaut : false. Ce champ est disponible uniquement pour la sortie en streaming. Les voix clonées sont prises en charge. Pour les voix système compatibles, consultez liste des voix Qwen-Audio-TTS. Les résultats d'horodatage sont inclus dans all_response de INativeStreamInputTtsCallback. |
seed | number | Non | Graine aléatoire utilisée pour varier le résultat synthétisé. Si la version du modèle, le texte, la voix et tous les autres paramètres sont identiques, la même seed reproduit le même résultat. Par défaut : 0. Plage valide : [0, 65535]. |
language_hints | string[] | Non | Pour les voix multilingues et dialectales de qwen-audio-3.1-tts-flash, ce paramètre permet de spécifier la langue ou le dialecte. Consultez les paramètres des voix multilingues et dialectales pour en savoir plus. "hello, this is 110" soit lu « un un zéro » en anglais au lieu de la lecture chinoise, ou faire en sorte que @ soit lu « at ».
Valeurs valides
|
instruction | string | Non | Instruction qui contrôle le dialecte, l'émotion ou le rôle. Consultez Contrôle des instructions. |
enable_aigc_tag | boolean | Non | Indique s'il faut intégrer une balise AIGC invisible. Par défaut : false. |
aigc_propagator | string | Non | ContentPropagator champ dans la balise AIGC. Prend effet uniquement lorsque enable_aigc_tag est true. Par défaut : l'UID Alibaba Cloud. Les modèles pris en charge sont les mêmes que pour enable_aigc_tag. |
aigc_propagate_id | string | Non | PropagateID champ dans la balise AIGC. Prend effet uniquement lorsque enable_aigc_tag est true. Par défaut : l'ID de la requête en cours. Les modèles pris en charge sont les mêmes que pour enable_aigc_tag. |
hot_fix | object | Non | Paramètres de correctif à chaud du texte pour la prononciation personnalisée et le remplacement de texte. Pour le schéma, consultez Événements client. |
CosyVoice
| Champ | Type | Obligatoire | Description |
|---|---|---|---|
model | string | Oui | Nom du modèle. Consultez Modèles de synthèse vocale. |
voice | string | Oui | Voix. Pour les voix système, consultez voix CosyVoice. Vous pouvez également utiliser une voix créée par clonage de voix ou Voice Design. |
format | string | Non | Format d'encodage audio : pcm, wav, mp3 (par défaut), ou opus. |
enable_audio_decoder | boolean | Non | Indique s'il faut activer le décodeur du SDK. Par défaut : false. Pour MP3 ou Opus, définissez ceci sur true pour décoder l'audio en PCM avant qu'il ne soit retourné via le rappel de données. |
volume | number | Non | Volume. Par défaut : 50. Plage valide : [0, 100]. |
sample_rate | number | Non | Taux d'échantillonnage en Hz. Valeurs valides : 8000, 16000, 22050 (par défaut), 24000, 44100, et 48000. |
rate | number | Non | Débit de parole. Par défaut : 1.0. Plage valide : [0.5, 2.0]. |
pitch | number | Non | Hauteur. Par défaut : 1.0. Plage valide : [0.5, 2.0]. |
bit_rate | number | Non | Débit binaire MP3 ou Opus en kbit/s. Par défaut : 32. Plage valide : [6, 510]. |
enable_ssml | boolean | Non | Indique s'il faut activer le SSML. Par défaut : false. Consultez Limites du SSML. |
word_timestamp_enabled | boolean | Non | Indique s'il faut retourner les horodatages au niveau des mots. Par défaut : false. Ce champ est disponible uniquement pour la sortie en streaming. Il prend en charge les voix clonées de cosyvoice-v3.5-plus, cosyvoice-v3.5-flash, cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2, ainsi que les voix système marquées comme prises en charge dans la liste des voix CosyVoice. Les voix clonées d'autres modèles ne sont pas prises en charge. Les résultats d'horodatage sont inclus dans all_response de INativeStreamInputTtsCallback. |
seed | number | Non | Graine aléatoire utilisée pour varier le résultat synthétisé. Si la version du modèle, le texte, la voix et tous les autres paramètres sont identiques, la même seed reproduit le même résultat. Par défaut : 0. Plage valide : [0, 65535]. |
language_hints | string[] | Non | Langue cible de la synthèse. Ce paramètre améliore la synthèse et est indépendant de la langue de l'échantillon audio utilisé pour le clonage de voix. Pour définir la langue source d'une tâche de clonage de voix, consultez la référence de l’API de clonage de voix. La version actuelle utilise uniquement le premier élément du tableau, transmettez donc une seule valeur. Utilisez ce champ lorsque la lecture des nombres, des abréviations ou des symboles est inattendue, ou lorsque la synthèse dans une langue moins courante n'est pas naturelle. Par exemple, il peut faire en sorte que "hello, this is 110" soit lu « un un zéro » en anglais au lieu de la lecture chinoise, ou faire en sorte que @ soit lu « at ».
Valeurs valides Valeurs prises en charge : zh, en, fr, de, ja, ko, ru, pt, th, id, vi, es, it, ms, fil, et ar. |
instruction | string | Non | Instruction qui contrôle le dialecte, l'émotion ou le rôle. Consultez Contrôle des instructions. |
enable_aigc_tag | boolean | Non | Indique s'il faut intégrer une balise AIGC invisible. Par défaut : false. Pris en charge par cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2. |
aigc_propagator | string | Non | ContentPropagator champ dans la balise AIGC. Prend effet uniquement lorsque enable_aigc_tag est true. Par défaut : l'UID Alibaba Cloud. Les modèles pris en charge sont les mêmes que pour enable_aigc_tag. |
aigc_propagate_id | string | Non | PropagateID champ dans la balise AIGC. Prend effet uniquement lorsque enable_aigc_tag est true. Par défaut : l'ID de la requête en cours. Les modèles pris en charge sont les mêmes que pour enable_aigc_tag. |
hot_fix | object | Non | Paramètres de correctif à chaud du texte pour la prononciation personnalisée et le remplacement de texte.cosyvoice-v2 ne prennent pas en charge ce champ. |
Référence de l’API
NativeNui
Le SDK HarmonyOS fournit la synthèse vocale en streaming via NativeNui.
- Créez une instance de synthèse vocale en streaming en appelant
new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS).NativeNui.GetInstance()retourne un singletonMODE_DIALOGet ne peut pas être utilisé pour la synthèse vocale en streaming. - N'appelez pas
initialize()en mode de synthèse vocale en streaming. Transmettez les identifiants et les paramètres de synthèse directement àstartStreamInputTts(),playStreamInputTts()ouasyncPlayStreamInputTts(). - Recevez les événements de synthèse et l'audio via
INativeStreamInputTtsCallback. - Le SDK retourne
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTEDau démarrage de la tâche, l'audio viaonStreamInputTtsDataCallback,STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEà la fin de la tâche, etSTREAM_INPUT_TTS_EVENT_TASK_FAILEDen cas d'échec de la synthèse.
startStreamInputTts
Démarre la synthèse en streaming bidirectionnel, ouvre la connexion et enregistre le rappel. Cette méthode peut être bloquante. Ne l'appelez pas sur le thread de l'interface utilisateur.
| Paramètre | Type | Description |
|---|---|---|
callback | INativeStreamInputTtsCallback | Rappel d'événement et audio. |
ticket | string | Chaîne JSON contenant les paramètres d'authentification, de connexion et de débogage. |
parameters | string | Chaîne JSON contenant les paramètres de synthèse. |
session_id | string | ID de session spécifié par le client. Transmettez une chaîne vide pour laisser le serveur en générer un. |
log_level | number | Niveau de journalisation du SDK. Utilisez une Constants.LogLevel valeur : 0 (VERBOSE), 1 (DEBUG), 2 (INFO), 3 (WARNING), 4 (ERROR) ou 5 (NONE). |
save_log | boolean | Indique s'il faut enregistrer les journaux localement. Si défini sur true, définissez debug_path dans ticket. |
Constants.NuiResultCode.SUCCESS (0) indique un succès.
sendStreamInputTts
startStreamInputTts. Cette méthode n'analyse pas les balises SSML. Une fois tout le texte envoyé, appelez stopStreamInputTts().
| Paramètre | Type | Description |
|---|---|---|
text | string | Texte à synthétiser. SSML n'est pas pris en charge. Les balises SSML sont lues comme du texte ordinaire. |
stopStreamInputTts
true(par défaut) : Termine de manière asynchrone et retourne immédiatement. AttendezSTREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEpour déterminer que la synthèse est terminée.false: Bloque jusqu'à la réception de tout l'audio et de l'événement de fin de synthèse. Le délai d'attente est contrôlé parcomplete_waiting_ms.
| Paramètre | Type | Description |
|---|---|---|
flag_async | boolean | Indique s'il faut terminer de manière asynchrone. Par défaut : true. true retourne sans attendre de réponse du serveur. false bloque jusqu'à ce que la synthèse soit terminée. |
cancelStreamInputTts
cancelStreamInputTtsKeepConnection
playStreamInputTts
startStreamInputTts et n'appelez pas de méthode d'arrêt ensuite. Le SSML est activé par défaut. Si enable_ssml est explicitement défini, cette valeur est prioritaire. N'appelez pas cette méthode sur le thread de l'interface utilisateur.
callback, ticket, parameters, session_id, log_level et save_log sont définis dans startStreamInputTts. text est le texte à synthétiser et prend en charge le SSML. La méthode retourne un code d'erreur.
asyncPlayStreamInputTts
startStreamInputTts et n'appelez pas de méthode d'arrêt ensuite. Le SSML est activé par défaut. Si enable_ssml est explicitement défini, cette valeur est prioritaire.
callback, ticket, parameters, session_id, log_level et save_log sont définis dans startStreamInputTts. text est le texte à synthétiser et prend en charge le SSML. La méthode retourne un code d'erreur.
releaseStreamInputTts
INativeStreamInputTtsCallback
onStreamInputTtsEventCallback
| Paramètre | Type | Description |
|---|---|---|
event | StreamInputTtsEvent | Événement de synthèse. |
task_id | string | ID de la tâche de synthèse. |
session_id | string | ID de session. Une valeur spécifiée par le client est retournée inchangée. Sinon, le serveur en génère une. |
ret_code | number | Code d'erreur. Valide uniquement pour un événement d'échec de tâche. |
error_msg | string | Message d'erreur. Valide uniquement pour un événement d'échec de tâche. |
timestamp | string | Résultat de l'horodatage. |
all_response | string | Réponse complète du serveur sous forme de chaîne JSON. Analysez-la pour obtenir les détails d'utilisation, d'horodatage et d'erreur. |
onStreamInputTtsDataCallback
- Les données MP3 et Opus nécessitent un décodeur en streaming. Vous pouvez également définir
enable_audio_decodersurtruepour que le SDK retourne du PCM. - Pour assembler un fichier complet, ajoutez les données de rappel dans l'ordre.
- Pour les formats WAV et MP3, seul le premier rappel contient l'en-tête du fichier. Chaque trame Opus est une page Ogg indépendante et peut être concaténée dans l'ordre.
StreamInputTtsEvent
| Événement | Description |
|---|---|
STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED | Le serveur a accepté la requête et a commencé le traitement. Les premières données audio arrivent généralement via onStreamInputTtsDataCallback peu après cet événement. |
STREAM_INPUT_TTS_EVENT_SENTENCE_BEGIN | Le serveur a commencé à synthétiser une énonciation. |
STREAM_INPUT_TTS_EVENT_SENTENCE_SYNTHESIS | Informations sur la progression de la synthèse, y compris les informations de facturation et les horodatages. |
STREAM_INPUT_TTS_EVENT_SENTENCE_END | Le serveur a terminé la synthèse d'un énoncé. |
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE | Le serveur a renvoyé toutes les données audio. onStreamInputTtsEventCallback n'est pas appelé après cet événement, qui est le signal explicite de fin de flux. Cet événement n'indique pas que la lecture locale est terminée. |
STREAM_INPUT_TTS_EVENT_TASK_FAILED | Échec de la synthèse. Récupérer task_id, error_code, et error_message depuis all_response, ou utiliser les ret_code et error_msg arguments de rappel. |
SSML
Objectif : Intégrer des balises XML dans le texte pour contrôler la prononciation, le débit de parole, les pauses et d'autres détails de synthèse.
Limites : Seules les API d'entrée unique playStreamInputTts et asyncPlayStreamInputTts prennent en charge le SSML. L'API d'entrée en streaming sendStreamInputTts ne le prend pas en charge.
Utilisation : Le SDK active le SSML par défaut pour playStreamInputTts et asyncPlayStreamInputTts. Transmettez le texte SSML dans text. Pour plus d'informations, consultez SSML et LaTeX.
Expressions mathématiques
Objectif : Faire en sorte que le modèle lise correctement les formules et expressions mathématiques courantes.
Utilisation : Transmettez du texte contenant une expression mathématique au format LaTeX dans text. Pour la syntaxe prise en charge, consultez Synthèse vocale LaTeX.
Qwen-Audio-TTS
Flux d'appels
Qwen-Audio-TTS prend en charge l'entrée unique et l'entrée en streaming.
L'entrée unique convient aux textes courts ou aux scénarios nécessitant le SSML.
- Appelez
playStreamInputTtsouasyncPlayStreamInputTtspour transmettre le texte complet et démarrer la synthèse. La première méthode bloque jusqu'à la fin de la synthèse. La seconde retourne immédiatement et synthétise en arrière-plan. N'appelez pas d'abordstartStreamInputTtset n'appelez pas de méthode d'arrêt ensuite. - Recevez l'audio dans
onStreamInputTtsDataCallback. - La synthèse se termine lorsque
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEest reçu.
- Appelez
startStreamInputTtspour ouvrir la connexion et configurer le rappel et les paramètres. - Appelez
sendStreamInputTtspour envoyer des fragments de texte. - Recevez l'audio dans
onStreamInputTtsDataCallback. - Une fois tout le texte envoyé, appelez
stopStreamInputTts. - La synthèse se termine lorsque
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEest reçu.
releaseStreamInputTts pour libérer les ressources.
La longueur d'une seule entrée de texte et la longueur cumulée de plusieurs entrées sont toutes deux limitées. Consultez l'API WebSocket Qwen-Audio-TTS.
Fonctionnalités avancées
CosyVoice
Flux d'appels
CosyVoice prend en charge l'entrée unique et l'entrée en streaming.
L'entrée unique convient aux textes courts ou aux scénarios nécessitant le SSML.
- Appelez
playStreamInputTtsouasyncPlayStreamInputTtspour transmettre le texte complet et démarrer la synthèse. La première méthode bloque jusqu'à la fin de la synthèse. La seconde retourne immédiatement et synthétise en arrière-plan. N'appelez pas d'abordstartStreamInputTtset n'appelez pas de méthode d'arrêt ensuite. - Recevez l'audio dans
onStreamInputTtsDataCallback. - La synthèse se termine lorsque
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEest reçu.
- Appelez
startStreamInputTtspour ouvrir la connexion et configurer le rappel et les paramètres. - Appelez
sendStreamInputTtspour envoyer des fragments de texte. - Recevez l'audio dans
onStreamInputTtsDataCallback. - Une fois tout le texte envoyé, appelez
stopStreamInputTts. - La synthèse se termine lorsque
STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETEest reçu.
releaseStreamInputTts pour libérer les ressources.
La longueur d'une seule entrée de texte et la longueur cumulée de plusieurs entrées sont toutes deux limitées. Consultez l'API WebSocket CosyVoice.