Struct TextToSpeech

pub struct TextToSpeech<'a> { /* private fields */ }

Available on crate feature tts only.

Creates a client used to send requests to your Text To Speech endpoint

Implementations

impl TextToSpeech<'_>

pub async fn create_custom_model( &self, name: impl AsRef<str>, language: Option<Language>, description: Option<impl AsRef<str>>, ) -> Result<Model, CreateModelError>

Creates a new empty custom model. You must specify a name for the new custom model. You can optionally specify the language and a description for the new model. The model is owned by the instance of the service whose credentials are used to create it

Parameters

• name - The name of the new custom model
• language - The language of the new custom model. You create a custom model for a specific language, not for a specific voice. A custom model can be used with any voice for its specified language. If None is specified, the default language is used
• description - A description of the new custom model. Specifying a description is recommended

Example

let model = tts.create_custom_model("new model", None, Some("example")).await?;
println!("model: {:#?}", model);

pub async fn list_custom_models( &self, language: Option<Language>, ) -> Result<Vec<Model>, ListModelError>

Lists metadata such as the name and description for all custom models that are owned by an instance of the service. Specify a language to list the custom models for that language only. To see the words and prompts in addition to the metadata for a specific custom model, use get_custom_model(). You must use credentials for the instance of the service that owns a model to list information about it.

Parameters

• language - The language for which custom models that are owned by the requesting credentials are to be returned. Pass None to see all custom models that are owned by the requester

Example

let models = tts.list_custom_models(None).await?;
println!("found: {:#?} models", models.len());

pub async fn update_custom_model( &self, customisation_id: impl AsRef<str>, name: Option<&str>, description: Option<&str>, words: Option<&[Word]>, ) -> Result<(), UpdateModelError>

Updates information for the specified custom model. You can update metadata such as the name and description of the model. You can also update the words in the model and their translations. Adding a new translation for a word that already exists in a custom model overwrites the word’s existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to update it

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• name - A new name for the custom model
• description - A new description for the custom model
• words - An array of Word objects that provides the words and their translations that are to be added or updated for the custom model. Pass an empty array to make no additions or updates

Example

tts.update_custom_model("cust-id", Some("foo"), None, None).await?;

pub async fn get_custom_model( &self, customisation_id: impl AsRef<str>, ) -> Result<Model, GetModelError>

Gets all information about a specified custom model. In addition to metadata such as the name and description of the custom model, the output includes the words and their translations that are defined for the model, as well as any prompts that are defined for the model. To see just the metadata for a model, use list_custom_models().

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model

Example

let model = tts.get_custom_model("cust-id").await?;
println!("{:#?}", model);

pub async fn delete_custom_model( &self, customisation_id: impl AsRef<str>, ) -> Result<(), DeleteModelError>

Deletes the specified custom model. You must use credentials for the instance of the service that owns a model to delete it.

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model

Example

if tts.delete_custom_model("cust-id").await.is_ok() {
    println!("model deleted");
}

impl TextToSpeech<'_>

pub async fn list_custom_prompts( &self, customisation_id: impl AsRef<str>, ) -> Result<Vec<Prompt>, ListPromptsError>

Lists information about all custom prompts that are defined for a custom model. The information includes the prompt ID, prompt text, status, and optional speaker ID for each prompt of the custom model. You must use credentials for the instance of the service that owns the custom model. The same information about all of the prompts for a custom model is also provided by get_custom_model(). That method provides complete details about a specified custom model, including its language, owner, custom words, and more. Custom prompts are supported only for use with US English custom models and voices.

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model

Example

let prompts = tts.list_custom_prompts("word").await?;
println!("{:#?}", prompts);

pub async fn add_custom_prompt( &self, customisation_id: impl AsRef<str>, prompt: &Prompt, audio_file: impl AsRef<Path>, ) -> Result<Prompt, AddPromptError>

