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/index.html). ### API usage guidelines * Audio formats: The service can produce audio in many formats (MIME types). 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). SSML is an XML-based markup language that provides text annotation for speech-synthesis applications. 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 sounds-like or phonetic translations for words. Phonetic translations are based on the SSML phoneme format for representing a word. You can specify them in standard International Phonetic Alphabet (IPA) representation

<phoneme alphabet=”ipa” ph=”təmˈɑto”></phoneme> or in the proprietary IBM Symbolic Phonetic Representation (SPR) <phoneme alphabet=”ibm” ph=”1gAstroEntxrYFXs”></phoneme> See [Understanding

customization](https://console.bluemix.net/docs/services/text-to-speech/custom-intro.html). * WebSocket interface: The service also offers a WebSocket 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). * Customization IDs: Many methods accept a customization ID, which is a Globally Unique Identifier (GUID). Customization IDs are hexadecimal strings that have the format xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. * `X-Watson-Learning-Opt-Out`: By default, all Watson services log requests and their results. Logging is done only to improve the services for future users. The logged data is not shared or made public. To prevent IBM from accessing your data for general service improvements, set the X-Watson-Learning-Opt-Out request header to true for all requests. You must set the header on each request that you do not want IBM to access for general service improvements.

Methods of the customization interface do not log words and translations that you use to

build custom voice models. Your training data is never used to improve the service’s base models. However, the service does log such data when a custom model is used with a synthesize request. You must set the X-Watson-Learning-Opt-Out request header to true to prevent IBM from accessing the data to improve the service. * `X-Watson-Metadata`: This header allows you to associate a customer ID with data that is passed with a request. If necessary, you can use the Delete labeled data method to delete the data for a customer ID. See [Information security](https://console.bluemix.net/docs/services/text-to-speech/information-security.html).

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. To list information about all available voices, use the List voices method.

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. :param dict headers: A dict containing the request headers :return: A dict containing the Voice response. :rtype: 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. To see information about a specific voice, use the Get a voice method.

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.

Parameters:
  • text (str) – The text to synthesize.
  • accept (str) – The requested audio format (MIME type) of the audio. You can

use the Accept header or the accept query parameter to specify the audio format. (For the audio/l16 format, you can optionally specify endianness=big-endian or endianness=little-endian; the default is little endian.) 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). :param str voice: The voice to use for synthesis. :param str customization_id: 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. :param dict headers: A dict containing the request headers :return: A Response <Response> object representing the response. :rtype: 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. :param str format: The phoneme format in which to return the pronunciation. Omit the parameter to obtain the pronunciation in the default format. :param str customization_id: 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. :param dict headers: A dict containing the request headers :return: A dict containing the Pronunciation response. :rtype: 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 for 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. :param str description: A description of the new custom voice model. Specifying a description is recommended. :param dict headers: A dict containing the request headers :return: A dict containing the VoiceModel response. :rtype: 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. :param dict headers: A dict containing the request headers :rtype: 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. :param dict headers: A dict containing the request headers :return: A dict containing the VoiceModel response. :rtype: 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. :param dict headers: A dict containing the request headers :return: A dict containing the VoiceModels response. :rtype: 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. :param str name: A new name for the custom voice model. :param str description: A new description for the custom voice model. :param list[Word] words: 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. :param dict headers: A dict containing the request headers :rtype: 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. You must use credentials for the instance of the service that owns a model to add a word to 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. :param str word: The word that is to be added or updated for the custom voice model. :param 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. :param str part_of_speech: 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). :param dict headers: A dict containing the request headers :rtype: 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. You must use credentials for the instance of the service that owns a model to add words to 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. :param list[Word] words: The Add custom words method accepts an array of Word objects. Each object provides a word that is to be added or updated for the custom voice model and the word’s translation. The List custom words method returns an array of Word objects. Each object shows a word and its translation 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. :param dict headers: A dict containing the request headers :rtype: 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. You must use credentials for the instance of the service that owns a model to delete its words. 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. :param str word: The word that is to be deleted from the custom voice model. :param dict headers: A dict containing the request headers :rtype: 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. You must use credentials for the instance of the service that owns a model to list its words. 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. :param str word: The word that is to be queried from the custom voice model. :param dict headers: A dict containing the request headers :return: A dict containing the Translation response. :rtype: 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. You must use credentials for the instance of the service that owns a model to list its words. 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. :param dict headers: A dict containing the request headers :return: A dict containing the Words response. :rtype: dict

get_customization_words(**kwargs)
delete_user_data(customer_id, **kwargs)[source]

Delete labeled data.

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. You associate a customer ID with data by passing the X-Watson-Metadata header with a request that passes the data. For more information about customer IDs and about using this method, see [Information security](https://console.bluemix.net/docs/services/text-to-speech/information-security.html).

Parameters:
  • customer_id (str) – The customer ID for which all data is to be deleted.
  • headers (dict) – A dict containing the request headers
Return type:

None
class Pronunciation(pronunciation)[source]

Bases: object

Pronunciation.

Attr str pronunciation:
 The pronunciation of the specified text in the requested

voice and format. If a custom voice model is specified, the pronunciation also reflects that custom voice.

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. This field is returned only by the Get a voice method and only when you specify the customization ID of a custom voice model.

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. The

Create a custom model method returns only this field. It does not 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. This field is returned only by the Get a voice method and only when you specify the customization ID of a 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:
 The Add custom words method accepts an array of Word

objects. Each object provides a word that is to be added or updated for the custom voice model and the word’s translation. The List custom words method returns an array of Word objects. Each object shows a word and its translation 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.