Struct Client

pub struct Client { /* private fields */ }

Client for Amazon Polly

Client for invoking operations on Amazon Polly. Each operation on Amazon Polly is a method on this this struct. .send() MUST be invoked on the generated operations to dispatch the request to the service.

Constructing a Client

A Config is required to construct a client. For most use cases, the aws-config crate should be used to automatically resolve this config using aws_config::load_from_env(), since this will resolve an SdkConfig which can be shared across multiple different AWS SDK clients. This config resolution process can be customized by calling aws_config::from_env() instead, which returns a ConfigLoader that uses the builder pattern to customize the default config.

In the simplest case, creating a client looks as follows:

let config = aws_config::load_from_env().await;
let client = aws_sdk_polly::Client::new(&config);

Occasionally, SDKs may have additional service-specific values that can be set on the Config that is absent from SdkConfig, or slightly different settings for a specific client may be desired. The Builder struct implements From<&SdkConfig>, so setting these specific settings can be done as follows:

let sdk_config = ::aws_config::load_from_env().await;
let config = aws_sdk_polly::config::Builder::from(&sdk_config)
    .some_service_specific_setting("value")
    .build();

See the aws-config docs and Config for more information on customizing configuration.

Note: Client construction is expensive due to connection thread pool initialization, and should be done once at application start-up.

Using the Client

A client has a function for every operation that can be performed by the service. For example, the DeleteLexicon operation has a Client::delete_lexicon, function which returns a builder for that operation. The fluent builder ultimately has a send() function that returns an async future that returns a result, as illustrated below:

let result = client.delete_lexicon()
    .name("example")
    .send()
    .await;

The underlying HTTP requests that get made by this can be modified with the customize_operation function on the fluent builder. See the customize module for more information.

Implementations

impl Client

pub fn delete_lexicon(&self) -> DeleteLexiconFluentBuilder

Constructs a fluent builder for the DeleteLexicon operation.

• The fluent builder is configurable:
  • name(impl Into<String>) / set_name(Option<String>):
    required: true
    

    The name of the lexicon to delete. Must be an existing lexicon in the region.

    
    
• On success, responds with DeleteLexiconOutput
• On failure, responds with SdkError<DeleteLexiconError>

impl Client

pub fn describe_voices(&self) -> DescribeVoicesFluentBuilder

Constructs a fluent builder for the DescribeVoices operation.

• The fluent builder is configurable:
  • engine(Engine) / set_engine(Option<Engine>):
    required: false
    

    Specifies the engine (standard, neural, long-form or generative) used by Amazon Polly when processing input text for speech synthesis.

    
    
  • language_code(LanguageCode) / set_language_code(Option<LanguageCode>):
    required: false
    

    The language identification tag (ISO 639 code for the language name-ISO 3166 country code) for filtering the list of voices returned. If you don’t specify this optional parameter, all available voices are returned.

    
    
  • include_additional_language_codes(bool) / set_include_additional_language_codes(Option<bool>):
    required: false
    

    Boolean value indicating whether to return any bilingual voices that use the specified language as an additional language. For instance, if you request all languages that use US English (es-US), and there is an Italian voice that speaks both Italian (it-IT) and US English, that voice will be included if you specify yes but not if you specify no.

    
    
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    An opaque pagination token returned from the previous DescribeVoices operation. If present, this indicates where to continue the listing.

    
    
• On success, responds with DescribeVoicesOutput with field(s):
  • voices(Option<Vec::<Voice>>):

    A list of voices with their properties.

  • next_token(Option<String>):

    The pagination token to use in the next request to continue the listing of voices. NextToken is returned only if the response is truncated.

• On failure, responds with SdkError<DescribeVoicesError>

impl Client

pub fn get_lexicon(&self) -> GetLexiconFluentBuilder

Constructs a fluent builder for the GetLexicon operation.

• The fluent builder is configurable:
  • name(impl Into<String>) / set_name(Option<String>):
    required: true
    

    Name of the lexicon.

    
    
