radio-free-elsewhere/CLAUDE.md

# Radio Free Elsewhere

## Project Overview

Radio Free Elsewhere is an Internet radio station streaming eclectic music (Celtic folk, ambient/space, surf rock, and more). It runs on Icecast hosted on a Yunohost server. Streams are live and occasional — a few times per week in the evenings, typically around 7:30pm Eastern, running roughly two hours. This is not a 24/7 automated station.

The shows have distinct themes and identities:
- **O'Morain's Pub** — Celtic folk
- **Cosmoeuphoria** — ambient and space music
- **Bisexual Surfers From the Twilight of Time** — surf rock and rockabilly
- **The Bollocks** - punk rock
- **The Spin** - eclectic tunes from all genres

## Scope

This repo covers the **website** — the public pages, the admin backend, and the site's MariaDB database. Icecast configuration, Yunohost server administration, and streaming software are out of scope. Do not look for or suggest changes to server-side streaming config.

The one approved exception is [cli/poll_icecast.php](cli/poll_icecast.php), a cron job that reads the Icecast status API to record track history. It only reads from Icecast; it never configures it.

## Key Files

Public pages:
- [index.php](index.php) — Main page. The sidebar shows the queued (or live) show from the database: icon, name, scheduled start time in Eastern and UTC, and description. The main column has the about section.
- [live.php](live.php) — Page to send listeners to while streaming. Player on the left, recently played list on the right; the sidebar background and the heading change with the current show.
- [now_playing.php](now_playing.php) — Returns the currently playing track as HTML. Called by `index.php` and `live.php` every 15 seconds.
- [recently_played.php](recently_played.php) — Returns the current broadcast's track history as table rows for `live.php`.

Admin backend ([admin/](admin/)):
- [admin/login.php](admin/login.php), [admin/logout.php](admin/logout.php) — Username/password login.
- [admin/index.php](admin/index.php) — Dashboard: broadcast status, queue the next show (with an optional episode title, date and Eastern start time), switch the live show or its episode title, clear the queue.
- [admin/shows.php](admin/shows.php), [admin/show_edit.php](admin/show_edit.php) — List, add, edit and delete shows, including the description and icon and background image uploads.

Shared includes:
- [includes/db.php](includes/db.php) — `getDB()` returns a shared PDO connection (session time zone UTC).
- [includes/icecast.php](includes/icecast.php) — Icecast fetching/parsing, album art lookup (iTunes Search API) and Last.fm link helpers.
- [includes/broadcasts.php](includes/broadcasts.php) — Broadcast lifecycle, show queueing and track history logic.
- [includes/auth.php](includes/auth.php) — Admin sessions, login throttling and CSRF helpers.
- [includes/admin_layout.php](includes/admin_layout.php) — `adminHeader()`/`adminFooter()` page chrome and `flash()` messages for admin pages.

Command-line tools (run over SSH from the site root):
- [cli/poll_icecast.php](cli/poll_icecast.php) — Cron-run poller that records broadcasts and tracks.
- [cli/set_show.php](cli/set_show.php) — Lists shows, or queues/sets the show by slug, optionally with a start time and episode title (`php cli/set_show.php <slug> 2026-10-30 19:30 --title="Ethereal and Enya"`). Same behaviour as the dashboard control.
- [cli/create_admin.php](cli/create_admin.php) — Creates an admin account or resets its password.

Other:
- [sql/schema.sql](sql/schema.sql) — Full database schema plus seed data for the five shows. Safe to re-run.
- [config/db_credentials.example.php](config/db_credentials.example.php) — Template for the gitignored `config/db_credentials.php`.
- [SETUP.md](SETUP.md) — Step-by-step guide to installing the site on a Yunohost server, including the poller cron job.

## Architecture