Adds a custom prompt to a custom model. A prompt is defined by the text that is to be spoken, the audio for that text, a unique user-specified ID for the prompt, and an optional speaker ID. The information is used to generate prosodic data that is not visible to the user. This data is used by the service to produce the synthesized audio upon request. You must use credentials for the instance of the service that owns a custom model to add a prompt to it. You can add a maximum of 1000 custom prompts to a single custom model

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• prompt - The prompt that is to be added to the custom model
• audio_file - An audio file that speaks the text of the prompt with intonation and prosody that matches how you would like the prompt to be spoken
  • The prompt audio must be in WAV format and must have a minimum sampling rate of 16 kHz. The service accepts audio with higher sampling rates. The service transcodes all audio to 16 kHz before processing it
  • The length of the prompt audio is limited to 30 seconds

Example

let file_path = std::path::Path::new("/home/user/audio.wav");
let prompt = Prompt {
    prompt: String::from("foo"),
    prompt_id: String::from("bar"),
    ..Default::default()
};
let _ = tts.add_custom_prompt("cust-id", &prompt, &file_path).await?;

pub async fn get_custom_prompt( &self, customisation_id: impl AsRef<str>, prompt_id: impl AsRef<str>, ) -> Result<Prompt, GetPromptError>

Gets information about a specified custom prompt for a specified custom model. The information includes the prompt ID, prompt text, status, and optional speaker ID for each prompt of the custom model. You must use credentials for the instance of the service that owns the custom model. Custom prompts are supported only for use with US English custom models and voices

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• prompt_id - The identifier (name) of the prompt

Example

let prompt = tts.get_custom_prompt("cust-id", "prompt_id").await?;
println!("{:#?}", prompt);

pub async fn delete_custom_prompt( &self, customisation_id: impl AsRef<str>, prompt_id: impl AsRef<str>, ) -> Result<(), DeletePromptError>

Deletes an existing custom prompt from a custom model. The service deletes the prompt with the specified ID. You must use credentials for the instance of the service that owns the custom model from which the prompt is to be deleted

Parameters

customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model prompt_id - The identifier (name) of the prompt that is to be deleted

Example

if tts.delete_custom_prompt("cust-id", "prompt-id").await.is_ok() {
    println!("prompt deleted");
}

impl TextToSpeech<'_>

pub async fn add_custom_words( &self, customisation_id: impl AsRef<str>, words: &[Word], ) -> Result<(), AddWordError>

Adds one or more words and their translations to the specified custom model. Adding a new translation for a word that already exists in a custom model overwrites the word’s existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to add words to it.

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• words - Words that are to be added or updated for the custom model and the translation for each specified word

Example

let word = Word {
    word: String::default(),
    translation: String::default(),
    part_of_speech: Option::default()
};
let mut words = vec![];
words.push(word);
if let Ok(_) = tts.add_custom_words("word", &words).await {
    println!("word(s) added!");
}

pub async fn list_custom_words( &self, customisation_id: impl AsRef<str>, ) -> Result<Vec<Word>, ListWordsError>

Lists all of the words and their translations for the specified custom model. The output shows the translations as they are defined in the model. You must use credentials for the instance of the service that owns a model to list its words

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model

Example

let words = tts.list_custom_words("customisation_id").await?;

pub async fn add_custom_word( &self, customisation_id: impl AsRef<str>, word: &Word, ) -> Result<(), AddWordError>

Adds a single word and its translation to the specified custom model. Adding a new translation for a word that already exists in a custom model overwrites the word’s existing translation. A custom model can contain no more than 20,000 entries. You must use credentials for the instance of the service that owns a model to add a word to it

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• word - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model

Example

let word = Word {
    word: String::default(),
    translation: String::default(),
    part_of_speech: Option::default()
};
tts.add_custom_word("customisation_id", &word).await?;

pub async fn get_custom_word( &self, customisation_id: impl AsRef<str>, word: impl AsRef<str>, ) -> Result<Word, GetWordError>

Gets the translation for a single word from the specified custom model. The output shows the translation as it is defined in the model. You must use credentials for the instance of the service that owns a model to list its words.

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• word - The word that is to be queried from the custom model

Example

let word = tts.get_custom_word("customisation_id", "foo").await?;
println!("{:#?}", word);

pub async fn delete_custom_word( &self, customisation_id: impl AsRef<str>, word: impl AsRef<str>, ) -> Result<(), DeleteWordError>

Deletes a single word from the specified custom model. You must use credentials for the instance of the service that owns a model to delete its words.

