# Create audio from text by using client libraries

This quickstart walks you through the process of using client libraries to make
a request to Cloud TTS, creating audio from text.

To learn more about the fundamental concepts in Cloud Text-to-Speech,
read [Cloud Text-to-Speech Basics](https://docs.cloud.google.com/text-to-speech/docs/basics.md.txt). To see which
synthetic voices are available for your language, see the
[supported voices and languages page](https://docs.cloud.google.com/text-to-speech/docs/voices).

## Before you begin

Before you can send a request to the Cloud Text-to-Speech API, you must have completed
the following actions. See the
[before you begin](https://docs.cloud.google.com/text-to-speech/docs/before-you-begin) page for details.

- Enable Cloud Text-to-Speech on a Google Cloud project.
- Make sure billing is enabled for Cloud Text-to-Speech.
-
  [Install](https://docs.cloud.google.com/sdk/docs/install) the Google Cloud CLI.

  After installation,
  [initialize](https://docs.cloud.google.com/sdk/docs/initializing) the Google Cloud CLI by running the following command:

  ```bash
  gcloud init
  ```


  If you're using an external identity provider (IdP), you must first
  [sign in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).
-

  If you're using a local shell, then create local authentication credentials for your user
  account:

  ```bash
  gcloud auth application-default login
  ```

  You don't need to do this if you're using Cloud Shell.


  If an authentication error is returned, and you are using an external identity provider
  (IdP), confirm that you have
  [signed in to the gcloud CLI with your federated identity](https://docs.cloud.google.com/iam/docs/workforce-log-in-gcloud.md.txt).

## Install the client library

### Go

```
go get cloud.google.com/go/texttospeech/apiv1
```

### Java

If you are using [Maven](https://maven.apache.org/), add
the following to your `pom.xml` file. For more information about
BOMs, see [The Google Cloud Platform Libraries BOM](https://cloud.google.com/java/docs/bom).

```java
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.90.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>
```

If you are using [Gradle](https://gradle.org/),
add the following to your dependencies:

```java
implementation platform('com.google.cloud:libraries-bom:26.90.0')

implementation 'com.google.cloud:google-cloud-texttospeech'
```

If you are using [sbt](https://www.scala-sbt.org/), add
the following to your dependencies:

```java
libraryDependencies += "com.google.cloud" % "google-cloud-texttospeech" % "2.103.0"
```

If you're using Visual Studio Code or IntelliJ, you can add client libraries to your
project using the following IDE plugins:

- [Cloud Code for VS Code](https://docs.cloud.google.com/code/docs/vscode/client-libraries.md.txt)
- [Cloud Code for IntelliJ](https://docs.cloud.google.com/code/docs/intellij/client-libraries.md.txt)

The plugins provide additional functionality, such as key management for service accounts. Refer
to each plugin's documentation for details.

> [!NOTE]
> **Note:** Cloud Java client libraries do not currently support Android.

### Node.js

Before installing the library, make sure you've [prepared your environment for Node.js development](https://docs.cloud.google.com/nodejs/docs/setup.md.txt).

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

### Python

Before installing the library, make sure you've [prepared your environment for Python development](https://docs.cloud.google.com/python/docs/setup.md.txt).

```
pip install --upgrade google-cloud-texttospeech
```

### Additional languages


**C#** :
Please follow the

[C# setup instructions](https://docs.cloud.google.com/text-to-speech/docs/libraries.md.txt)
on the client libraries page

and then visit the
[Cloud TTS reference documentation for .NET.](https://googleapis.github.io/google-cloud-dotnet/docs/Google.Cloud.TextToSpeech.V1/index.html)


**PHP** :
Please follow the

[PHP setup instructions](https://docs.cloud.google.com/text-to-speech/docs/libraries.md.txt)
on the client libraries page

and then visit the
[Cloud TTS reference documentation for PHP.](https://docs.cloud.google.com/php/docs/reference/cloud-text-to-speech/latest.md.txt)


**Ruby** :
Please follow the

[Ruby setup instructions](https://docs.cloud.google.com/text-to-speech/docs/libraries.md.txt)
on the client libraries page

and then visit the
[Cloud TTS reference documentation for Ruby.](https://googleapis.dev/ruby/google-cloud-text_to_speech/latest/Google/Cloud/TextToSpeech/V1.html)

<br />

## Create audio data

Now you can use Cloud TTS to create an audio file
of synthetic human speech. Use the following code to send a
[`synthesize`](https://docs.cloud.google.com/text-to-speech/docs/reference/rest/v1beta1/text/synthesize.md.txt) request to the Cloud Text-to-Speech API.

### Go

```go

// Command quickstart generates an audio file with the content "Hello, World!".
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	texttospeech "cloud.google.com/go/texttospeech/apiv1"
	"cloud.google.com/go/texttospeech/apiv1/texttospeechpb"
)

func main() {
	// Instantiates a client.
	ctx := context.Background()

	client, err := texttospeech.NewClient(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	// Perform the text-to-speech request on the text input with the selected
	// voice parameters and audio file type.
	req := texttospeechpb.SynthesizeSpeechRequest{
		// Set the text input to be synthesized.
		Input: &texttospeechpb.SynthesisInput{
			InputSource: &texttospeechpb.SynthesisInput_Text{Text: "Hello, World!"},
		},
		// Build the voice request, select the language code ("en-US") and the SSML
		// voice gender ("neutral").
		Voice: &texttospeechpb.VoiceSelectionParams{
			LanguageCode: "en-US",
			SsmlGender:   texttospeechpb.SsmlVoiceGender_NEUTRAL,
		},
		// Select the type of audio file you want returned.
		AudioConfig: &texttospeechpb.AudioConfig{
			AudioEncoding: texttospeechpb.AudioEncoding_MP3,
		},
	}

	resp, err := client.SynthesizeSpeech(ctx, &req)
	if err != nil {
		log.Fatal(err)
	}

	// The resp's AudioContent is binary.
	filename := "output.mp3"
	err = os.WriteFile(filename, resp.AudioContent, 0644)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Printf("Audio content written to file: %v\n", filename)
}
```

### Java

```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.protobuf.ByteString;
import java.io.FileOutputStream;
import java.io.OutputStream;

/**
 * Google Cloud TextToSpeech API sample application. Example usage: mvn package exec:java
 * -Dexec.mainClass='com.example.texttospeech.QuickstartSample'
 */
public class QuickstartSample {

  /** Demonstrates using the Text-to-Speech API. */
  public static void main(String... args) throws Exception {
    // Instantiates a client
    try (TextToSpeechClient textToSpeechClient = TextToSpeechClient.create()) {
      // Set the text input to be synthesized
      SynthesisInput input = SynthesisInput.newBuilder().setText("Hello, World!").build();

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

      // Select the type of audio file you want returned
      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("output.mp3")) {
        out.write(audioContents.toByteArray());
        System.out.println("Audio content written to file \"output.mp3\"");
      }
    }
  }
}
```

### Node.js

Before running the example, make sure you've [prepared your environment for Node.js development](https://docs.cloud.google.com/nodejs/docs/setup.md.txt).

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

// Import other required libraries
const {writeFile} = require('node:fs/promises');

// Creates a client
const client = new textToSpeech.TextToSpeechClient();

async function quickStart() {
  // The text to synthesize
  const text = 'hello, world!';

  // Construct the request
  const request = {
    input: {text: text},
    // Select the language and SSML voice gender (optional)
    voice: {languageCode: 'en-US', ssmlGender: 'NEUTRAL'},
    // select the type of audio encoding
    audioConfig: {audioEncoding: 'MP3'},
  };

  // Performs the text-to-speech request
  const [response] = await client.synthesizeSpeech(request);

  // Save the generated binary audio content to a local file
  await writeFile('output.mp3', response.audioContent, 'binary');
  console.log('Audio content written to file: output.mp3');
}

await quickStart();
```

### Python

Before running the example, make sure you've [prepared your environment for Python development](https://docs.cloud.google.com/python/docs/setup.md.txt).

```python
"""Synthesizes speech from the input string of text or ssml.
Make sure to be working in a virtual environment.

Note: ssml must be well-formed according to:
    https://www.w3.org/TR/speech-synthesis/
"""
from google.cloud import texttospeech

# Instantiates a client
client = texttospeech.TextToSpeechClient()

# Set the text input to be synthesized
synthesis_input = texttospeech.SynthesisInput(text="Hello, World!")

# Build the voice request, select the language code ("en-US") and the ssml
# voice gender ("neutral")
voice = texttospeech.VoiceSelectionParams(
    language_code="en-US", ssml_gender=texttospeech.SsmlVoiceGender.NEUTRAL
)

# Select the type of audio file you want returned
audio_config = texttospeech.AudioConfig(
    audio_encoding=texttospeech.AudioEncoding.MP3
)

# Perform 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
)

# The response's audio_content is binary.
with open("output.mp3", "wb") as out:
    # Write the response to the output file.
    out.write(response.audio_content)
    print('Audio content written to file "output.mp3"')
```

<br />

Congratulations! You've sent your first request to Cloud Text-to-Speech.

## How did it go?

<button class="button button-blue expand-control gc-analytics-event" data-category="Quickstart" data-action="Feedback" data-label="Cloud Text-to-Speech API, Client Libraries" data-value="1" track-type="quickstart" track-name="feedbackLink" track-metadata-position="steps" track-metadata-end-goal="itWorked"> It worked! </button>

> [!TIP]
> **Great!** What did you like about the quickstart? What could we have done better? [Let us know!](https://docs.cloud.google.com/text-to-speech/docs/create-audio-text-client-libraries.md.txt#).

<button class="button expand-control gc-analytics-event" data-category="Quickstart" data-action="Feedback" data-label="Cloud Text-to-Speech API, Client Libraries" data-value="0" style="position: absolute; top: 0; left: 110px;" track-type="quickstart" track-name="feedbackLink" track-metadata-position="steps" track-metadata-end-goal="itFailed"> I got stuck. </button>

> [!WARNING]
> **We're sorry to hear that.** [Let us know what went wrong](https://docs.cloud.google.com/text-to-speech/docs/create-audio-text-client-libraries.md.txt#). We'll want to fix it.

## Clean up


To avoid incurring charges to your Google Cloud account for
the resources used on this page, follow these steps.

- Use the [Google Cloud console](https://console.cloud.google.com/) to delete your project if you don't need it.

## What's next


- Learn more about Cloud Text-to-Speech by reading the [basics](https://docs.cloud.google.com/text-to-speech/docs/basics.md.txt).
- Review the list of [available voices](https://docs.cloud.google.com/text-to-speech/docs/voices) you can use for synthetic speech.

<br />