gatsby-transformer-polly

🗣 Easy text-to-speech for your Gatsby site, powered by Amazon Polly.

gatsby-transformer-polly

Installation

npm install --save gatsby-transformer-polly

How to use

Prerequisites

1. In order to use this plugin you need an AWS account. You can use the text-to-speech service (AWS Polly) for free for the first 12 months (up to a couple million words to be precise).

   Attention: If you exceed the limits or use it after your initial free tier, using this plugin will generate costs in your AWS account!

2. As this plugin is based on SSML files, the gatsby-source-filesystem is required to be installed and configured as well.

Mandatory configurations

gatsby-config.js

To include this plugin add it to your gatsby-config.js file as follows. Also, make sure you have included an entry for the necessary gatsby-source-filesystem plugin. Now link them together by setting gatsby-transformer-polly's ssmlFilesSourceInstanceName option to the same value as gatsby-source-filesystem's name option.

The other options shown in this example are also mandatory:

// In your gatsby-config.js
plugins: [
  {
    resolve: `gatsby-source-filesystem`,
    options: {
      name: `ssml`,
      path: `${__dirname}/src/ssml/`,
    },
  },
  {
    resolve: `gatsby-transformer-polly`,
    options: {
      ssmlFilesSourceInstanceName: `ssml`,
      awsRegion: `us-east-1`,
    },
  },
],

AWS credentials

The plugin requires your AWS credentials in order to generate the text-to-speech data.

Important: For security reasons it is not a good idea to keep access keys with administrator permissions on your local machine, without at least using MFA authentication. Even better is to restrict the AWS user's permissions to AmazonPollyReadOnlyAccess, which is all this plugin needs.

There are various ways to provide your AWS credentials to the plugin. For example:

• Create a shared credentials file and add a profile for your AWS user that will use AWS Polly. You can either configure it as your default profile or use the awsProfile plugin option or AWS_PROFILE environment variable to pass the custom profile name to the plugin.

// In your gatsby-config.js
  {
    resolve: "gatsby-transformer-polly",
    options: {
      awsProfile: "gatsby-transformer-polly",
    },
  },

• Use environment variables AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY to directly configure your user's access key (e.g. to build in a CI environment).

All configurations

Option	Required	Example
ssmlFilesSourceInstanceName	Yes	"ssml"
awsRegion	Yes	"us-east-1"
awsProfile	No	"gatsby-transformer-polly"

Create SSML files

As this plugin transforms SSML files into e.g. *.mp3 files or speech mark data, you will have to create some SSML files first.

Create them in the directory defined in the gatsby-source-filesystem declaration inside your gatsby-config.js.

Make sure you only use the SSML tags supported by AWS Polly.

Here is an example SSML file content:

<speak>
     Hello <break time="300ms"/> World.
</speak>

Query speech output data

Now you can just query the required data using GraphQL:

const data = useStaticQuery(graphql`
  query {
    file(relativePath: { eq: "hello-world.xml" }) {
      childPolly {
        # Specify the speech output attributes right in the query.
        polly(voiceId: "Justin", audioFileFormat: "mp3") {
          audioFileSrc
          speechMarks
        }
      }
    }
  }
`);

Query parameters

The following query parameters can be used to modify the generated speech output:

Parameter	Required	Example	Valid values
voiceId	Yes	"Justin"	See Voices in Amazon Polly
audioFileFormat	Yes	"mp3"	mp3 / ogg_vorbis / pcm
engine	No	"standard"	standard / neural
languageCode	No	"en-US"	See "LanguageCode" in SynthesizeSpeech docs
lexiconNames	No	["LexA", "LexB"]	See "LexiconNames" in SynthesizeSpeech docs
sampleRate	No	16000	See "SampleRate" in SynthesizeSpeech docs
speechMarkTypes	No	["sentence", "word"]	See "SpeechMarkTypes" in SynthesizeSpeech docs

Contribute 🦸

Contributions are more than welcome! I would love to see text-to-speech becoming a thing in the already very accessible Gatsby ecosystem. If you agree with this and would like to join me on this mission it would be awesome to get in touch! 😊

Please feel free to create, comment and of course solve some of the issues. To get started you can also go for the easier issues marked with the good first issue label if you like.

License

The MIT License

Credits

The gatsby-transformer-polly library is maintained and sponsored by the Swiss web and mobile app development company Florian Gyger Software.

If this library saved you some time and money please consider sponsoring me, so I can build more libraries for free and actively maintain them for you. Thank you 🙏

Changelog

1.0.0

Breaking Changes

• Plugin option awsCredentials was removed. Use awsProfile or environment variables instead (see README for details).

Major Changes

• a5e1c39: Added support for Gatsby 5.