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.

Installation

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

npm install --save playht

pnpm install --save playht

yarn add playht

Initializing the client

An API Key and User ID are required to initialize the client. If you don't yet have one, 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 initializing 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: 'PlayDialog',
});

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.

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.', {voiceEngine: "PlayDialog"});

// 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);

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.