Qwen-Audio-TTS HarmonyOS SDK - Alibaba Cloud Model Studio - Centre de documentation Alibaba Cloud

Découvrez l'intégration du SDK HarmonyOS, les paramètres, les API, les rappels et le code d'exemple pour la synthèse vocale en temps réel.

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 singleton MODE_DIALOG et 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() ou asyncPlayStreamInputTts().
Recevez les événements de synthèse et l'audio via INativeStreamInputTtsCallback.
Le SDK retourne STREAM_INPUT_TTS_EVENT_SYNTHESIS_STARTED au démarrage de la tâche, l'audio via onStreamInputTtsDataCallback, STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE à la fin de la tâche, et STREAM_INPUT_TTS_EVENT_TASK_FAILED en cas d'échec de la synthèse.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_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 playStreamInputTts ou asyncPlayStreamInputTts pour 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'abord startStreamInputTts et 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_COMPLETE est reçu.

L'entrée en streaming convient aux conversations en temps réel ou à la synthèse incrémentielle de textes longs. Le SSML n'est pas pris en charge dans ce mode.

Appelez startStreamInputTts pour ouvrir la connexion et configurer le rappel et les paramètres.
Appelez sendStreamInputTts pour 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_COMPLETE est reçu.

Lorsque la synthèse vocale n'est plus nécessaire, appelez 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.

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.

startStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

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`.

La méthode retourne un code d'erreur. Constants.NuiResultCode.SUCCESS (0) indique un succès.

champs ticket

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

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/inference` pour Pékin ou `wss://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api-ws/v1/inference` pour 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.

champs parameters

{
  "model": "qwen-audio-3.0-tts-flash",
  "voice": "longanlingxi",
  "format": "mp3",
  "sample_rate": 24000,
  "volume": 50,
  "rate": 1.0,
  "pitch": 1.0,
  "enable_audio_decoder": true
}

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	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`.
`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.

sendStreamInputTts

sendStreamInputTts(text: string): number

Envoie un fragment de texte après la réussite de 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.

La méthode renvoie un code d'erreur.

stopStreamInputTts

stopStreamInputTts(flag_async: boolean = true): number

Termine l'entrée en streaming.

true (par défaut) : Termine de manière asynchrone et retourne immédiatement. Attendez STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE pour 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é par complete_waiting_ms.

L'appel d'une méthode d'annulation après un arrêt synchrone peut bloquer. Nous recommandons le mode asynchrone par défaut.

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.

La méthode renvoie un code d'erreur.

cancelStreamInputTts

cancelStreamInputTts(): number

Ferme immédiatement la connexion et met fin à la tâche en cours. Aucun autre rappel audio n'est reçu après cet appel. La méthode retourne un code d'erreur.

cancelStreamInputTtsKeepConnection

cancelStreamInputTtsKeepConnection(): number

Envoie une commande d'annulation au niveau du protocole pour mettre fin à la tâche en cours tout en maintenant la connexion WebSocket ouverte. Utilisez cette méthode lorsqu'un autre cycle de synthèse doit démarrer immédiatement, évitant ainsi le coût de la réouverture de la connexion. La méthode retourne un code d'erreur.

playStreamInputTts

playStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Synthèse unique synchrone. Cette méthode initialise la tâche, envoie le texte, reçoit tout l'audio, puis retourne. N'appelez pas d'abord 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

asyncPlayStreamInputTts(
  callback: INativeStreamInputTtsCallback,
  ticket: string,
  parameters: string,
  text: string,
  session_id: string,
  log_level: number,
  save_log: boolean
): number

Synthèse unique asynchrone. Cette méthode retourne immédiatement et fournit les résultats via des rappels. N'appelez pas d'abord 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.

releaseStreamInputTts

releaseStreamInputTts(): number

Libère l'instance TTS en streaming et ses ressources. Appelez cette méthode lorsque la page est détruite ou que la synthèse vocale n'est plus nécessaire. La méthode retourne un code d'erreur.

