watson_developer_cloud.text_to_speech_v1 module

### Service Overview The IBM® Text to Speech service provides an API that uses IBM’s speech-synthesis capabilities to synthesize text into natural-sounding speech in a variety of languages, dialects, and voices. The service supports at least one male or female voice, sometimes both, for each language. The audio is streamed back to the client with minimal delay. For more information about the service, see the [IBM® Cloud documentation](https://console.bluemix.net/docs/services/text-to-speech/getting-started.html). ### API Overview The Text to Speech service provides the following endpoints: * Voices provides information about the voices available for synthesized speech. * Synthesis synthesizes written text to audio speech. * Pronunciation returns the pronunciation for a specified word. Currently a beta feature. * Custom models and let users create custom voice models, which are dictionaries of words and their translations for use in speech synthesis. All custom model methods are currently beta features. * Custom words let users manage the words in a custom voice model. All custom word methods are currently beta features. ### API Usage The following information provides details about using the service to synthesize audio: * Audio formats: The service supports a number of audio formats (MIME types). For more information about audio formats and sampling rates, including links to a number of Internet sites that provide technical and usage details about the different formats, see [Specifying an audio format](https://console.bluemix.net/docs/services/text-to-speech/http.html#format). * SSML: Many methods refer to the Speech Synthesis Markup Language (SSML), an XML-based markup language that provides annotations of text for speech-synthesis applications; for example, many methods accept or produce translations that use an SSML-based phoneme format. See [Using SSML](https://console.bluemix.net/docs/services/text-to-speech/SSML.html) and [Using IBM SPR](https://console.bluemix.net/docs/services/text-to-speech/SPRs.html). * Word translations: Many customization methods accept or return sounds-like or phonetic translations for words. A phonetic translation is based on the SSML format for representing the phonetic string of a word. Phonetic translations can use standard International Phonetic Alphabet (IPA) representation:

<phoneme alphabet=”ipa” ph=”təmˈɑto”></phoneme> or the proprietary IBM Symbolic Phonetic Representation (SPR): <phoneme alphabet=”ibm” ph=”1gAstroEntxrYFXs”></phoneme> For more information about customization and about sounds-like and phonetic

