= AWS Polly Component
:doctitle: AWS Polly
:shortname: aws2-polly
:artifactid: camel-aws2-polly
:description: Synthesize speech using AWS Polly and AWS SDK version 2.x.
:since: 4.18
:supportlevel: Stable
:tabs-sync-option:
:component-header: Only producer is supported
//Manually maintained attributes
:group: AWS
:camel-spring-boot-name: aws2-polly

*Since Camel {since}*

*{component-header}*

The AWS2 Polly component supports text-to-speech synthesis using the AWS Polly service.
https://aws.amazon.com/polly/[AWS Polly] is a cloud service that converts text into lifelike speech.

Prerequisites

You must have a valid Amazon Web Services developer account, and be
signed up to use Amazon Polly. More information is available at
https://aws.amazon.com/polly/[Amazon Polly].

== URI Format

-------------------------
aws2-polly://label[?options]
-------------------------

You can append query options to the URI in the following format:

`?options=value&option2=value&...`


// component options: START
include::partial$component-configure-options.adoc[]
include::partial$component-endpoint-options.adoc[]
include::partial$component-endpoint-headers.adoc[]
// component options: END


Required Polly component options

You have to provide the amazonPollyClient in the
Registry or your accessKey and secretKey to access
the https://aws.amazon.com/polly/[Amazon Polly] service.

== Usage

=== Static credentials, Default Credential Provider and Profile Credentials Provider

You have the possibility of avoiding the usage of explicit static credentials by specifying the useDefaultCredentialsProvider option and set it to true.

The order of evaluation for Default Credentials Provider is the following:

 - Java system properties - `aws.accessKeyId` and `aws.secretKey`
 - Environment variables - `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY`.
 - Web Identity Token from AWS STS.
 - The shared credentials and config files.
 - Amazon ECS container credentials - loaded from the Amazon ECS if the environment variable `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` is set.
 - Amazon EC2 Instance profile credentials.

You have also the possibility of using Profile Credentials Provider, by specifying the useProfileCredentialsProvider option to true and profileCredentialsName to the profile name.

Only one of static, default and profile credentials could be used at the same time.

For more information about this you can look at https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/credentials.html[AWS credentials documentation]

=== Polly Producer operations

Camel-AWS Polly component provides the following operations on the producer side:

- synthesizeSpeech
- describeVoices
- listLexicons
- getLexicon
- putLexicon
- deleteLexicon
- startSpeechSynthesisTask
- getSpeechSynthesisTask
- listSpeechSynthesisTasks

== Examples

=== Synthesize Speech example

[source,java]
------------------------------------------------------------------------------------------------------
from("direct:start")
  .setHeader(Polly2Constants.VOICE_ID, constant(VoiceId.JOANNA))
  .setBody(constant("Hello, this is a test of Amazon Polly text to speech synthesis."))
  .to("aws2-polly://test?operation=synthesizeSpeech")
  .to("file:output?fileName=speech.mp3");
------------------------------------------------------------------------------------------------------

As a result, you'll get an exchange containing the audio stream (InputStream) with the synthesized speech.

=== Using Neural Voices

[source,java]
------------------------------------------------------------------------------------------------------
from("direct:start")
  .setHeader(Polly2Constants.VOICE_ID, constant(VoiceId.MATTHEW))
  .setHeader(Polly2Constants.ENGINE, constant(Engine.NEURAL))
  .setBody(constant("This is synthesized using a neural voice."))
  .to("aws2-polly://test?operation=synthesizeSpeech&outputFormat=MP3");
------------------------------------------------------------------------------------------------------

=== Describe Voices example

[source,java]
------------------------------------------------------------------------------------------------------
from("direct:start")
  .to("aws2-polly://test?operation=describeVoices")
  .log("Available voices: ${body}");
------------------------------------------------------------------------------------------------------

=== Asynchronous Speech Synthesis with S3

For long text, you can use asynchronous synthesis which stores the result in S3:

[source,java]
------------------------------------------------------------------------------------------------------
from("direct:start")
  .setHeader(Polly2Constants.VOICE_ID, constant(VoiceId.JOANNA))
  .setHeader(Polly2Constants.S3_BUCKET, constant("my-audio-bucket"))
  .setHeader(Polly2Constants.S3_KEY_PREFIX, constant("audio/"))
  .setBody(constant("This is a very long text that will be synthesized asynchronously..."))
  .to("aws2-polly://test?operation=startSpeechSynthesisTask");
------------------------------------------------------------------------------------------------------

=== Using a POJO as body

Sometimes building an AWS Request can be complex because of multiple options. We introduce the possibility to use a POJO as the body.
In AWS Polly, you can do something like:

[source,java]
------------------------------------------------------------------------------------------------------
from("direct:start")
  .setBody(SynthesizeSpeechRequest.builder()
              .voiceId(VoiceId.JOANNA)
              .outputFormat(OutputFormat.MP3)
              .text("Hello from Camel!")
              .build())
  .to("aws2-polly://test?operation=synthesizeSpeech&pojoRequest=true");
------------------------------------------------------------------------------------------------------

In this way, you'll pass the request directly without the need of passing headers and options specifically related to this operation.

== Dependencies

Maven users will need to add the following dependency to their pom.xml.

*pom.xml*

[source,xml]
---------------------------------------
<dependency>
    <groupId>org.apache.camel</groupId>
    <artifactId>camel-aws2-polly</artifactId>
    <version>${camel-version}</version>
</dependency>
---------------------------------------

where `$\{camel-version}` must be replaced by the actual version of Camel.


include::spring-boot:partial$starter.adoc[]
