> ## Documentation Index
> Fetch the complete documentation index at: https://plivo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Audio Output

> Play audio, text-to-speech, and DTMF tones during calls

This page covers the XML elements for audio output: converting text to speech, playing audio files, and sending DTMF tones.

***

## Speak

The `<Speak>` element converts text to speech and plays it to the caller. Use it for dynamic messages that can't be prerecorded.

### Basic Usage

```xml theme={null}
<Response>
    <Speak>Hello! Welcome to our service.</Speak>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.SpeakElement('Hello! Welcome to our service.'))
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
response.addSpeak('Hello! Welcome to our service.');
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

include Plivo::XML

response = Response.new
response.addSpeak('Hello! Welcome to our service.')
puts PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addSpeak('Hello! Welcome to our service.');
echo $response->toXML();
```

```java Java theme={null}
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Speak;

Response response = new Response()
    .children(new Speak("Hello! Welcome to our service."));
System.out.println(response.toXmlString());
```

```csharp .NET theme={null}
using Plivo.XML;

var response = new Response();
response.AddSpeak("Hello! Welcome to our service.");
Console.WriteLine(response.ToString());
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
    response := xml.ResponseElement{
        Contents: []interface{}{
            new(xml.SpeakElement).AddSpeak("Hello! Welcome to our service."),
        },
    }
    print(response.String())
}
```

### Speak Attributes

| Attribute | Type | Default | Description |
| - | - | - | - |
| `voice` | string | `WOMAN` | Voice tone. Allowed: `WOMAN`, `MAN` |
| `language` | string | `en-US` | Language for speech. See supported languages below |
| `loop` | integer | `1` | Number of times to repeat. `0` = infinite |

### Change Voice and Language

```xml theme={null}
<Response>
    <Speak voice="MAN" language="en-GB">
        Good day! This message uses a British male voice.
    </Speak>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.SpeakElement(
    'Good day! This message uses a British male voice.',
    voice='MAN',
    language='en-GB'
))
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
response.addSpeak('Good day! This message uses a British male voice.', {
    voice: 'MAN',
    language: 'en-GB'
});
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

include Plivo::XML

response = Response.new
response.addSpeak('Good day!', voice: 'MAN', language: 'en-GB')
puts PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addSpeak('Good day!', ['voice' => 'MAN', 'language' => 'en-GB']);
echo $response->toXML();
```

### Loop a Message

Play a message multiple times:

```xml theme={null}
<Response>
    <Speak loop="3">Please hold. Your call is important to us.</Speak>
</Response>
```

Set `loop="0"` to repeat indefinitely until the call ends:

```xml theme={null}
<Response>
    <Speak loop="0">Please wait while we connect you.</Speak>
</Response>
```

### Supported Languages

| Language | Code | Woman | Man |
| - | - | - | - |
| Danish | `da-DK` | Yes | No |
| Dutch | `nl-NL` | Yes | Yes |
| English (Australian) | `en-AU` | Yes | Yes |
| English (British) | `en-GB` | Yes | Yes |
| English (USA) | `en-US` | Yes | Yes |
| French | `fr-FR` | Yes | Yes |
| French (Canadian) | `fr-CA` | Yes | No |
| German | `de-DE` | Yes | Yes |
| Italian | `it-IT` | Yes | Yes |
| Polish | `pl-PL` | Yes | Yes |
| Portuguese | `pt-PT` | No | Yes |
| Portuguese (Brazilian) | `pt-BR` | Yes | Yes |
| Russian | `ru-RU` | Yes | No |
| Spanish | `es-ES` | Yes | Yes |
| Spanish (USA) | `es-US` | Yes | Yes |
| Swedish | `sv-SE` | Yes | No |

### SSML Support

Speech Synthesis Markup Language (SSML) provides fine-grained control over pronunciation, pitch, rate, and pauses. Use Polly voices for SSML support.

