***

id: 45a1ab11-3240-48a6-acb0-6a169f7f40a1
title: Playlist
keywords: >-
SignalWire, Realtime SDK, Node.js, audio playlist, media queue, play multiple
audio
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/v4/node/reference/voice/types#ringtonename

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

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

[voice-playlist]: /docs/server-sdk/v4/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

In this example, we create a playlist for playing the following items sequentially:

* A TTS message
* 1 second of silence
* 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

<ParamField path="params" type="object">
  Object containing the parameters of the constructor.
</ParamField>

<Indent>
  <ParamField path="volume" type="number" default="0">
    Default volume to apply to the media in the playlist, between -40dB and +40dB.
  </ParamField>
</Indent>

#### Example

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

## **Properties**

<ParamField path="media" type="NestedArray<Object>">
  The list of media items that have been added to this Playlist.
</ParamField>

<ParamField path="volume" type="number | undefined">
  The default volume for the audio in the playlist, between -40dB and +40dB.
</ParamField>

## **Methods**

### add

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

Adds the speecified media in series to the Playlist.

#### Parameters

<ParamField path="params" type="object" required>
  A media object. See [`Audio`][link-1], [`Ringtone`][link-2], [`Silence`][link-3], and [`TTS`][link-4].
</ParamField>

#### Returns

[`Playlist`][voice-playlist]

#### Example

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

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

const playlist = new Voice.Playlist()
  .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 }));

await call.play(playlist);
```

***

### Audio

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

An audio media.

#### Parameters

<ParamField path="params" type="object" required>
  Object containing the parameters of the method.
</ParamField>

<Indent>
  <ParamField path="url" type="string" required>
    URL of media to play.
  </ParamField>
</Indent>

#### Returns

`Object`

#### Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

const playlist = new Voice.Playlist()
  .add(Voice.Playlist.Audio({
    url: "https://cdn.signalwire.com/default-music/welcome.mp3",
  }));

await call.play(playlist);
```

***

### Ringtone

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

A ringtone media.

#### Parameters

<ParamField path="params" type="object" required>
  Object containing the parameters of the method.
</ParamField>

<Indent>
  <ParamField path="name" type="RingtoneName" required>
    Name of the ringtone to play. See [`RingtoneName`][types].
  </ParamField>

  <ParamField path="duration" type="number">
    How long to play ringtone, in seconds.
  </ParamField>
</Indent>

#### Returns

`Object`

#### Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

const playlist = new Voice.Playlist()
  .add(Voice.Playlist.Ringtone({
    name: "it",
    duration: 30,
  }));

await call.play(playlist);
```

***

### Silence

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

A silence interval.

#### Parameters

<ParamField path="params" type="object" required>
  Object containing the parameters of the method.
</ParamField>

<Indent>
  <ParamField path="duration" type="number" required>
    How long to play silence, in seconds.
  </ParamField>
</Indent>

#### Returns

`Object`

#### Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

// Use silence to create a pause between other media
const playlist = new Voice.Playlist()
  .add(Voice.Playlist.TTS({ text: "Please hold." }))
  .add(Voice.Playlist.Silence({ duration: 2 }))
  .add(Voice.Playlist.TTS({ text: "Connecting you now." }));

await call.play(playlist);
```

***

### TTS

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

A TTS media.

#### Parameters

<ParamField path="params" type="object" required>
  Object containing the parameters of the method.
</ParamField>

<Indent>
  <ParamField path="text" type="string" required>
    Text to play. SSML may be entered as a string wrapped in `<speak>` tags. See our [supported voices and languages][voice-and-languages] documentation for usage and supported tags.
  </ParamField>

  <ParamField path="language" type="string" default="&#x22;en-US&#x22;">
    Language of the text in `ISO 639-1` (language name) + `ISO 3166` (country code). Supported languages can be found [here][link-5].
  </ParamField>

  <ParamField path="gender" type="&#x22;female&#x22; | &#x22;male&#x22;" default="&#x22;female&#x22;">
    Gender of the voice.
  </ParamField>

  <ParamField path="voice" type="string">
    Voice to use (takes precedence over `gender`). Supported voices can be found [here][link-5].
  </ParamField>
</Indent>

#### Returns

`Object`

#### Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

const playlist = new Voice.Playlist()
  .add(Voice.Playlist.TTS({
    text: "Welcome to SignalWire!",
    gender: "male",
    language: "en-US",
  }));

await call.play(playlist);
```

##### SSML Example

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

const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });

const call = await client.voice.dialPhone({
  from: "+1xxxxxxxxxx",
  to: "+1yyyyyyyyyy",
  timeout: 30
});

const playlist = new Voice.Playlist()
  .add(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",
  }));

await call.play(playlist);
```