• On success, responds with GetLexiconOutput with field(s):
  • lexicon(Option<Lexicon>):

    Lexicon object that provides name and the string content of the lexicon.

  • lexicon_attributes(Option<LexiconAttributes>):

    Metadata of the lexicon, including phonetic alphabetic used, language code, lexicon ARN, number of lexemes defined in the lexicon, and size of lexicon in bytes.

• On failure, responds with SdkError<GetLexiconError>

impl Client

pub fn get_speech_synthesis_task(&self) -> GetSpeechSynthesisTaskFluentBuilder

Constructs a fluent builder for the GetSpeechSynthesisTask operation.

• The fluent builder is configurable:
  • task_id(impl Into<String>) / set_task_id(Option<String>):
    required: true
    

    The Amazon Polly generated identifier for a speech synthesis task.

    
    
• On success, responds with GetSpeechSynthesisTaskOutput with field(s):
  • synthesis_task(Option<SynthesisTask>):

    SynthesisTask object that provides information from the requested task, including output format, creation time, task status, and so on.

• On failure, responds with SdkError<GetSpeechSynthesisTaskError>

impl Client

pub fn list_lexicons(&self) -> ListLexiconsFluentBuilder

Constructs a fluent builder for the ListLexicons operation.

• The fluent builder is configurable:
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    An opaque pagination token returned from previous ListLexicons operation. If present, indicates where to continue the list of lexicons.

    
    
• On success, responds with ListLexiconsOutput with field(s):
  • lexicons(Option<Vec::<LexiconDescription>>):

    A list of lexicon names and attributes.

  • next_token(Option<String>):

    The pagination token to use in the next request to continue the listing of lexicons. NextToken is returned only if the response is truncated.

• On failure, responds with SdkError<ListLexiconsError>

impl Client

pub fn list_speech_synthesis_tasks( &self, ) -> ListSpeechSynthesisTasksFluentBuilder

Constructs a fluent builder for the ListSpeechSynthesisTasks operation. This operation supports pagination; See into_paginator().

• The fluent builder is configurable:
  • max_results(i32) / set_max_results(Option<i32>):
    required: false
    

    Maximum number of speech synthesis tasks returned in a List operation.

    
    
  • next_token(impl Into<String>) / set_next_token(Option<String>):
    required: false
    

    The pagination token to use in the next request to continue the listing of speech synthesis tasks.

    
    
  • status(TaskStatus) / set_status(Option<TaskStatus>):
    required: false
    

    Status of the speech synthesis tasks returned in a List operation

    
    
• On success, responds with ListSpeechSynthesisTasksOutput with field(s):
  • next_token(Option<String>):

    An opaque pagination token returned from the previous List operation in this request. If present, this indicates where to continue the listing.

  • synthesis_tasks(Option<Vec::<SynthesisTask>>):

    List of SynthesisTask objects that provides information from the specified task in the list request, including output format, creation time, task status, and so on.

• On failure, responds with SdkError<ListSpeechSynthesisTasksError>

impl Client

pub fn put_lexicon(&self) -> PutLexiconFluentBuilder

Constructs a fluent builder for the PutLexicon operation.

• The fluent builder is configurable:
  • name(impl Into<String>) / set_name(Option<String>):
    required: true
    

    Name of the lexicon. The name must follow the regular express format [0-9A-Za-z]{1,20}. That is, the name is a case-sensitive alphanumeric string up to 20 characters long.

    
    
  • content(impl Into<String>) / set_content(Option<String>):
    required: true
    

    Content of the PLS lexicon as string data.

    
    
• On success, responds with PutLexiconOutput
• On failure, responds with SdkError<PutLexiconError>

impl Client

pub fn start_speech_synthesis_task( &self, ) -> StartSpeechSynthesisTaskFluentBuilder

Constructs a fluent builder for the StartSpeechSynthesisTask operation.

