***

id: 8e713e38-693b-4c01-8663-31707fbac3f5
title: Playlist
slug: /node/reference/voice/playlist
description: >-
Playlist reference for building media sequences with audio files, TTS,
ringtones, and silence. Chain multiple media items for playback during voice
calls.
max-toc-depth: 3
----------------

[link-1]: #audio

[link-2]: #ringtone

[link-3]: #silence

[link-4]: #tts

[link-5]: /docs/platform/voice/tts

[link]: #add

[types]: /docs/server-sdk/v3/node/reference/voice/types#ringtonename

[voice-and-languages]: /docs/platform/voice/tts

[voice-call]: /docs/server-sdk/v3/node/reference/voice/call/play

[voice-playlist]: /docs/server-sdk/v3/node/reference/voice/playlist

A Playlist object allows you to specify a series of media which should be played in sequence. You can then pass the playlist to the methods that support it, for example [Call.play][voice-call].

#### Example

Creates a playlist for playing, in sequence, a TTS message, 1 second of silence, and an mp3 file.

```js
import { Voice } from "@signalwire/realtime-api";

const playlist = new Voice.Playlist({ volume: 1.0 })
  .add(
    Voice.Playlist.TTS({
      text: "Welcome to SignalWire!",
    })
  )
  .add(Voice.Playlist.Silence({ duration: 1 }))
  .add(
    Voice.Playlist.Audio({
      url: "https://cdn.signalwire.com/default-music/welcome.mp3",
    })
  );
```

## Constructors

### constructor

• **new Playlist**(`params?`)

Instantiates an empty Playlist. Use the [`add`][link] method to add media to this Playlist.

#### Parameters

| Name             | Type     | Description                                                                                  |
| :--------------- | :------- | :------------------------------------------------------------------------------------------- |
| `params?`        | `Object` | -                                                                                            |
| `params.volume?` | `number` | Default volume to apply to the media in the playlist, between -40dB and +40dB. Default is 0. |

#### Example

```js
const playlist = new Voice.Playlist({ volume: 1.0 });
```

## Properties

### media

Get the list of media that have been added to this Playlist.

**Syntax:** `Playlist.media()`

**Returns:** `NestedArray<Object>`

***

### volume

Default volume for the audio in the playlist.

**Syntax:** `Playlist.volume()`

**Returns:** `undefined` | `number`

## Methods

### add

▸ **add**(`params`): [`Playlist`][voice-playlist]

Adds the speecified media in series to the Playlist.

#### Parameters

| Name     | Type   | Description                                                                                            |
| :------- | :----- | :----------------------------------------------------------------------------------------------------- |
| `params` | Object | A media object. See [`Audio`][link-1], [`Ringtone`][link-2], [`Silence`][link-3], and [`TTS`][link-4]. |

#### Returns

[`Playlist`][voice-playlist]

#### Example

A playlist to play some audio, then a short silence, and finally a ringtone.

```js
const playlist = new Voice.DeviceBuilder()
  .add(
    Voice.Playlist.Audio({
      url: "https://cdn.signalwire.com/default-music/welcome.mp3",
    })
  )
  .add(Voice.Playlist.Silence({ duration: 1 }))
  .add(Voice.Playlist.Ringtone({ name: "it", duration: 5 }));

call.play(playlist);
```

***

### Audio

▸ `Static` **Audio**(`params`): `Object`

An audio media.

#### Parameters

| Name         | Type     | Description           |
| :----------- | :------- | :-------------------- |
| `params`     | `object` | -                     |
| `params.url` | `string` | URL of media to play. |

#### Returns

`Object`

#### Example

```js
Voice.Playlist.Audio({
  url: "https://cdn.signalwire.com/default-music/welcome.mp3",
});
```

***

### Ringtone

▸ `Static` **Ringtone**(`params`): `Object`

A ringtone media.

#### Parameters

| Name               | Type                    | Description                            |
| :----------------- | :---------------------- | :------------------------------------- |
| `params`           | `object`                | -                                      |
| `params.duration?` | `number`                | How long to play ringtone, in seconds. |
| `params.name`      | [`RingtoneName`][types] | Name of the ringtone to play.          |

#### Returns

`Object`

#### Example

```js
Voice.Playlist.Ringtone({
  name: "it",
  duration: 30,
});
```

***

### Silence

▸ `Static` **Silence**(`params`): `Object`

A silence interval.

#### Parameters

| Name              | Type     | Description                           |
| :---------------- | :------- | :------------------------------------ |
| `params`          | `object` | -                                     |
| `params.duration` | `number` | How long to play silence, in seconds. |

#### Returns

`Object`

#### Example

```js
Voice.Playlist.Silence({
  duration: 2,
});
```

***

### TTS

▸ `Static` **TTS**(`params`): `Object`

A TTS media.

#### Parameters

| Name               | Type                   | Description                                                                                                                                                                              |
| :----------------- | :--------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `params`           | `object`               | -                                                                                                                                                                                        |
| `params.gender?`   | `'female'` \| `'male'` | Gender of the voice. Defaults to `female`.                                                                                                                                               |
| `params.language?` | `string`               | Language of the text in `ISO 639-1` (language name) + `ISO 3166` (country code). Defaults to `en-US`.<br />Supported languages can be found [here][link-5]                               |
| `params.text`      | `string`               | Text to play. SSML may be entered as a string wrapped in `<speak>` tags. <br />See our [supported voices and languages][voice-and-languages] documentation for usage and supported tags. |
| `params.voice?`    | `string`               | Voice to use (takes precedence on `gender`).<br />Supported voices can be found [here][link-5]                                                                                           |

#### Returns

`Object`

### Examples

```js
Voice.Playlist.TTS({
  text: "Welcome to SignalWire!",
  gender: "male",
  language: "en-US",
});
```

Using SSML:

```js
Voice.Playlist.TTS({
  text: `<speak>
      Here are <say-as interpret-as="characters">SSML</say-as> samples.
      I can pause <break time="3s"/>.
      I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
      Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.
      Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.
      I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.
      Finally, I can speak a paragraph with two sentences.
      <p><s>This is sentence one.</s><s>This is sentence two.</s></p>
      </speak>
      `,
  voice: "polly.Joey-Neural",
});
```