gatsby-transformer-polly
v1.0.0
Published
Generate AWS Polly speech output data from SSML files.
Downloads
3
Maintainers
Readme
🗣 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
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!
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 orAWS_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
andAWS_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 🙏