```xml theme={null}
<Response>
    <Speak voice="Polly.Joey" language="en-US">
        <prosody rate="medium">
            Hello and welcome to Plivo.
            <break time="500ms"/>
            The word <say-as interpret-as="spell-out">SSML</say-as>
            stands for Speech Synthesis Markup Language.
        </prosody>
    </Speak>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
speak = plivoxml.SpeakElement(
    content="The word",
    voice="Polly.Joey",
    language="en-US"
)
speak.add_say_as("read", interpret_as="characters")
speak.add_s("may be interpreted as either the present simple form")
speak.add_w("read", role="amazon:VB")
speak.add_s("or the past participle form")
speak.add_w("read", role="amazon:VBD")
response.add(speak)
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
const speakElem = response.addSpeak('The word', {
    voice: 'Polly.Joey',
    language: 'en-US'
});
speakElem.addSayAs('read', { 'interpret-as': 'characters' });
speakElem.addS('may be interpreted differently');
speakElem.addW('read', { role: 'amazon:VB' });
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

response = Plivo::XML::Response.new
speak_elem = response.addSpeak('The word', voice: 'Polly.Joey', language: 'en-US')
speak_elem.addSayAs('read', 'interpret-as' => 'characters')
speak_elem.addS('may be interpreted differently')
speak_elem.addW('read', 'role' => 'amazon:VB')
puts Plivo::XML::PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$speak_elem = $response->addSpeak('The word', [
    'language' => 'en-US',
    'voice' => 'Polly.Joey'
]);
$speak_elem->addSayAs('read', ['interpret-as' => 'characters']);
$speak_elem->addS('may be interpreted differently');
echo $response->toXML();
```

#### Common SSML Tags

| Tag | Description | Example |
| - | - | - |
| `<break>` | Add a pause | `<break time="500ms"/>` |
| `<say-as>` | Control pronunciation | `<say-as interpret-as="spell-out">ABC</say-as>` |
| `<prosody>` | Modify pitch, rate, volume | `<prosody rate="slow">Slowly</prosody>` |
| `<emphasis>` | Add emphasis | `<emphasis level="strong">Important</emphasis>` |
| `<p>` | Paragraph pause | `<p>First paragraph.</p>` |
| `<s>` | Sentence pause | `<s>First sentence.</s>` |

### Speak Nesting

`<Speak>` can be nested inside:

* `<GetDigits>` - Play message while collecting input
* `<GetInput>` - Play message while collecting speech/digits
* `<PreAnswer>` - Play message before answering

```xml theme={null}
<Response>
    <GetDigits action="/handle-input/" numDigits="1">
        <Speak>Press 1 for sales, press 2 for support.</Speak>
    </GetDigits>
</Response>
```

***

## Play

The `<Play>` element plays an audio file to the caller. Use it for pre-recorded messages, music, or sound effects.

### Basic Usage

```xml theme={null}
<Response>
    <Play>https://example.com/audio/welcome.mp3</Play>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PlayElement('https://example.com/audio/welcome.mp3'))
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
response.addPlay('https://example.com/audio/welcome.mp3');
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

include Plivo::XML

response = Response.new
response.addPlay('https://example.com/audio/welcome.mp3')
puts PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addPlay('https://example.com/audio/welcome.mp3');
echo $response->toXML();
```

```java Java theme={null}
import com.plivo.api.xml.Response;
import com.plivo.api.xml.Play;

Response response = new Response()
    .children(new Play("https://example.com/audio/welcome.mp3"));
System.out.println(response.toXmlString());
```

```csharp .NET theme={null}
using Plivo.XML;

var response = new Response();
response.AddPlay("https://example.com/audio/welcome.mp3");
Console.WriteLine(response.ToString());
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
    response := xml.ResponseElement{
        Contents: []interface{}{
            new(xml.PlayElement).SetContents("https://example.com/audio/welcome.mp3"),
        },
    }
    print(response.String())
}
```

### Play Attributes

| Attribute | Type | Default | Description |
| - | - | - | - |
| `loop` | integer | `1` | Number of times to play the audio. `0` = infinite loop |

### Loop Audio

Play hold music on repeat:

```xml theme={null}
<Response>
    <Play loop="0">https://example.com/audio/hold-music.mp3</Play>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PlayElement(
    'https://example.com/audio/hold-music.mp3',
    loop=0
))
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
response.addPlay('https://example.com/audio/hold-music.mp3', { loop: 0 });
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

include Plivo::XML

response = Response.new
response.addPlay('https://example.com/audio/hold-music.mp3', loop: 0)
puts PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addPlay('https://example.com/audio/hold-music.mp3', ['loop' => 0]);
echo $response->toXML();
```

### Supported Formats

| Format | Extension | Notes |
| - | - | - |
| MP3 | `.mp3` | Recommended for smaller file sizes |
| WAV | `.wav` | Highest quality, larger files |

**Requirements:**

* Audio must be served over HTTPS
* Maximum file size: 10 MB
* Recommended: 8kHz or 16kHz sample rate, mono

### Combine with Speak

```xml theme={null}
<Response>
    <Play>https://example.com/audio/intro-jingle.mp3</Play>
    <Speak>Welcome to Acme Corporation. How can we help you today?</Speak>
</Response>
```

### Play During IVR

Nest `<Play>` inside `<GetDigits>` to play audio while collecting input:

