Audio Streams

The Audio Streams API lets you receive raw audio from active calls over a WebSocket connection in near real-time. Use it for real-time transcription, voice AI, call analytics, or custom audio processing.

API Endpoint

https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

The Audio Stream Object

Attribute	Type	Description
`stream_id`	string	Unique identifier for the audio stream
`call_uuid`	string	UUID of the call being streamed
`service_url`	string	WebSocket URL receiving the stream
`bidirectional`	boolean	Whether stream supports two-way audio
`audio_track`	string	Audio direction: `inbound`, `outbound`, `both`
`content_type`	string	Audio codec and sample rate
`start_time`	string	When streaming started
`end_time`	string	When streaming ended
`bill_duration`	integer	Streaming duration in seconds
`billed_amount`	string	Cost in USD

Example Response

{
    "api_id": "f7615566-13c5-11ee-b552-0242ac110005",
    "stream_id": "20170ada-f610-433b-8758-c02a2aab3662",
    "call_uuid": "78737f83-4660-490d-98e1-025dfe4b5c8f",
    "service_url": "wss://mysocket.com/wss/v2/1/demo/",
    "audio_track": "both",
    "bidirectional": false,
    "content_type": "audio/x-l16;rate=8000",
    "start_time": "2023-06-21 18:53:16+05:30",
    "end_time": "2023-06-21 18:53:43+05:30",
    "bill_duration": 27,
    "billed_amount": "0.00300",
    "rounded_bill_duration": 60
}

Start an Audio Stream

Initiate streaming for an active call.

POST https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Parameters