Parameters

• customisation_id - The customisation ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model
• word - The word that is to be queried from the custom model

Example

if tts.delete_custom_word("customisation_id", "foo").await.is_ok() {
    println!("word deleted");
}

impl TextToSpeech<'_>

pub async fn get_pronunciation( &self, text: impl AsRef<str>, voice: Option<WatsonVoice>, format: Option<PhonemeFormat>, customisation_id: Option<impl AsRef<str>>, ) -> Result<Pronunciation, PronunciationError>

Gets the phonetic Pronunciation for the specified word. You can request the pronunciation for a specific format. You can also request the pronunciation for a specific voice to see the default translation for the language of that voice or for a specific custom model to see the translation for that model.

Parameters

• text - The word for which the pronunciation is requested
• voice - A voice that specifies the language in which the pronunciation is to be returned. If None, the voice you set for the service will be used. If none has been set, the default will be used
• format - The PhonemeFormat in which to return the pronunciation. The Arabic, Chinese, Dutch, Australian English, and Korean languages support only IPA. Omit the parameter to obtain the pronunciation in the default format
• customisation_id - The customisation ID (GUID) of a custom model for which the pronunciation is to be returned. The language of a specified custom model must match the language of the specified voice. If the word is not defined in the specified custom model, the service returns the default translation for the custom model’s language. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to see the translation for the specified voice with no customisation

Example

let customisation_id = Some("cust-id");
let pronunciation = tts.get_pronunciation("word", None, None, customisation_id).await?;
println!("{:#?}", pronunciation);

impl TextToSpeech<'_>

pub async fn list_speaker_models( &self, ) -> Result<Vec<Speaker>, ListSpeakersError>

Lists information about all speaker models that are defined for a service instance. The information includes the speaker ID and speaker name of each defined speaker. You must use credentials for the instance of a service to list its speakers. Speaker models and the custom prompts with which they are used are supported only for use with US English custom models and voices.

Example

let speakers = tts.list_speaker_models().await?;
println!("Speakers count: {}", speakers.len());

pub async fn create_speaker_model( &self, speaker_name: impl AsRef<str>, audio_file: impl AsRef<Path>, ) -> Result<String, CreateSpeakerError>

Creates a new speaker model, which is an optional enrollment token for users who are to add prompts to custom models. A speaker model contains information about a user’s voice. The service extracts this information from a WAV audio sample that you pass as the body of the request. Associating a speaker model with a prompt is optional, but the information that is extracted from the speaker model helps the service learn about the speaker’s voice

Parameters

• speaker_name - The name of the speaker that is to be added to the service instance
  • Include a maximum of 49 characters in the name
  • Include only alphanumeric characters and _ (underscores) in the name
  • Do not include XML sensitive characters (double quotes, single quotes, ampersands, angle brackets, and slashes) in the name
  • Do not use the name of an existing speaker that is already defined for the service instance
• audio_file - An enrollment audio file that contains a sample of the speaker’s voice
  • The enrollment audio must be in WAV format and must have a minimum sampling rate of 16 kHz. The service accepts audio with higher sampling rates. It transcodes all audio to 16 kHz before processing it
  • The length of the enrollment audio is limited to 1 minute. Speaking one or two paragraphs of text that include five to ten sentences is recommended

Returns

The speaker_id for the newly created speaker

Example

let file_path = std::path::Path::new("/home/user/audio.wav");
let speaker_id = tts.create_speaker_model("speaker_one", &file_path).await?;
println!("created speaker: {}", speaker_id);

pub async fn get_speaker_model( &self, speaker_id: impl AsRef<str>, ) -> Result<SpeakerCustomModel, GetSpeakerError>

Gets information about all prompts that are defined by a specified speaker for all custom models that are owned by a service instance. The information is grouped by the customisation IDs of the custom models. For each custom model, the information lists information about each prompt that is defined for that custom model by the speaker. You must use credentials for the instance of the service that owns a speaker model to list its prompts. Speaker models and the custom prompts with which they are used are supported only for use with US English custom models and voices

Parameters

• speaker_id - The speaker ID (GUID) of the speaker model. You must make the request with service credentials for the instance of the service that owns the speaker model

