Talkify TTS API


Library to generate text-to-speech audio through Talkify.net APIs.

Installation

This is a Node.js module available through the npm registry. Installation is done using the npm install command:

``bash
npm i talkify-tts-api --save
`

Features

- Low-effort text-to-speech generation using Talkify service
- Synthetized response as a readable stream for data manipulation or saving into a file
- Support for Speech Synthesis Markup Language (SSML) by default
- Fetch current available voices list from Talkify and their enabled features

API

This module exports a contructor function which takes an options object.

$3

Creates a new Talkify instance

#### Arguments

- options (Required) - A plain JavaScript object that contains the configuration options.

#### Options

- key (Required): A string that contains the API Key from Talkify, which can be created at https://manage.talkify.net.
- format: This will determine the output format generated by the Talkify service. Acceptable values: mp3 and wav. Default: mp3.
- fallbackLanguage: The default language to fallback to Talkify when the service is unable to detect the language automatically. It accepts a string with the language name or a Language object. Default: undefined.
- voice: The default voice to be used when synthetizing text. It accepts a string with the voice name, or a Voice object. Omit for automatic language detection. Default: undefined.
- rate: The rate of speech as an signed integer. Accepted range: -5 to 5. Default: 0.
- ssml: Defines if the text should be parsed as SSML (true) or plain text (false). Default: true.
- whisper: Use the whispering effect. Only applicable to selected voices. Default: false.
- soft: Use the softer speech effect. Only applicable to selected voices. Default: false.
- volume: Adjusts the base volume. Only applicable to selected voices. Accepted range: -10 to 10. Default: 0.
- wordBreak: Adds a break in milliseconds between words. Only applicable to selected voices. Accepted range: 0 to 1000. Default: 0.
- pitch: Controls the pitch of the spoken text. Accepted range: -10 to 10. Default: 0.

#### Return value

A Talkify instance.

#### Exceptions

Throws a TalkifyError exception if the required options are missing or if any of the other options has any invalid value or range.

#### Example

In TypeScript:

`js
import Talkify from 'talkify-tts-api'

const talkify = new Talkify({
key: 'YOUR_TALKIFY_API_KEY'
})
`

Or in CommonJS:

`js
const { Talkify } = require('talkify-tts-api')

const talkify = new Talkify({
key: 'YOUR_TALKIFY_API_KEY'
})
`

Available methods

$3

This method will synthetize a text-to-speech audio with the given text string or SSML XML content.

Important: When using SSML, the text input must be correct. All XML characters that are not part of the SSML syntax must be escaped or a Bad Request will be thrown.

#### Parameters

- text (Required): The text to be used for generating the TTS audio.
- options: An optional SpeechOptions object that will override the default options from the Talkify instance.

#### Return Value

A SpeechStream object will be returned, which is a Readable stream that can be used for piping into processing or writing into a file.

#### Exceptions

Throws a TalkifyError exception if any of the other options has any invalid value or range, or if the API request failed.

#### The SpeechOptions Object

- format: This will determine the output format generated by the Talkify service. Acceptable values: mp3 and wav.
- fallbackLanguage: The default language to fallback to Talkify when the service is unable to detect the language automatically. It accepts a string with the language name or a Language object.
- voice: The default voice to be used when synthetizing text. Omit for automatic language detection.
- rate: The rate of speech as an signed integer. Accepted range: -5 to 5.
- ssml: Defines if the text should be parsed as SSML (true) or plain text (false).
- whisper: Use the whispering effect. Only applicable to selected voices.
- soft: Use the softer speech effect. Only applicable to selected voices.
- volume: Adjusts the base volume. Only applicable to selected voices. Accepted range: -10 to 10.
- wordBreak: Adds a break in milliseconds between words. Only applicable to selected voices. Accepted range: 0 to 1000.
- pitch: Controls the pitch of the spoken text. Accepted range: -10 to 10.

$3

This method will fetch a list of the voices available at Talkify, with their own features. Optionally, it can filter voices by language.

#### Parameters

- language: The language to filter the voices from the list. It accepts a string with the language name or a Language object. Omit for showing all voices for all languages. Example: english. Default: null.

#### Return Value

An array of Voice objects will be returned.

#### Exceptions

Throws a TalkifyError exception if the API request failed.

#### The Voice Object

- culture: The culture. Example: en-US.
- name: Name of the voice, this is used for the voice parameter when calling the talkify.speech() method. Example: Zira.
- gender: The gender of the voice. Example: Female.
- language: The language of this voice. Example: English
- supportedFormats: A list of the supported formats that this voice can generate audio. Example: ['mp3', 'wav'].
- description: The voice description. Example: Zira (English - en-US).
- isStandard: If this voice belongs to the standard tier. Example: true.
- isPremium: If this voice belongs to the premium tier. Example: true.
- isExclusive: If this voice belongs to the exclusive tier. Example: true.
- isNeural: If this voice belongs to the neural voices tier. Example: true.
- canUseSpeechMarks: If this voice can use the speech marks feature. Example: true.
- canWhisper: If this voice can use the speech marks feature. Example: true.
- canUseWordBreak: If this voice can use the word break pause feature. Example: true.
- canSpeakSoftly: If this voice can use the softer speech feature. Example: true.
- canUseVolume: If this voice can use the volume setting. Example: true.
- canUsePitch: If this voice can use the pitch setting. Example: true.

$3

This method will use the Talkify API to detect the language for the given text string.

#### Parameters

- text (Required): The string that will be used to detect the language. Example: May the Force be with you.

#### Return Value

A Language object will be returned. If a language can't be detected, undefined will be returned instead.

#### Exceptions

Throws a TalkifyError exception if the API request failed.

#### The Language Object

- name: Name of the language, this is used for the language parameter when calling the class methods. Example: English.
- cultures: An array with the cultures. Example: ['en-US', 'en-GB'].

Usage Examples

Examples can be found at the examples folder of this repository, it contains both TypeScript and CommonJS files for feature demonstration.

The API key can be placed inside a .env file, so it can be used within the examples. (Please refer to the examples/.env.example` file)