Options
All
  • Public
  • Public/Protected
  • All
Menu

Class TextToSpeechV1

The IBM Watson™ Text to Speech service provides APIs that use 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. interfaces

For speech synthesis, the service supports a synchronous HTTP Representational State Transfer (REST) interface and a WebSocket interface. Both interfaces support plain text and SSML input. SSML is an XML-based markup language that provides text annotation for speech-synthesis applications. The WebSocket interface also supports the SSML <mark> element and word timings.

The service offers a customization interface that you can use to define sounds-like or phonetic translations for words. A sounds-like translation consists of one or more words that, when combined, sound like the word. A phonetic translation is based on the SSML phoneme format for representing a word. You can specify a phonetic translation in standard International Phonetic Alphabet (IPA) representation or in the proprietary IBM Symbolic Phonetic Representation (SPR). The Arabic, Chinese, Dutch, Australian English, and Korean languages support only IPA.

Hierarchy

  • BaseService
    • TextToSpeechV1

Index

Namespaces

Constructors

Properties

Methods

Constructors

constructor

Properties

Static DEFAULT_SERVICE_NAME

DEFAULT_SERVICE_NAME: string = "text_to_speech"

Static DEFAULT_SERVICE_URL

DEFAULT_SERVICE_URL: string = "https://api.us-south.text-to-speech.watson.cloud.ibm.com"

Methods

addWord

  • Add a custom word.

    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.

    You can define sounds-like or phonetic translations for words. A sounds-like translation consists of one or more words that, when combined, sound like the word. 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 also:

    Parameters

    Name Type Attribute Description
    params AddWordParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.
    translation string 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. The Arabic, Chinese, Dutch, Australian English, and Korean languages support only IPA. A sounds-like is one or more words that, when combined, sound like the word.
    word string The word that is to be added or updated for the custom model.
    headers OutgoingHttpHeaders Optional
    partOfSpeech PartOfSpeech | string 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://cloud.ibm.com/docs/text-to-speech?topic=text-to-speech-rules#jaNotes).

    Returns Promise<Response<Empty>>

addWords

  • Add custom words.

    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.

    You can define sounds-like or phonetic translations for words. A sounds-like translation consists of one or more words that, when combined, sound like the word. 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 also:

    Parameters

    Name Type Attribute Description
    params AddWordsParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization 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 Word[] 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 model and the word's translation.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Empty>>

createCustomModel

  • Create a custom model.

    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.

    See also: Creating a custom model.

    Important voice updates

    The service's voices underwent significant change on 2 December 2020.

    • The Arabic, Chinese, Dutch, Australian English, and Korean voices are now neural instead of concatenative.
    • The ar-AR_OmarVoice voice is deprecated. Use ar-MS_OmarVoice voice instead.
    • The ar-AR language identifier cannot be used to create a custom model. Use the ar-MS identifier instead.
    • The standard concatenative voices for the following languages are now deprecated: Brazilian Portuguese, United Kingdom and United States English, French, German, Italian, Japanese, and Spanish (all dialects).
    • The features expressive SSML, voice transformation SSML, and use of the volume attribute of the <prosody> element are deprecated and are not supported with any of the service's neural voices.
    • All of the service's voices are now customizable and generally available (GA) for production use.

    The deprecated voices and features will continue to function for at least one year but might be removed at a future date. You are encouraged to migrate to the equivalent neural voices at your earliest convenience. For more information about all voice updates, see the 2 December 2020 service update in the release notes.

    Parameters

    Name Type Attribute Description
    params CreateCustomModelParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    name string The name of the new custom model.
    description string Optional A description of the new custom model. Specifying a description is recommended.
    headers OutgoingHttpHeaders Optional
    language Language | string Optional 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. Omit the parameter to use the the default language, `en-US`. **Note:** The `ar-AR` language identifier cannot be used to create a custom model. Use the `ar-MS` identifier instead.

    Returns Promise<Response<CustomModel>>

deleteCustomModel

  • Delete a custom model.

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

    See also: Deleting a custom model.

    Parameters

    Name Type Attribute Description
    params DeleteCustomModelParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Empty>>

deleteUserData

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

    Note: If you delete an instance of the service from the service console, all data associated with that service instance is automatically deleted. This includes all custom models and word/translation pairs, and all data related to speech synthesis requests.

    See also: Information security.

    Parameters

    Name Type Attribute Description
    params DeleteUserDataParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customerId string The customer ID for which all data is to be deleted.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Empty>>

deleteWord

  • Delete a custom word.

    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.

    See also: Deleting a word from a custom model.

    Parameters

    Name Type Attribute Description
    params DeleteWordParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization 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 string The word that is to be deleted from the custom model.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Empty>>

