# Getting started with Amazon Transcribe Before you can create transcriptions, you have a few prerequisites: + [Sign up for an AWS account](#getting-started-sign-up) + [Install the AWS CLI and SDKs](#getting-started-api) (if you're using the AWS Management Console for your transcriptions, you can skip this step) + [Configure IAM credentials](#getting-started-iam) + [Set up an Amazon S3 bucket](#getting-started-s3) + [Create an IAM policy](#getting-started-policy) Once you complete these prerequisites, you're ready to transcribe. Select your preferred transcription method from the following list to get started. + [AWS CLI](getting-started-cli.md) + [AWS Management Console](getting-started-console.md) + [AWS SDK](getting-started-sdk.md) + [HTTP](getting-started-http-websocket.md) + [WebSockets](getting-started-http-websocket.md) **Tip** If you're new to Amazon Transcribe or would like to explore our features, we recommend using the [AWS Management Console](https://console.aws.amazon.com/transcribe). This is also the easiest option if you'd like to start a stream using your computer microphone. Because streaming using HTTP/2 and WebSockets is more complicated than the other transcription methods, we recommend reviewing the [Setting up a streaming transcription](streaming-setting-up.md) section before getting started with these methods. **Note that we strongly recommend using an SDK for streaming transcriptions.** ## Signing up for an AWS account You can sign up for a [free tier](https://aws.amazon.com/free/) account or a [paid account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html). Both options give you access to all AWS services. The free tier has a trial period during which you can explore AWS services and estimate your usage. Once your trial period expires, you can migrate to a paid account. Fees are accrued on a pay-as-you-use basis; see [Amazon Transcribe Pricing](https://aws.amazon.com/transcribe/pricing/) for details. **Tip** When setting up your account, make note of your AWS account ID because you need it to create IAM entities. ## Installing the AWS CLI and SDKs To use the Amazon Transcribe API, you must first install the AWS CLI. The current AWS CLI is version 2. You can find installation instructions for [Linux](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html), [Mac](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-mac.html), [Windows](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-windows.html), and [Docker](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-docker.html) in the [https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-welcome.html). Once you have the AWS CLI installed, you must [configure](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html) it for your security credentials and AWS Region. If you want to use Amazon Transcribe with an SDK, select your preferred language for installation instructions: + [.NET](https://docs.aws.amazon.com/sdk-for-net/v3/developer-guide/quick-start.html) + [C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/getting-started.html) + [Go](https://aws.github.io/aws-sdk-go-v2/docs/) + [Java V2](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/setup.html) + [JavaScript](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html) + [PHP V3](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/getting-started_installation.html) + [AWS SDK for Python (Boto3)](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) (batch transcriptions) + [Python](https://github.com/awslabs/amazon-transcribe-streaming-sdk) (streaming transcriptions) + [Ruby V3](https://docs.aws.amazon.com/sdk-for-ruby/v3/developer-guide/setup-install.html) + [Rust](https://crates.io/crates/aws-sdk-transcribe) (batch transcriptions) + [Rust](https://crates.io/crates/aws-sdk-transcribestreaming) (streaming transcriptions) ## Configure IAM credentials When you create an AWS account, you begin with one sign-in identity that has complete access to all AWS services and resources in your account. This identity is called the AWS account root user and is accessed by signing in with the email address and password that you used to create the account. We strongly recommend that you do not use the root user for your everyday tasks. Safeguard your root user credentials and use them to perform the tasks that only the root user can perform. As a best practice, require users—including those that require administrator access—to use federation with an identity provider to access AWS services by using temporary credentials. A federated identity is any user who accesses AWS services by using credentials provided through an identity source. When federated identities access AWS accounts, they assume roles, and the roles provide temporary credentials. For centralized access management, we recommend that you use [AWS IAM Identity Center](https://docs.aws.amazon.com/singlesignon/latest/userguide/what-is.html). You can create users and groups in IAM Identity Center. Or you can connect and synchronize to a set of users and groups in your own identity source for use across all your AWS accounts and applications. For more information, see [Identity and Access Management for Amazon Transcribe](security-iam.md). To learn more about IAM best practices, refer to [Security best practices in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/best-practices.html). ## Creating an Amazon S3 bucket Amazon S3 is a secure object storage service. Amazon S3 stores your files (called *objects*) in containers (called *buckets*). To run a batch transcription, you must first upload your media files into an Amazon S3 bucket. If you don't specify an Amazon S3 bucket for your transcription output, Amazon Transcribe puts your transcript in a temporary AWS-managed Amazon S3 bucket. Transcription output in AWS-managed buckets is automatically deleted after 90 days. Learn how to [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) and [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html). ## Creating an IAM policy To manage access in AWS, you must create policies and attach them to IAM identities (users, groups, or roles) or AWS resources. A policy defines the permissions of the entity it is attached to. For example, a role can only access a media file located in your Amazon S3 bucket if you've attached a policy to that role which grants it access. If you want to further restrict that role, you can instead limit its access to a specific file within an Amazon S3 bucket. To learn more about using AWS policies see: + [Policies and permissions in IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies.html) + [Creating IAM policies](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) + [How Amazon Transcribe works with IAM](security_iam_service-with-iam.md) For example policies you can use with Amazon Transcribe, see [Amazon Transcribe identity-based policy examples](security_iam_id-based-policy-examples.md). If you want to generate custom policies, consider using the [AWS Policy Generator](https://awspolicygen.s3.amazonaws.com/policygen.html). You can add a policy using the AWS Management Console, AWS CLI, or AWS SDK. For instructions, see [Adding and removing IAM identity permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html#add-policy-api). Policies have the format: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "my-policy-name", "Effect": "Allow", "Action": [ "service:action" ], "Resource": [ "amazon-resource-name" ] } ] } ``` ------ Amazon Resource Names (ARNs) uniquely identify all AWS resources, such as an Amazon S3 bucket. You can use ARNs in your policy to grant permissions for specific actions to use specific resources. For example, if you want to grant read access to an Amazon S3 bucket and its sub-folders, you can add the following code to your trust policy's `Statement` section: ``` { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] } ``` Here's an example policy that grants Amazon Transcribe read (`GetObject`, `ListBucket`) and write (`PutObject`) permissions to an Amazon S3 bucket, `amzn-s3-demo-bucket`, and its sub-folders: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] }, { "Effect": "Allow", "Action": [ "s3:PutObject" ], "Resource": [ "arn:aws:s3:::amzn-s3-demo-bucket", "arn:aws:s3:::amzn-s3-demo-bucket/*" ] } ] } ``` ------ # Transcribing with the AWS Management Console You can use the AWS console for batch and streaming transcriptions. If you're transcribing a media file located in an Amazon S3 bucket, you're performing a batch transcription. If you're transcribing a real-time stream of audio data, you're performing a streaming transcription. Before starting a batch transcription, you must first upload your media file to an Amazon S3 bucket. For streaming transcriptions using the AWS Management Console, you must use your computer microphone. To view supported media formats and other media requirements and constraints, see [Data input and output](how-input.md). Expand the following sections for short walkthroughs of each transcription method. # Batch transcriptions First make sure that you've uploaded the media file you want to transcribe into an Amazon S3 bucket. If you're unsure how to do this, refer to the *Amazon S3 User Guide*: [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html). 1. From the [AWS Management Console](https://console.aws.amazon.com/transcribe), select **Transcription jobs** in the left navigation pane. This takes you to a list of your transcription jobs. ![\[Amazon Transcribe console screenshot: the 'transcription jobs' page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-1.png) Select **Create job**. 1. Complete the fields on the **Specify job details** page. ![\[Amazon Transcribe console screenshot: the 'specify job details' page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-job-details-1.png) The input location *must* be an object within an Amazon S3 bucket. For output location, you can choose a secure Amazon S3 service-managed bucket or you can specify your own Amazon S3 bucket. If you choose a service-managed bucket, you can view a transcript preview in the AWS Management Console and you can download your transcript from the job details page (see below). If you choose your own Amazon S3 bucket, you cannot see a preview in the AWS Management Console and must go to the Amazon S3 bucket to download your transcript. ![\[Amazon Transcribe console screenshot: the input and output data panes for a batch transcription.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-job-details-2.png) Select **Next**. 1. Select any desired options on the **Configure job** page. If you want to use [Custom vocabularies](custom-vocabulary.md) or [Custom language models](custom-language-models.md) with your transcription, you must create these before starting your transcription job. ![\[Amazon Transcribe console screenshot: the 'configure job' page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-configure-job.png) Select **Create job**. 1. You're now on the **Transcription jobs** page. Here you can see the status of the transcription job. Once complete, select your transcription. ![\[Amazon Transcribe console screenshot: the transcription jobs summary page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-transcription-jobs.png) 1. You're now viewing the **Job details** page for your transcription. Here you can view all of the options you specified when setting up your transcription job. To view your transcript, select the linked filepath in the right column under **Output data location**. This takes you to the Amazon S3 output folder you specified. Select your output file, which now has a .json extension. ![\[Amazon Transcribe console screenshot: summary page for completed transcription.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-complete.png) 1. How you download your transcript depends on whether you chose a service-managed Amazon S3 bucket or your own Amazon S3 bucket. 1. If you chose a service-managed bucket, you can see a **Transcription preview** pane on your transcription job's information page, along with a **Download** button. ![\[Amazon Transcribe console screenshot: summary page for transcription in a service-managed bucket.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-output-service-s3.png) Select **Download** and choose **Download transcript**. 1. If you chose your own Amazon S3 bucket, you don't see any text in the **Transcription preview** pane on your transcription job's information page. Instead, you see a blue information box with a link to the Amazon S3 bucket you chose. ![\[Amazon Transcribe console screenshot: summary page for transcription in a self-managed bucket.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-batch-output-own-s3.png) To access your transcript, go to the specified Amazon S3 bucket using the link under **Output data location** in the **Job details** pane or the **S3 Bucket** link within the blue information box in the **Transcription preview** pane. # Streaming transcriptions 1. From the [AWS Management Console](https://console.aws.amazon.com/transcribe), select **Real-time transcription** in the left navigation pane. This takes you to the main streaming page where you can select options before starting your stream. ![\[Amazon Transcribe console screenshot: the 'real-time transcription' page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-stream-1.png) 1. Below the **Transcription output** box, you have the option to select various language and audio settings. ![\[Amazon Transcribe console screenshot: a list of available transcription settings.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-stream-settings.png) 1. After you've selected the appropriate settings, scroll to the top of the page and choose **Start streaming**, then begin speaking into your computer microphone. You can see your speech transcribed in real time. ![\[Amazon Transcribe console screenshot: the 'transcription' panel on the 'real-time transcription' page.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-stream-start.png) 1. When you're finished, select **Stop streaming**. ![\[Amazon Transcribe console screenshot: example preview for a real-time transcription.\]](http://docs.aws.amazon.com/transcribe/latest/dg/images/console-stream-stop.png) You can now download your transcript by selecting **Download full transcript**. # Transcribing with the AWS CLI When using the AWS CLI to start a transcription, you can run all commands at the CLI level. Or you can run the command you want to use, followed by the AWS Region and the location of a JSON file that contains a request body. Examples throughout this guide show both methods; however, this section focuses on the former method. The AWS CLI does not support streaming transcriptions. Before you continue, make sure you've: + Uploaded your media file into an Amazon S3 bucket. If you're unsure how to create an Amazon S3 bucket or upload your file, refer to [Create your first Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) and [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html). + Installed the [AWS CLI](getting-started.md#getting-started-api). You can find all AWS CLI commands for Amazon Transcribe in the [AWS CLI Command Reference](https://awscli.amazonaws.com/v2/documentation/api/latest/reference/transcribe/index.html#cli-aws-transcribe). ## Starting a new transcription job To start a new transcription, use the `start-transcription-job` command. 1. In a terminal window, type the following: ``` aws transcribe start-transcription-job \ ``` A '`>`' appears on the next line, and you can now continue adding required parameters, as described in the next step. You can also omit the '`\`' and append all parameters, separating each with a space. 1. With the `start-transcription-job` command, you must include `region`, `transcription-job-name`, `media`, and either `language-code` or `identify-language`. If you want to specify an output location, include `output-bucket-name` in your request; if you want to specify a sub-folder of the specified output bucket, also include `output-key`. ``` aws transcribe start-transcription-job \ --region us-west-2 \ --transcription-job-name my-first-transcription-job \ --media MediaFileUri=s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac \ --language-code en-US ``` If appending all parameters, this request looks like: ``` aws transcribe start-transcription-job --region us-west-2 --transcription-job-name my-first-transcription-job --media MediaFileUri=s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac --language-code en-US ``` If you choose not to specify an output bucket using `output-bucket-name`, Amazon Transcribe places your transcription output in a service-managed bucket. Transcripts stored in a service-managed bucket expire after 90 days. Amazon Transcribe responds with: ``` { "TranscriptionJob": { "TranscriptionJobName": "my-first-transcription-job", "TranscriptionJobStatus": "IN_PROGRESS", "LanguageCode": "en-US", "Media": { "MediaFileUri": "s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac" }, "StartTime": "2022-03-07T15:03:44.246000-08:00", "CreationTime": "2022-03-07T15:03:44.229000-08:00" } } ``` Your transcription job is successful if [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_TranscriptionJob.html#transcribe-Type-TranscriptionJob-TranscriptionJobStatus](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_TranscriptionJob.html#transcribe-Type-TranscriptionJob-TranscriptionJobStatus) changes from `IN_PROGRESS` to `COMPLETED`. To see the updated [https://docs.aws.amazon.com/transcribe/latest/APIReference/API_TranscriptionJob.html#transcribe-Type-TranscriptionJob-TranscriptionJobStatus](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_TranscriptionJob.html#transcribe-Type-TranscriptionJob-TranscriptionJobStatus), use the `get-transcription-job` or `list-transcription-job` command, as shown in the following section. ## Getting the status of a transcription job To get information about your transcription job, use the `get-transcription-job` command. The only required parameters for this command are the AWS Region where the job is located and the name of the job. ``` aws transcribe get-transcription-job \ --region us-west-2 \ --transcription-job-name my-first-transcription-job ``` Amazon Transcribe responds with: ``` { "TranscriptionJob": { "TranscriptionJobName": "my-first-transcription-job", "TranscriptionJobStatus": "COMPLETED", "LanguageCode": "en-US", "MediaSampleRateHertz": 48000, "MediaFormat": "flac", "Media": { "MediaFileUri": "s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac" }, "Transcript": { "TranscriptFileUri": "https://s3.the-URI-where-your-job-is-located.json" }, "StartTime": "2022-03-07T15:03:44.246000-08:00", "CreationTime": "2022-03-07T15:03:44.229000-08:00", "CompletionTime": "2022-03-07T15:04:01.158000-08:00", "Settings": { "ChannelIdentification": false, "ShowAlternatives": false } } } ``` If you've selected your own Amazon S3 bucket for your transcription output, this bucket is listed with `TranscriptFileUri`. If you've selected a service-managed bucket, a temporary URI is provided; use this URI to download your transcript. **Note** Temporary URIs for service-managed Amazon S3 buckets are only valid for 15 minutes. If you get an `AccesDenied` error when using the URI, run the `get-transcription-job` request again to get a new temporary URI. ## Listing your transcription jobs To list all your transcription jobs in a given AWS Region, use the `list-transcription-jobs` command. The only required parameter for this command is the AWS Region in which your transcription jobs are located. ``` aws transcribe list-transcription-jobs \ --region us-west-2 ``` Amazon Transcribe responds with: ``` { "NextToken": "A-very-long-string", "TranscriptionJobSummaries": [ { "TranscriptionJobName": "my-first-transcription-job", "CreationTime": "2022-03-07T15:03:44.229000-08:00", "StartTime": "2022-03-07T15:03:44.246000-08:00", "CompletionTime": "2022-03-07T15:04:01.158000-08:00", "LanguageCode": "en-US", "TranscriptionJobStatus": "COMPLETED", "OutputLocationType": "SERVICE_BUCKET" } ] } ``` ## Deleting your transcription job To delete your transcription job, use the `delete-transcription-job` command. The only required parameters for this command are the AWS Region where the job is located and the name of the job. ``` aws transcribe delete-transcription-job \ --region us-west-2 \ --transcription-job-name my-first-transcription-job ``` To confirm your delete request is successful, you can run the `list-transcription-jobs` command. Your job should no longer appear in the list. # Transcribing with the AWS SDKs You can use SDKs for both batch and streaming transcriptions. If you're transcribing a media file located in an Amazon S3 bucket, you're performing a batch transcription. If you're transcribing a real-time stream of audio data, you're performing a streaming transcription. For a list of the programming languages you can use with Amazon Transcribe, see [Supported programming languages](supported-languages.md#supported-sdks). Note that streaming transcriptions are not supported with all AWS SDKs. To view supported media formats and other media requirements and constraints, see [Data input and output](how-input.md). For more information on all available AWS SDKs and builder tools, refer to [Tools to Build on AWS](https://aws.amazon.com/developer/tools). **Tip** For additional examples using the AWS SDKs, including feature-specific, scenario, and cross-service examples, refer to the [Code examples for Amazon Transcribe using AWS SDKs](service_code_examples.md) chapter. You can also find SDK code samples in these GitHub repositories: [AWS Code Examples](https://github.com/aws-samples) [Amazon Transcribe Examples](https://github.com/aws-samples/amazon-transcribe-examples) # Batch transcriptions You can create batch transcriptions using the URI of a media file located in an Amazon S3 bucket. If you're unsure how to create an Amazon S3 bucket or upload your file, refer to [Create your first S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html) and [Upload an object to your bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/uploading-an-object-bucket.html). ------ #### [ Java ] ``` import software.amazon.awssdk.auth.credentials.AwsCredentialsProvider; import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider; import software.amazon.awssdk.regions.Region; import software.amazon.awssdk.services.transcribe.TranscribeClient; import software.amazon.awssdk.services.transcribe.model.*; import software.amazon.awssdk.services.transcribestreaming.model.LanguageCode; public class TranscribeDemoApp { private static final Region REGION = Region.US_WEST_2; private static TranscribeClient client; public static void main(String args[]) { client = TranscribeClient.builder() .credentialsProvider(getCredentials()) .region(REGION) .build(); String transcriptionJobName = "my-first-transcription-job"; String mediaType = "flac"; // can be other types Media myMedia = Media.builder() .mediaFileUri("s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac") .build(); String outputS3BucketName = "s3://amzn-s3-demo-bucket"; // Create the transcription job request StartTranscriptionJobRequest request = StartTranscriptionJobRequest.builder() .transcriptionJobName(transcriptionJobName) .languageCode(LanguageCode.EN_US.toString()) .mediaSampleRateHertz(16000) .mediaFormat(mediaType) .media(myMedia) .outputBucketName(outputS3BucketName) .build(); // send the request to start the transcription job StartTranscriptionJobResponse startJobResponse = client.startTranscriptionJob(request); System.out.println("Created the transcription job"); System.out.println(startJobResponse.transcriptionJob()); // Create the get job request GetTranscriptionJobRequest getJobRequest = GetTranscriptionJobRequest.builder() .transcriptionJobName(transcriptionJobName) .build(); // send the request to get the transcription job including the job status GetTranscriptionJobResponse getJobResponse = client.getTranscriptionJob(getJobRequest); System.out.println("Get the transcription job request"); System.out.println(getJobResponse.transcriptionJob()); } private static AwsCredentialsProvider getCredentials() { return DefaultCredentialsProvider.create(); } } ``` ------ #### [ JavaScript ] ``` const { TranscribeClient, StartTranscriptionJobCommand } = require("@aws-sdk/client-transcribe"); // CommonJS import const region = "us-west-2"; const credentials = { "accessKeyId": "", "secretAccessKey": "", }; const input = { TranscriptionJobName: "my-first-transcription-job", LanguageCode: "en-US", Media: { MediaFileUri: "s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac" }, OutputBucketName: "amzn-s3-demo-bucket", }; async function startTranscriptionRequest() { const transcribeConfig = { region, credentials }; const transcribeClient = new TranscribeClient(transcribeConfig); const transcribeCommand = new StartTranscriptionJobCommand(input); try { const transcribeResponse = await transcribeClient.send(transcribeCommand); console.log("Transcription job created, the details:"); console.log(transcribeResponse.TranscriptionJob); } catch(err) { console.log(err); } } startTranscriptionRequest(); ``` ------ #### [ Python ] ``` import time import boto3 def transcribe_file(job_name, file_uri, transcribe_client): transcribe_client.start_transcription_job( TranscriptionJobName = job_name, Media = { 'MediaFileUri': file_uri }, MediaFormat = 'flac', LanguageCode = 'en-US' ) max_tries = 60 while max_tries > 0: max_tries -= 1 job = transcribe_client.get_transcription_job(TranscriptionJobName = job_name) job_status = job['TranscriptionJob']['TranscriptionJobStatus'] if job_status in ['COMPLETED', 'FAILED']: print(f"Job {job_name} is {job_status}.") if job_status == 'COMPLETED': print( f"Download the transcript from\n" f"\t{job['TranscriptionJob']['Transcript']['TranscriptFileUri']}.") break else: print(f"Waiting for {job_name}. Current status is {job_status}.") time.sleep(10) def main(): transcribe_client = boto3.client('transcribe', region_name = 'us-west-2') file_uri = 's3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac' transcribe_file('Example-job', file_uri, transcribe_client) if __name__ == '__main__': main() ``` ------ # Streaming transcriptions You can create streaming transcriptions using a streamed media file or a live media stream. Note that the standard AWS SDK for Python (Boto3) is not supported for Amazon Transcribe streaming. To start a streaming transcription using Python, use this [async Python SDK for Amazon Transcribe](https://github.com/awslabs/amazon-transcribe-streaming-sdk). ------ #### [ Java ] The following example is a Java program that transcribes streaming audio. To run this example, note the following: + You must use the [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html). + Clients must use Java 1.8 to be compatible with the [AWS SDK for Java 2.x](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/home.html). + The sample rate you specify must match the actual sample rate of your audio stream. See also: [Retry client for Amazon Transcribe streaming (Java SDK)](https://github.com/awsdocs/aws-doc-sdk-examples/tree/b320aeae1a3e650bffc23f9584a26a7ca177cbb2/javav2/example_code/transcribe/src/main/java/com/amazonaws/transcribestreaming). This code manages the connection to Amazon Transcribe and retries sending data when there are errors on the connection. For example, if there is a transient error on the network, this client resends the request that failed. ``` public class TranscribeStreamingDemoApp { private static final Region REGION = Region.US_WEST_2; private static TranscribeStreamingAsyncClient client; public static void main(String args[]) throws URISyntaxException, ExecutionException, InterruptedException, LineUnavailableException { client = TranscribeStreamingAsyncClient.builder() .credentialsProvider(getCredentials()) .region(REGION) .build(); CompletableFuture result = client.startStreamTranscription(getRequest(16_000), new AudioStreamPublisher(getStreamFromMic()), getResponseHandler()); result.get(); client.close(); } private static InputStream getStreamFromMic() throws LineUnavailableException { // Signed PCM AudioFormat with 16,000 Hz, 16 bit sample size, mono int sampleRate = 16000; AudioFormat format = new AudioFormat(sampleRate, 16, 1, true, false); DataLine.Info info = new DataLine.Info(TargetDataLine.class, format); if (!AudioSystem.isLineSupported(info)) { System.out.println("Line not supported"); System.exit(0); } TargetDataLine line = (TargetDataLine) AudioSystem.getLine(info); line.open(format); line.start(); InputStream audioStream = new AudioInputStream(line); return audioStream; } private static AwsCredentialsProvider getCredentials() { return DefaultCredentialsProvider.create(); } private static StartStreamTranscriptionRequest getRequest(Integer mediaSampleRateHertz) { return StartStreamTranscriptionRequest.builder() .languageCode(LanguageCode.EN_US.toString()) .mediaEncoding(MediaEncoding.PCM) .mediaSampleRateHertz(mediaSampleRateHertz) .build(); } private static StartStreamTranscriptionResponseHandler getResponseHandler() { return StartStreamTranscriptionResponseHandler.builder() .onResponse(r -> { System.out.println("Received Initial response"); }) .onError(e -> { System.out.println(e.getMessage()); StringWriter sw = new StringWriter(); e.printStackTrace(new PrintWriter(sw)); System.out.println("Error Occurred: " + sw.toString()); }) .onComplete(() -> { System.out.println("=== All records stream successfully ==="); }) .subscriber(event -> { List results = ((TranscriptEvent) event).transcript().results(); if (results.size() > 0) { if (!results.get(0).alternatives().get(0).transcript().isEmpty()) { System.out.println(results.get(0).alternatives().get(0).transcript()); } } }) .build(); } private InputStream getStreamFromFile(String myMediaFileName) { try { File inputFile = new File(getClass().getClassLoader().getResource(myMediaFileName).getFile()); InputStream audioStream = new FileInputStream(inputFile); return audioStream; } catch (FileNotFoundException e) { throw new RuntimeException(e); } } private static class AudioStreamPublisher implements Publisher { private final InputStream inputStream; private static Subscription currentSubscription; private AudioStreamPublisher(InputStream inputStream) { this.inputStream = inputStream; } @Override public void subscribe(Subscriber s) { if (this.currentSubscription == null) { this.currentSubscription = new SubscriptionImpl(s, inputStream); } else { this.currentSubscription.cancel(); this.currentSubscription = new SubscriptionImpl(s, inputStream); } s.onSubscribe(currentSubscription); } } public static class SubscriptionImpl implements Subscription { private static final int CHUNK_SIZE_IN_BYTES = 1024 * 1; private final Subscriber subscriber; private final InputStream inputStream; private ExecutorService executor = Executors.newFixedThreadPool(1); private AtomicLong demand = new AtomicLong(0); SubscriptionImpl(Subscriber s, InputStream inputStream) { this.subscriber = s; this.inputStream = inputStream; } @Override public void request(long n) { if (n <= 0) { subscriber.onError(new IllegalArgumentException("Demand must be positive")); } demand.getAndAdd(n); executor.submit(() -> { try { do { ByteBuffer audioBuffer = getNextEvent(); if (audioBuffer.remaining() > 0) { AudioEvent audioEvent = audioEventFromBuffer(audioBuffer); subscriber.onNext(audioEvent); } else { subscriber.onComplete(); break; } } while (demand.decrementAndGet() > 0); } catch (Exception e) { subscriber.onError(e); } }); } @Override public void cancel() { executor.shutdown(); } private ByteBuffer getNextEvent() { ByteBuffer audioBuffer = null; byte[] audioBytes = new byte[CHUNK_SIZE_IN_BYTES]; int len = 0; try { len = inputStream.read(audioBytes); if (len <= 0) { audioBuffer = ByteBuffer.allocate(0); } else { audioBuffer = ByteBuffer.wrap(audioBytes, 0, len); } } catch (IOException e) { throw new UncheckedIOException(e); } return audioBuffer; } private AudioEvent audioEventFromBuffer(ByteBuffer bb) { return AudioEvent.builder() .audioChunk(SdkBytes.fromByteBuffer(bb)) .build(); } } } ``` ------ #### [ JavaScript ] ``` const { TranscribeStreamingClient, StartStreamTranscriptionCommand, } = require("@aws-sdk/client-transcribe-streaming"); const { createReadStream } = require("fs"); const { join } = require("path"); const audio = createReadStream(join(__dirname, "my-media-file.flac"), { highWaterMark: 1024 * 16}); const LanguageCode = "en-US"; const MediaEncoding = "pcm"; const MediaSampleRateHertz = "16000"; const credentials = { "accessKeyId": "", "secretAccessKey": "", }; async function startRequest() { const client = new TranscribeStreamingClient({ region: "us-west-2", credentials }); const params = { LanguageCode, MediaEncoding, MediaSampleRateHertz, AudioStream: (async function* () { for await (const chunk of audio) { yield {AudioEvent: {AudioChunk: chunk}}; } })(), }; const command = new StartStreamTranscriptionCommand(params); // Send transcription request const response = await client.send(command); // Start to print response try { for await (const event of response.TranscriptResultStream) { console.log(JSON.stringify(event)); } } catch(err) { console.log("error") console.log(err) } } startRequest(); ``` ------ #### [ Python ] The following example is a Python program that transcribes streaming audio. To run this example, note the following: + You must use this [SDK for Python ](https://github.com/awslabs/amazon-transcribe-streaming-sdk). + The sample rate you specify must match the actual sample rate of your audio stream. ``` import asyncio # This example uses aiofile for asynchronous file reads. # It's not a dependency of the project but can be installed # with `pip install aiofile`. import aiofile from amazon_transcribe.client import TranscribeStreamingClient from amazon_transcribe.handlers import TranscriptResultStreamHandler from amazon_transcribe.model import TranscriptEvent """ Here's an example of a custom event handler you can extend to process the returned transcription results as needed. This handler will simply print the text out to your interpreter. """ class MyEventHandler(TranscriptResultStreamHandler): async def handle_transcript_event(self, transcript_event: TranscriptEvent): # This handler can be implemented to handle transcriptions as needed. # Here's an example to get started. results = transcript_event.transcript.results for result in results: for alt in result.alternatives: print(alt.transcript) async def basic_transcribe(): # Set up our client with your chosen Region client = TranscribeStreamingClient(region = "us-west-2") # Start transcription to generate async stream stream = await client.start_stream_transcription( language_code = "en-US", media_sample_rate_hz = 16000, media_encoding = "pcm", ) async def write_chunks(): # NOTE: For pre-recorded files longer than 5 minutes, the sent audio # chunks should be rate limited to match the real-time bitrate of the # audio stream to avoid signing issues. async with aiofile.AIOFile('filepath/my-media-file.flac', 'rb') as afp: reader = aiofile.Reader(afp, chunk_size = 1024 * 16) async for chunk in reader: await stream.input_stream.send_audio_event(audio_chunk = chunk) await stream.input_stream.end_stream() # Instantiate our handler and start processing events handler = MyEventHandler(stream.output_stream) await asyncio.gather(write_chunks(), handler.handle_events()) loop = asyncio.get_event_loop() loop.run_until_complete(basic_transcribe()) loop.close() ``` ------ #### [ C\$1\$1 ] Refer to the Code examples chapter for the [streaming C\$1\$1 SDK example ](https://docs.aws.amazon.com/code-library/latest/ug/cpp_1_transcribe-streaming_code_examples.html). ------ ## Using this service with an AWS SDK AWS software development kits (SDKs) are available for many popular programming languages. Each SDK provides an API, code examples, and documentation that make it easier for developers to build applications in their preferred language. | SDK documentation | Code examples | | --- | --- | | [AWS SDK for C\$1\$1](https://docs.aws.amazon.com/sdk-for-cpp) | [AWS SDK for C\$1\$1 code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/cpp) | | [AWS CLI](https://docs.aws.amazon.com/cli) | [AWS CLI code examples](https://docs.aws.amazon.com/code-library/latest/ug/cli_2_code_examples.html) | | [AWS SDK for Go](https://docs.aws.amazon.com/sdk-for-go) | [AWS SDK for Go code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/gov2) | | [AWS SDK for Java](https://docs.aws.amazon.com/sdk-for-java) | [AWS SDK for Java code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javav2) | | [AWS SDK for JavaScript](https://docs.aws.amazon.com/sdk-for-javascript) | [AWS SDK for JavaScript code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/javascriptv3) | | [AWS SDK for Kotlin](https://docs.aws.amazon.com/sdk-for-kotlin) | [AWS SDK for Kotlin code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/kotlin) | | [AWS SDK for .NET](https://docs.aws.amazon.com/sdk-for-net) | [AWS SDK for .NET code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/dotnetv3) | | [AWS SDK for PHP](https://docs.aws.amazon.com/sdk-for-php) | [AWS SDK for PHP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/php) | | [AWS Tools for PowerShell](https://docs.aws.amazon.com/powershell) | [AWS Tools for PowerShell code examples](https://docs.aws.amazon.com/code-library/latest/ug/powershell_5_code_examples.html) | | [AWS SDK for Python (Boto3)](https://docs.aws.amazon.com/pythonsdk) | [AWS SDK for Python (Boto3) code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/python) | | [AWS SDK for Ruby](https://docs.aws.amazon.com/sdk-for-ruby) | [AWS SDK for Ruby code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/ruby) | | [AWS SDK for Rust](https://docs.aws.amazon.com/sdk-for-rust) | [AWS SDK for Rust code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1) | | [AWS SDK for SAP ABAP](https://docs.aws.amazon.com/sdk-for-sapabap) | [AWS SDK for SAP ABAP code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/sap-abap) | | [AWS SDK for Swift](https://docs.aws.amazon.com/sdk-for-swift) | [AWS SDK for Swift code examples](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/swift) | For examples specific to this service, see [Code examples for Amazon Transcribe using AWS SDKs](service_code_examples.md). **Example availability** Can't find what you need? Request a code example by using the **Provide feedback** link at the bottom of this page. # Transcribing with HTTP or WebSockets Amazon Transcribe supports HTTP for both batch (HTTP/1.1) and streaming (HTTP/2) transcriptions. WebSockets are supported for streaming transcriptions. If you're transcribing a media file located in an Amazon S3 bucket, you're performing a batch transcription. If you're transcribing a real-time stream of audio data, you're performing a streaming transcription. Both HTTP and WebSockets require you to authenticate your request using AWS Signature Version 4 headers. Refer to [Signing AWS API requests](https://docs.aws.amazon.com/general/latest/gr/signing_aws_api_requests.html) for more information. ## Batch transcriptions You can make a batch HTTP request using the following headers: + host + x-amz-target + content-type + x-amz-content-sha256 + x-amz-date + authorization Here's an example of a `StartTranscriptionJob` request: ``` POST /transcribe HTTP/1.1 host: transcribe.us-west-2.amazonaws.com x-amz-target: com.amazonaws.transcribe.Transcribe.StartTranscriptionJob content-type: application/x-amz-json-1.1 x-amz-content-sha256: string x-amz-date: YYYYMMDDTHHMMSSZ authorization: AWS4-HMAC-SHA256 Credential=access-key/YYYYMMSS/us-west-2/transcribe/aws4_request, SignedHeaders=content-type;host;x-amz-content-sha256;x-amz-date;x-amz-target;x-amz-security-token, Signature=string { "TranscriptionJobName": "my-first-transcription-job", "LanguageCode": "en-US", "Media": { "MediaFileUri": "s3://amzn-s3-demo-bucket/my-input-files/my-media-file.flac" }, "OutputBucketName": "amzn-s3-demo-bucket", "OutputKey": "my-output-files/" } ``` Additional operations and parameters are listed in the [API Reference](https://docs.aws.amazon.com/transcribe/latest/APIReference/API_Reference.html); parameters common to all AWS API operations are listed in the [Common Parameters](https://docs.aws.amazon.com/transcribe/latest/APIReference/CommonParameters.html) section. Other signature elements are detailed in [Elements of an AWS Signature Version 4 request](https://docs.aws.amazon.com/general/latest/gr/sigv4_elements.html). ## Streaming transcriptions Streaming transcriptions using HTTP/2 and WebSockets are more involved than using SDKs. We recommend reviewing the [Setting up a streaming transcription](streaming-setting-up.md) section before setting up your first stream. For more information on these methods, refer to [Setting up an HTTP/2 stream](streaming-setting-up.md#streaming-http2) or [Setting up a WebSocket stream](streaming-setting-up.md#streaming-websocket). **Note** We strongly recommend using an SDK for streaming transcriptions. For a list of supported SDKs, refer to [Supported programming languages](supported-languages.md#supported-sdks).