• The fluent builder is configurable:
  • engine(Engine) / set_engine(Option<Engine>):
    required: false
    

    Specifies the engine (standard, neural, long-form or generative) for Amazon Polly to use when processing input text for speech synthesis. Using a voice that is not supported for the engine selected will result in an error.

    
    
  • language_code(LanguageCode) / set_language_code(Option<LanguageCode>):
    required: false
    

    Optional language code for the Speech Synthesis request. This is only necessary if using a bilingual voice, such as Aditi, which can be used for either Indian English (en-IN) or Hindi (hi-IN).

    If a bilingual voice is used and no language code is specified, Amazon Polly uses the default language of the bilingual voice. The default language for any voice is the one returned by the DescribeVoices operation for the LanguageCode parameter. For example, if no language code is specified, Aditi will use Indian English rather than Hindi.

    
    
  • lexicon_names(impl Into<String>) / set_lexicon_names(Option<Vec::<String>>):
    required: false
    

    List of one or more pronunciation lexicon names you want the service to apply during synthesis. Lexicons are applied only if the language of the lexicon is the same as the language of the voice.

    
    
  • output_format(OutputFormat) / set_output_format(Option<OutputFormat>):
    required: true
    

    The format in which the returned output will be encoded. For audio stream, this will be mp3, ogg_vorbis, or pcm. For speech marks, this will be json.

    
    
  • output_s3_bucket_name(impl Into<String>) / set_output_s3_bucket_name(Option<String>):
    required: true
    

    Amazon S3 bucket name to which the output file will be saved.

    
    
  • output_s3_key_prefix(impl Into<String>) / set_output_s3_key_prefix(Option<String>):
    required: false
    

    The Amazon S3 key prefix for the output speech file.

    
    
  • sample_rate(impl Into<String>) / set_sample_rate(Option<String>):
    required: false
    

    The audio frequency specified in Hz.

    The valid values for mp3 and ogg_vorbis are “8000”, “16000”, “22050”, and “24000”. The default value for standard voices is “22050”. The default value for neural voices is “24000”. The default value for long-form voices is “24000”. The default value for generative voices is “24000”.

    Valid values for pcm are “8000” and “16000” The default value is “16000”.

    
    
  • sns_topic_arn(impl Into<String>) / set_sns_topic_arn(Option<String>):
    required: false
    

    ARN for the SNS topic optionally used for providing status notification for a speech synthesis task.

    
    
  • speech_mark_types(SpeechMarkType) / set_speech_mark_types(Option<Vec::<SpeechMarkType>>):
    required: false
    

    The type of speech marks returned for the input text.

    
    
  • text(impl Into<String>) / set_text(Option<String>):
    required: true
    

    The input text to synthesize. If you specify ssml as the TextType, follow the SSML format for the input text.

    
    
  • text_type(TextType) / set_text_type(Option<TextType>):
    required: false
    

    Specifies whether the input text is plain text or SSML. The default value is plain text.

    
    
  • voice_id(VoiceId) / set_voice_id(Option<VoiceId>):
    required: true
    

    Voice ID to use for the synthesis.

    
    
• On success, responds with StartSpeechSynthesisTaskOutput with field(s):
  • synthesis_task(Option<SynthesisTask>):

    SynthesisTask object that provides information and attributes about a newly submitted speech synthesis task.

• On failure, responds with SdkError<StartSpeechSynthesisTaskError>

impl Client

pub fn synthesize_speech(&self) -> SynthesizeSpeechFluentBuilder

Constructs a fluent builder for the SynthesizeSpeech operation.

