Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

The Amazon SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the Amazon SDK for JavaScript version 3 (V3).

Getting started in a browser script

This section walks you through an example that demonstrates how to run version 3 (V3) of the SDK for JavaScript in the browser.

For other examples of using (V3) of the SDK for JavaScript with the Node.js in the browser, see:

This browser script example shows you:

The Scenario

Amazon Polly is a cloud service that converts text into lifelike speech. You can use Amazon Polly to develop applications that increase engagement and accessibility. Amazon Polly supports multiple languages and includes a variety of lifelike voices. For more information about Amazon Polly, see the Amazon Polly Developer Guide.

This example shows you how to set up and run a browser script that takes text, sends that text to Amazon Polly, and returns the URL of the synthesized audio of the text for you to play. The browser script uses an Amazon Cognito Identity pool to provide credentials needed to access Amazon services. The example demonstrates the basic patterns for loading and using the SDK for JavaScript in browser scripts.

The browser script uses the SDK for JavaScript to synthesize text by using the following APIs:

Step 1: Create an Amazon Cognito Identity Pool

In this exercise, you create and use an Amazon Cognito Identity pool to provide unauthenticated access to your browser script for the Amazon Polly service. Creating an identity pool also creates two Amazon Identity and Access Management (IAM) roles, one to support users authenticated by an identity provider and the other to support unauthenticated guest users.

In this exercise, we will only work with the unauthenticated user role to keep the task focused. You can integrate support for an identity provider and authenticated users later.

After you create your Amazon Cognito identity pool, you're ready to add permissions for Amazon Polly that are needed by your browser script.

Step 2: Add a Policy to the Created IAM Role

To enable browser script access to Amazon Polly for speech synthesis, use the unauthenticated IAM role created for your Amazon Cognito identity pool. This requires you to add an IAM policy to the role. For more information about IAM roles, see Creating a Role to Delegate Permissions to an Amazon Service in the IAM User Guide.

After you create your Amazon Cognito identity pool and add permissions for Amazon Polly to your IAM role for unauthenticated users, you are ready to build the webpage and browser script.

Step 3: Create a project environment

Set up the project environment to run these Node TypeScript examples, and install the required Amazon SDK for JavaScript and third-party modules. Follow the instructions on GitHub.

Step 4: Create the HTML Page

The sample app consists of a single HTML page that contains the user interface, and a JavaScript file that contains the required JavaScript. To begin, create an HTML document and copy the following contents into it. The page includes an input field and button, an <audio> element to play the synthesized speech, and a <p> element to display messages. (Note that the full example is shown at the bottom of this page.)

The <script> element adds the main.js file, which contains all the required JavaScript for the example.

You use webpack to create the main.js file, as described in Step 5: Write the JavaScript.

For more information about the <audio> element, see audio.

The full HTML page is available here on GitHub.

Save the HTML file, naming it polly.html. After you have created the user interface for the application, you're ready to add the browser script code that runs the application.

To use V3 of the Amazon SDK for JavaScript in the browser, you require Webpack to bundle the JavaScript modules and functions, which you installed in the Step 3: Create a project environment.

Step 5: Write the JavaScript

Create a file named polly.js, and paste the code below into it. The full JavaScript page is available here on GitHub. The code first imports the required Amazon SDK clients and commands. Then it creates the Polly service client object, specifying the credentials for the SDK. To synthesize speech with Amazon Polly, it provides a variety of parameters including the sound format of the output, the sampling rate, the ID of the voice to use, and the text to play back. When you initially create the parameters, set the Text: parameter to an empty string; the Text: parameter will be set to the value you retrieve from the <input> element in the webpage.

Next, it creates a function named speakText() that is be invoked as an event handler by the button. Amazon Polly returns synthesized speech as an audio stream. The easiest way to play that audio in a browser is to have Amazon Polly make the audio available at a presigned URL you can then set as the src attribute of the <audio> element in the webpage.

Next it creates the Presigner object you'll use to create the presigned URL from which the synthesized speech audio can be retrieved. You must pass the speech parameters that you defined as well as the Polly service object that you created to the Polly.Presigner constructor.

After it creates the presigner object, it calls the getSynthesizeSpeechUrl method of that object, passing the speech parameters. If successful, this method returns the URL of the synthesized speech, which the code then assign to the <audio> element for playback.

Finally, from your project folder containing polly.js run the following at the command prompt to bundle the JavaScript for this example in a file named main.js:

webpack --entry polly.js --mode development --target web --devtool false -o main.js

import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity";
import {
    fromCognitoIdentityPool,
} from "@aws-sdk/credential-provider-cognito-identity";
import { Polly } from "@aws-sdk/client-polly";
import { getSynthesizeSpeechUrl } from "@aws-sdk/polly-request-presigner";

// Create the Polly service client, assigning your credentials
const client = new Polly({
    region: "REGION",
    credentials: fromCognitoIdentityPool({
        client: new CognitoIdentityClient({ region: "REGION" }),
        identityPoolId: "IDENTITY_POOL_ID" // IDENTITY_POOL_ID
    }),
});

// Set the parameters
const speechParams = {
    OutputFormat: "OUTPUT_FORMAT", // For example, 'mp3'
    SampleRate: "SAMPLE_RATE", // For example, '16000
    Text: "", // The 'speakText' function supplies this value
    TextType: "TEXT_TYPE", // For example, "text"
    VoiceId: "POLLY_VOICE" // For example, "Matthew"
};
const speakText = async () => {
    // Update the Text parameter with the text entered by the user
    speechParams.Text = document.getElementById("textEntry").value;
    try{
        let url = await getSynthesizeSpeechUrl({
            client, params: speechParams
        });
        console.log(url);
        // Load the URL of the voice recording into the browser
        document.getElementById('audioSource').src = url;
        document.getElementById('audioPlayback').load();
        document.getElementById('result').innerHTML = "Speech ready to play.";
    } catch (err) {
        console.log("Error", err);
        document.getElementById('result').innerHTML = err;
    }
};
// Expose the function to the browser
window.speakText = speakText;

Step 6: Run the Example

To run the example app, load polly.html into a web browser. The app should look similar to the following.

Enter a phrase you want turned to speech in the input box, then choose Synthesize. When the audio is ready to play, a message appears. Use the audio player controls to hear the synthesized speech.

Possible Enhancements

Here are variations on this application you can use to further explore using the SDK for JavaScript in a browser script.