Voice

Playlist

View as Markdown

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.

Example

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

  • A TTS message
  • 1 second of silence
  • An mp3 file
1import { Voice } from "@signalwire/realtime-api";
2
3const playlist = new Voice.Playlist({ volume: 1.0 })
4  .add(
5    Voice.Playlist.TTS({
6      text: "Welcome to SignalWire!",
7    })
8  )
9  .add(Voice.Playlist.Silence({ duration: 1 }))
10  .add(
11    Voice.Playlist.Audio({
12      url: "https://cdn.signalwire.com/default-music/welcome.mp3",
13    })
14  );

Constructors

constructor

• new Playlist(params?)

Instantiates an empty Playlist. Use the add method to add media to this Playlist.

Parameters

params
object

Object containing the parameters of the constructor.

volume
numberDefaults to 0

Default volume to apply to the media in the playlist, between -40dB and +40dB.

Example

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

Properties

media
NestedArray<Object>

The list of media items that have been added to this Playlist.

volume
number | undefined

The default volume for the audio in the playlist, between -40dB and +40dB.

Methods

add

▸ add(params): Playlist

Adds the speecified media in series to the Playlist.

Parameters

params
objectRequired

A media object. See Audio, Ringtone, Silence, and TTS.

Returns

Playlist

Example

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

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11const playlist = new Voice.Playlist()
12  .add(
13    Voice.Playlist.Audio({
14      url: "https://cdn.signalwire.com/default-music/welcome.mp3",
15    })
16  )
17  .add(Voice.Playlist.Silence({ duration: 1 }))
18  .add(Voice.Playlist.Ringtone({ name: "it", duration: 5 }));
19
20await call.play(playlist);

Audio

▸ Static Audio(params): Object

An audio media.

Parameters

params
objectRequired

Object containing the parameters of the method.

url
stringRequired

URL of media to play.

Returns

Object

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11const playlist = new Voice.Playlist()
12  .add(Voice.Playlist.Audio({
13    url: "https://cdn.signalwire.com/default-music/welcome.mp3",
14  }));
15
16await call.play(playlist);

Ringtone

▸ Static Ringtone(params): Object

A ringtone media.

Parameters

params
objectRequired

Object containing the parameters of the method.

name
RingtoneNameRequired

Name of the ringtone to play. See RingtoneName.

duration
number

How long to play ringtone, in seconds.

Returns

Object

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11const playlist = new Voice.Playlist()
12  .add(Voice.Playlist.Ringtone({
13    name: "it",
14    duration: 30,
15  }));
16
17await call.play(playlist);

Silence

▸ Static Silence(params): Object

A silence interval.

Parameters

params
objectRequired

Object containing the parameters of the method.

duration
numberRequired

How long to play silence, in seconds.

Returns

Object

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11// Use silence to create a pause between other media
12const playlist = new Voice.Playlist()
13  .add(Voice.Playlist.TTS({ text: "Please hold." }))
14  .add(Voice.Playlist.Silence({ duration: 2 }))
15  .add(Voice.Playlist.TTS({ text: "Connecting you now." }));
16
17await call.play(playlist);

TTS

▸ Static TTS(params): Object

A TTS media.

Parameters

params
objectRequired

Object containing the parameters of the method.

text
stringRequired

Text to play. SSML may be entered as a string wrapped in <speak> tags. See our supported voices and languages documentation for usage and supported tags.

language
stringDefaults to "en-US"

Language of the text in ISO 639-1 (language name) + ISO 3166 (country code). Supported languages can be found here.

gender
"female" | "male"Defaults to "female"

Gender of the voice.

voice
string

Voice to use (takes precedence over gender). Supported voices can be found here.

Returns

Object

Example

1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11const playlist = new Voice.Playlist()
12  .add(Voice.Playlist.TTS({
13    text: "Welcome to SignalWire!",
14    gender: "male",
15    language: "en-US",
16  }));
17
18await call.play(playlist);
SSML Example
1import { SignalWire, Voice } from "@signalwire/realtime-api";
2
3const client = await SignalWire({ project: "your-project-id", token: "your-api-token" });
4
5const call = await client.voice.dialPhone({
6  from: "+1xxxxxxxxxx",
7  to: "+1yyyyyyyyyy",
8  timeout: 30
9});
10
11const playlist = new Voice.Playlist()
12  .add(Voice.Playlist.TTS({
13    text: `<speak>
14      Here are <say-as interpret-as="characters">SSML</say-as> samples.
15      I can pause <break time="3s"/>.
16      I can speak in cardinals. Your number is <say-as interpret-as="cardinal">10</say-as>.
17      Or I can speak in ordinals. You are <say-as interpret-as="ordinal">10</say-as> in line.
18      Or I can even speak in digits. The digits for ten are <say-as interpret-as="characters">10</say-as>.
19      I can also substitute phrases, like the <sub alias="World Wide Web Consortium">W3C</sub>.
20      Finally, I can speak a paragraph with two sentences.
21      <p><s>This is sentence one.</s><s>This is sentence two.</s></p>
22    </speak>`,
23    voice: "polly.Joey-Neural",
24  }));
25
26await call.play(playlist);