***

id: 2735c0c1-8778-4c45-9441-45aaa28a3be9
title: play
slug: /reference/play
description: 'Play file(s), ringtones, speech or silence.'
max-toc-depth: 3
----------------

[statuscallbacks]: #statuscallbacks

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

## **Properties**

<ParamField path="play" type="object" required={true} toc={true}>
  An object that accepts the following properties. Accepts either a single URL or multiple URLs. See [audio source](#audio-source) below.
</ParamField>

<Indent>
  <ParamField path="play.status_url" type="string" toc={true}>
    HTTP or HTTPS URL to deliver play status events. Learn more about [status callbacks][statuscallbacks].
  </ParamField>
</Indent>

## **Audio source**

The `play` object accepts one of the following properties to specify the audio source:

<Tabs>
  <Tab title="Single URL (url)">
    <ParamField path="play.url" type="string" required={true} toc={true}>
      A single [playable sound](#playable-sounds). Authentication can also be set in the url in the format of `username:password@url`.
    </ParamField>
  </Tab>

  <Tab title="Multiple URLs (urls)">
    <ParamField path="play.urls" type="string[]" required={true} toc={true}>
      An array of [playable sounds](#playable-sounds). Authentication can also be set in the url in the format of `username:password@url`.
    </ParamField>
  </Tab>
</Tabs>

## Playable sounds

**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. Authentication can also be set in the url in the format of `username:password@url`.

Example: `https://cdn.signalwire.com/swml/audio.mp3`

**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](#supported-ring-tones) 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

**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 properties](#properties). For the list of useable voices and languages,
refer to the [supported voices and languages](#supported-voices-and-languages) section below.

**Silence**

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

## 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](/docs/platform/voice/tts).

### 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**. |

## **StatusCallbacks**

A POST request will be sent to `status_url` with a JSON payload like the following:

<ParamField path="event_type" type="string" toc={true}>
  The type of event. Always `calling.call.play` for this method.
</ParamField>

<ParamField path="event_channel" type="string" toc={true}>
  The channel for the event, includes the SWML session ID.
</ParamField>

<ParamField path="timestamp" type="number" toc={true}>
  Unix timestamp (float) when the event was generated.
</ParamField>

<ParamField path="project_id" type="string" toc={true}>
  The project ID associated with the call.
</ParamField>

<ParamField path="space_id" type="string" toc={true}>
  The Space ID associated with the call.
</ParamField>

<ParamField path="params" type="object" toc={true}>
  An object containing playback-specific parameters.
</ParamField>

<Indent>
  <ParamField path="params.call_id" type="string" toc={true}>
    The call ID.
  </ParamField>

  <ParamField path="params.node_id" type="string" toc={true}>
    The node handling the call.
  </ParamField>

  <ParamField path="params.control_id" type="string" toc={true}>
    The control ID for this play operation.
  </ParamField>

  <ParamField path="params.state" type="string" toc={true}>
    The current playback state. **Valid values:** `playing`, `paused`, `finished`, `error`.
  </ParamField>
</Indent>

### Raw JSON example

```json
{
  "event_type": "calling.call.play",
  "event_channel": "swml:xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "timestamp": 1640000000.123,
  "project_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "space_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "params": {
    "call_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "node_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "control_id": "xxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "state": "finished"
  }
}
```

***

## Examples

### Playing a single URL

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - play:
            url: 'https://cdn.signalwire.com/swml/audio.mp3'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "play": {
              "url": "https://cdn.signalwire.com/swml/audio.mp3"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Playing multiple URLs

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - play:
            urls:
              - 'https://cdn.signalwire.com/swml/audio.mp3'
              - 'say: this is something to say'
              - 'silence: 3.0'
              - 'ring:10.0:us'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "play": {
              "urls": [
                "https://cdn.signalwire.com/swml/audio.mp3",
                "say: this is something to say",
                "silence: 3.0",
                "ring:10.0:us"
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Playing multiple URLs with volume adjusted

<CodeBlocks>
  <CodeBlock title="YAML">
    ```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'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```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"
              ]
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

### Specifying a voice to use for speaking

**Globally**

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - set:
            say_voice: gcloud.en-US-Neural2-A
        - play:
            url: 'say:Hi, do I sound different?'
        - play:
            url: 'say:I don''t, do I?'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "set": {
              "say_voice": "gcloud.en-US-Neural2-A"
            }
          },
          {
            "play": {
              "url": "say:Hi, do I sound different?"
            }
          },
          {
            "play": {
              "url": "say:I don't, do I?"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>

**For just one instance**

<CodeBlocks>
  <CodeBlock title="YAML">
    ```yaml
    version: 1.0.0
    sections:
      main:
        - play:
            url: 'say:Hi, do I sound different?'
            say_voice: gcloud.en-US-Neural2-A
        - play:
            url: 'say:I was down with the flu'
    ```
  </CodeBlock>

  <CodeBlock title="JSON">
    ```json
    {
      "version": "1.0.0",
      "sections": {
        "main": [
          {
            "play": {
              "url": "say:Hi, do I sound different?",
              "say_voice": "gcloud.en-US-Neural2-A"
            }
          },
          {
            "play": {
              "url": "say:I was down with the flu"
            }
          }
        ]
      }
    }
    ```
  </CodeBlock>
</CodeBlocks>