- **Backend:** PHP only. No Composer, no package manager, no build step.
- **Frontend:** HTML5 UP Strata template with custom CSS additions. No npm, no webpack, no preprocessor — edit CSS directly in `assets/css/main.css` or inline `<style>` blocks.
- **Now-playing:** `index.php` and `live.php` fetch `now_playing.php` via JavaScript every 15 seconds and inject the result into `#now-playing`. The fetch uses `arrayBuffer` + `TextDecoder` to handle the UTF-8 encoding correctly on the client side. `live.php` fetches `recently_played.php` the same way.
- **Duplicated sidebar:** `live.php` was copied from `index.php`, so the sidebar markup, now-playing styles and fetch script exist in both. Changes to one usually need making in the other.
- **Sidebar background:** `#header` in `main.css` uses `images/bg.jpg` with `background-size: cover`. Don't switch it back to `bg.png` — that file has an alpha fade at the bottom that lets the brown background colour show through.

## Database

MariaDB on localhost. Credentials live in `config/db_credentials.php`, which is gitignored and uploaded to the server separately. Tables (see [sql/schema.sql](sql/schema.sql)):

- `shows` — the shows, with a unique `slug`, a plain-text `description` (blank lines separate paragraphs) and optional `icon_image` and `background_image` (filenames in `images/backgrounds/`).
- `broadcasts` — one row per streaming session: pending (`started_at` NULL, queued from the dashboard or `cli/set_show.php`), live (`ended_at` NULL), or ended. `scheduled_at` is the advertised start time shown on `index.php`; the broadcast still starts whenever the stream comes online. `episode_title` is an optional per-episode title (e.g. "Ethereal and Enya") shown under the show name on `index.php` and under the heading on `live.php`.
- `played_tracks` — tracks per broadcast. Cleared ten minutes after the broadcast ends; no long-term history is kept.
- `admins` — admin accounts (username + password hash).
- `login_attempts` — failed logins by IP, used for throttling.

All DATETIME values are UTC. Show start times are entered and displayed in the station time zone (`STATION_TIMEZONE`, America/New_York, in [includes/broadcasts.php](includes/broadcasts.php)) and converted with `stationTimeToUtc()`/`utcToStationTime()`. `recently_played.php` outputs `<time datetime="...Z">` and `live.php` reformats them in the listener's local time zone.

## Broadcasts and Track History

`cli/poll_icecast.php` runs from cron every minute and polls Icecast four times, 15 seconds apart (with a lock file so runs never overlap). Rules, implemented in `recordPoll()` in [includes/broadcasts.php](includes/broadcasts.php):

- When the stream comes online, the queued broadcast starts. If nothing was queued, a broadcast with no show is created so tracks are still recorded.
- A new track is recorded whenever title/artist/album differ from the last one, with its album art URL looked up once.
- A broadcast ends once it has been unseen for five minutes, so brief encoder drop-outs don't split a show. `liveBroadcast()` and `currentShow()` apply the same five-minute rule when reading, so if the poller isn't running (e.g. on a dev server without the cron job), a stale broadcast doesn't show as live.
- Tracks are deleted ten minutes after their broadcast ends.
- If the status API can't be reached, the poll is skipped entirely so an outage isn't mistaken for the stream ending.

In the recently played list, album art and album title link to the album's Last.fm page; the now-playing widget links to the track's Last.fm page.

## Admin Authentication

Username and password only; the site sends no email. Accounts are created and passwords reset over SSH with `php cli/create_admin.php <username>`. Passwords are hashed with `password_hash()` (PASSWORD_DEFAULT — bcrypt, chosen for portability over Argon2). Sessions use a `rfe_admin` cookie scoped to the admin directory (HttpOnly, SameSite=Strict, Secure over HTTPS) and expire after four hours idle. Five failed logins from one IP within 15 minutes locks that IP out for the rest of the window.

When adding admin pages:
- Call `requireAdmin()` first and render with `adminHeader($title, $admin)` / `adminFooter()`.
- Every POST form must include `csrfField()`, and its handler must call `verifyCsrf()` before doing anything else.
- Use post-redirect-get: handle the POST, call `flash()`, then redirect.

## Image Uploads

