PlayHT Node.js SDK is an open source library for creating audio from text using the PlayHT API. You can access the repository on GitHub here.

If you want to see complete examples of the SDK usage, see the realtime streaming examples here, or the async example here.

Usage

This module is distributed via npm and should be installed as one of your project's dependencies:

npm install --save playht

or for installation with yarn package manager:

yarn add playht

Initialising the library

Before using the SDK, you need to initialise the library with your credentials. You will need your API Secret Key and your User ID. If you already have a PlayHT account, navigate to the API access page. For more details see the API documentation.

Important: Keep your API Secret Key confidential. Do not share it with anyone or include it in publicly accessible code repositories.

Import methods from the library and call init() with your credentials to set up the SDK:

import * as PlayHT from 'playht';

PlayHT.init({
  apiKey: '<YOUR API KEY>',
  userId: '<YOUR API KEY>',
});

Note: All the examples below require that you call the init() method with your credentials first.

When initialising the library, you can also set a default voice and default voice engine to be used for any subsequent speech generation methods when a voice is not defined:

import * as PlayHT from 'playht';

PlayHT.init({
  apiKey: '<YOUR API KEY>',
  userId: '<YOUR API KEY>',
  defaultVoiceId: 's3://peregrine-voices/oliver_narrative2_parrot_saad/manifest.json',
  defaultVoiceEngine: 'PlayHT2.0',
});

Generating Speech

To get an URL with the audio for a generated file using the default settings, call the generate() method with the text you wish to convert.

import * as PlayHT from 'playht';

// Generate audio from text
const generated = await PlayHT.generate('Computers can speak now!');

// Grab the generated file URL
const { audioUrl } = generated;

console.log('The url for the audio file is', audioUrl);

The output also contains a generationId field and an optional message field. generationId is a unique identifier for the generation request, which can be used for tracking and referencing the specific generation job. The optional message field gives additional information about the generation such as status or error messages.

For more speech generation options, see Generating Speech Options below.

Streaming Speech

The stream() method streams audio from text. It returns a readable stream where the audio bytes will flow to as soon as they're ready. For example, to use the default settings to convert text into a audio stream and write it into a file:

import * as PlayHT from 'playht';
import fs from 'fs';

// Create a file stream
const fileStream = fs.createWriteStream('hello-playht.mp3');

// Stream audio from text
const stream = await PlayHT.stream('This sounds very realistic.');

// Pipe stream into file
stream.pipe(fileStream);

The stream() method also allows you to stream audio from a text stream input. For example, to convert a text stream into an audio file using the default settings:

import * as PlayHT from 'playht';
import { Readable } from 'stream';
import fs from 'fs';

// Create a test stream
const textStream = new Readable({
  read() {
    this.push('You can stream');
    this.push('text right into');
    this.push('an audio stream!');
    this.push(null); // End of data
  },
});

// Stream audio from text
const stream = await PlayHT.stream(textStream);

// Create a file stream
const fileStream = fs.createWriteStream('hello-playht.mp3');
stream.pipe(fileStream);

For a full example of using the streaming speech from input stream API, see our ChatGPT Integration Example.

For more speech generation options, see Generating Speech Options.

Note: For lowest possible latency, use the streaming API with a PlayHT 2.0 voice.

Generating Speech Options

All text-to-speech methods above accept an optional options parameter. You can use it to generate audio with different voices, AI models, output file formats and much more.

The options available will depend on the AI model that synthesize the selected voice. PlayHT API supports 3 different types of models: 'PlayHT2.0', 'PlayHT1.0' and 'Standard'. For all available options, see the typescript type definitions in the code.

PlayHT 2.0 Voices

Our newest conversational voice AI model with added emotion direction and instant cloning. Compatible with PlayHT2.0-turbo, our fastest model for streaming. Supports english only.

To generate an audio file using a PlayHT 2.0 voice with emotion and other options:

import * as PlayHT from 'playht';

const text = 'Am I a conversational voice with options?';

// Generate audio from text
const generated = await PlayHT.generate(text, {
  voiceEngine: 'PlayHT2.0',
  voiceId: 's3://peregrine-voices/oliver_narrative2_parrot_saad/manifest.json',
  outputFormat: 'mp3',
  temperature: 1.5,
  quality: 'high',
  speed: 0.8,
});

// Grab the generated file URL
const { audioUrl } = generated;

console.log('The url for the audio file is', audioUrl);

To stream using the PlayHT2.0-turbo model:

import * as PlayHT from 'playht';
import fs from 'fs';

