> ## 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`.
</Note>

<CodeGroup>
  ```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/
  ```
</CodeGroup>

### 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}/
```

<CodeGroup>
  ```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}/
  ```
</CodeGroup>

***

## List All Audio Streams

Get all audio streams for a call.

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

<CodeGroup>
  ```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/
  ```
</CodeGroup>

### 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}/
```

<CodeGroup>
  ```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}/
  ```
</CodeGroup>

**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/
```

<CodeGroup>
  ```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/
  ```
</CodeGroup>

***

## 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](/voice/xml/audiostream/) - Start streams via XML
* [Calls API](/voice/api/calls/) - Call management