# Alarm Audio Streaming Protocol

## Overview

The Raspberry Pi streams alarm audio to the ESP32-S3 over a dedicated WebSocket connection on **port 8766**. The protocol uses mixed text and binary frames — text for control messages, binary for raw PCM data.

## Connection

| Parameter | Value |
|-----------|-------|
| Port | 8766 |
| Transport | WebSocket |
| Direction | Pi (server) → ESP32 (client) |

The ESP32 connects and stays connected. The server initiates alarm playback when needed.

## Message Sequence

```
Pi                          ESP32
 │                            │
 │◄──── WS connect ──────────│
 │                            │
 │  (idle until alarm fires)  │
 │                            │
 ├─ alarm_start (text) ──────►│  → open codec
 ├─ PCM chunk (binary) ──────►│  → queue + play
 ├─ PCM chunk (binary) ──────►│
 │  ...                       │
 ├─ alarm_stop (text) ────────►│  → drain + close codec
 │                            │
```

## Control Messages (Text Frames)

### alarm_start

Sent before the first PCM chunk. The ESP32 uses these parameters to configure the DAC.

```json
{
  "type": "alarm_start",
  "sample_rate": 24000,
  "channels": 2,
  "bits": 16
}
```

### alarm_stop

Sent after the last PCM chunk.

```json
{
  "type": "alarm_stop"
}
```

## PCM Data (Binary Frames)

- **Format:** Raw signed 16-bit little-endian, interleaved stereo (L, R, L, R, ...)
- **Chunk size:** 4096 bytes (1024 stereo samples at 16-bit)
- **Pacing:** Chunks sent at ~90% real-time speed to maintain buffer without overflow
- **Byte order:** Little-endian (native for both Pi and ESP32)

At 24kHz / 2ch / 16-bit:
- Bytes per second: 96,000
- Chunk duration: ~42.7 ms
- Send interval: ~38.4 ms (90% pacing)

## ESP32 Buffering

- FreeRTOS queue: 10 slots of pointer-to-chunk
- Total buffer capacity: ~427 ms of audio
- Overflow policy: drop chunk and log warning

## Future: Alarm Scheduling

Not yet implemented. Planned JSON format for alarm configuration:

```json
{
  "alarm_time": "070000",
  "alarm_days": ["Mon", "Tue", "Wed"],
  "alarm_audio": "path/to/file.wav"
}
```