Énoncer des adresses avec SSML

Ce tutoriel explique comment utiliser le langage de balisage de synthèse vocale (SSML) pour énoncer un fichier texte d'adresses. Vous pouvez baliser une chaîne de texte avec des tags SSML afin de personnaliser le son synthétique à partir de Text-to-Speech.

Texte brut	Affichage SSML du texte brut
123 Street Ln	<speak>123 Street Ln</speak>
1 Number St	<speak>1 Number St</speak>
1 Piazza del Fibonacci	<speak>1 Piazza del Fibonacci</speak>

Objectif

Envoyer une requête de voix synthétique à Text-to-Speech à l'aide de SSML et des bibliothèques clientes de Text-to-Speech

Coûts

Reportez-vous à la page des tarifs de Text-to-Speech pour obtenir des informations sur les coûts.

Avant de commencer

Assurez-vous de disposer d'un projet Text-to-Speech dans Google Cloud Console.
Ce tutoriel vous permet d'utiliser Java, Node.js ou Python. Si vous comptez utiliser Java, téléchargez et installez Maven. Si vous comptez utiliser Node.js, téléchargez npm.

Télécharger les exemples de code

Pour télécharger les exemples de code, clonez les exemples GitHub Google Cloud associés au langage de programmation que vous souhaitez utiliser.

Java

Ce tutoriel utilise du code figurant dans le répertoire texttospeech/cloud-client/src/main/java/com/example/texttospeech/ du dépôt d'exemples Java Google Cloud Platform.

Pour télécharger le code pour ce tutoriel et y accéder, exécutez les commandes suivantes depuis le terminal.

git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
cd java-docs-samples/texttospeech/cloud-client/src/main/java/com/example/texttospeech/

Node.js

Ce tutoriel utilise du code figurant dans le répertoire texttospeech du dépôt d'exemples Node.js de Google Cloud Platform.

Pour télécharger le code pour ce tutoriel et y accéder, exécutez les commandes suivantes depuis le terminal.

git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
cd texttospeech/

Python

Ce tutoriel utilise du code figurant dans le répertoire texttospeech/snippets du dépôt d'exemples Python Google Cloud Platform.

Pour télécharger le code pour ce tutoriel et y accéder, exécutez les commandes suivantes depuis le terminal.

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
cd samples/snippets

Installer la bibliothèque cliente

Ce tutoriel utilise la bibliothèque cliente de Text-to-Speech.

Java

Ce tutoriel utilise les dépendances suivantes.

<!--  Using libraries-bom to manage versions.
See https://github.com/GoogleCloudPlatform/cloud-opensource-java/wiki/The-Google-Cloud-Platform-Libraries-BOM -->
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.32.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>
  <dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-texttospeech</artifactId>
  </dependency>
</dependencies>

Node.js

Depuis le terminal, exécutez la commande ci-dessous.

npm install @google-cloud/text-to-speech

Python

Depuis le terminal, exécutez la commande ci-dessous.

pip install --upgrade google-cloud-texttospeech

Configurer vos identifiants Google Cloud Platform

Fournissez des identifiants d'authentification au code de votre application en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS. Cette variable ne s'applique qu'à la session de shell actuelle. Si vous souhaitez que la variable s'applique aux futures sessions de shell, définissez-la dans le fichier de démarrage du shell, par exemple dans le fichier ~/.bashrc ou ~/.profile.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Remplacez KEY_PATH par le chemin d'accès du fichier JSON contenant vos identifiants.

Par exemple :

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Pour PowerShell :

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Remplacez KEY_PATH par le chemin d'accès du fichier JSON contenant vos identifiants.

Par exemple :

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Pour l'invite de commande :

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Remplacez KEY_PATH par le chemin d'accès du fichier JSON contenant vos identifiants.

Importer des bibliothèques

Ce tutoriel utilise les systèmes et bibliothèques clientes indiqués ci-dessous.

Java

Pour savoir comment installer et utiliser la bibliothèque cliente pour Text-to-Speech, consultez la page Bibliothèques clientes Text-to-Speech. Pour en savoir plus, consultez la documentation de référence de l'API Text-to-Speech en langage Java.

Pour vous authentifier auprès de Text-to-Speech, configurez le service Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

// Imports the Google Cloud client library
import com.google.cloud.texttospeech.v1.AudioConfig;
import com.google.cloud.texttospeech.v1.AudioEncoding;
import com.google.cloud.texttospeech.v1.SsmlVoiceGender;
import com.google.cloud.texttospeech.v1.SynthesisInput;
import com.google.cloud.texttospeech.v1.SynthesizeSpeechResponse;
import com.google.cloud.texttospeech.v1.TextToSpeechClient;
import com.google.cloud.texttospeech.v1.VoiceSelectionParams;
import com.google.common.html.HtmlEscapers;
import com.google.protobuf.ByteString;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.OutputStream;
import java.nio.file.Files;
import java.nio.file.Paths;