• The fluent builder is configurable:
  • engine(Engine) / set_engine(Option<Engine>):
    required: false
    

    Specifies the engine (standard, neural, long-form, or generative) for Amazon Polly to use when processing input text for speech synthesis. Provide an engine that is supported by the voice you select. If you don’t provide an engine, the standard engine is selected by default. If a chosen voice isn’t supported by the standard engine, this will result in an error. For information on Amazon Polly voices and which voices are available for each engine, see Available Voices.

    Type: String

    Valid Values: standard | neural | long-form | generative

    Required: Yes

    
    
  • language_code(LanguageCode) / set_language_code(Option<LanguageCode>):
    required: false
    

    Optional language code for the Synthesize Speech request. This is only necessary if using a bilingual voice, such as Aditi, which can be used for either Indian English (en-IN) or Hindi (hi-IN).

    If a bilingual voice is used and no language code is specified, Amazon Polly uses the default language of the bilingual voice. The default language for any voice is the one returned by the DescribeVoices operation for the LanguageCode parameter. For example, if no language code is specified, Aditi will use Indian English rather than Hindi.

    
    
  • lexicon_names(impl Into<String>) / set_lexicon_names(Option<Vec::<String>>):
    required: false
    

    List of one or more pronunciation lexicon names you want the service to apply during synthesis. Lexicons are applied only if the language of the lexicon is the same as the language of the voice. For information about storing lexicons, see PutLexicon.

    
    
  • output_format(OutputFormat) / set_output_format(Option<OutputFormat>):
    required: true
    

    The format in which the returned output will be encoded. For audio stream, this will be mp3, ogg_vorbis, or pcm. For speech marks, this will be json.

    When pcm is used, the content returned is audio/pcm in a signed 16-bit, 1 channel (mono), little-endian format.

    
    
  • sample_rate(impl Into<String>) / set_sample_rate(Option<String>):
    required: false
    

    The audio frequency specified in Hz.

    The valid values for mp3 and ogg_vorbis are “8000”, “16000”, “22050”, and “24000”. The default value for standard voices is “22050”. The default value for neural voices is “24000”. The default value for long-form voices is “24000”. The default value for generative voices is “24000”.

    Valid values for pcm are “8000” and “16000” The default value is “16000”.

    
    
  • speech_mark_types(SpeechMarkType) / set_speech_mark_types(Option<Vec::<SpeechMarkType>>):
    required: false
    

    The type of speech marks returned for the input text.

    
    
  • text(impl Into<String>) / set_text(Option<String>):
    required: true
    

    Input text to synthesize. If you specify ssml as the TextType, follow the SSML format for the input text.

    
    
  • text_type(TextType) / set_text_type(Option<TextType>):
    required: false
    

    Specifies whether the input text is plain text or SSML. The default value is plain text. For more information, see Using SSML.

    
    
  • voice_id(VoiceId) / set_voice_id(Option<VoiceId>):
    required: true
    

    Voice ID to use for the synthesis. You can get a list of available voice IDs by calling the DescribeVoices operation.

    
    
• On success, responds with SynthesizeSpeechOutput with field(s):
  • audio_stream(ByteStream):

    Stream containing the synthesized speech.

  • content_type(Option<String>):

    Specifies the type audio stream. This should reflect the OutputFormat parameter in your request.

    • If you request mp3 as the OutputFormat, the ContentType returned is audio/mpeg.

    • If you request ogg_vorbis as the OutputFormat, the ContentType returned is audio/ogg.

    • If you request pcm as the OutputFormat, the ContentType returned is audio/pcm in a signed 16-bit, 1 channel (mono), little-endian format.

    • If you request json as the OutputFormat, the ContentType returned is application/x-json-stream.

  • request_characters(i32):

    Number of characters synthesized.

• On failure, responds with SdkError<SynthesizeSpeechError>

impl Client

pub fn from_conf(conf: Config) -> Self

Creates a new client from the service Config.

Panics

This method will panic in the following cases:

• Retries or timeouts are enabled without a sleep_impl configured.
• Identity caching is enabled without a sleep_impl and time_source configured.
• No behavior_version is provided.

The panic message for each of these will have instructions on how to resolve them.

pub fn config(&self) -> &Config

Returns the client’s configuration.

impl Client

pub fn new(sdk_config: &SdkConfig) -> Self

Creates a new client from an SDK Config.

Panics

• This method will panic if the sdk_config is missing an async sleep implementation. If you experience this panic, set the sleep_impl on the Config passed into this function to fix it.
• This method will panic if the sdk_config is missing an HTTP connector. If you experience this panic, set the http_connector on the Config passed into this function to fix it.
• This method will panic if no BehaviorVersion is provided. If you experience this panic, set behavior_version on the Config or enable the behavior-version-latest Cargo feature.

Trait Implementations

impl Clone for Client

fn clone(&self) -> Client

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Client

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.