Parameter	Type	Required	Description
`service_url`	string	Yes	WebSocket URL (wss://) to receive audio
`bidirectional`	boolean	No	Enable two-way audio. Default: `false`
`audio_track`	string	No	Track to stream: `inbound`, `outbound`, `both`. Default: `inbound`
`stream_timeout`	integer	No	Max duration in seconds. Default: `86400` (24 hours)
`content_type`	string	No	Audio format. Default: `audio/x-l16;rate=8000`
`status_callback_url`	string	No	URL for stream status events
`status_callback_method`	string	No	`GET` or `POST`. Default: `POST`
`extra_headers`	string	No	Custom headers: `key1=val1,key2=val2`
`noise_cancellation`	string	No	Enable noise cancellation: `"true"` or `"false"`. Default: `"false"`
`noise_cancellation_level`	integer	No	Noise reduction intensity (`60`–`100`). Default: `85`. Only applies when `noise_cancellation` 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-l16;rate=24000`	Linear PCM, 24kHz
`audio/x-mulaw;rate=8000`	G.711 mu-law, 8kHz

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

import plivo

client = plivo.RestClient('<auth_id>', '<auth_token>')

response = client.calls.create_stream(
    'call_uuid_here',
    service_url='wss://yourserver.example.com/audiostream',
    bidirectional=False,
    audio_track='both',
    stream_timeout=3600,
    content_type='audio/x-l16;rate=16000'
)
print(response)

const plivo = require('plivo');

const client = new plivo.Client('<auth_id>', '<auth_token>');

client.calls.startStream('call_uuid_here', {
    serviceUrl: 'wss://yourserver.example.com/audiostream',
    bidirectional: false,
    audioTrack: 'both',
    streamTimeout: 3600
}).then(console.log);

require 'plivo'

api = Plivo::RestClient.new('<auth_id>', '<auth_token>')

response = api.calls.create_stream(
    'call_uuid_here',
    'wss://yourserver.example.com/audiostream',
    bidirectional: false,
    audio_track: 'both'
)
puts response

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

$client = new RestClient('<auth_id>', '<auth_token>');

$response = $client->calls->startStream(
    'call_uuid_here',
    ['serviceUrl' => 'wss://yourserver.example.com/audiostream']
);
print_r($response);

import com.plivo.api.Plivo;
import com.plivo.api.models.call.Call;

Plivo.init("<auth_id>", "<auth_token>");

Call.streamCreator("call_uuid_here")
    .serviceUrl("wss://yourserver.example.com/audiostream")
    .bidirectional(false)
    .audioTrack("both")
    .create();

using Plivo;

var api = new PlivoApi("<auth_id>", "<auth_token>");

var response = api.Call.StartStream(
    "call_uuid_here",
    "wss://yourserver.example.com/audiostream"
);
Console.WriteLine(response);

package main

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

func main() {
    client, _ := plivo.NewClient("<auth_id>", "<auth_token>", &plivo.ClientOptions{})

    response, _ := client.Calls.CreateStream(
        "call_uuid_here",
        plivo.StreamParams{
            ServiceUrl: "wss://yourserver.example.com/audiostream",
            AudioTrack: "both",
        },
    )
}

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{"service_url": "wss://yourserver.example.com/audiostream", "audio_track": "both"}' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Start a Stream with Noise Cancellation

curl -i --user AUTH_ID:AUTH_TOKEN \
    -H "Content-Type: application/json" \
    -d '{
        "service_url": "wss://yourserver.example.com/audiostream",
        "bidirectional": true,
        "noise_cancellation": "true",
        "noise_cancellation_level": 85
    }' \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Retrieve an Audio Stream

Get details of a specific audio stream.

GET https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/

response = client.calls.get_stream('call_uuid', 'stream_id')

client.calls.getStream('call_uuid', 'stream_id').then(console.log);

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/

List All Audio Streams

Get all audio streams for a call.

GET https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

response = client.calls.get_all_streams('call_uuid')

client.calls.listStreams('call_uuid').then(console.log);

curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Response

{
    "api_id": "87399872-13cb-11ee-9da1-0242ac110003",
    "meta": {
        "limit": 20,
        "offset": 0,
        "total_count": 1
    },
    "objects": [
        {
            "stream_id": "4543157e-60d3-4c3a-b9d8-189c47686bf0",
            "call_uuid": "816e0b22-6913-4b43-88a9-6d3054b77df9",
            "service_url": "wss://example.com/stream",
            "audio_track": "both",
            "bidirectional": false,
            "start_time": "2023-06-26 08:14:29+05:30",
            "end_time": "2023-06-26 08:14:50+05:30"
        }
    ]
}

Stop a Specific Audio Stream

Stop streaming for a specific stream.

DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/

client.calls.delete_specific_stream('call_uuid', 'stream_id')

client.calls.stopStream('call_uuid', 'stream_id').then(console.log);

api.calls.stop_stream('call_uuid', 'stream_id')

curl -i --user AUTH_ID:AUTH_TOKEN -X DELETE \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/{stream_id}/

Response: HTTP 204 No Content

Stop All Audio Streams

Stop all active streams on a call.

DELETE https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

client.calls.delete_all_streams('call_uuid')

client.calls.stopAllStreams('call_uuid').then(console.log);

curl -i --user AUTH_ID:AUTH_TOKEN -X DELETE \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/

Bidirectional Streaming

When bidirectional=true, your WebSocket server can send audio back to the call.

Sending Audio to Call

Send a JSON message to the WebSocket:

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

Field	Values
`contentType`	`audio/x-l16`, `audio/x-mulaw`
`sampleRate`	`8000`, `16000`
`payload`	Base64-encoded raw audio

Status Callback Events

Notifications sent to status_callback_url:

Event	Description
Stream connected	Audio streaming has started
Stream stopped	Streaming stopped intentionally
Stream timeout	`stream_timeout` duration reached
Stream failed	Connection failed or dropped

AudioStream XML - Start streams via XML
Calls API - Call management

Getting Started

Concepts

API Reference

XML Reference

SDKs

Troubleshooting

Voice Tutorials

Migration Guides

Audio Streams

API Endpoint

The Audio Stream Object

Example Response

Start an Audio Stream

Parameters

Audio Formats

Start a Stream with Noise Cancellation

Retrieve an Audio Stream

List All Audio Streams

Response

Stop a Specific Audio Stream

Stop All Audio Streams

Bidirectional Streaming

Sending Audio to Call

Status Callback Events

​API Endpoint

​The Audio Stream Object

​Example Response

​Start an Audio Stream

​Parameters

​Audio Formats

​Start a Stream with Noise Cancellation

​Retrieve an Audio Stream

​List All Audio Streams

​Response

​Stop a Specific Audio Stream

​Stop All Audio Streams

​Bidirectional Streaming

​Sending Audio to Call

​Status Callback Events

​Related

API Endpoint

The Audio Stream Object

Example Response

Start an Audio Stream

Parameters

Audio Formats

Start a Stream with Noise Cancellation

Retrieve an Audio Stream

List All Audio Streams

Response

Stop a Specific Audio Stream

Stop All Audio Streams

Bidirectional Streaming

Sending Audio to Call

Status Callback Events

Related