getAuthenticator

  • getAuthenticator(): any

  • Get the instance of the authenticator set on the service.

    Returns any

getCustomModel

  • Get a custom model.

    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 as defined in the model. To see just the metadata for a model, use the List custom models method.

    See also: Querying a custom model.

    Parameters

    Name Type Attribute Description
    params GetCustomModelParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<CustomModel>>

getPronunciation

  • 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 model to see the translation for that model.

    See also: Querying a word from a language.

    Important voice updates

    The service's voices underwent significant change on 2 December 2020.

    • The Arabic, Chinese, Dutch, Australian English, and Korean voices are now neural instead of concatenative.
    • The ar-AR_OmarVoice voice is deprecated. Use ar-MS_OmarVoice voice instead.
    • The ar-AR language identifier cannot be used to create a custom model. Use the ar-MS identifier instead.
    • The standard concatenative voices for the following languages are now deprecated: Brazilian Portuguese, United Kingdom and United States English, French, German, Italian, Japanese, and Spanish (all dialects).
    • The features expressive SSML, voice transformation SSML, and use of the volume attribute of the <prosody> element are deprecated and are not supported with any of the service's neural voices.
    • All of the service's voices are now customizable and generally available (GA) for production use.

    The deprecated voices and features will continue to function for at least one year but might be removed at a future date. You are encouraged to migrate to the equivalent neural voices at your earliest convenience. For more information about all voice updates, see the 2 December 2020 service update in the release notes.

    Parameters

    Name Type Attribute Description
    params GetPronunciationParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    text string The word for which the pronunciation is requested.
    customizationId string Optional The customization 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 customization.
    format Format | string Optional The phoneme format 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.
    headers OutgoingHttpHeaders Optional
    voice Voice | string Optional 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. For more information about specifying a voice, see **Important voice updates** in the method description.

    Returns Promise<Response<Pronunciation>>

getVoice

  • 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 a custom model that is defined for the language of the specified voice. To list information about all available voices, use the List voices method.

    See also: Listing a specific voice.

    Important voice updates

    The service's voices underwent significant change on 2 December 2020.

    • The Arabic, Chinese, Dutch, Australian English, and Korean voices are now neural instead of concatenative.
    • The ar-AR_OmarVoice voice is deprecated. Use ar-MS_OmarVoice voice instead.
    • The ar-AR language identifier cannot be used to create a custom model. Use the ar-MS identifier instead.
    • The standard concatenative voices for the following languages are now deprecated: Brazilian Portuguese, United Kingdom and United States English, French, German, Italian, Japanese, and Spanish (all dialects).
    • The features expressive SSML, voice transformation SSML, and use of the volume attribute of the <prosody> element are deprecated and are not supported with any of the service's neural voices.
    • All of the service's voices are now customizable and generally available (GA) for production use.

    The deprecated voices and features will continue to function for at least one year but might be removed at a future date. You are encouraged to migrate to the equivalent neural voices at your earliest convenience. For more information about all voice updates, see the 2 December 2020 service update in the release notes.

    Parameters

    Name Type Attribute Description
    params GetVoiceParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    voice Voice | string The voice for which information is to be returned. For more information about specifying a voice, see **Important voice updates** in the method description.
    customizationId string Optional The customization 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 customization.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Voice>>

getWord

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

    See also: Querying a single word from a custom model.

    Parameters

    Name Type Attribute Description
    params GetWordParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization 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 string The word that is to be queried from the custom model.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Translation>>

listCustomModels

  • List custom models.

    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 in addition to the metadata for a specific custom 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.

    See also: Querying all custom models.

    Parameters

    Name Type Attribute Description
    params ListCustomModelsParams Optional

    Properties

    Name Type Attributes Description
    headers OutgoingHttpHeaders Optional
    language Language | string Optional The language for which custom models that are owned by the requesting credentials are to be returned. Omit the parameter to see all custom models that are owned by the requester.

    Returns Promise<Response<CustomModels>>

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. 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 the Get a voice method.

    See also: Listing all available voices.

    Parameters

    Name Type Attribute Description
    params ListVoicesParams Optional

    Properties

    Name Type Attributes Description
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Voices>>

listWords

  • List custom words.

    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.

    See also: Querying all words from a custom model.

    Parameters

    Name Type Attribute Description
    params ListWordsParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.
    headers OutgoingHttpHeaders Optional

    Returns Promise<Response<Words>>

setEnableGzipCompression

  • setEnableGzipCompression(setting: boolean): void

  • Turn request body compression on or off.

    Parameters

    Name Type Attribute Description
    setting boolean

    Will turn it on if 'true', off if 'false'.

    Returns void

