Audio Streaming

The <Stream> element streams raw audio from active calls over a WebSocket connection in near real-time. Use it for real-time speech processing, transcription, or AI voice applications.

Basic Usage

<Response>
    <Stream>wss://yourserver.example.com/audiostream</Stream>
</Response>

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.StreamElement('wss://yourserver.example.com/audiostream'))
print(response.to_string())

const plivo = require('plivo');

const response = plivo.Response();
response.addStream('wss://yourserver.example.com/audiostream');
console.log(response.toXML());

require 'plivo'

include Plivo::XML

response = Response.new
response.addStream('wss://yourserver.example.com/audiostream')
puts PlivoXML.new(response).to_xml

<?php
require 'vendor/autoload.php';
use Plivo\XML\Response;

$response = new Response();
$response->addStream('wss://yourserver.example.com/audiostream');
echo $response->toXML();

import com.plivo.api.xml.*;

Response response = new Response()
    .children(new Stream("wss://yourserver.example.com/audiostream"));
System.out.println(response.toXmlString());

using Plivo.XML;

var response = new Response();
var stream = new Stream("wss://yourserver.example.com/audiostream", new Dictionary<string, string>() {
    {"bidirectional", "false"},
    {"audioTrack", "both"}
});
Console.WriteLine(response.ToString());

package main

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

func main() {
    response := xml.ResponseElement{
        Contents: []interface{}{
            new(xml.StreamElement).SetContents("wss://yourserver.example.com/audiostream"),
        },
    }
    print(response.String())
}

Attributes

Attribute	Type	Default	Description
`bidirectional`	boolean	`false`	Enable two-way audio (read/write)
`audioTrack`	string	`inbound`	Which audio to stream: `inbound`, `outbound`, `both`
`streamTimeout`	integer	`86400`	Max stream duration in seconds
`contentType`	string	`audio/x-l16;rate=8000`	Audio codec and sample rate
`keepCallAlive`	boolean	`false`	Continue call only after stream ends
`extraHeaders`	string	-	Custom key-value pairs for WebSocket
`statusCallbackUrl`	URL	-	URL for stream status events
`statusCallbackMethod`	string	`POST`	HTTP method for callback
`noiseCancellation`	string	`"false"`	Enable noise cancellation: `"true"` or `"false"`
`noiseCancellationLevel`	integer	`85`	Noise reduction intensity (`60`–`100`). Only applies when `noiseCancellation` is `"true"`

Audio Formats

Content Type	Description
`audio/x-l16;rate=8000`	Linear PCM, 8kHz (default)
`audio/x-l16;rate=16000`	Linear PCM, 16kHz
`audio/x-mulaw;rate=8000`	G.711 mu-law, 8kHz

Bidirectional Streaming

Enable two-way audio for voice AI applications:

<Response>
    <Stream bidirectional="true" keepCallAlive="true">
        wss://ai.example.com/voice-agent
    </Stream>
</Response>

When bidirectional="true", your WebSocket server can send audio back:

{
    "event": "playAudio",
    "media": {
        "contentType": "audio/x-l16",
        "sampleRate": "8000",
        "payload": "<base64-encoded-audio>"
    }
}

When bidirectional is true, audioTrack cannot be outbound or both.

Stream Both Directions

Capture audio from both parties:

<Response>
    <Stream audioTrack="both" streamTimeout="3600">
        wss://transcription.example.com/stream
    </Stream>
    <Speak>This call is being transcribed for quality purposes.</Speak>
</Response>

Status Callbacks

Monitor stream connection status:

<Response>
    <Stream
        statusCallbackUrl="https://example.com/stream-status/"
        statusCallbackMethod="POST">
        wss://yourserver.example.com/audiostream
    </Stream>
</Response>

Callback Events

Notifications sent when:

Audio stream is connected
Audio stream is stopped (intentionally or timeout)
Audio stream failed or disconnected

Callback Parameters

Parameter	Description
`bidirectional`	Whether stream is bidirectional
`audioTrack`	Which audio tracks are streamed
`streamTimeout`	Max stream duration
`contentType`	Audio codec used
`extraHeaders`	Custom headers sent
`keepCallAlive`	Whether call waits for stream

Custom Headers

Pass metadata to your WebSocket server:

<Response>
    <Stream extraHeaders="userId=12345,sessionId=abc123">
        wss://yourserver.example.com/audiostream
    </Stream>
</Response>

Constraints:

Max length: 512 bytes
Allowed characters: [A-Z], [a-z], [0-9]

Keep Call Alive

Wait for stream to end before continuing:

<Response>
    <Stream keepCallAlive="true">
        wss://ai.example.com/conversation
    </Stream>
    <Speak>Thank you for using our AI assistant.</Speak>
</Response>

When keepCallAlive="true":

Stream element runs exclusively
Subsequent XML executes only after stream disconnects

Noise Cancellation

Filter out background noise in real-time to improve voice clarity and transcription accuracy for voice agent applications in noisy environments.

<Response>
    <Stream bidirectional="true"
            keepCallAlive="true"
            noiseCancellation="true"
            noiseCancellationLevel="85">
        wss://ai.example.com/voice-agent
    </Stream>
</Response>

Choosing a cancellation level:

Level Range	Environment	Notes
`60`–`70`	Quiet (home, office)	Light filtering, preserves voice detail
`70`–`85`	Moderate noise	Good balance for most use cases (default: `85`)
`85`–`100`	Heavy noise (traffic, crowds)	Aggressive filtering, may introduce minor artifacts

Start with the default value of 85. Increase toward 100 for heavy background noise. Decrease toward 60 if you notice audio artifacts or voice distortion.

Use Cases

Scenario	Configuration
Real-time transcription	`audioTrack="both"`, `contentType="audio/x-l16;rate=16000"`
Voice AI agent	`bidirectional="true"`, `keepCallAlive="true"`
Voice AI in noisy environments	`bidirectional="true"`, `keepCallAlive="true"`, `noiseCancellation="true"`
Call monitoring	`audioTrack="inbound"`
Quality analysis	`audioTrack="both"`

WebSocket Events

Your WebSocket server receives:

Event	Description
Connection	Initial metadata about the stream and call
Media	Base64-encoded audio chunks with contentType, sampleRate, payload
Stop	Notification when stream ends

For detailed event protocol, see Stream Event Protocol.

Audio Streaming Guide - Complete audio streaming documentation
Stream Event Protocol - WebSocket message reference
Audio Streams API - Control streams via API

Concepts

Integration Guides

Workflows

Deploy

API Reference

XML Reference

Troubleshooting

Audio Streaming

Basic Usage

Attributes

Audio Formats

Bidirectional Streaming

Stream Both Directions

Status Callbacks

Callback Events

Callback Parameters

Custom Headers

Keep Call Alive

Noise Cancellation

Use Cases

WebSocket Events

​Basic Usage

​Attributes

​Audio Formats

​Bidirectional Streaming

​Stream Both Directions

​Status Callbacks

​Callback Events

​Callback Parameters

​Custom Headers

​Keep Call Alive

​Noise Cancellation

​Use Cases

​WebSocket Events

​Related

Basic Usage

Attributes

Audio Formats

Bidirectional Streaming

Stream Both Directions

Status Callbacks

Callback Events

Callback Parameters

Custom Headers

Keep Call Alive

Noise Cancellation

Use Cases

WebSocket Events

Related