GSP222

Overview

The Text-to-Speech API lets you create audio files of machine-generated, or *synthetic, *human speech. You provide the content as text or Speech Synthesis Markup Language (SSML), specify a voice (a unique 'speaker' of a language with a distinctive tone and accent), and configure the output; the Text-to-Speech API returns to you the content that you sent as spoken word, audio data, delivered by the voice that you specified.

In this lab you will create a series of audio files using the Text-to-Speech API, then listen to them to compare the differences.

Setup and requirements

Before you click the Start Lab button

Read these instructions. Labs are timed and you cannot pause them. The timer, which starts when you click Start Lab, shows how long Google Cloud resources will be made available to you.

This hands-on lab lets you do the lab activities yourself in a real cloud environment, not in a simulation or demo environment. It does so by giving you new, temporary credentials that you use to sign in and access Google Cloud for the duration of the lab.

To complete this lab, you need:

• Access to a standard internet browser (Chrome browser recommended).

Note: Use an Incognito or private browser window to run this lab. This prevents any conflicts between your personal account and the Student account, which may cause extra charges incurred to your personal account.

• Time to complete the lab---remember, once you start, you cannot pause a lab.

Note: If you already have your own personal Google Cloud account or project, do not use it for this lab to avoid extra charges to your account.

How to start your lab and sign in to the Google Cloud Console

1. Click the Start Lab button. If you need to pay for the lab, a pop-up opens for you to select your payment method. On the left is the Lab Details panel with the following:

   • The Open Google Console button
   • Time remaining
   • The temporary credentials that you must use for this lab
   • Other information, if needed, to step through this lab

2. Click Open Google Console. The lab spins up resources, and then opens another tab that shows the Sign in page.

   Tip: Arrange the tabs in separate windows, side-by-side.

   Note: If you see the Choose an account dialog, click Use Another Account.

3. If necessary, copy the Username from the Lab Details panel and paste it into the Sign in dialog. Click Next.

4. Copy the Password from the Lab Details panel and paste it into the Welcome dialog. Click Next.

   Important: You must use the credentials from the left panel. Do not use your Google Cloud Skills Boost credentials. Note: Using your own Google Cloud account for this lab may incur extra charges.

5. Click through the subsequent pages:

   • Accept the terms and conditions.
   • Do not add recovery options or two-factor authentication (because this is a temporary account).
   • Do not sign up for free trials.

After a few moments, the Cloud Console opens in this tab.

Note: You can view the menu with a list of Google Cloud Products and Services by clicking the Navigation menu at the top-left.

Activate Cloud Shell

Cloud Shell is a virtual machine that is loaded with development tools. It offers a persistent 5GB home directory and runs on the Google Cloud. Cloud Shell provides command-line access to your Google Cloud resources.

1. Click Activate Cloud Shell at the top of the Google Cloud console.

When you are connected, you are already authenticated, and the project is set to your PROJECT_ID. The output contains a line that declares the PROJECT_ID for this session:

Your Cloud Platform project in this session is set to YOUR_PROJECT_ID

gcloud is the command-line tool for Google Cloud. It comes pre-installed on Cloud Shell and supports tab-completion.

2. (Optional) You can list the active account name with this command:

gcloud auth list

3. Click Authorize.

4. Your output should now look like this:

Output:

ACTIVE: * ACCOUNT: student-01-xxxxxxxxxxxx@qwiklabs.net To set the active account, run: $ gcloud config set account `ACCOUNT`

5. (Optional) You can list the project ID with this command:

gcloud config list project

Output:

[core] project = <project_ID>

Example output:

[core] project = qwiklabs-gcp-44776a13dea667a6 Note: For full documentation of gcloud, in Google Cloud, refer to the gcloud CLI overview guide.

Task 1. Enable the Text-to-Speech API

1. Select the APIs and Services dashboard from the drop down.

2. On the Dashboard, click Enable APIs and Services.

3. Enter for "text-to-speech" in the search box.