setServiceUrl

  • setServiceUrl(url: string): void

  • Set the service URL to send requests to.

    Parameters

    Name Type Attribute Description
    url string

    The base URL for the service.

    Returns void

synthesize

  • Synthesize audio.

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

    The method accepts a maximum of 5 KB of input text in the body of the request, and 8 KB for the URL and headers. The 5 KB limit includes any SSML tags that you specify. The service returns the synthesized audio stream as an array of bytes.

    See also: The HTTP interface.

    Audio formats (accept types)

    The service can return audio in the following formats (MIME types).

    • Where indicated, you can optionally specify the sampling rate (rate) of the audio. You must specify a sampling rate for the audio/l16 and audio/mulaw formats. A specified sampling rate must lie in the range of 8 kHz to 192 kHz. Some formats restrict the sampling rate to certain values, as noted.
    • For the audio/l16 format, you can optionally specify the endianness (endianness) of the audio: endianness=big-endian or endianness=little-endian.

    Use the Accept header or the accept parameter to specify the requested format of the response audio. If you omit an audio format altogether, the service returns the audio in Ogg format with the Opus codec (audio/ogg;codecs=opus). The service always returns single-channel audio.

    • audio/basic - The service returns audio with a sampling rate of 8000 Hz.
    • audio/flac - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/l16 - You must specify the rate of the audio. You can optionally specify the endianness of the audio. The default endianness is little-endian.
    • audio/mp3 - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/mpeg - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/mulaw - You must specify the rate of the audio.
    • audio/ogg - The service returns the audio in the vorbis codec. You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/ogg;codecs=opus - You can optionally specify the rate of the audio. Only the following values are valid sampling rates: 48000, 24000, 16000, 12000, or 8000. If you specify a value other than one of these, the service returns an error. The default sampling rate is 48,000 Hz.
    • audio/ogg;codecs=vorbis - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/wav - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.
    • audio/webm - The service returns the audio in the opus codec. The service returns audio with a sampling rate of 48,000 Hz.
    • audio/webm;codecs=opus - The service returns audio with a sampling rate of 48,000 Hz.
    • audio/webm;codecs=vorbis - You can optionally specify the rate of the audio. The default sampling rate is 22,050 Hz.

    For more information about specifying an audio format, including additional details about some of the formats, see Audio formats.

    Important voice updates

    The service's voices underwent significant change on 2 December 2020.

    • The Arabic, Chinese, Dutch, Australian English, and Korean voices are now neural instead of concatenative.
    • The ar-AR_OmarVoice voice is deprecated. Use ar-MS_OmarVoice voice instead.
    • The ar-AR language identifier cannot be used to create a custom model. Use the ar-MS identifier instead.
    • The standard concatenative voices for the following languages are now deprecated: Brazilian Portuguese, United Kingdom and United States English, French, German, Italian, Japanese, and Spanish (all dialects).
    • The features expressive SSML, voice transformation SSML, and use of the volume attribute of the <prosody> element are deprecated and are not supported with any of the service's neural voices.
    • All of the service's voices are now customizable and generally available (GA) for production use.

    The deprecated voices and features will continue to function for at least one year but might be removed at a future date. You are encouraged to migrate to the equivalent neural voices at your earliest convenience. For more information about all voice updates, see the 2 December 2020 service update in the release notes.

    Warning messages

    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

    Name Type Attribute Description
    params SynthesizeParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    text string The text to synthesize.
    accept Accept | string Optional The requested format (MIME type) of the audio. You can use the `Accept` header or the `accept` parameter to specify the audio format. For more information about specifying an audio format, see **Audio formats (accept types)** in the method description.
    customizationId string Optional The customization 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 customization.
    headers OutgoingHttpHeaders Optional
    voice Voice | string Optional The voice to use for synthesis. For more information about specifying a voice, see **Important voice updates** in the method description.

    Returns Promise<Response<ReadableStream | Buffer>>

updateCustomModel

  • Update a custom model.

    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.

    You can define sounds-like or phonetic translations for words. A sounds-like translation consists of one or more words that, when combined, sound like the word. 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 also:

    Parameters

    Name Type Attribute Description
    params UpdateCustomModelParams

    The parameters to send to the service.

    Properties

    Name Type Attributes Description
    customizationId string The customization ID (GUID) of the custom model. You must make the request with credentials for the instance of the service that owns the custom model.
    description string Optional A new description for the custom model.
    headers OutgoingHttpHeaders Optional
    name string Optional A new name for the custom model.
    words Word[] Optional 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.

    Returns Promise<Response<Empty>>

Generated using TypeDoc