# Node.js SDK

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](https://github.com/playht/playht-nodejs-sdk).

## Installation

This module is distributed via [npm](https://www.npmjs.com/) and [yarn](https://yarnpkg.com/) and should be installed as one of your project's dependencies:

```shell npm
npm install --save playht
```
```shell pnpm
pnpm install --save playht
```
```Text yarn
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](https://play.ht/studio/api-access). For more details [see the API documentation](https://docs.play.ht/docs/authentication).

***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:

```javascript
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:

```javascript
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.

```javascript
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:

```javascript
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:

```javascript
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);
```

<br />

## Listing Available Voices

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

```javascript
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:

```javascript
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.

```javascript
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:

```javascript
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.

```javascript
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.