The Speech-to-Text service of Vertex AI on
Google Distributed Cloud (GDC) air-gapped lets you convert speech from audio files into
text transcriptions. You can use the pre-trained Speech-to-Text API and the
Python client library to process recorded audio with the default model.

## Before you begin

To transcribe audio files, request the necessary permissions from your
administrator.

### Request IAM roles

To transcribe audio using the default Speech-to-Text model, contact your
IAM Project Admin to request the **Vertex AI Speech Developer**
(`ai-speech-developer`) role in your project namespace.

For more information about this role, see
[Prepare IAM permissions](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-ao-permissions.md.txt).

Before you can start using the Speech-to-Text API, you must have a project with
the Speech-to-Text API enabled and have the appropriate credentials. You can
also install client libraries to help you make calls to the API. For more
information, see [Set up a speech recognition project](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-set-up-stt.md.txt).

## Transcribe audio with the default model

Speech-to-Text performs speech recognition. You send the audio file
from which you want to recognize speech directly as content in the API request.
The system returns the resulting transcribed text in the API response.

You must provide a `RecognitionConfig` configuration object when making a speech
recognition request. This object tells the API how to process your audio data
and what kind of output you expect. If a model is not explicitly specified in
this configuration object, Speech-to-Text selects a default model.

For more information, see the [`Speech` API documentation](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/speech-to-text/rpc/google.cloud.speech.v1.md.txt).

The following example transcribes speech from an audio file using the default
Speech-to-Text model:

### Python

Follow these steps to use the Speech-to-Text service from a Python
script to transcribe speech from an audio file:

1. [Install the latest version of the Speech-to-Text client library](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-install-libraries.md.txt).

2. [Set the required environment variables on a Python script](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vai-set-up-stt.md.txt#set-env-var).

3. [Authenticate your API request](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-auth.md.txt).

4. Add the following code to the Python script you created:

   ```python
   import base64

   from google.cloud import speech_v1p1beta1 as speech
   import google.auth
   from google.auth.transport import requests
   from google.api_core.client_options import ClientOptions

   audience="https://ENDPOINT:443"
   api_endpoint="ENDPOINT:443"

   def get_client(creds):
     opts = ClientOptions(api_endpoint=api_endpoint)
     return speech.SpeechClient(credentials=creds, client_options=opts)

   def main():
     creds = None
     try:
       creds, project_id = google.auth.default()
       creds = creds.with_gdch_audience(audience)
       req = requests.Request()
       creds.refresh(req)
     except Exception as e:
       print("Caught exception" + str(e))
       raise e
     return creds

   def speech_func(creds):
     tc = get_client(creds)

     content="BASE64_ENCODED_AUDIO"

     audio = speech.RecognitionAudio(
         content=base64.standard_b64decode(content)
     )
     config = speech.RecognitionConfig(
         encoding=speech.RecognitionConfig.AudioEncoding.ENCODING,
         sample_rate_hertz=RATE_HERTZ,
         audio_channel_count=CHANNEL_COUNT,
         language_code="LANGUAGE_CODE",
     )

     metadata = [("x-goog-user-project", "projects/PROJECT_ID")]
     resp = tc.recognize(config=config, audio=audio, metadata=metadata)
     print(resp)

   if __name__=="__main__":
     creds = main()
     speech_func(creds)
   ```

   Replace the following:
   - `ENDPOINT`: the Speech-to-Text endpoint that you use for your organization. For more information, [view service status and endpoints](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-api-status.md.txt).
   - `PROJECT_ID`: your project ID.
   - `BASE64_ENCODED_AUDIO`: the audio data bytes encoded in a Base64 representation. This string begins with characters that look similar to `ZkxhQwAAACIQABAAAAUJABtAA+gA8AB+W8FZndQvQAyjv`. For more information, see [`RecognitionAudio`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/speech-to-text/rpc/google.cloud.speech.v1.md.txt#recognitionaudio).
   - `ENCODING`: the encoding of the audio data sent in the request, such as `LINEAR16`. For more information, see [`AudioEncoding`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/speech-to-text/rpc/google.cloud.speech.v1.md.txt#audioencoding).
   - `RATE_HERTZ`: the sample rate in Hertz (`8000`-`48000`) of the audio data sent in the request, such as `16000`. Required for `LINEAR16`, `FLAC`, and `MULAW` encodings (including WAV files). For more information, see [`RecognitionConfig`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/speech-to-text/rpc/google.cloud.speech.v1.md.txt#recognitionconfig).
   - `LANGUAGE_CODE`: the language of the supplied audio as a BCP-47 language tag, such as `en-US`. See the list of [supported languages](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/application/ao-user/vertex-ai-stt-supported-langs.md.txt) and their respective language codes.
   - `CHANNEL_COUNT`: the number of channels in the input audio data (`1`-`8`), such as `1` for mono audio. Setting `audio_channel_count` is required for `LINEAR16`, `FLAC`, and `MULAW` encodings. For more information, see [`RecognitionConfig`](https://docs.cloud.google.com/distributed-cloud/hosted/docs/latest/gdcag/apis/vertex-ai/speech-to-text/rpc/google.cloud.speech.v1.md.txt#recognitionconfig).
5. Save the Python script.

6. Run the Python script to transcribe audio:

   ```python
   python SCRIPT_NAME
   ```

   Replace `SCRIPT_NAME` with the name you gave to
   your Python script, for example, `speech.py`.