# Toggle audio monitoring

`PUT http://127.0.0.1:19470/v1/monitor`

Enables or disables audio monitoring (hear yourself) and saves the setting.
Uses the monitor device chosen in the desktop app. While the voice changer
is running the change applies right away, otherwise on the next start.

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

## Request body (application/json)

- `enabled` (boolean, required): Whether to enable audio monitoring

```json
{
  "enabled": true
}
```

## Responses

### 200: Monitor setting updated

- `ok` (boolean, required)
- `enabled` (boolean, required): The saved monitoring setting
- `monitorDevice` (string or null): The device you hear yourself on, or null when monitoring is off
- `status` (EngineStatus): The voice changer status after an action
  - `state` (string, required): Current state of the voice changer One of: `idle`, `starting`, `running`, `stopping`, `error`.
  - `message` (string, required)
  - `startedAt` (integer or null): When the current run started, in milliseconds since the Unix epoch
  - `updatedAt` (integer): When this status was set, in milliseconds since the Unix epoch
  - `latencyMs` (integer or null): How far the changed voice lags behind your microphone, in milliseconds: the measured end-to-end delay, smoothed and rounded to 10 ms. Null while the voice changer isn't running. Delay your camera by this much (for example with a video delay filter in OBS) to keep it in sync with your voice.
- `error` (string or null): Why the running engine could not switch; null when `ok` is `true`

```json
{
  "ok": true,
  "enabled": true,
  "monitorDevice": "MacBook Pro Speakers",
  "status": {
    "state": "running",
    "message": "Voice changer is running.",
    "startedAt": 1793750400000,
    "updatedAt": 1793750430000
  },
  "error": null
}
```

### 400: Invalid request body, or the running engine could not switch monitoring

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

```json
{
  "error": "Missing required field: enabled (boolean)"
}
```

### 401: Invalid or missing API key

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

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

## Examples

```bash
curl -X PUT http://127.0.0.1:19470/v1/monitor \
  -H "Authorization: Bearer $VOICES_AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true}'
```

```javascript
const res = await fetch('http://127.0.0.1:19470/v1/monitor', {
  method: 'PUT',
  headers: {
    Authorization: `Bearer ${process.env.VOICES_AI_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true
  }),
});
const data = await res.json();
```

```python
import os
import requests

res = requests.put(
    "http://127.0.0.1:19470/v1/monitor",
    headers={"Authorization": f"Bearer {os.environ['VOICES_AI_API_KEY']}"},
    json={"enabled":True},
)
print(res.json())
```