4. Click Cloud Text-to-Speech API.

5. In the Cloud Text-toSpeech API dialog boc, click Enable to enable the Text-to-Speech API.

Wait for a few seconds for the API to be enabled for the project. You will see this once it's enabled:

Click Check my progress to verify the objective. Enable the Text-to-Speech API

Task 2. Create a virtual environment

Python virtual environments are used to isolate package installation from the system.

1. Install the virtualenv environment:

sudo apt-get install -y virtualenv

2. Build the virtual environment:

python3 -m venv venv

3. Activate the virtual environment.

source venv/bin/activate

Task 3. Create a service account

You should use a service account to authenticate your calls to the Text-to-Speech API.

1. To create a service account, run the following command in Cloud Shell:

gcloud iam service-accounts create tts-qwiklab

For this next step, you need to copy the name of your Google Cloud project.

2. Run the following command and copy the output:

gcloud config get-value project 2> /dev/null

Now you need to generate a key to use that service account.

3. To create and download a key, run the following command in Cloud Shell, replacing [PROJECT_ID] with the ID of your Google Cloud project (that you copied in the previous step):

gcloud iam service-accounts keys create tts-qwiklab.json --iam-account tts-qwiklab@[PROJECT_ID].iam.gserviceaccount.com

4. Finally, set the GOOGLE_APPLICATION_CREDENTIALS environment variable to the location of your key file:

export GOOGLE_APPLICATION_CREDENTIALS=tts-qwiklab.json

Click Check my progress to verify the objective. Create a service account

Task 4. Get a list of available voices

As mentioned previously, the Text-to-Speech API provides many different voices and languages that you can use to create audio files. You can use any of the available voices as the speaker for your content.

Note: The Text-to-Speech API includes several premium voices, known as WaveNet voices, that generate more natural-sounding synthetic speech. These voices are also a bit more expensive than other available voices. Refer to the Cloud Text-to-Speech pricing page for more details.

1. The following curl command gets the list of all the voices you can select from when creating synthetic speech using the Text-to-Speech API:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://texttospeech.googleapis.com/v1/voices"

The Text-to-Speech API returns a JSON-formatted result that looks similar to the following:

{ "voices": [ { "languageCodes": [ "es-ES" ], "name": "es-ES-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 24000 }, { "languageCodes": [ "ja-JP" ], "name": "ja-JP-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 22050 }, { "languageCodes": [ "pt-BR" ], "name": "pt-BR-Standard-A", "ssmlGender": "FEMALE", "naturalSampleRateHertz": 24000 }, ... ] }

Looking at the results from the curl command, you'll notice that each voice has four fields:

• name: The ID of the voice that you provide when you request that voice.
• ssmlGender: The gender of the voice to speak the text, as defined in the SSML W3 Recommendation.
• naturalSampleRateHertz: The sampling rate of the voice.
• languageCodes: The list of language codes associated with that voice.

You'll also notice that some languages have several voices to choose from.

2. You can scope the results returned from the API to just a single language code by running:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ "https://texttospeech.googleapis.com/v1/voices?language_code=en"

Task 5. Create synthetic speech from text

Now that you've seen how to get the names of voices to speak your text, it's time to create some synthetic speech!

For this, you'll build your request to the Text-to-Speech API in a text file titled synthesize-text.json.

1. Create this file in Cloud Shell by running the following command:

touch synthesize-text.json

2. Using a line editor (nano, vim, etc.) or the Cloud Shell code editor, create a file called synthesize-text.jsonand paste the following into the file:

{ 'input':{ 'text':'Cloud Text-to-Speech API allows developers to include natural-sounding, synthetic human speech as playable audio in their applications. The Text-to-Speech API converts text or Speech Synthesis Markup Language (SSML) input into audio data like MP3 or LINEAR16 (the encoding used in WAV files).' }, 'voice':{ 'languageCode':'en-gb', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'audioEncoding':'MP3' } }

The JSON-formatted request body provides three objects:

• The input object provides the text to translate into synthetic speech.

