# Transcribe speech to text by using client libraries

This page shows you how to send a speech recognition request to
Cloud Speech-to-Text in your favorite programming language using the
Google Cloud Client Libraries.


Cloud Speech-to-Text enables easy integration of Google speech
recognition technologies into developer applications. You can send
audio data to the Cloud Speech-to-Text API, which then returns a
text transcription of that audio file. For more information about
the service, see
[Cloud STT basics](https://docs.cloud.google.com/speech-to-text/docs/basics).

## Before you begin

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

- Enable Cloud Speech-to-Text on a Google Cloud project.
- Make sure billing is enabled for Cloud Speech-to-Text.
-
  [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).
- [Verify that you have the permissions required to
  complete this guide](https://docs.cloud.google.com/speech-to-text/docs/v1/transcribe-client-libraries#required-roles). If you created a new project for this guide, then you already have the required permissions.
- (Optional) Create a new Cloud Storage bucket to store your audio data.

### Required roles


To get the permissions that
you need to transcribe speech to text,

ask your administrator to grant you the
[Service Usage Consumer](https://docs.cloud.google.com/iam/docs/roles-permissions/serviceusage.md.txt#serviceusage.serviceUsageConsumer) (`roles/serviceusage.serviceUsageConsumer`) IAM role on your project.


For more information about granting roles, see [Manage access to projects, folders, and organizations](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access.md.txt).


You might also be able to get
the required permissions through [custom
roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

## Install the client library

### Go

```
go get cloud.google.com/go/speech/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-speech</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-speech'
```

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

```java
libraryDependencies += "com.google.cloud" % "google-cloud-speech" % "4.97.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/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-speech
```

<br />

## Make an audio transcription request

Now you can use Cloud STT to transcribe an audio file
to text. Use the following code to send a
[`recognize`](https://docs.cloud.google.com/speech-to-text/docs/reference/rest/v1/speech/recognize.md.txt) request to the Cloud Speech-to-Text API.

### Go

```go

// Sample speech-quickstart uses the Google Cloud Speech API to transcribe
// audio.
package main

import (
	"context"
	"fmt"
	"log"

	speech "cloud.google.com/go/speech/apiv1"
	"cloud.google.com/go/speech/apiv1/speechpb"
)

func main() {
	ctx := context.Background()

	// Creates a client.
	client, err := speech.NewClient(ctx)
	if err != nil {
		log.Fatalf("Failed to create client: %v", err)
	}
	defer client.Close()

	// The path to the remote audio file to transcribe.
	fileURI := "gs://cloud-samples-data/speech/brooklyn_bridge.raw"

	// Detects speech in the audio file.
	resp, err := client.Recognize(ctx, &speechpb.RecognizeRequest{
		Config: &speechpb.RecognitionConfig{
			Encoding:        speechpb.RecognitionConfig_LINEAR16,
			SampleRateHertz: 16000,
			LanguageCode:    "en-US",
		},
		Audio: &speechpb.RecognitionAudio{
			AudioSource: &speechpb.RecognitionAudio_Uri{Uri: fileURI},
		},
	})
	if err != nil {
		log.Fatalf("failed to recognize: %v", err)
	}

	// Prints the results.
	for _, result := range resp.Results {
		for _, alt := range result.Alternatives {
			fmt.Printf("\"%v\" (confidence=%3f)\n", alt.Transcript, alt.Confidence)
		}
	}
}
```

### Java

```java
// Imports the Google Cloud client library
import com.google.cloud.speech.v1.RecognitionAudio;
import com.google.cloud.speech.v1.RecognitionConfig;
import com.google.cloud.speech.v1.RecognitionConfig.AudioEncoding;
import com.google.cloud.speech.v1.RecognizeResponse;
import com.google.cloud.speech.v1.SpeechClient;
import com.google.cloud.speech.v1.SpeechRecognitionAlternative;
import com.google.cloud.speech.v1.SpeechRecognitionResult;
import java.util.List;

public class QuickstartSample {

  /** Demonstrates using the Speech API to transcribe an audio file. */
  public static void main(String... args) throws Exception {
    // Instantiates a client
    try (SpeechClient speechClient = SpeechClient.create()) {

      // The path to the audio file to transcribe
      String gcsUri = "gs://cloud-samples-data/speech/brooklyn_bridge.raw";

      // Builds the sync recognize request
      RecognitionConfig config =
          RecognitionConfig.newBuilder()
              .setEncoding(AudioEncoding.LINEAR16)
              .setSampleRateHertz(16000)
              .setLanguageCode("en-US")
              .build();
      RecognitionAudio audio = RecognitionAudio.newBuilder().setUri(gcsUri).build();

      // Performs speech recognition on the audio file
      RecognizeResponse response = speechClient.recognize(config, audio);
      List<SpeechRecognitionResult> results = response.getResultsList();

      for (SpeechRecognitionResult result : results) {
        // There can be several alternative transcripts for a given chunk of speech. Just use the
        // first (most likely) one here.
        SpeechRecognitionAlternative alternative = result.getAlternativesList().get(0);
        System.out.printf("Transcription: %s%n", alternative.getTranscript());
      }
    }
  }
}
```

### 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 speech = require('@google-cloud/speech');

// Creates a client
const client = new speech.SpeechClient();

async function quickstart() {
  // The path to the remote LINEAR16 file
  const gcsUri = 'gs://cloud-samples-data/speech/brooklyn_bridge.raw';

  // The audio file's encoding, sample rate in hertz, and BCP-47 language code
  const audio = {
    uri: gcsUri,
  };
  const config = {
    encoding: 'LINEAR16',
    sampleRateHertz: 16000,
    languageCode: 'en-US',
  };
  const request = {
    audio: audio,
    config: config,
  };

  // Detects speech in the audio file
  const [response] = await client.recognize(request);
  const transcription = response.results
    .map(result => result.alternatives[0].transcript)
    .join('\n');
  console.log(`Transcription: ${transcription}`);
}
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

# Imports the Google Cloud client library


from google.cloud import speech



def run_quickstart() -> speech.RecognizeResponse:
    # Instantiates a client
    client = speech.SpeechClient()

    # The name of the audio file to transcribe
    gcs_uri = "gs://cloud-samples-data/speech/brooklyn_bridge.raw"

    audio = speech.RecognitionAudio(uri=gcs_uri)

    config = speech.RecognitionConfig(
        encoding=speech.RecognitionConfig.AudioEncoding.LINEAR16,
        sample_rate_hertz=16000,
        language_code="en-US",
    )

    # Detects speech in the audio file
    response = client.recognize(config=config, audio=audio)

    for result in response.results:
        print(f"Transcript: {result.alternatives[0].transcript}")
```

<br />

Congratulations! You've sent your first request to Cloud STT.


If you receive an error or an empty response from
Cloud STT, take a look at the
[troubleshooting](https://docs.cloud.google.com/speech-to-text/docs/troubleshooting.md.txt) and
[error mitigation](https://docs.cloud.google.com/speech-to-text/docs/error-messages) steps.

## 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 do not need it.

## What's next


- Practice [transcribing short audio files](https://docs.cloud.google.com/speech-to-text/docs/sync-recognize.md.txt).
- Learn how to [batch long audio files for speech recognition](https://docs.cloud.google.com/speech-to-text/docs/async-recognize).
- Learn how to [transcribe streaming audio](https://docs.cloud.google.com/speech-to-text/docs/streaming-recognize.md.txt) like from a microphone.
- Get started with the Cloud STT in your language of choice by using a [Cloud STT client library](https://docs.cloud.google.com/speech-to-text/docs/reference/libraries).
- Work through the [sample applications](https://docs.cloud.google.com/speech-to-text/docs/samples.md.txt).
- For best performance, accuracy, and other tips, see the [best practices](https://docs.cloud.google.com/speech-to-text/docs/best-practices.md.txt) documentation.

<br />