Node.js

Pour savoir comment installer et utiliser la bibliothèque cliente Text-to-Speech, consultez la page Bibliothèques clientes Text-to-Speech. Pour en savoir plus, consultez la documentation de référence de l'API Text-to-Speech en langage Node.js.

// Imports the Google Cloud client library
const textToSpeech = require('@google-cloud/text-to-speech');

// Import other required libraries
const fs = require('fs');
//const escape = require('escape-html');
const util = require('util');

Python

import html

from google.cloud import texttospeech

Utiliser l'API Text-to-Speech

La fonction suivante récupère une chaîne de texte taguée à l'aide de SSML, ainsi que le nom d'un fichier MP3. La fonction utilise le texte tagué à l'aide de SSML pour générer un son synthétique. La fonction enregistre le son synthétique au format MP3 en utilisant le nom de fichier désigné en tant que paramètre.

L'intégralité de l'entrée SSML ne peut être lue que par une seule voix. Vous pouvez définir la voix dans l'objet VoiceSelectionParams.

Java

/**
 * Generates synthetic audio from a String of SSML text.
 *
 * <p>Given a string of SSML text and an output file name, this function calls the Text-to-Speech
 * API. The API returns a synthetic audio version of the text, formatted according to the SSML
 * commands. This function saves the synthetic audio to the designated output file.
 *
 * @param ssmlText String of tagged SSML text
 * @param outFile String name of file under which to save audio output
 * @throws Exception on errors while closing the client
 */
public static void ssmlToAudio(String ssmlText, String outFile) throws Exception {
  // Instantiates a client
  try (TextToSpeechClient textToSpeechClient = TextToSpeechClient.create()) {
    // Set the ssml text input to synthesize
    SynthesisInput input = SynthesisInput.newBuilder().setSsml(ssmlText).build();

    // Build the voice request, select the language code ("en-US") and
    // the ssml voice gender ("male")
    VoiceSelectionParams voice =
        VoiceSelectionParams.newBuilder()
            .setLanguageCode("en-US")
            .setSsmlGender(SsmlVoiceGender.MALE)
            .build();

    // Select the audio file type
    AudioConfig audioConfig =
        AudioConfig.newBuilder().setAudioEncoding(AudioEncoding.MP3).build();

    // Perform the text-to-speech request on the text input with the selected voice parameters and
    // audio file type
    SynthesizeSpeechResponse response =
        textToSpeechClient.synthesizeSpeech(input, voice, audioConfig);

    // Get the audio contents from the response
    ByteString audioContents = response.getAudioContent();

    // Write the response to the output file
    try (OutputStream out = new FileOutputStream(outFile)) {
      out.write(audioContents.toByteArray());
      System.out.println("Audio content written to file " + outFile);
    }
  }
}

Node.js

/**
 * Generates synthetic audio from a String of SSML text.
 *
 * Given a string of SSML text and an output file name, this function
 * calls the Text-to-Speech API. The API returns a synthetic audio
 * version of the text, formatted according to the SSML commands. This
 * function saves the synthetic audio to the designated output file.
 *
 * ARGS
 * ssmlText: String of tagged SSML text
 * outfile: String name of file under which to save audio output
 * RETURNS
 * nothing
 *
 */
async function ssmlToAudio(ssmlText, outFile) {
  // Creates a client
  const client = new textToSpeech.TextToSpeechClient();

  // Constructs the request
  const request = {
    // Select the text to synthesize
    input: {ssml: ssmlText},
    // Select the language and SSML Voice Gender (optional)
    voice: {languageCode: 'en-US', ssmlGender: 'MALE'},
    // Select the type of audio encoding
    audioConfig: {audioEncoding: 'MP3'},
  };

  // Performs the Text-to-Speech request
  const [response] = await client.synthesizeSpeech(request);
  // Write the binary audio content to a local file
  const writeFile = util.promisify(fs.writeFile);
  await writeFile(outFile, response.audioContent, 'binary');
  console.log('Audio content written to file ' + outFile);
}

Python

