# Configuration reference

Everything is environment variables — no config files beyond `.env` sourcing.

## shipper (generator machine)

| Var | Default | Meaning |
|---|---|---|
| `LIBRARY_DIR` | `library` | ai-radio app library dir (contains `index.json` + genre folders) |
| `SHIP_STAGING_DIR` | `ship_out` | local dir for transcoded mp3s + playlist |
| `SHIP_REMOTE_TARGET` | — (required) | scp target: `user@vps:/opt/airstudio/web/ai-radio/` |
| `SHIP_SSH_KEY` | — | identity file for scp |
| `SHIP_POLL_INTERVAL_S` | `60` | seconds between cycles |
| `PLAYLIST_SIZE` | `40` | tracks in the rolling playlist |
| `NEWNESS_BIAS` | `3` | lower = fresher songs dominate (weight=1/(rank+bias)) |
| `MP3_BITRATE` | `128k` | transcode bitrate |
| `STATION_NAME` | `AI Radio` | ID3 album + playlist prefix |

## streamer (VPS)

| Var | Default | Meaning |
|---|---|---|
| `STREAM_WEBROOT` | `/usr/local/share/icecast/web/ai-radio` | where shipped files live |
| `ICECAST_ADDR` | `icecast:8000` | icecast host:port |
| `ICECAST_SOURCE_PASSWORD` | `hackme` | **change this** |
| `ICECAST_MOUNT` | `/ai-radio.mp3` | mount point |
| `STATION_NAME` | `AI Radio` | stream name / MQTT artist |
| `STATION_DESCRIPTION` | `Endless AI-generated radio` | icecast description |
| `MP3_BITRATE` | `128` | kbps, used for stream pacing + icecast metadata |
| `STREAM_PUBLIC_URL` | — | advertised URL (MQTT payload, icecast url) |
| `MQTT_ADDR` | empty = disabled | `host:port` of the MQTT broker |
| `MQTT_USER` / `MQTT_PASS` | — | broker auth (optional) |
| `MQTT_CLIENT_ID` | `radio-streamer` | MQTT client id |
| `MQTT_TOPIC` | `airstudio/nowplaying` | now-playing topic |

## icecast.xml (VPS)

Three secrets must be changed from `CHANGE_ME_*`:
`source-password` (matches `ICECAST_SOURCE_PASSWORD`), `relay-password`,
`admin-password`. Admin UI: `http://<vps>:8000/admin/`.

## Tuning cheat-sheet

- Want the stereo to hear new songs ASAP → `NEWNESS_BIAS=1`, small `SHIP_POLL_INTERVAL_S`.
- Want variety over freshness → `NEWNESS_BIAS=10+`.
- Better sound → `MP3_BITRATE=192k` (also bump streamer `MP3_BITRATE=192`).
- MQTT-only mode (no icecast): not supported; the stream is the product.