Example

let speaker = tts.get_speaker_model("speaker_id").await?;
println!("Speaker: {:#?}", speaker);

pub async fn delete_speaker_model( &self, speaker_id: impl AsRef<str>, ) -> Result<(), DeleteSpeakerError>

Deletes an existing speaker model from the service instance. The service deletes the enrolled speaker with the specified speaker ID. You must use credentials for the instance of the service that owns a speaker model to delete the speaker

Parameters

speaker_id - The speaker ID (GUID) of the speaker model. You must make the request with service credentials for the instance of the service that owns the speaker model

Example

if tts.delete_speaker_model("speaker-id").await.is_ok() {
    println!("speaker deleted");
}

impl TextToSpeech<'_>

pub async fn synthesise( &self, text: impl AsRef<str>, format: Option<AudioFormat>, customisation_id: Option<&str>, ) -> Result<Bytes, SynthesisError>

Synthesises text to audio that is spoken in the specified voice. The service bases its understanding of the language for the input text on the specified voice. Use a voice that matches the language of the input text.

Parameters

• text - The text to synthesise
• format - The requested AudioFormat (MIME type) of the audio. Defaults to AudioOggCodecsOpus
• customisation_id - The customisation ID (GUID) of a custom model to use for the synthesis. If a custom model is specified, it works only if it matches the language of the indicated voice. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customisation

Example

let synth_bytes = tts.synthesise("Hey there", None, None).await?;

impl TextToSpeech<'_>

pub async fn delete_labeled_data( &self, customer_id: impl AsRef<str>, ) -> Result<(), DeleteLabeledDataError>

Deletes all data that is associated with a specified customer ID. The method deletes all data for the customer ID, regardless of the method by which the information was added. The method has no effect if no data is associated with the customer ID. You must issue the request with credentials for the same instance of the service that was used to associate the customer ID with the data

Parameters

• customer_id - The customer ID for which all data is to be deleted

Example

if tts.delete_labeled_data("me-id").await.is_ok() {
    println!("user data deleted");
}

impl TextToSpeech<'_>

pub async fn list_voices(&self) -> Result<Vec<Voice>, ListVoicesError>

Lists all voices available for use with the service. The information includes the name, language, gender, and other details about the voice. The ordering of the list of voices can change from call to call; do not rely on an alphabetized or static list of voices. To see information about a specific voice, use get_voice()

Example

let voices = tts.list_voices().await?;
println!("Total: {}", voices.len());

pub async fn get_voice( &self, voice: WatsonVoice, customisation_id: Option<&str>, ) -> Result<Voice, GetVoiceError>

Returns information about the specified Voice. The information includes the name, language, gender, and other details about the voice. Specify a customisation ID to obtain information for a custom model that is defined for the language of the specified voice. To list information about all available voices, use list_voices()

Parameters

• voice - The particular WatsonVoice you want information about
• customisation_id - The customisation ID (GUID) of a custom model for which information is to be returned. You must make the request with credentials for the instance of the service that owns the custom model. Omit the parameter to see information about the specified voice with no customisation

Example

let kate = tts.get_voice(WatsonVoice::EnGbKateV3, None).await?;
println!("Gender: {}", kate.gender);

impl<'a> TextToSpeech<'a>

pub fn new(authenticator: &'a IamAuthenticator, service_url: &'a str) -> Self

Create a new Text To Speech instance. This instance will be used to make all the requests to the text to speech service.

Parameters

• authenticator - The IamAuthenticator containing your IAM Access Token
• service_url - The endpoint for your text to speech instance. All Text To Speech requests will be made to this endpoint

Examples

let auth = IamAuthenticator::new("api_key").await?;
let tts = TextToSpeech::new(&auth, "service_url");
let voice = tts.get_voice(WatsonVoice::EnGbCharlotteV3, None).await?;

pub fn set_voice(&mut self, voice: WatsonVoice)

Change the default voice to use for Text To Speech requests

Parameters

• voice - Use this voice in place of the default one

Examples

let mut tts = TextToSpeech::new(&auth, "service_url");
tts.set_voice(WatsonVoice::EnGbCharlotteV3);