INativeStreamInputTtsCallback

export interface INativeStreamInputTtsCallback {
  onStreamInputTtsEventCallback(
    event: StreamInputTtsEvent,
    task_id: string,
    session_id: string,
    ret_code: number,
    error_msg: string,
    timestamp: string,
    all_response: string
  ): void;

  onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;
}

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

onStreamInputTtsDataCallback(data: ArrayBuffer | null): void;

Renvoie en continu des fragments audio. Notez ce qui suit :

Les données MP3 et Opus nécessitent un décodeur en streaming. Vous pouvez également définir enable_audio_decoder sur true pour 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.

Exemple de réponse d'échec de tâche :

{
  "header": {
    "task_id": "2bf83b9a-baeb-4fda-8d9a-xxxxxxxxxxxx",
    "event": "task-failed",
    "error_code": "InvalidParameter",
    "error_message": "[tts:]Engine return error code: 418",
    "attributes": {}
  },
  "payload": {}
}

Exemple de code

Obtenez une clé API. Ne codez pas en dur une clé API à longue durée de vie dans une application cliente. Nous vous recommandons de faire en sorte que votre serveur d'application obtienne une clé API temporaire et l'envoie au client.
Téléchargez le dernier package SDK. Extrayez le package, copiez entry/libs/neonui.har dans le répertoire entry/libs de votre application, et ajoutez la dépendance à entry/oh-package.json5 :

{
  "dependencies": {
    "neonui": "file:libs/neonui.har"
  }
}

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.

import { Constants, INativeStreamInputTtsCallback, NativeNui, StreamInputTtsEvent } from 'neonui';

const callback: INativeStreamInputTtsCallback = {
  onStreamInputTtsEventCallback: (event: StreamInputTtsEvent, taskId: string,
    sessionId: string, retCode: number, errorMsg: string,
    timestamp: string, allResponse: string): void => {
    if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_SYNTHESIS_COMPLETE) {
      // Synthesis is complete.
    } else if (event == StreamInputTtsEvent.STREAM_INPUT_TTS_EVENT_TASK_FAILED) {
      // Handle the error based on retCode, errorMsg, or allResponse.
    }
  },
  onStreamInputTtsDataCallback: (data: ArrayBuffer | null): void => {
    if (data != null) {
      // Write PCM to AudioRenderer, or append encoded audio data in order.
    }
  }
};

const nuiInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
const ticket: Record<string, Object> = {
  'url': 'wss://dashscope.aliyuncs.com/api-ws/v1/inference',
  'apikey': 'st-****',
  'device_id': 'my_device_id'
};
const parameters: Record<string, Object> = {
  'model': 'qwen-audio-3.0-tts-flash',
  'voice': 'longanlingxi',
  'format': 'mp3',
  'sample_rate': 24000,
  'enable_audio_decoder': true
};

const result = nuiInstance.startStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);

if (result == Constants.NuiResultCode.SUCCESS) {
  nuiInstance.sendStreamInputTts('Hello, ');
  nuiInstance.sendStreamInputTts('welcome to real-time speech synthesis.');
  nuiInstance.stopStreamInputTts(true);
}

// Call nuiInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Pour une entrée unique, appelez directement playStreamInputTts ou asyncPlayStreamInputTts :

const oneShotInstance = new NativeNui(Constants.ModeType.MODE_STREAM_INPUT_TTS);
oneShotInstance.asyncPlayStreamInputTts(
  callback,
  JSON.stringify(ticket),
  JSON.stringify(parameters),
  'Hello, welcome to real-time speech synthesis.',
  '',
  Constants.LogLevel.LOG_LEVEL_INFO,
  false
);
// Call oneShotInstance.releaseStreamInputTts() from the SYNTHESIS_COMPLETE handler.

Fonctionnalités avancées

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.