Getting Started in a Browser Script

This browser script example shows you:

How to access AWS services from a browser script using Amazon Cognito Identity.
How to turn text into synthesized speech using Amazon Polly.
How to use a presigner object to create a presigned URL.

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 http://docs.aws.amazon.com/polly/latest/dg/.

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

Note
Playback of the synthesized speech in this example depends on running in a browser that supports HTML 5 audio.

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

http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/CognitoIdentityCredentials.html constructor
http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html constructor
http://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/Polly/Presigner.html#getSynthesizeSpeechUrl-property

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 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.

To create an Amazon Cognito identity pool

Sign in to the AWS Management Console and open the Amazon Cognito console at https://console.aws.amazon.com/cognito/.
Choose Manage Identity Pools on the console opening page.
On the next page, choose Create new identity pool.
In the Getting started wizard, type a name for your identity pool in Identity pool name.
Choose Enable access to unauthenticated identities.
Choose Create Pool.
On the next page, choose View Details to see the names of the two IAM roles created for your identity pool. Make a note of the name of the role for unauthenticated identities. You need this name to add the required policy for Amazon Polly.
Choose Allow.
On the Sample code page, copy or write down the identity pool ID displayed in red. You need this value for your browser script.

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 on IAM roles, see Creating a Role to Delegate Permissions to an AWS Service in the IAM User Guide.

To add an Amazon Polly policy to the IAM role associated with unauthenticated users

Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.
In the navigation panel on the left of the page, choose Roles.
In the list of IAM roles, choose the unauthenticated identities role previously created by Amazon Cognito.
In the Summary page for this role, choose Attach policies.
In the Attach Permissions page for this role, find and then choose AmazonPollyFullAccess.
Choose Attach policy.

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 the HTML Page

The sample app consists of a single HTML page that contains the user interface and browser script. Create an HTML document and copy the following contents into it. The page includes an <audio> element to play the synthesized speech, and a <p> element to display messages.

For more information on the <audio> element, see The Embed Audio element on the Mozilla Developer website.

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>AWS SDK for JavaScript - Browser Getting Started Application</title>
</head>

<body>
    <div id="textToSynth">
    <input autofocus size="23" type="text" id="textEntry" value="It's very good to meet you."/>
    <button class="btn default" onClick="speakText()">Synthesize</button><p id="result">Enter text above then click Synthesize</p>
    </div>
        <audio id="audioPlayback" controls>
  	        <source id="audioSource" type="audio/mp3" src="">
		    <p id="result">result</p>
    </audio>
</body>
</html>

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.

Step 4: Write the Browser Script

The first thing to do in creating the browser script is to add the SDK for JavaScript by adding this line after the <audio> element in the page.

<script src="https://sdk.amazonaws.com/js/aws-sdk-2.282.1.min.js"></script>

Then add a new script element after the SDK entry in which you'll add the browser script. Set the AWS Region and credentials for the SDK. Next, create a function named speakText() that will be invoked as an event handler by the button.

To synthesize speech with Amazon Polly, you must first create the parameters JSON needed, which includes the sound format of the output, sampling rate, the ID of the voice to use, and the text to play back. Set the Text: attribute to empty text initially, so that you can retrieve the value of the <input> element in the webpage and assign that value into the JSON.

// Initialize the Amazon Cognito credentials provider
AWS.config.region = 'REGION'; 
AWS.config.credentials = new AWS.CognitoIdentityCredentials({IdentityPoolId: 'IDENTITY_POOL_ID'});

