playht

AI Powered Voice Generation Platform

The PlayHT SDK provides easy to use methods to wrap the PlayHT API.

• Usage
  • Initializing the library
  • Generating Speech
  • Streaming Speech
  • Generating Speech Options
    • PlayDialog Voices (Recommended)
    • PlayHT 2.0 Voices
    • PlayHT 1.0 Voices
    • Standard Voices
  • Listing Available Voices
  • Instant Clone a Voice
    • Deleting a Cloned Voice
• SDK Examples
  • Example Server
  • ChatGPT Integration Example

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

Initializing the library

Before using the SDK, you need to initialize it with your credentials. You will need your API Secret Key and your User ID. If you have a PlayHT account, you can find both on the API access page. For more details, see the API documentation.

Important: Keep your API Secret Key confidential. Do not share it 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_USER_ID>',
});

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_USER_ID>',
  defaultVoiceId: 's3://voice-cloning-zero-shot/831bd330-85c6-4333-b2b4-10c476ea3491/original/manifest.json',
  defaultVoiceEngine: 'PlayDialog',
});

Generating Speech

To get a 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 a 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 an audio stream and write it into a file:

import * as PlayHT from 'playht';
import fs from 'fs';
import { pipeline } from 'node:stream/promises';

// 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
await pipeline(stream, 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';
import { pipeline } from 'node:stream/promises';

// 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');
await pipeline(stream, 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 the lowest possible latency, use the streaming API with the Play3.0-mini model. For the best overall quality and multi-turn dialogue capabilities, we recommend our flagship model, PlayDialog.

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 synthesizes the selected voice. PlayHT API supports different types of models: PlayDialog, Play3.0-mini, PlayHT2.0, PlayHT2.0-turbo, PlayHT1.0 and Standard. For all available options, see the TypeScript type definitions in the code.

PlayDialog Voices (Recommended)

Our flagship conversational voice AI model, offering the best quality, multi-turn dialogue capabilities, multilingual support, and instant cloning. It's highly reliable and fast for streaming across various languages.

To stream using the PlayDialog model in English:

import * as PlayHT from 'playht';
import fs from 'fs';
import { pipeline } from 'node:stream/promises';

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

// Stream audio from text
const stream = await PlayHT.stream('Stream realistic voices that say what you want!', {
  voiceEngine: 'PlayDialog',
  voiceId: 's3://voice-cloning-zero-shot/831bd330-85c6-4333-b2b4-10c476ea3491/original/manifest.json',
  outputFormat: 'mp3',
});

// Pipe stream into file
await pipeline(stream, fileStream);

Here's an example using PlayDialog with an Arabic voice:

import * as PlayHT from 'playht';
import fs from 'fs';
import { pipeline } from 'node:stream/promises';

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

// Stream audio from text
const stream = await PlayHT.stream('مرحبا بالعالم', {
  voiceEngine: 'PlayDialog',
  voiceId: 's3://voice-cloning-zero-shot/mzC-mRcDq38LCRzodkM-Z/amira-arabic/manifest.json',
  outputFormat: 'mp3',
});

// Pipe stream into file
await pipeline(stream, fileStream);

Here's an example using PlayDialog with a Hindi voice:

import * as PlayHT from 'playht';
import fs from 'fs';
import { pipeline } from 'node:stream/promises';

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

// Stream audio from text
const stream = await PlayHT.stream('नमस्ते दुनिया', {
  voiceEngine: 'PlayDialog',
  voiceId: 's3://voice-cloning-zero-shot/831bd330-85c6-4333-b2b4-10c476ea3491/original/manifest.json',
  outputFormat: 'mp3',
});

// Pipe stream into file
await pipeline(stream, fileStream);

PlayHT 2.0 Voices

Our newest conversational voice AI model with added emotion direction and instant cloning. Compatible with PlayHT2.0-turbo. 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,
  emotion: 'male_fearful',
  styleGuidance: 20,
});

// 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';
import { pipeline } from 'node:stream/promises';

// 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',
  emotion: 'female_happy',
  styleGuidance: 10,
});

// Pipe stream into file
await pipeline(stream, 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

Ideal for multilingual text-to-speech, changing pitch, adding pauses, and using Speech Synthesis Markup Language (SSML). These voices offer reliable output and support over 100 languages.

Here's an example using a 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';
import { pipeline } from 'node:stream/promises';

// 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,
});
await pipeline(stream, fileStream);

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

import * as PlayHT from 'playht';
import fs from 'fs';
import { pipeline } from 'node:stream/promises';

// 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,
});
await pipeline(stream, 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.

SDK Examples

This repository contains an implementation example for the API and an example of integrating with ChatGPT API.

To authenticate requests for the examples, you need to generate an API Secret Key and get your User ID. If you already have a PlayHT account, navigate to the API access page. For more details see the API documentation.

Before running the examples, build the SDK:

cd packages/playht
yarn install
yarn build

Example Server

Create a new .env file in the packages/sdk-example folder by copying the .env.example file provided. Then edit the file with your credentials.

To run it locally:

cd packages/sdk-example
yarn
yarn install:all
yarn start

Navigate to http://localhost:3000/ to see the example server.

ChatGPT Integration Example

Create a new .env file in the packages/gpt-example/server folder by copying the .env.example file provided. Then edit the file with your credentials. This example requires your OpenAI credentials too, the example .env file for details.

To run it locally:

cd packages/gpt-example
yarn
yarn install:all
yarn start

See the full ChatGPT Integration Example documentation.