def ssml_to_audio(ssml_text, outfile):
    # Generates SSML text from plaintext.
    #
    # Given a string of SSML text and an output file name, this function
    # calls the Text-to-Speech API. The API returns a synthetic audio
    # version of the text, formatted according to the SSML commands. This
    # function saves the synthetic audio to the designated output file.
    #
    # Args:
    # ssml_text: string of SSML text
    # outfile: string name of file under which to save audio output
    #
    # Returns:
    # nothing

    # Instantiates a client
    client = texttospeech.TextToSpeechClient()

    # Sets the text input to be synthesized
    synthesis_input = texttospeech.SynthesisInput(ssml=ssml_text)

    # Builds the voice request, selects the language code ("en-US") and
    # the SSML voice gender ("MALE")
    voice = texttospeech.VoiceSelectionParams(
        language_code="en-US", ssml_gender=texttospeech.SsmlVoiceGender.MALE
    )

    # Selects the type of audio file to return
    audio_config = texttospeech.AudioConfig(
        audio_encoding=texttospeech.AudioEncoding.MP3
    )

    # Performs the text-to-speech request on the text input with the selected
    # voice parameters and audio file type
    response = client.synthesize_speech(
        input=synthesis_input, voice=voice, audio_config=audio_config
    )

    # Writes the synthetic audio to the output file.
    with open(outfile, "wb") as out:
        out.write(response.audio_content)
        print("Audio content written to file " + outfile)

Personnaliser le son synthétique

La fonction suivante accepte en entrée le nom d'un fichier texte et convertit le contenu du fichier en une chaîne de texte taguée par le biais de SSML.

Java

/**
 * Generates SSML text from plaintext.
 *
 * <p>Given an input filename, this function converts the contents of the input text file into a
 * String of tagged SSML text. This function formats the SSML String so that, when synthesized,
 * the synthetic audio will pause for two seconds between each line of the text file. This
 * function also handles special text characters which might interfere with SSML commands.
 *
 * @param inputFile String name of plaintext file
 * @return a String of SSML text based on plaintext input.
 * @throws IOException on files that don't exist
 */
public static String textToSsml(String inputFile) throws Exception {

  // Read lines of input file
  String rawLines = new String(Files.readAllBytes(Paths.get(inputFile)));

  // Replace special characters with HTML Ampersand Character Codes
  // These codes prevent the API from confusing text with SSML tags
  // For example, '<' --> '&lt;' and '&' --> '&amp;'
  String escapedLines = HtmlEscapers.htmlEscaper().escape(rawLines);

  // Convert plaintext to SSML
  // Tag SSML so that there is a 2 second pause between each address
  String expandedNewline = escapedLines.replaceAll("\\n", "\n<break time='2s'/>");
  String ssml = "<speak>" + expandedNewline + "</speak>";

  // Return the concatenated String of SSML
  return ssml;
}

Node.js

/**
 * Generates SSML text from plaintext.
 *
 * Given an input filename, this function converts the contents of the input text file
 * into a String of tagged SSML text. This function formats the SSML String so that,
 * when synthesized, the synthetic audio will pause for two seconds between each line
 * of the text file. This function also handles special text characters which might
 * interfere with SSML commands.
 *
 * ARGS
 * inputfile: String name of plaintext file
 * RETURNS
 * a String of SSML text based on plaintext input
 *
 */
