Como falar endereços com SSML

Este tutorial demonstra como usar a Linguagem de marcação de síntese de fala (SSML, na sigla em inglês) para falar um arquivo de texto que contém endereços. Marque uma string de texto com tags SSML para personalizar o áudio sintético do Text-to-Speech.

Texto simples Renderização de SSML de texto simples

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>

Objetivo

Envie uma solicitação de fala sintetizada para o Text-to-Speech usando SSML e bibliotecas de cliente do Text-to-Speech.

Custos

Consulte a página de preços do Text-to-Speech para informações sobre custos.

Antes de começar

Como fazer o download dos códigos de amostra

Para fazer o download das amostras de código, clone as amostras do GitHub para Google Cloud para a linguagem de programação que você pretende usar.

Java

Neste tutorial, o código é usado no diretório texttospeech/cloud-client/src/main/java/com/example/texttospeech/ das amostras do Java para Google Cloud Platform.

Para fazer o download do código deste tutorial e navegar até ele, execute os comandos a seguir no 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

Neste tutorial, o código é usado no diretório nodejs-text-to-speech/samples do repositório do googleapis.

Para fazer o download do código deste tutorial e navegar até ele, execute os comandos a seguir no terminal.

git clone https://github.com/googleapis/nodejs-text-to-speech.git
cd nodejs-text-to-speech/samples/

Python

Neste tutorial, o código usado está no diretório samples/snippets da biblioteca da Text-to-Speech para Python.

Para fazer o download do código deste tutorial e navegar até ele, execute os comandos a seguir no terminal.

git clone https://github.com/googleapis/python-texttospeech.git
cd samples/snippets

Instalar a biblioteca de cliente

Neste tutorial, é usada a biblioteca de cliente do Text-to-Speech.

Java

Neste tutorial, são usadas as seguintes dependências:

<!--  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>24.0.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

No terminal, execute o comando follow.

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

Python

No terminal, execute o comando follow.

pip install --upgrade google-cloud-texttospeech

Como configurar suas credenciais do Google Cloud Platform

Forneça credenciais de autenticação ao código do aplicativo definindo a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS. Essa variável se aplica somente à sessão de shell atual. Se você quiser que a variável seja aplicada em sessões de shell futuras, defina a variável no arquivo de inicialização de shell, por exemplo, no arquivo ~/.bashrc ou ~/.profile.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Exemplo:

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

Windows

Para PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Exemplo:

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

Para prompt de comando:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Substitua KEY_PATH pelo caminho do arquivo JSON que contém a chave da conta de serviço.

Como importar bibliotecas

Neste tutorial, são usadas as bibliotecas de cliente e sistema a seguir.

Java

// 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

// 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

Como usar a API Text-to-Speech

A função a seguir usa uma string de texto marcada com SSML e o nome de um arquivo MP3. A função usa o texto marcado com SSML para gerar áudio sintético. A função salva o áudio sintético no nome de arquivo MP3 designado como um parâmetro.

Toda a entrada SSML só pode ser lida por uma única voz. Você pode definir a voz no objeto 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)

Como personalizar o áudio sintético

A função a seguir usa o nome de um arquivo de texto e converte o conteúdo do arquivo em uma string de texto marcada com o 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, "r") 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

Como reunir tudo

Este programa usa a seguinte entrada.

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

Como passar o texto acima para text_to_ssml() gera o seguinte texto com tags.

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

Executar o código

Para gerar um arquivo de áudio de fala sintética, execute o código a seguir na linha de comando.

Java

Linux ou MacOS

No diretório java-docs-samples/texttospeech/cloud-client/, execute o seguinte comando na linha de comando.

$ mvn clean package

Windows

No diretório java-docs-samples/texttospeech/cloud-client/, execute o seguinte comando na linha de comando.

$ mvn clean package

Node.js

Linux ou MacOS

No arquivo hybridGlossaries.js, remova o comentário das variáveis TODO (developer) comentadas.

Substitua projectId pelo ID do projeto do Google Cloud com o comando a seguir. No diretório nodejs-text-to-speech/samples, execute o seguinte comando na linha de comando.

$ node ssmlAddresses.js projectId

Windows

No arquivo hybridGlossaries.js, remova o comentário das variáveis TODO (developer) comentadas.

Substitua projectId pelo ID do projeto do Google Cloud com o comando a seguir. No diretório nodejs-text-to-speech/samples, execute o seguinte comando na linha de comando.

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

Python

Linux ou MacOS

No diretório python-texttospeech/samples/snippets, execute o seguinte comando na linha de comando.

$ python ssml_addresses.py

Windows

No diretório python-texttospeech/samples/snippets, execute o seguinte comando na linha de comando.

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

Como verificar sua saída

O programa gera um arquivo de áudio example.mp3 com fala sintética.

Java

Navegue até o diretório java-docs-samples/texttospeech/cloud-client/resources/.

Verifique se há um arquivo example.mp3 no diretório resources.

Node.js

Navegue até o diretório nodejs-text-tospeech/samples/resources/.

Verifique se há um arquivo example.mp3 no diretório resources.

Python

Navegue até python-texttospeech/samples/snippets/resources.

Verifique se há um arquivo example.mp3 no diretório resources.

Ouça esse áudio para verificar se o arquivo example.mp3 é igual.


Solução de problemas

  • Esquecer de definir a variável de ambiente GOOGLE_APPLICATION_CREDENTIALS na linha de comando gera a mensagem de erro:

    The Application Default Credentials are not available.

  • Passar o nome text_to_ssml() de um arquivo inexistente gera a mensagem de erro:

    IOError: [Errno 2] No such file or directory
    

  • Transmitir um parâmetro ssml_text para ssml_to_audio() que contém None gera esta mensagem de erro:

    InvalidArgument: 400 Invalid input type. Type has to be text or SSML
    

  • Verifique se você está executando o código do diretório correto.

A seguir

Limpeza

Para evitar cobranças na sua conta do Google Cloud Platform referentes aos recursos usados neste tutorial, use o Console do Google Cloud para excluir seu projeto, caso você não precise dele.

Como excluir o projeto

  1. No Console do Cloud, acesse a página "Projetos".
  2. Na lista de projetos, selecione um e clique em Excluir.
  3. Na caixa de diálogo, insira a ID do projeto e clique em Encerrar para excluí-lo.