# Stream realtime events

`GET http://127.0.0.1:19470/v1/events`

Opens a Server-Sent Events stream. The first event is always a `status`
snapshot. Subsequent events are sent whenever voice changer status,
selected voice, quality mode, monitoring, or the sounds playing change.

Event names and payloads:

- `status`: the voice changer status, including `latencyMs`; sent when the
  state changes or the latency moves by 20 ms or more. The initial snapshot
  also includes selected voice, quality mode, and monitoring state
- `voice`: `{ "voiceId": "hazel" }`
- `quality`: `{ "mode": "adaptive" }`
- `monitoring`: `{ "enabled": true }`
- `sounds`: `{ "playing": ["pad_3f2a"] }`, the pad IDs playing now, whoever
  pressed them (an empty list when the last one ends)

A keepalive comment is sent every 15 seconds while no events occur, and
SSE clients are instructed to reconnect after two seconds if disconnected.
Browser clients should use streaming `fetch` so the Bearer authorization
header can be included; native `EventSource` cannot set that header.

Authenticate with `Authorization: Bearer <API key>` (key from Settings > Developer in Voices AI Live).

## Responses

### 200: Realtime Server-Sent Events stream

```text
event: status
data: {"state":"running","message":"Voice changer is running.","startedAt":1793750400000,"updatedAt":1793750401000,"latencyMs":190,"voiceId":"hazel","qualityMode":"adaptive","monitorEnabled":false}

event: monitoring
data: {"enabled":true}
```

### 401: Invalid or missing API key

- `error` (string, required): Error message

```json
{
  "error": "Invalid or missing API key"
}
```

## Examples

```bash
curl -N http://127.0.0.1:19470/v1/events \
  -H "Authorization: Bearer $VOICES_AI_API_KEY"
```

```javascript
const res = await fetch('http://127.0.0.1:19470/v1/events', {
  headers: {
    Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`,
  },
});

// Server-Sent Events: read the stream as it arrives.
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
for (;;) {
  const { value, done } = await reader.read();
  if (done) break;
  console.log(value);
}
```

```python
import os
import requests

res = requests.get(
    "http://127.0.0.1:19470/v1/events",
    headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"},
    stream=True,
)
for line in res.iter_lines(decode_unicode=True):
    print(line)
```