function textToSsml(inputFile) {
  let rawLines = '';
  // Read input file
  try {
    rawLines = fs.readFileSync(inputFile, 'utf8');
  } catch (e) {
    console.log('Error:', e.stack);
    return;
  }

  // Replace special characters with HTML Ampersand Character Codes
  // These codes prevent the API from confusing text with SSML tags
  // For example, '<' --> '&lt;' and '&' --> '&amp;'
  let escapedLines = rawLines;
  escapedLines = escapedLines.replace(/&/g, '&amp;');
  escapedLines = escapedLines.replace(/"/g, '&quot;');
  escapedLines = escapedLines.replace(/</g, '&lt;');
  escapedLines = escapedLines.replace(/>/g, '&gt;');

  // Convert plaintext to SSML
  // Tag SSML so that there is a 2 second pause between each address
  const expandedNewline = escapedLines.replace(/\n/g, '\n<break time="2s"/>');
  const ssml = '<speak>' + expandedNewline + '</speak>';

  // Return the concatenated String of SSML
  return ssml;
}

Python

def text_to_ssml(inputfile):
    # Generates SSML text from plaintext.
    # Given an input filename, this function converts the contents of the text
    # file into a string of formatted SSML text. This function formats the SSML
    # string so that, when synthesized, the synthetic audio will pause for two
    # seconds between each line of the text file. This function also handles
    # special text characters which might interfere with SSML commands.
    #
    # Args:
    # inputfile: string name of plaintext file
    #
    # Returns:
    # A string of SSML text based on plaintext input

    # Parses lines of input file
    with open(inputfile) as f:
        raw_lines = f.read()

    # Replace special characters with HTML Ampersand Character Codes
    # These Codes prevent the API from confusing text with
    # SSML commands
    # For example, '<' --> '&lt;' and '&' --> '&amp;'

    escaped_lines = html.escape(raw_lines)

    # Convert plaintext to SSML
    # Wait two seconds between each address
    ssml = "<speak>{}</speak>".format(
        escaped_lines.replace("\n", '\n<break time="2s"/>')
    )

    # Return the concatenated string of ssml script
    return ssml

Regrouper tous les éléments

Ce programme utilise l'entrée suivante.

123 Street Ln, Small Town, IL 12345 USA
1 Jenny St & Number St, Tutone City, CA 86753
1 Piazza del Fibonacci, 12358 Pisa, Italy

Le transfert du texte ci-dessus vers text_to_ssml() génère le texte tagué suivant.

<speak>123 Street Ln, Small Town, IL 12345 USA
<break time="2s"/>1 Jenny St &amp; Number St, Tutone City, CA 86753
<break time="2s"/>1 Piazza del Fibonacci, 12358 Pisa, Italy
<break time="2s"/></speak>

Exécuter le code

Pour générer un fichier audio de voix synthétique, exécutez le code suivant à partir de la ligne de commande.

Java

Linux ou MacOS

Dans le répertoire java-docs-samples/texttospeech/cloud-client/, exécutez la commande suivante sur la ligne de commande.

$ mvn clean package

Windows

Dans le répertoire java-docs-samples/texttospeech/cloud-client/, exécutez la commande suivante sur la ligne de commande.

$ mvn clean package

Node.js

Linux ou MacOS

Dans le fichier hybridGlossaries.js, annulez la mise en commentaire sur les variables TODO (developer) commentées.

Dans la commande suivante, remplacez projectId par votre ID de projet Google Cloud. Dans le répertoire nodejs-docs-samples/texttospeech, exécutez la commande suivante sur la ligne de commande.

$ node ssmlAddresses.js projectId

Windows

Dans le fichier hybridGlossaries.js, annulez la mise en commentaire sur les variables TODO (developer) commentées.

Dans la commande suivante, remplacez projectId par votre ID de projet Google Cloud. Dans le répertoire nodejs-docs-samples/texttospeech, exécutez la commande suivante sur la ligne de commande.

$env: C:/Node.js/node.exe C: ssmlAddresses.js projectId

Python

Linux ou MacOS

Dans le répertoire python-docs-samples/texttospeech/snippets, exécutez la commande suivante sur la ligne de commande.

$ python ssml_addresses.py

Windows

Dans le répertoire python-docs-samples/texttospeech/snippets, exécutez la commande suivante sur la ligne de commande.

$env: C:/Python3/python.exe C: ssml_addresses.py

Vérifier le résultat

Ce programme génère un fichier audio de voix synthétique nommé example.mp3.

Java

Accédez au répertoire java-docs-samples/texttospeech/cloud-client/resources/.

Recherchez un fichier example.mp3 dans le répertoire resources.

Node.js

Accédez au répertoire nodejs-docs-samples/texttospeech/resources/.

Recherchez un fichier example.mp3 dans le répertoire resources.

Python

Accédez à python-docs-samples/texttospeech/snippets/resources.

Recherchez un fichier example.mp3 dans le répertoire resources.

Écoutez le clip audio suivant pour vérifier que votre fichier example.mp3 est ressemblant.

Résoudre les problèmes

Si vous oubliez de définir la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS sur la ligne de commande, le message d'erreur suivant s'affiche :
```
The Application Default Credentials are not available.
```
Si vous transmettez le nom d'un fichier inexistant à text_to_ssml(), le message d'erreur suivant s'affiche :
```
IOError: [Errno 2] No such file or directory
```
Si vous transmettez à ssml_to_audio() un paramètre ssml_text contenant la valeur None, le message d'erreur suivant s'affiche :
```
InvalidArgument: 400 Invalid input type. Type has to be text or SSML
```
Vérifiez que vous exécutez le code à partir du répertoire approprié.

Étape suivante

Découvrez d'autres tags SSML.
Découvrez comment utiliser SSML avec les API Translation et Vision.

Effectuer un nettoyage

Pour éviter que les ressources utilisées dans ce tutoriel soient facturées sur votre compte Google Cloud Platform, supprimez votre projet à l'aide de Google Cloud Console une fois que vous n'en avez plus besoin.

Supprimer votre projet

Dans Google Cloud Console, accédez à la page Projets.
Dans la liste des projets, sélectionnez celui que vous souhaitez supprimer, puis cliquez sur Supprimer.
Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez sur Arrêter pour le supprimer.