Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/thaispalmer/talkify-tts-api

Library to generate TTS directly from Talkify.net APIs
https://github.com/thaispalmer/talkify-tts-api

speech-synthesis text-to-speech tts tts-js

Last synced: 3 months ago
JSON representation

Library to generate TTS directly from Talkify.net APIs

Host: GitHub
URL: https://github.com/thaispalmer/talkify-tts-api
Owner: thaispalmer
License: mit
Created: 2022-01-24T16:31:40.000Z (almost 3 years ago)
Default Branch: master
Last Pushed: 2022-02-10T18:44:52.000Z (almost 3 years ago)
Last Synced: 2024-07-28T12:13:54.206Z (4 months ago)
Topics: speech-synthesis, text-to-speech, tts, tts-js
Language: TypeScript
Homepage:
Size: 46.9 KB
Stars: 1
Watchers: 1
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

# Talkify TTS API

[![npm](https://img.shields.io/npm/v/talkify-tts-api)](https://www.npmjs.com/package/talkify-tts-api)
[![Types](https://img.shields.io/npm/types/talkify-tts-api)](https://www.jsdocs.io/package/talkify-tts-api#package-index)
[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/talkify-tts-api)
[![License](https://img.shields.io/npm/l/talkify-tts-api)](https://github.com/thaispalmer/talkify-tts-api/blob/master/LICENSE)

Library to generate text-to-speech audio through [Talkify.net](https://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](https://nodejs.org/api/stream.html#readable-streams) for data manipulation or saving into a file
- Support for [Speech Synthesis Markup Language (SSML)](https://en.wikipedia.org/wiki/Speech_Synthesis_Markup_Language) 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](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](https://talkify.net/products/text-to-speech-voices). Default: `false`.
- `soft`: Use the softer speech effect. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-voices). Default: `false`.
- `volume`: Adjusts the base volume. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-voices). Accepted range: `-10` to `10`. Default: `0`.
- `wordBreak`: Adds a break in milliseconds between words. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-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

### `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](https://nodejs.org/api/stream.html#readable-streams) 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](https://talkify.net/products/text-to-speech-voices).
- `soft`: Use the softer speech effect. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-voices).
- `volume`: Adjusts the base volume. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-voices). Accepted range: `-10` to `10`.
- `wordBreak`: Adds a break in milliseconds between words. Only applicable to [selected voices](https://talkify.net/products/text-to-speech-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)