// Function invoked by button click
function speakText() {			
    // Create synthesizeSpeech params JSON
    var speechParams = {
        OutputFormat: "mp3",
        SampleRate: "16000",
        Text: "",
        TextType: "text",
        VoiceId: "Matthew"
    };
    speechParams.Text = document.getElementById("textEntry").value;

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 property of the <audio> element in the webpage.

Create a new AWS.Polly service object. Then create an AWS.Polly.Presigner object you'll use to create a presigned URL at which the synthesized speech audio can be retrieved. You must pass the speech parameters JSON you just defined and the AWS.Polly service object to the AWS.Polly.Presigner constructor.

Then call the getSynthesizeSpeechUrl method of the presigner object, passing the speech parameters JSON. If successful, this method returns the URL of the synthesized speech, which you then assign to the <audio> element for playback.

// Create the Polly service object and presigner object
    var polly = new AWS.Polly({apiVersion: '2016-06-10'});
    var signer = new AWS.Polly.Presigner(speechParams, polly)

    // Create presigned URL of synthesized speech file
    signer.getSynthesizeSpeechUrl(speechParams, function(error, url) {
    if (error) {
	  document.getElementById('result').innerHTML = error;
    } else {
	  audioSource.src = url;  	  
	  document.getElementById('result').innerHTML = "Speech ready to play.";
    }
  });
}

Step 5: Run the Sample

To run the sample app, load polly.html into a web browser. This is what the browser presentation should resemble.

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.

Full Sample

Here is the full HTML page with the browser script. It's also available here on GitHub.

<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>AWS SDK for JavaScript - Browser Getting Started Application</title>
</head>

<body>
    <div id="textToSynth">
    <input autofocus size="23" type="text" id="textEntry" value="It's very good to meet you."/>
    <button class="btn default" onClick="speakText()">Synthesize</button><p id="result">Enter text above then click Synthesize</p>
    </div>
    <audio id="audioPlayback" controls>
      	<source id="audioSource" type="audio/mp3" src="">
    	<p id="result">result</p>
    </audio>
    <script src="https://sdk.amazonaws.com/js/aws-sdk-2.282.1.min.js"></script>
    <script>
        // Initialize the Amazon Cognito credentials provider
        AWS.config.region = 'REGION'; 
        AWS.config.credentials = new AWS.CognitoIdentityCredentials({IdentityPoolId: 'IDENTITY_POOL_ID'});
        
        // Function invoked by button click
        function speakText() {			
            // Create synthesizeSpeech params JSON
            var speechParams = {
                OutputFormat: "mp3",
                SampleRate: "16000",
                Text: "",
                TextType: "text",
                VoiceId: "Matthew"
            };
            speechParams.Text = document.getElementById("textEntry").value;
            
            // Create the Polly service object and presigner object
            var polly = new AWS.Polly({apiVersion: '2016-06-10'});
            var signer = new AWS.Polly.Presigner(speechParams, polly)
        
            // Create presigned URL of synthesized speech file
            signer.getSynthesizeSpeechUrl(speechParams, function(error, url) {
            if (error) {
        	  document.getElementById('result').innerHTML = error;
            } else {
        	  audioSource.src = url;  	  
        	  document.getElementById('result').innerHTML = "Speech ready to play.";
            }
          });
        }
    </script>
</body>
</html>

Possible Enhancements

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

Experiment with other sound output formats.
Add the option to select any of the various voices provided by Amazon Polly.
Integrate an identity provider like Facebook or Amazon to use with the authenticated IAM role.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

getting-started-browser.md

getting-started-browser.md

Getting Started in a Browser Script

The Scenario

Step 1: Create an Amazon Cognito Identity Pool

Step 2: Add a Policy to the Created IAM Role

Step 3: Create the HTML Page

Step 4: Write the Browser Script

Step 5: Run the Sample

Full Sample

Possible Enhancements

Files

getting-started-browser.md

Latest commit

History

getting-started-browser.md

File metadata and controls

Getting Started in a Browser Script

The Scenario

Step 1: Create an Amazon Cognito Identity Pool

Step 2: Add a Policy to the Created IAM Role

Step 3: Create the HTML Page

Step 4: Write the Browser Script

Step 5: Run the Sample

Full Sample

Possible Enhancements