• The voice object specifies the voice to use for the synthetic speech.

• The audioConfig object tells the Text-to-Speech API what kind of audio encoding to send back.

3. Use the following code to call the Text-to-Speech API using the curl command:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-text.json "https://texttospeech.googleapis.com/v1/text:synthesize" \ > synthesize-text.txt

The output of this call is saved to a file called synthesize-text.txt.

4. Open the synthesize-text.txt file. You'll notice that the Text-to-Speech API provides the audio output in base64-encoded text assigned to the audioContent field, similar to what's shown below:

{ "audioContent": "//NExAASGoHwABhGudEACdzqFXfRE4EY3AACkD/zX4ADf/6J/[...]" }

To translate the response into audio, you need to select the audio data it contains and decode it into an audio file - for this lab, MP3. Although there are many ways that you can do this, in this lab you'll use some really simple Python code. Don't worry if you're not a Python expert; you need only create the file and invoke it from the command line.

5. Create a file named tts_decode.py and add the following code into that file:

import argparse from base64 import decodebytes import json """ Usage: python tts_decode.py --input "synthesize-text.txt" \ --output "synthesize-text-audio.mp3" """ def decode_tts_output(input_file, output_file): """ Decode output from Cloud Text-to-Speech. input_file: the response from Cloud Text-to-Speech output_file: the name of the audio file to create """ with open(input_file) as input: response = json.load(input) audio_data = response['audioContent'] with open(output_file, "wb") as new_file: new_file.write(decodebytes(audio_data.encode('utf-8'))) if __name__ == '__main__': parser = argparse.ArgumentParser( description="Decode output from Cloud Text-to-Speech", formatter_class=argparse.RawDescriptionHelpFormatter) parser.add_argument('--input', help='The response from the Text-to-Speech API.', required=True) parser.add_argument('--output', help='The name of the audio file to create', required=True) args = parser.parse_args() decode_tts_output(args.input, args.output)

6. Now, to create an audio file from the response you received from the Text-to-Speech API, run the following command from Cloud Shell:

python tts_decode.py --input "synthesize-text.txt" --output "synthesize-text-audio.mp3"

This creates a new MP3 file named synthesize-text-audio.mp3.

Of course, since the synthesize-text-audio.mp3 lives in the cloud, you can't just play it directly from Cloud Shell! To listen to the file, you can create a Web server hosting a simple web page that embeds the file as playable audio (from an HTML <audio> control).

7. Open the Cloud Shell Code Editor by clicking on the pencil icon ():

8. Create a new file called index.html, then paste the following HTML into the file:

<html> <body> <h1>Cloud Text-to-Speech codelab</h1> <p> Output from synthesizing text: </p> <audio controls> <source src="synthesize-text-audio.mp3" /> </audio> </body> </html>

9. Back in Cloud Shell, start a simple Python HTTP server from the command prompt:

python -m http.server 8080

10. Finally, click Web Preview ().

11. Then select the 8080 port number from the displayed menu.

In the new browser window, you should see something like the following:

12. Play the audio embedded on the page. You'll hear the synthetic voice speak the text that you provided to it!

13. When you're done listening to the audio files, you can shut down the HTTP server by pressing CTRL + C in Cloud Shell.

Task 6. Create synthetic speech from SSML

In addition to using text, you can also provide input to the Text-to-Speech API in the form of Speech Synthesis Markup Language (SSML). SSML defines an XML format for representing synthetic speech. Using SSML input, you can more precisely control pauses, emphasis, pronunciation, pitch, speed, and other qualities in the synthetic speech output.

1. First, build your request to the Text-to-Speech API in a text file titled synthesize-ssml.json. Create this file in Cloud Shell by running the following command:

touch synthesize-ssml.json

2. Using a line editor (nano, vim, emacs) or the Cloud Shell code editor, paste the following JSON into the synthesize-ssml.json file:

