talkify-tts-api v1.1.0

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:

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.

Talkify(options)

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:

import Talkify from 'talkify-tts-api'

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

Or in CommonJS:

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

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

Available methods

talkify.speech(text[, options])

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.

talkify.availableVoices([language])

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.

talkify.detectLanguage(text)

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)