Show backgrounds and icons are uploaded through `admin/show_edit.php`: JPEG, PNG or WebP, backgrounds up to 5 MB and icons up to 1 MB (PHP's `post_max_size` is 8 MB). Files are validated by content (finfo + `getimagesize`), not extension, and saved to `images/backgrounds/` as `<slug>-<random>.<ext>` (icons `<slug>-icon-<random>.<ext>`). Replaced or removed images are deleted from disk. The web server user must be able to write to that directory. Uploads are gitignored — they belong to each server's database, so they're uploaded per server through the admin page.

## Conventions

- Files in `includes/` and `config/` return 403 if requested directly; files in `cli/` refuse to run outside the command line (`PHP_SAPI !== 'cli'`). Follow the same pattern for new files.
- Use prepared statements for all queries with user input, and escape all output with `htmlspecialchars` (the `e()` helper in admin pages).
- `index.php` and `live.php` use CRLF line endings; the PHP includes and scripts use LF. Preserve whichever a file already has.
- PHP files use 4-space indentation; the HTML templates use tabs, matching Strata.

## Icecast Integration

- **Stream URL:** `https://radio.cyberpunklibrarian.nohost.me/rfe`
- **Status API:** `https://radio.cyberpunklibrarian.nohost.me/status-json.xsl`

The status API returns JSON with track metadata under `icestats.source`; when the stream is offline there is no `source` key. The `source` key may be a single object or an array depending on how many mountpoints are active; `fetchCurrentTrack()` in [includes/icecast.php](includes/icecast.php) handles both cases. Track titles arrive as `Title - Artist - Album`.

## Known Encoding Quirk

Icecast double-encodes track metadata as Latin-1 interpreted as UTF-8. The fix in `decodeMetaField()` in [includes/icecast.php](includes/icecast.php) deliberately converts the string from UTF-8 to ISO-8859-1 to strip the outer encoding layer and recover the correct UTF-8 byte sequence. Do not remove or "simplify" this conversion — it is intentional and necessary for non-ASCII characters (accented names, etc.) to display correctly.

## Deployment

There is no CI/CD pipeline. Deployment is manual:

1. Commit and push changes to the self-hosted Gitea repository.
2. Upload changed files to the Yunohost web server via SFTP. Never overwrite `config/db_credentials.php` or the contents of `images/backgrounds/` on the server.

There is no staging environment — changes go straight to production.

Server-only setup (one-time, or when the schema changes):
- Apply the schema: `mysql -u <db_user> -p <db_name> < sql/schema.sql` (use `sudo mysql <db_name> < sql/schema.sql` if the database user lacks CREATE privileges).
- Upload `config/db_credentials.php` with the server's credentials.
- Add the cron entry in `/etc/cron.d` (see [SETUP.md](SETUP.md)): `* * * * * <app_user> /usr/bin/php8.x /path/to/rfe/cli/poll_icecast.php`, run as a user that can read the credentials file. Without it the recently played list stays empty and queued shows never start.
- Make `images/backgrounds/` writable by the user PHP runs as.
- Create an admin account with `php cli/create_admin.php <username>`.

## Updating Show Information

The `index.php` sidebar is driven by the database. Before a show, queue it on the admin dashboard (or `php cli/set_show.php <slug> <date> <time>`) with its date, Eastern start time and optional episode title; the sidebar then shows its icon, name, episode title, start time (with the UTC conversion) and description, switches to "On the Air Now" while live (with the icon and a "Broadcasting Live" link pointing to `live.php`), and falls back to a short "nothing scheduled" note once nothing is queued. Edit descriptions and icons on the show's admin page.

The commented-out show blocks in the `#one` section of `index.php` are the hand-written history from before this; leave them as they are.

Point listeners to `live.php` while streaming.

## Planned Work

- `index.php` will be reworked into more evergreen content (About, schedules, etc.) and will link to `live.php` more prominently. For now, the only links to `live.php` are in the `index.php` sidebar while a show is live (the show icon and a "Broadcasting Live" link).
- The admin backend will grow to manage more of the site.