{ 'input':{ 'ssml':'<speak><s> <emphasis level="moderate">Cloud Text-to-Speech API</emphasis> allows developers to include natural-sounding <break strength="x-weak"/> synthetic human speech as playable audio in their applications.</s> <s>The Text-to-Speech API converts text or <prosody rate="slow">Speech Synthesis Markup Language</prosody> <say-as interpret-as=\"characters\">SSML</say-as> input into audio data like <say-as interpret-as=\"characters\">MP3</say-as> or <sub alias="linear sixteen">LINEAR16</sub> <break strength="weak"/> (the encoding used in <sub alias="wave">WAV</sub> files).</s></speak>' }, 'voice':{ 'languageCode':'en-gb', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'audioEncoding':'MP3' } }

Notice that the input object of the JSON payload to send includes some different stuff this time around. Rather than a text field, the input object has a ssml field instead. The ssml field contains XML-formatted content the <speak> element as its root. Each of the elements present in this XML representation of the input affects the output of the synthetic speech.

Specifically, the elements in this sample have the following effects:

• <s> contains a sentence.
• <emphasis> adds stress on the enclosed word or phrase.
• <break> inserts a pause in the speech.
• <prosody> customizes the pitch, speaking rate, or volume of the enclosed text, as specified by the rate, pitch, or volume attributes.
• <say-as> provides more guidance about how to interpret and then say the enclosed text, for example, whether to speak a sequence of numbers as ordinal or cardinal.
• <sub> specifies a substitution value to speak for the enclosed text.

Note: You can see the full list of SSML elements supported by Cloud Text-to-Speech by reviewing the SSML reference.

3. In Cloud Shell use the following code to call the Text-to-Speech API, which saves the output to a file called synthesize-ssml.txt:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-ssml.json "https://texttospeech.googleapis.com/v1/text:synthesize" \ > synthesize-ssml.txt

Again, you need to decode the output from the Text-to-Speech API before you can hear the audio.

4. Run the following command to generate an audio file named synthesize-ssml-audio.mp3 using the tts_decode.py utility that you created previously:

python tts_decode.py --input "synthesize-ssml.txt" --output "synthesize-ssml-audio.mp3"

5. Next, open the index.html file that you created earlier. Replace the contents of the file with the following HTML:

<html> <body> <h1>Cloud Text-to-Speech Demo</h1> <p> Output from synthesizing text: </p> <audio controls> <source src="synthesize-text-audio.mp3" /> </audio> <p> Output from synthesizing SSML: </p> <audio controls> <source src="synthesize-ssml-audio.mp3" /> </audio> </body> </html>

6. Then, start a simple Python HTTP server from the Cloud Shell command prompt:

python -m http.server 8080

7. As before, click Web Preview and then select the port number from the displayed menu. In the new browser window, you should see something like the following:

8. Play the two embedded audio files. Notice the differences in the SSML output: although both audio files say the same words, the SSML output speaks them a bit differently, adding pauses and different pronunciations for abbreviations.

Task 7. Configure audio output and device profiles

Going beyond SSML, you can provide even more customization to your synthetic speech output created by the Text-to-Speech API. You can specify other audio encodings, change the pitch of the audio output, and even request that the output be optimized for a specific type of hardware.

Build your request to the Text-to-Speech API in a text file titled synthesize-with-settings.json.

1. To do this, create this file in Cloud Shell by running the following command:

touch synthesize-with-settings.json

2. Using a line editor (nano, vim, emacs) or the Cloud Shell code editor, paste the following JSON into the synthesize-with-settings.json file:

{ 'input':{ 'text':'The Text-to-Speech API is ideal for any application that plays audio of human speech to users. It allows you to convert arbitrary strings, words, and sentences into the sound of a person speaking the same things.' }, 'voice':{ 'languageCode':'en-us', 'name':'en-GB-Standard-A', 'ssmlGender':'FEMALE' }, 'audioConfig':{ 'speakingRate': 1.15, 'pitch': -2, 'audioEncoding':'OGG_OPUS', 'effectsProfileId': ['headphone-class-device'] } }

