play

Play file(s), ringtones, speech or silence.

Parameters

The play method expects the following parameters:

Name	Type	Required?	Description
play	string | string[] | play_params object	Required	Either a playable sound, an array of playable sounds, or the play params object

Playable sounds

1. Audio file from a URL
   To play an audio file from the web, simply list that audio's URL. Specified audio file should be accessible with an HTTP GET request. HTTP and HTTPS URLs are supported. For example: https://cdn.signalwire.com/swml/audio.mp3

2. Ring
   To play the standard ringtone of a certain country, use ring:[duration:]<country code>.

   The total duration can be specified in seconds as an optional second parameter. When left unspecified, it will ring just once. The country code must be specified. It has values like us for United States, it for Italy. For the list of available country codes, refer to the supported ringtones section below. For example:

   ring:us - ring with the US ringtone once
   ring:3.2:uk - ring with the UK ringtone for 3.2 seconds

3. Speak using a TTS
   To speak using a TTS, use say:<text to speak>. When using say, you can optionally set say_voice, say_language and say_gender in the play or prompt params params. For the list of useable voices and languages, refer to the supported voices and languages section below.

4. Silence
   To be silent for a certain duration, use silence:<duration>. The duration is in seconds.

play params

Name	Type	Required?	Default	Description
urls (or url)	string | string[]	Required		Either a playable sound, or an array of playable sounds
volume	number	Optional	0	Volume gain to apply to played URLs. Allowed values from -40.0 to 40.0.
say_voice	string	Optional	Polly.Salli	Voice to use with say: for text to speech.
say_language	string	Optional	en-US	Language to use with say: for text to speech.
say_gender	string	Optional	female	Gender to use with say: for text to speech.

Variables

Read by the method:

• say_voice: (in) - Optional voice to use for text to speech.
• say_language: (in) - Optional language to use for text to speech.
• say_gender: (in) - Optional gender to use for text to speech.

Possible Values for Voice, Language and Ringtone

Supported Voices and Languages

To learn more about the supported voices and languages, please visit the Supported Voices and Languages Documentation.

Supported Ring tones

Parameter
urls.ring	Available values are the following ISO 3166-1 alpha-2 country codes: at, au, bg, br, be, ch, cl, cn, cz, de, dk, ee, es, fi, fr, gr, hu, il, in, it, lt, jp, mx, my, nl, no, nz, ph, pl, pt, ru, se, sg, th, uk, us, us-old, tw, ve, za.

Examples

Playing a single URL

YAML

version: 1.0.0
sections:
  main:
    - play: https://cdn.signalwire.com/swml/audio.mp3

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": "https://cdn.signalwire.com/swml/audio.mp3"
      }
    ]
  }
}

or

YAML

version: 1.0.0
sections:
  main:
    - play:
        url: https://cdn.signalwire.com/swml/audio.mp3

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": {
          "url": "https://cdn.signalwire.com/swml/audio.mp3"
        }
      }
    ]
  }
}

Playing multiple URLs

YAML

version: 1.0.0
sections:
  main:
    - play:
        - https://cdn.signalwire.com/swml/audio.mp3
        - "say: this is something to say"
        - "silence: 3.0"
        - "ring:10.0:us"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": [
          "https://cdn.signalwire.com/swml/audio.mp3",
          "say: this is something to say",
          "silence: 3.0",
          "ring:10.0:us"
        ]
      }
    ]
  }
}

Playing multiple URLs with volume adjusted

YAML

version: 1.0.0
sections:
  main:
    - play:
        volume: 20
        urls:
          - https://cdn.signalwire.com/swml/audio.mp3
          - say:this is something to say
          - silence:3.0
          - ring:10.0:us

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": {
          "volume": 20,
          "urls": [
            "https://cdn.signalwire.com/swml/audio.mp3",
            "say:this is something to say",
            "silence:3.0",
            "ring:10.0:us"
          ]
        }
      }
    ]
  }
}

Specifying a voice to use for speaking

Globally

YAML

version: 1.0.0
sections:
  main:
    - set:
        say_voice: "gcloud.en-US-Neural2-A"
    - play: "say:Hi, do I sound different?"
    - play: "say:I don't, do I?"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "set": {
          "say_voice": "gcloud.en-US-Neural2-A"
        }
      },
      {
        "play": "say:Hi, do I sound different?"
      },
      {
        "play": "say:I don't, do I?"
      }
    ]
  }
}

For just one instance

YAML

version: 1.0.0
sections:
  main:
    - play:
        url: "say:Hi, do I sound different?"
        say_voice: "gcloud.en-US-Neural2-A"
    - play: "say:I was down with the flu"

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "play": {
          "url": "say:Hi, do I sound different?",
          "say_voice": "gcloud.en-US-Neural2-A"
        }
      },
      {
        "play": "say:I was down with the flu"
      }
    ]
  }
}