> Documentation index: https://nao-rs.lukaloehr.com/llms.txt, a list of every page in this documentation.

# Audio

> REST API: Speaker and microphone. Generated from the OpenAPI document.

## Audio format

`GET /v1/audio`

The robot speaks and hears mono 16-bit PCM at 16 kHz.

**Token:** required · **Lease:** not needed

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Audio format on the wire | [AudioInfo](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#audioinfo) |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/audio
```

## Stream the microphones

`GET /v1/audio/microphone`

An endless WAV (or raw s16le) stream, mono 16 kHz. The robot only mixes microphone audio while someone listens.

**Token:** required · **Lease:** not needed

| Parameter | In | Type | Required | Meaning |
| --- | --- | --- | --- | --- |
| `format` | query | [StreamFormat](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#streamformat) | no |  |

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | Endless mono 16 kHz 16-bit stream of the microphones | `audio/wav`, `application/octet-stream` |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 503 | Too many streams open | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -N -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/audio/microphone > mic.wav
```

## Play audio on the speakers

`POST /v1/audio/speaker`

16-bit PCM WAV at any rate and channel count (converted to 16 kHz mono) or raw s16le 16 kHz mono, at most 4 MiB. Queued after what is playing.

**Token:** required · **Lease:** required (`Nao-Lease` header)

**Request body** (`application/octet-stream` or `audio/wav`): 16-bit PCM WAV (any rate and channel count, converted to 16 kHz mono) or raw s16le 16 kHz mono; at most 4 MiB

| Status | Meaning | Body |
| --- | --- | --- |
| 202 | Queued for the speakers | [Queued](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#queued) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 413 | Larger than 4 MiB | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 415 | Unsupported content type | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Not usable audio | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" -H 'Content-Type: audio/wav' \
  --data-binary @hello.wav http://$ROBOT:7702/v1/audio/speaker
```

## Stop the speakers

`DELETE /v1/audio/speaker`

Drops queued speaker audio.

**Token:** required · **Lease:** required (`Nao-Lease` header)

| Status | Meaning | Body |
| --- | --- | --- |
| 204 | Queued speaker audio dropped |  |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X DELETE -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" http://$ROBOT:7702/v1/audio/speaker
```

## Speaker volume

`GET /v1/audio/volume`

What the mixer holds now. Every boot starts at 65 %; changes are not kept across reboots.

**Token:** required · **Lease:** not needed

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | The speaker volume | [VolumeStatus](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#volumestatus) |
| 401 | Missing or wrong token | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 503 | No mixer (simulator), or not read yet | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -H "Authorization: Bearer $TOKEN" http://$ROBOT:7702/v1/audio/volume
```

## Set the speaker volume

`PUT /v1/audio/volume`

Changes the mixer only, never the audio stream, so it does not pop. Applied within about
0.1 s; `GET /v1/audio/volume` reads it back. Not persistent: the next boot is at 65 % again.

**Token:** required · **Lease:** required (`Nao-Lease` header)

**Request body** (`application/json`)

[VolumeRequest](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#volumerequest). A volume change. Give `percent`, `muted` or both; a percent above 0 also unmutes unless
`muted` is given too.

| Field | Type | Required | Meaning |
| --- | --- | --- | --- |
| `muted` | boolean or null | no |  |
| `percent` | integer or null | no | 0 to 100. (0 to 100) |

```json
{"percent":50}
```

| Status | Meaning | Body |
| --- | --- | --- |
| 202 | Requested | [VolumeRequest](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#volumerequest) |
| 409 | Not the active lease | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 422 | Invalid input (percent outside 0..100, nothing given) | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |
| 428 | No `Nao-Lease` header | [ErrorBody](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md#errorbody) |

```bash
curl -X PUT -H "Authorization: Bearer $TOKEN" -H "Nao-Lease: $LEASE" -H 'Content-Type: application/json' \
  -d '{"percent": 50}' http://$ROBOT:7702/v1/audio/volume
```

## Related topics

- [REST API](https://nao-rs.lukaloehr.com/reference/rest-api.md)
- [System](https://nao-rs.lukaloehr.com/reference/rest-api/system.md)
- [Robot](https://nao-rs.lukaloehr.com/reference/rest-api/robot.md)
- [State](https://nao-rs.lukaloehr.com/reference/rest-api/state.md)
- [Events](https://nao-rs.lukaloehr.com/reference/rest-api/events.md)
- [Safety](https://nao-rs.lukaloehr.com/reference/rest-api/safety.md)
- [Control](https://nao-rs.lukaloehr.com/reference/rest-api/control.md)
- [LEDs](https://nao-rs.lukaloehr.com/reference/rest-api/leds.md)
- [Cameras](https://nao-rs.lukaloehr.com/reference/rest-api/cameras.md)
- [Power](https://nao-rs.lukaloehr.com/reference/rest-api/power.md)
- [Motion](https://nao-rs.lukaloehr.com/reference/rest-api/motion.md)
- [Schemas](https://nao-rs.lukaloehr.com/reference/rest-api/schemas.md)
- Previous: [LEDs](https://nao-rs.lukaloehr.com/reference/rest-api/leds.md)
- Next: [Cameras](https://nao-rs.lukaloehr.com/reference/rest-api/cameras.md)