# Stream

The `<Stream>` noun forks a call's audio to a WebSocket endpoint you control, for real-time processing such as a live voice agent or transcription pipeline. Nest `<Stream>` inside `<Connect>` for a two-way, blocking media session, inside `<Start>` to fork audio one-way in the background without blocking the document, or inside `<Stop>` to end a stream you started earlier.

In every form, `url` must start with `wss://`; PressOne rejects the document otherwise.

## Connect: bidirectional, blocking

`<Connect><Stream>` opens a two-way audio connection: PressOne sends the caller's audio to your WebSocket endpoint, and plays back any audio your endpoint sends in return. `<Connect><Stream>` blocks: PressOne waits for the stream to end (your endpoint closes the connection, or the call ends) before executing the next verb in the document.

`<Connect>` itself accepts `action` and `method` attributes:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `action` | string (uri) | — | Accepted but not currently applied. When the stream ends, execution continues with the next verb in the document; PressOne does not request this URL. |
| `method` | string | `POST` | HTTP method for `action`. One of `GET` or `POST`. |

The nested `<Stream>` accepts:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `url` | string (uri) | — | Required. WebSocket URL to stream audio to and from. Must start with `wss://`. |
| `name` | string | — | Label to identify this stream. |

## Start: one-way, non-blocking

`<Start><Stream>` forks the call's audio to your WebSocket endpoint one way: PressOne sends audio, but does not play back anything your endpoint sends. `<Start>` does not block: PressOne starts the stream in the background and immediately executes the next verb in the document. The stream keeps running until a matching `<Stop>` or the call ends.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `url` | string (uri) | — | Required. WebSocket URL to stream audio to. Must start with `wss://`. |
| `name` | string | — | Label to identify this stream, so a later `<Stop>` can target it. |
| `track` | string | `inbound_track` | Which audio to stream. One of `inbound_track` (caller audio only), `outbound_track` (the other leg's audio only), or `both_tracks`. |

## Stop: end a stream

`<Stop><Stream name="..."/></Stop>` ends a stream previously started with `<Start>`, identified by `name`.

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `name` | string | — | Required. Name of the stream to stop, matching the `name` given to `<Start><Stream>`. |

## Custom parameters

Nest one or more `<Parameter>` elements inside `<Stream>` (either the `<Connect>` or `<Start>` form) to send custom key/value data to your WebSocket endpoint:

| Name | Type | Default | Description |
|------|------|---------|-------------|
| `name` | string | — | Required. Parameter name. |
| `value` | string | — | Required. Parameter value. |

## Metadata sent on stream start

When the stream starts, PressOne includes the following in the metadata delivered to your WebSocket endpoint, alongside any `<Parameter>` values:

| Field | Sent by `<Connect>` | Sent by `<Start>` |
|-------|:---:|:---:|
| `call_sid` | Yes | Yes |
| `account_sid` | Yes | No |
| `custom_parameters` (containing `From` and `To`) | Yes | Yes |

## Examples

Connecting a call to a WebSocket voice agent:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Connecting you to our voice assistant.</Say>
  <Connect>
    <Stream url="wss://agent.example.com/voice-stream"/>
  </Connect>
</Response>
```

Forking audio to a background transcription service without blocking the call, then stopping it later:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Start>
    <Stream url="wss://transcribe.example.com/live" name="call-transcript" track="both_tracks"/>
  </Start>
  <Say>This call is being transcribed for quality purposes.</Say>
  <Dial>+2341800000001</Dial>
</Response>
```

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Stop>
    <Stream name="call-transcript"/>
  </Stop>
  <Hangup/>
</Response>
```

## See also

- [Dial](/voice/oneml/dial)
- [Disconnect](/voice/oneml/disconnect)
- [OneML overview](/voice/oneml/overview)