```xml theme={null}
<Response>
    <GetDigits action="/handle-input/" numDigits="1" timeout="10">
        <Play>https://example.com/audio/menu-options.mp3</Play>
    </GetDigits>
    <Speak>We didn't receive any input. Goodbye.</Speak>
</Response>
```

### Play Nesting

`<Play>` can be nested inside:

* `<GetDigits>` - Play while collecting digits
* `<GetInput>` - Play while collecting speech/digits
* `<PreAnswer>` - Play before answering the call

### Play Best Practices

1. **Use HTTPS** - Audio URLs must use HTTPS
2. **Optimize file size** - Compress audio for faster loading
3. **Host reliably** - Use a CDN for audio file hosting
4. **Test audio quality** - Ensure audio is clear at phone quality (8kHz)
5. **Provide fallback** - Use `<Speak>` as backup if audio fails to load

***

## DTMF

The `<DTMF>` element sends DTMF (Dual-Tone Multi-Frequency) tones on the current call. Use it to navigate IVR systems, enter PINs, or interact with telephony systems.

### Basic Usage

```xml theme={null}
<Response>
    <DTMF>1234</DTMF>
</Response>
```

```python Python theme={null}
from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DTMFElement('1234'))
print(response.to_string())
```

```javascript Node.js theme={null}
const plivo = require('plivo');

const response = plivo.Response();
response.addDTMF('1234');
console.log(response.toXML());
```

```ruby Ruby theme={null}
require 'plivo'

include Plivo::XML

response = Response.new
response.addDTMF('1234')
puts PlivoXML.new(response).to_xml
```

```php PHP theme={null}
<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addDTMF('1234');
echo $response->toXML();
```

```java Java theme={null}
import com.plivo.api.xml.*;

Response response = new Response()
    .children(new DTMF("1234"));
System.out.println(response.toXmlString());
```

```csharp .NET theme={null}
using Plivo.XML;

var response = new Response();
response.AddDTMF("1234");
Console.WriteLine(response.ToString());
```

```go Go theme={null}
package main

import "github.com/plivo/plivo-go/v7/xml"

func main() {
    response := xml.ResponseElement{
        Contents: []interface{}{
            new(xml.DTMFElement).SetContents("1234"),
        },
    }
    print(response.String())
}
```

### DTMF Attributes

| Attribute | Type | Default | Description |
| - | - | - | - |
| `async` | boolean | `true` | Send asynchronously and continue to next element |

### Allowed Characters

| Character | Description |
| - | - |
| `0-9` | Digit tones |
| `*` | Star key |
| `#` | Pound/hash key |
| `w` | Wait 0.5 seconds |
| `W` | Wait 1 second |

### With Pauses

Use `w` (0.5s) or `W` (1s) to add delays between tones:

```xml theme={null}
<Response>
    <DTMF>1ww2ww3ww4</DTMF>
</Response>
```

This sends 1, waits 1 second, sends 2, waits 1 second, etc.

### Navigate External IVR

When dialing an external number with an IVR:

```xml theme={null}
<Response>
    <Dial>
        <Number sendDigits="wwww1234#">+14155559999</Number>
    </Dial>
</Response>
```

This is typically done using the `sendDigits` attribute on `<Number>` rather than the `<DTMF>` element.

### Send During Call

Send tones during an active call:

```xml theme={null}
<Response>
    <Speak>Sending your confirmation code now.</Speak>
    <DTMF>5678</DTMF>
    <Speak>Code sent.</Speak>
</Response>
```

### Synchronous vs Asynchronous

**Async (default):** DTMF sends while next element starts

```xml theme={null}
<DTMF async="true">123</DTMF>
<Speak>Processing...</Speak>
```

**Sync:** Wait for DTMF to complete before continuing

```xml theme={null}
<DTMF async="false">123</DTMF>
<Speak>DTMF complete.</Speak>
```

### DTMF Use Cases

| Scenario | Example |
| - | - |
| Enter PIN | `<DTMF>1234#</DTMF>` |
| Navigate IVR menu | `<DTMF>1</DTMF>` |
| Enter extension | `<DTMF>wwww5678</DTMF>` |
| Star code | `<DTMF>*67</DTMF>` |

### Combined with Dial

When using with `<Dial>`, prefer `sendDigits` on the `<Number>` element:

```xml theme={null}
<Response>
    <Dial>
        <Number sendDigits="wwww123#">+14155551234</Number>
    </Dial>
</Response>
```

***

## Related

* [Input Collection](https://plivo.com/docs/voice/xml/input.md) - GetDigits, GetInput
* [Call Routing](https://plivo.com/docs/voice/xml/routing.md) - Dial, Redirect, Hangup, Wait
* [SSML Concepts](https://plivo.com/docs/voice/concepts/ssml.md) - Advanced speech control