> ## 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 Streams

> Stream real-time audio from active calls via WebSocket API

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

```json theme={null}
{
    "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 |

> [!NOTE]
>
> When `bidirectional` is `true`, `audio_track` cannot be `outbound` or `both`.

```python Python theme={null}
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)
```

```javascript Node.js theme={null}
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);
```

```ruby Ruby theme={null}
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 PHP theme={null}
<?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);
```

```java Java theme={null}
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();
```

```csharp .NET theme={null}
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);
```

```go Go theme={null}
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",
        },
    )
}
```

```bash cURL theme={null}
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

```bash theme={null}
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}/
```

```python Python theme={null}
response = client.calls.get_stream('call_uuid', 'stream_id')
```

```javascript Node.js theme={null}
client.calls.getStream('call_uuid', 'stream_id').then(console.log);
```

```bash cURL theme={null}
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/
```

```python Python theme={null}
response = client.calls.get_all_streams('call_uuid')
```

```javascript Node.js theme={null}
client.calls.listStreams('call_uuid').then(console.log);
```

```bash cURL theme={null}
curl -i --user AUTH_ID:AUTH_TOKEN \
    https://api.plivo.com/v1/Account/{auth_id}/Call/{call_uuid}/Stream/
```

### Response

```json theme={null}
{
    "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}/
```

```python Python theme={null}
client.calls.delete_specific_stream('call_uuid', 'stream_id')
```

```javascript Node.js theme={null}
client.calls.stopStream('call_uuid', 'stream_id').then(console.log);
```

```ruby Ruby theme={null}
api.calls.stop_stream('call_uuid', 'stream_id')
```

```bash cURL theme={null}
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/
```

```python Python theme={null}
client.calls.delete_all_streams('call_uuid')
```

```javascript Node.js theme={null}
client.calls.stopAllStreams('call_uuid').then(console.log);
```

```bash cURL theme={null}
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:

```json theme={null}
{
    "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 |

***

## Related

* [AudioStream XML](https://plivo.com/docs/voice/xml/audio-streaming.md) - Start streams via XML
* [Calls API](https://plivo.com/docs/voice/api/calls.md) - Call management