com.ibm.watson.developer_cloud.text_to_speech.v1

Class TextToSpeech

java.lang.Object

com.ibm.watson.developer_cloud.service.WatsonService

com.ibm.watson.developer_cloud.text_to_speech.v1.TextToSpeech

public class TextToSpeech
extends WatsonService

### 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).

See Also:

Text to Speech

Field Summary

Fields inherited from class com.ibm.watson.developer_cloud.service.WatsonService

defaultHeaders, MESSAGE_CODE, MESSAGE_ERROR, skipAuthentication, VERSION

Constructor Summary

Constructors

Constructor and Description
TextToSpeech() Instantiates a new `TextToSpeech`.
TextToSpeech(IamOptions iamOptions) Instantiates a new `TextToSpeech` with IAM.
TextToSpeech(java.lang.String username, java.lang.String password) Instantiates a new `TextToSpeech` with username and password.

Method Summary

Methods

Modifier and Type	Method and Description
ServiceCall<java.lang.Void>	addWord(AddWordOptions addWordOptions) Add a custom word.
ServiceCall<java.lang.Void>	addWords(AddWordsOptions addWordsOptions) Add custom words.
ServiceCall<VoiceModel>	createVoiceModel(CreateVoiceModelOptions createVoiceModelOptions) Create a custom model.
ServiceCall<java.lang.Void>	deleteVoiceModel(DeleteVoiceModelOptions deleteVoiceModelOptions) Delete a custom model.
ServiceCall<java.lang.Void>	deleteWord(DeleteWordOptions deleteWordOptions) Delete a custom word.
ServiceCall<Pronunciation>	getPronunciation(GetPronunciationOptions getPronunciationOptions) Get pronunciation.
ServiceCall<Voice>	getVoice(GetVoiceOptions getVoiceOptions) Get a voice.
ServiceCall<VoiceModel>	getVoiceModel(GetVoiceModelOptions getVoiceModelOptions) Get a custom model.
ServiceCall<Translation>	getWord(GetWordOptions getWordOptions) Get a custom word.
ServiceCall<VoiceModels>	listVoiceModels() List custom models.
ServiceCall<VoiceModels>	listVoiceModels(ListVoiceModelsOptions listVoiceModelsOptions) List custom models.
ServiceCall<Voices>	listVoices() List voices.
ServiceCall<Voices>	listVoices(ListVoicesOptions listVoicesOptions) List voices.
ServiceCall<Words>	listWords(ListWordsOptions listWordsOptions) List custom words.
ServiceCall<java.io.InputStream>	synthesize(SynthesizeOptions synthesizeOptions) Synthesize audio.
ServiceCall<java.lang.Void>	updateVoiceModel(UpdateVoiceModelOptions updateVoiceModelOptions) Update a custom model.

Methods inherited from class com.ibm.watson.developer_cloud.service.WatsonService

configureHttpClient, createServiceCall, getApiKey, getEndPoint, getName, getPassword, getToken, getUsername, isTokenManagerSet, processServiceCall, setApiKey, setAuthentication, setDefaultHeaders, setDefaultHeaders, setEndPoint, setIamCredentials, setSkipAuthentication, setUsernameAndPassword, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

TextToSpeech

public TextToSpeech()

Instantiates a new `TextToSpeech`.

TextToSpeech

public TextToSpeech(java.lang.String username,
            java.lang.String password)

Instantiates a new `TextToSpeech` with username and password.

Parameters:

username - the username

password - the password

TextToSpeech

public TextToSpeech(IamOptions iamOptions)

Instantiates a new `TextToSpeech` with IAM. Note that if the access token is specified in the iamOptions, you accept responsibility for managing the access token yourself. You must set a new access token before this one expires. Failing to do so will result in authentication errors after this token expires.

Parameters:

iamOptions - the options for authenticating through IAM

Method Detail

getVoice

public ServiceCall<Voice> getVoice(GetVoiceOptions getVoiceOptions)

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:

getVoiceOptions - the GetVoiceOptions containing the options for the call

Returns:

a ServiceCall with a response type of Voice

listVoices

public ServiceCall<Voices> listVoices(ListVoicesOptions listVoicesOptions)

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:

listVoicesOptions - the ListVoicesOptions containing the options for the call

Returns:

a ServiceCall with a response type of Voices

listVoices

public ServiceCall<Voices> listVoices()

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

Returns:

a ServiceCall with a response type of Voices

synthesize

public ServiceCall<java.io.InputStream> synthesize(SynthesizeOptions synthesizeOptions)

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:

synthesizeOptions - the SynthesizeOptions containing the options for the call

Returns:

a ServiceCall with a response type of InputStream

getPronunciation

public ServiceCall<Pronunciation> getPronunciation(GetPronunciationOptions getPronunciationOptions)

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:

getPronunciationOptions - the GetPronunciationOptions containing the options for the call

Returns:

a ServiceCall with a response type of Pronunciation

createVoiceModel

public ServiceCall<VoiceModel> createVoiceModel(CreateVoiceModelOptions createVoiceModelOptions)

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:

createVoiceModelOptions - the CreateVoiceModelOptions containing the options for the call

Returns:

a ServiceCall with a response type of VoiceModel

deleteVoiceModel

public ServiceCall<java.lang.Void> deleteVoiceModel(DeleteVoiceModelOptions deleteVoiceModelOptions)

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:

deleteVoiceModelOptions - the DeleteVoiceModelOptions containing the options for the call

Returns:

a ServiceCall with a response type of Void

getVoiceModel

public ServiceCall<VoiceModel> getVoiceModel(GetVoiceModelOptions getVoiceModelOptions)

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:

getVoiceModelOptions - the GetVoiceModelOptions containing the options for the call

Returns:

a ServiceCall with a response type of VoiceModel

listVoiceModels

public ServiceCall<VoiceModels> listVoiceModels(ListVoiceModelsOptions listVoiceModelsOptions)

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:

listVoiceModelsOptions - the ListVoiceModelsOptions containing the options for the call

Returns:

a ServiceCall with a response type of VoiceModels

listVoiceModels

public ServiceCall<VoiceModels> listVoiceModels()

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.

Returns:

a ServiceCall with a response type of VoiceModels

updateVoiceModel

public ServiceCall<java.lang.Void> updateVoiceModel(UpdateVoiceModelOptions updateVoiceModelOptions)

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:

updateVoiceModelOptions - the UpdateVoiceModelOptions containing the options for the call

Returns:

a ServiceCall with a response type of Void

addWord

public ServiceCall<java.lang.Void> addWord(AddWordOptions addWordOptions)

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:

addWordOptions - the AddWordOptions containing the options for the call

Returns:

a ServiceCall with a response type of Void

addWords

public ServiceCall<java.lang.Void> addWords(AddWordsOptions addWordsOptions)

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:

addWordsOptions - the AddWordsOptions containing the options for the call

Returns:

a ServiceCall with a response type of Void

deleteWord

public ServiceCall<java.lang.Void> deleteWord(DeleteWordOptions deleteWordOptions)

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

Parameters:

deleteWordOptions - the DeleteWordOptions containing the options for the call

Returns:

a ServiceCall with a response type of Void

getWord

public ServiceCall<Translation> getWord(GetWordOptions getWordOptions)

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:

getWordOptions - the GetWordOptions containing the options for the call

Returns:

a ServiceCall with a response type of Translation

listWords

public ServiceCall<Words> listWords(ListWordsOptions listWordsOptions)

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:

listWordsOptions - the ListWordsOptions containing the options for the call

Returns:

a ServiceCall with a response type of Words