Looking at this JSON payload, you notice that the audioConfig object contains some additional fields now:

• The speakingRate field specifies a speed at which the speaker says the voice. A value of 1.0 is the normal speed for the voice, 0.5 is half that fast, and 2.0 is twice as fast.
• The pitch field specifies a difference in tone to speak the words. The value here specifies a number of semitones lower (negative) or higher (positive) to speak the words.
• The audioEncoding field specifies the audio encoding to use for the data. The accepted values for this field are LINEAR16, MP3, and OGG_OPUS.
• The effectsProfileId field requests that the Text-to-Speech API optimizes the audio output for a specific playback device. The API applies an predefined audio profile to the output that enhances the audio quality on the specified class of devices.

Note: The Audio Profiles feature is in Beta release status. Review the guide for details about how to use it in your application. All other settings described here are generally available for normal use in your application.

3. Use the following code to call the Text-to-Speech API using the curl command:

curl -H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \ -H "Content-Type: application/json; charset=utf-8" \ -d @synthesize-with-settings.json "https://texttospeech.googleapis.com/v1beta1/text:synthesize" \ > synthesize-with-settings.txt

The output of this call is saved to a file called synthesize-with-settings.txt.

4. Run the following command to generate an audio file named synthesize-with-settings-audio.mp3 from the output received from the Text-to-Speech API:

python tts_decode.py --input "synthesize-with-settings.txt" --output "synthesize-with-settings-audio.ogg"

5. Next open the index.html file that you created earlier and replace the contents of the file with the following HTML:

<html> <body> <h1>Cloud Text-to-Speech Demo</h1> <p> Output from synthesizing text: </p> <audio controls> <source src="synthesize-text-audio.mp3" /> </audio> <p> Output from synthesizing SSML: </p> <audio controls> <source src="synthesize-ssml-audio.mp3" /> </audio> </body> <p> Output with audio settings: </p> <audio controls> <source src="synthesize-with-settings-audio.ogg" /> </audio> </html>

6. Now, restart the Python HTTP server from the Cloud Shell command prompt:

python -m http.server 8080

7. As before, click Web Preview then select the port number from the displayed menu.

In the new browser window, you should see something like the following:

8. Play the third embedded audio file. Notice that the voice on the audio speaks a bit faster and lower than the previous examples.

Congratulations!

You have learned how to create synthetic speech using the Cloud Text-to-Speech API. You learned about:

• Listing all of the synthetic voices available through the Text-to-Speech API

• Creating a Text-to-Speech API request and calling the API with curl, providing both text and SSML

• Configuring the setting for audio output, including specifying a device profile for audio playback

Finish your quest

This self-paced lab is part of the Language, Speech, Text & Translation with Google CLoud APIs quest. A quest is a series of related labs that form a learning path. Completing this quest earns you a badge to recognize your achievement. You can make your badge or badges public and link to them in your online resume or social media account. Enroll in this quest and get immediate completion credit. Refer to the Google Cloud Skills Boost catalog for all available quests.

Take your next lab

Continue your quest with Translate Text with the Cloud Translation API or try one of these:

• Measuring and Improving Speech Accuracy

• Entity and Sentiment Analysis with the Natural Language API

Next steps / learn more

• Check out the detailed documentation for the Text-to-Speech API on cloud.google.com.
• Learn how to create synthetic speech using the client libraries for the Text-to-Speech API.

Google Cloud training and certification

...helps you make the most of Google Cloud technologies. Our classes include technical skills and best practices to help you get up to speed quickly and continue your learning journey. We offer fundamental to advanced level training, with on-demand, live, and virtual options to suit your busy schedule. Certifications help you validate and prove your skill and expertise in Google Cloud technologies.

Manual Last Updated September 7, 2022

Lab Last Tested August 13, 2019

Copyright 2023 Google LLC All rights reserved. Google and the Google logo are trademarks of Google LLC. All other company and product names may be trademarks of the respective companies with which they are associated.