translations, see [Understanding customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html). * WebSocket interface: The service also offers a WebSocket interface as an alternative to its HTTP REST interface for speech synthesis. The WebSocket interface supports both plain text and SSML input, including the SSML <mark> element and word timings. See [The WebSocket interface](https://console.bluemix.net/docs/services/text-to-speech/websockets.html). * GUIDs: The pronunciation and customization methods accept or return a Globally Unique Identifier (GUID). For example, customization IDs (specified with the customization_id parameter) and service credentials are GUIDs. GUIDs are hexadecimal strings that have the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. * Custom voice model ownership: In all cases, you must use service credentials created for the instance of the service that owns a custom voice model to use the methods described in this documentation with that model. For more information, see [Ownership of custom voice models](https://console.bluemix.net/docs/services/text-to-speech/custom-models.html#customOwner).

class TextToSpeechV1(url='https://stream.watsonplatform.net/text-to-speech/api', username=None, password=None, iam_api_key=None, iam_access_token=None, iam_url=None)[source]

Bases: watson_developer_cloud.watson_service.WatsonService

The Text to Speech V1 service.

default_url = 'https://stream.watsonplatform.net/text-to-speech/api'
get_voice(voice, customization_id=None, **kwargs)[source]

Get a voice.

Gets information about the specified voice. The information includes the name, language, gender, and other details about the voice. Specify a customization ID to obtain information for that custom voice model of the specified voice.

Parameters:
  • voice (str) – The voice for which information is to be returned.
  • customization_id (str) – The customization ID (GUID) of a custom voice model for which information is to be returned. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to see information about the specified voice with no customization.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the Voice response.
Return type:

dict
list_voices(**kwargs)[source]

List voices.

Lists all voices available for use with the service. The information includes the name, language, gender, and other details about the voice.

Parameters:headers (dict) – A dict containing the request headers
Returns:A dict containing the Voices response.
Return type:dict
voices(**kwargs)
synthesize(text, accept=None, voice=None, customization_id=None, **kwargs)[source]

Synthesize audio.

Synthesizes text to spoken audio, returning the synthesized audio stream as an array of bytes. You can pass a maximum of 5 KB of text. Use the Accept header or the accept query parameter to specify the requested format (MIME type) of the response audio. By default, the service uses audio/ogg;codecs=opus. For detailed information about the supported audio formats and sampling rates, see [Specifying an audio format](https://console.bluemix.net/docs/services/text-to-speech/http.html#format).

If a request includes invalid query parameters, the service returns a Warnings

response header that provides messages about the invalid parameters. The warning includes a descriptive message and a list of invalid argument strings. For example, a message such as “Unknown arguments:” or “Unknown url query arguments:” followed by a list of the form “invalid_arg_1, invalid_arg_2.” The request succeeds despite the warnings. Note about the Try It Out feature: The Try it out! button is not supported for use with the the POST /v1/synthesize method. For examples of calls to the method, see the [Text to Speech API reference](http://www.ibm.com/watson/developercloud/text-to-speech/api/v1/).

Parameters:
  • text (str) – The text to synthesize.
  • accept (str) – The type of the response: audio/basic, audio/flac, audio/l16;rate=nnnn, audio/ogg, audio/ogg;codecs=opus, audio/ogg;codecs=vorbis, audio/mp3, audio/mpeg, audio/mulaw;rate=nnnn, audio/wav, audio/webm, audio/webm;codecs=opus, or audio/webm;codecs=vorbis.
  • voice (str) – The voice to use for synthesis.
  • customization_id (str) – The customization ID (GUID) of a custom voice model to use for the synthesis. If a custom voice model is specified, it is guaranteed to work only if it matches the language of the indicated voice. You must make the request with service credentials created for the instance of the service that owns the custom model. Omit the parameter to use the specified voice with no customization.
  • headers (dict) – A dict containing the request headers
Returns:

A Response <Response> object representing the response.
Return type:

requests.models.Response
get_pronunciation(text, voice=None, format=None, customization_id=None, **kwargs)[source]

Get pronunciation.

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 voice model to see the translation for that voice model. Note: This method is currently a beta release.

Parameters:
  • text (str) – The word for which the pronunciation is requested.
  • voice (str) – A voice that specifies the language in which the pronunciation is to be returned. All voices for the same language (for example, en-US) return the same translation.
  • format (str) – The phoneme format in which to return the pronunciation. Omit the parameter to obtain the pronunciation in the default format.
  • customization_id (str) – The customization ID (GUID) of a custom voice 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 service credentials created for the instance of the service that owns the custom model. Omit the parameter to see the translation for the specified voice with no customization.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the Pronunciation response.
Return type:

dict
pronunciation(**kwargs)
create_voice_model(name, language=None, description=None, **kwargs)[source]

Create a custom model.

Creates a new empty custom voice model. You must specify a name for the new custom model; you can optionally specify the language and a description of the new model. The model is owned by the instance of the service whose credentials are used to create it. Note: This method is currently a beta release.

Parameters:
  • name (str) – The name of the new custom voice model.
  • language (str) – The language of the new custom voice model. Omit the parameter to use the the default language, en-US.
  • description (str) – A description of the new custom voice model. Specifying a description is recommended.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the VoiceModel response.
Return type:

dict
create_customization(**kwargs)
delete_voice_model(customization_id, **kwargs)[source]

Delete a custom model.

Deletes the specified custom voice model. You must use credentials for the instance of the service that owns a model to delete it. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • headers (dict) – A dict containing the request headers
Return type:

None
delete_customization(**kwargs)
get_voice_model(customization_id, **kwargs)[source]

Get a custom model.

Gets all information about a specified custom voice model. In addition to metadata such as the name and description of the voice model, the output includes the words and their translations as defined in the model. To see just the metadata for a voice model, use the List custom models method. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the VoiceModel response.
Return type:

dict
get_customization(**kwargs)
list_voice_models(language=None, **kwargs)[source]

List custom models.

Lists metadata such as the name and description for all custom voice models that are owned by an instance of the service. Specify a language to list the voice models for that language only. To see the words in addition to the metadata for a specific voice model, use the List a custom model method. You must use credentials for the instance of the service that owns a model to list information about it. Note: This method is currently a beta release.

Parameters:
  • language (str) – The language for which custom voice models that are owned by the requesting service credentials are to be returned. Omit the parameter to see all custom voice models that are owned by the requester.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the VoiceModels response.
Return type:

dict
customizations(**kwargs)
update_voice_model(customization_id, name=None, description=None, words=None, **kwargs)[source]

Update a custom model.

Updates information for the specified custom voice model. You can update metadata such as the name and description of the voice 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. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • name (str) – A new name for the custom voice model.
  • description (str) – A new description for the custom voice model.
  • words (list[Word]) – An array of Word objects that provides the words and their translations that are to be added or updated for the custom voice model. Pass an empty array to make no additions or updates.
  • headers (dict) – A dict containing the request headers
Return type:

None
update_customization(**kwargs)
add_word(customization_id, word, translation, part_of_speech=None, **kwargs)[source]

Add a custom word.

Adds a single word and its translation to the specified custom voice 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. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • word (str) – The word that is to be added or updated for the custom voice model.
  • translation (str) – The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA translation or as an IBM SPR translation. A sounds-like is one or more words that, when combined, sound like the word.
  • part_of_speech (str) – Japanese only. The part of speech for the word. The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see [Working with Japanese entries](https://console.bluemix.net/docs/services/text-to-speech/custom-rules.html#jaNotes).
  • headers (dict) – A dict containing the request headers
Return type:

None
set_customization_word(**kwargs)
add_words(customization_id, words, **kwargs)[source]

Add custom words.

Adds one or more words and their translations to the specified custom voice 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. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • words (list[Word]) – When adding words to a custom voice model, an array of Word objects that provides one or more words that are to be added or updated for the custom voice model and the translation for each specified word. When listing words from a custom voice model, an array of Word objects that lists the words and their translations from the custom voice model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if the custom model contains no words.
  • headers (dict) – A dict containing the request headers
Return type:

None
add_customization_words(**kwargs)
delete_word(customization_id, word, **kwargs)[source]

Delete a custom word.

Deletes a single word from the specified custom voice model. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • word (str) – The word that is to be deleted from the custom voice model.
  • headers (dict) – A dict containing the request headers
Return type:

None
delete_customization_word(**kwargs)
get_word(customization_id, word, **kwargs)[source]

Get a custom word.

Gets the translation for a single word from the specified custom model. The output shows the translation as it is defined in the model. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • word (str) – The word that is to be queried from the custom voice model.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the Translation response.
Return type:

dict
get_customization_word(**kwargs)
list_words(customization_id, **kwargs)[source]

List custom words.

Lists all of the words and their translations for the specified custom voice model. The output shows the translations as they are defined in the model. Note: This method is currently a beta release.

Parameters:
  • customization_id (str) – The customization ID (GUID) of the custom voice model. You must make the request with service credentials created for the instance of the service that owns the custom model.
  • headers (dict) – A dict containing the request headers
Returns:

A dict containing the Words response.
Return type:

dict
get_customization_words(**kwargs)
class Pronunciation(pronunciation)[source]

Bases: object

Pronunciation.

Attr str pronunciation:
 The pronunciation of the requested text in the specified voice and format.
class SupportedFeatures(custom_pronunciation, voice_transformation)[source]

Bases: object

SupportedFeatures.

Attr bool custom_pronunciation:
 If true, the voice can be customized; if false, the voice cannot be customized. (Same as customizable.).
Attr bool voice_transformation:
 If true, the voice can be transformed by using the SSML &lt;voice-transformation&gt; element; if false, the voice cannot be transformed.
class Translation(translation, part_of_speech=None)[source]

Bases: object

Translation.

Attr str translation:
 The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA translation or as an IBM SPR translation. A sounds-like is one or more words that, when combined, sound like the word.
Attr str part_of_speech:
 (optional) Japanese only. The part of speech for the word. The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see [Working with Japanese entries](https://console.bluemix.net/docs/services/text-to-speech/custom-rules.html#jaNotes).
class Voice(url, gender, name, language, description, customizable, supported_features, customization=None)[source]

Bases: object

Voice.

Attr str url:The URI of the voice.
Attr str gender:
 The gender of the voice: male or female.
Attr str name:The name of the voice. Use this as the voice identifier in all requests.
Attr str language:
 The language and region of the voice (for example, en-US).
Attr str description:
 A textual description of the voice.
Attr bool customizable:
 If true, the voice can be customized; if false, the voice cannot be customized. (Same as custom_pronunciation; maintained for backward compatibility.).
Attr SupportedFeatures supported_features:
 Describes the additional service features supported with the voice.
Attr VoiceModel customization:
 (optional) Returns information about a specified custom voice model. Note: This field is returned only when you list information about a specific voice and specify the GUID of a custom voice model that is based on that voice.
class VoiceModel(customization_id, name=None, language=None, owner=None, created=None, last_modified=None, description=None, words=None)[source]

Bases: object

VoiceModel.

Attr str customization_id:
 The customization ID (GUID) of the custom voice model. Note: When you create a new custom voice model, the service returns only the GUID of the new custom model; it does not return the other fields of this object.
Attr str name:(optional) The name of the custom voice model.
Attr str language:
 (optional) The language identifier of the custom voice model (for example, en-US).
Attr str owner:(optional) The GUID of the service credentials for the instance of the service that owns the custom voice model.
Attr str created:
 (optional) The date and time in Coordinated Universal Time (UTC) at which the custom voice model was created. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
Attr str last_modified:
 (optional) The date and time in Coordinated Universal Time (UTC) at which the custom voice model was last modified. Equals created when a new voice model is first added but has yet to be updated. The value is provided in full ISO 8601 format (YYYY-MM-DDThh:mm:ss.sTZD).
Attr str description:
 (optional) The description of the custom voice model.
Attr list[Word] words:
 (optional) An array of Word objects that lists the words and their translations from the custom voice model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if the custom model contains no words. Note: This field is returned only when you list information about a specific custom voice model.
class VoiceModels(customizations)[source]

Bases: object

VoiceModels.

Attr list[VoiceModel] customizations:
 An array of VoiceModel objects that provides information about each available custom voice model. The array is empty if the requesting service credentials own no custom voice models (if no language is specified) or own no custom voice models for the specified language.
class Voices(voices)[source]

Bases: object

Voices.

Attr list[Voice] voices:
 A list of available voices.
class Word(word, translation, part_of_speech=None)[source]

Bases: object

Word.

Attr str word:A word from the custom voice model.
Attr str translation:
 The phonetic or sounds-like translation for the word. A phonetic translation is based on the SSML format for representing the phonetic string of a word either as an IPA or IBM SPR translation. A sounds-like translation consists of one or more words that, when combined, sound like the word.
Attr str part_of_speech:
 (optional) Japanese only. The part of speech for the word. The service uses the value to produce the correct intonation for the word. You can create only a single entry, with or without a single part of speech, for any word; you cannot create multiple entries with different parts of speech for the same word. For more information, see [Working with Japanese entries](https://console.bluemix.net/docs/services/text-to-speech/custom-rules.html#jaNotes).
class Words(words)[source]

Bases: object

Words.

Attr list[Word] words:
 When adding words to a custom voice model, an array of Word objects that provides one or more words that are to be added or updated for the custom voice model and the translation for each specified word. When listing words from a custom voice model, an array of Word objects that lists the words and their translations from the custom voice model. The words are listed in alphabetical order, with uppercase letters listed before lowercase letters. The array is empty if the custom model contains no words.