Configuration

Configuration

Everything is configured through .env, with no source edits required. To point this at a different AzuraCast instance, set AZURACAST_BASE_URL and STATION_SHORTCODE.

Variable	Default	Description
BOT_TOKEN	none	Discord bot token (required unless DRY_RUN)
APPLICATION_ID	none	Discord application ID (required unless DRY_RUN)
USER_ID	none	Your Discord user ID (required unless DRY_RUN)
AZURACAST_BASE_URL	https://hails.live	Base URL of your AzuraCast instance
STATION_SHORTCODE	radio	Station shortcode to read
WIDGET_USERNAME	station name	Username shown on the widget
POLL_INTERVAL_MS	9000	How often to poll now-playing (ms)
META_REFRESH_MS	60000	How often to refresh station details, schedule, and requests (ms)
HISTORY_DEPTH	4	Number of history_N_* field sets to generate
REQUESTS_DEPTH	4	Number of request_N_* field sets to generate
ENABLED_FIELDS	all	Comma-separated allowlist that pushes only these field names
DRY_RUN	off	Set to 1 to print the field catalog with live values instead of sending to Discord

Data sources

Now-playing data is polled every POLL_INTERVAL_MS. Station details, the schedule, and the song requests list are refreshed less frequently (every META_REFRESH_MS) and cached. Each of those extra endpoints is fetched independently and degrades gracefully. If your instance has requests disabled or the schedule empty, those fields simply come back blank without affecting the rest.

Rate limiting

Discord rate-limits the identity-update endpoint. If you poll too aggressively you'll see Discord responded 429. The service reads the retry_after value and backs off automatically, but if 429s are frequent, raise POLL_INTERVAL_MS (e.g. 15000). A 9 to 15s interval keeps the progress bar smooth without tripping the limit.

Field limit

Discord allows at most 30 data fields per payload. The full catalog is 70+, so you must narrow it with ENABLED_FIELDS. See Field Catalog for the full field list and details, and Troubleshooting for error symptoms.