// Create a file stream
const fileStream = fs.createWriteStream('turbo-playht.mp3');

// Stream audio from text
const stream = await PlayHT.stream('Stream realistic voices that say what you want!', {
  voiceEngine: 'PlayHT2.0-turbo',
  voiceId: 's3://voice-cloning-zero-shot/d9ff78ba-d016-47f6-b0ef-dd630f59414e/female-cs/manifest.json',
  outputFormat: 'mp3',
});

// Pipe stream into file
stream.pipe(fileStream);

PlayHT 1.0 Voices

Lifelike voices ideal for expressive and conversational content. Supports english only.

To generate audio with a PlayHT 1.0 voice:

import * as PlayHT from 'playht';

const text = 'Options are never enough.';

// Generate audio from text
const generated = await PlayHT.generate(text, {
  voiceEngine: 'PlayHT1.0',
  voiceId: 'susan',
  outputFormat: 'wav',
  temperature: 0.5,
  quality: 'medium',
  seed: 11,
});

// Grab the generated file URL
const { audioUrl } = generated;

console.log('The url for the audio file is', audioUrl);

Standard Voices

For multi-lingual text-to speech generations, changing pitches, and adding pauses. Voices with reliable outputs and support for Speech Synthesis Markup Language (SSML). Supports 100+ languages.

And an example with standard voice in Spanish:

import * as PlayHT from 'playht';

const text = 'La inteligencia artificial puede hablar español.';

// Generate audio from text
const generated = await PlayHT.generate(text, {
  voiceEngine: 'Standard',
  voiceId: 'Mia',
  quality: 'low',
  speed: 1.2,
});

// Grab the generated file URL
const { audioUrl } = generated;

console.log('The url for the audio file is', audioUrl);

Listing Available Voices

To list all available voices in our platform, including voices you cloned, you can call the listVoices() method with no parameters:

import * as PlayHT from 'playht';

// Fetch all available voices
const voices = await PlayHT.listVoices();

// Output them to the console.
console.log(JSON.stringify(voices, null, 2));

The listVoices() method also takes in an optional parameter to filter the voices by different fields. To get all stock female PlayHT 2.0 voices:

import * as PlayHT from 'playht';

// Fetch stock female PlayHT 2.0 voices
const voices = await PlayHT.listVoices({
  gender: 'female',
  voiceEngine: ['PlayHT2.0'],
  isCloned: false,
});

// Output them to the console.
console.log(JSON.stringify(voices, null, 2));

Instant Clone a Voice

You can use the clone() method to create a cloned voice from audio data. The cloned voice is ready to be used straight away.

import * as PlayHT from 'playht';
import fs from 'fs';

// Load an audio file
const fileBlob = fs.readFileSync('voice-to-clone.mp3');

// Clone the voice
const clonedVoice = await PlayHT.clone('dolly', fileBlob, 'male');

// Display the cloned voice information in the console
console.log('Cloned voice info\n', JSON.stringify(clonedVoice, null, 2));

// Use the cloned voice straight away to generate an audio file
const fileStream = fs.createWriteStream('hello-dolly.mp3');
const stream = await PlayHT.stream('Cloned voices sound realistic too.', {
  voiceEngine: clonedVoice.voiceEngine,
  voiceId: clonedVoice.id,
});
stream.pipe(fileStream);

The clone() method can also take in an URL string as input:

import * as PlayHT from 'playht';
import fs from 'fs';

// Audio file url
const fileUrl = 'https://peregrine-samples.s3.amazonaws.com/peregrine-voice-cloning/Neil-DeGrasse-Tyson-sample.wav';

// Clone the voice
const clonedVoice = await PlayHT.clone('neil', fileUrl, 'male');

// Display the cloned voice information in the console
console.log('Cloned voice info\n', JSON.stringify(clonedVoice, null, 2));

// Use the cloned voice straight away to generate an audio file
const fileStream = fs.createWriteStream('hello-neil.mp3');
const stream = await PlayHT.stream('Cloned voices are pure science.', {
  voiceEngine: clonedVoice.voiceEngine,
  voiceId: clonedVoice.id,
});
stream.pipe(fileStream);

Deleting a Cloned Voice

Use the deleteClone() method to delete cloned voices.

import * as PlayHT from 'playht';

const cloneId = 's3://voice-cloning-zero-shot/abcdefgh-01d3-4613-asdf-9a8b7774dbc2/my-clone/manifest.json';

const message = await PlayHT.deleteClone(cloneId);

console.log('deleteClone result message is', message);

Keep in mind, this action cannot be undone.