Stations

RangerHQ Radio ships 44 hand-curated SomaFM stations organised across 10 genres. They are NOT fetched dynamically from SomaFM's channels.json — they are stored as a static PHP array in inc/stations.php and updated by hand when SomaFM adds or retires channels.

Why hand-curated, not dynamic?

Benefit	What it gets you
Quality filter	The catalogue is what David actually listens to. Not every SomaFM channel needs to be on the menu — some are seasonal, some are niche, some get retired.
Reliability	The plugin works even if `channels.json` is unreachable. No runtime dependency on a third-party JSON endpoint just to render the station list.
Performance	Zero outbound HTTP requests just to show the picker. Catalogue is in PHP memory, instantly available.
Predictability	The reviewer (wp.org or Chrome Web Store) can audit the exact set of stations the plugin ships. No surprises from a dynamic catalogue that could change after review.

The trade-off: the catalogue needs manual maintenance. SomaFM doesn't change much (they're a stable indie network), so this hasn't been a burden in practice.

The 10 genres

Genre	Examples
Ambient	Drone Zone, Deep Space One, Mission Control, Earwaves
Electronic	Groove Salad, Space Station Soma, cliqhop idm, DEF CON Radio, Beat Blender
Lounge	Secret Agent, Lush, Folk Forward
Rock	Indie Pop Rocks!, BAGeL Radio, U80s
Metal	Metal Detector, Doomed
Jazz	Sonic Universe, Vaporwaves
World	Suburbs of Goa, Illinois Street Lounge
Reggae	Reggaedelica
Holiday	Christmas Lounge, Christmas Rocks!, Jolly Ol' Soul, Xmas in Frisko
Specials	Black Rock FM, Boot Liquor, Covers, Seven Inch Soul, Underground 80s, ThistleRadio

(Examples — see inc/stations.php for the authoritative list of all 44.)

The station entry shape

array(
    'id'          => 'soma-groovesalad',         // namespaced unique ID
    'name'        => 'Groove Salad',
    'genre'       => 'Electronic',
    'stream_url'  => 'https://ice1.somafm.com/groovesalad-128-mp3',
    'description' => 'A nicely chilled plate of ambient/downtempo beats and grooves.',
    'art_url'     => 'https://api.somafm.com/img/groovesalad400.jpg',
    'songs_url'   => 'https://somafm.com/songs/groovesalad.json',
),

Every field is required. The songs_url is what assets/js/radio.js polls every 25 seconds for the "now playing" track metadata.

Lookup helpers

inc/stations.php exposes three helpers:

Function	What it returns
`radio_get_stations_flat()`	A flat array of all 44 station entries
`radio_get_stations_grouped()`	A map of `genre => array of stations` for the genre-grouped UI
`radio_find_station( $station_id )`	A single station entry by ID, or `null`
`radio_default_station_id()`	The default station for new users (Groove Salad)

How to add a station

The station array is a static PHP array. Adding one is a five-line patch.

Step 1 — verify the station on SomaFM

Check that the channel exists at the URL you'll use:

https://somafm.com/<channel-shortname>/

For example: https://somafm.com/groovesalad/. Confirm the songs/<shortname>.json endpoint also returns track metadata.

Step 2 — add the entry to `inc/stations.php`

array(
    'id'          => 'soma-<your-shortname>',
    'name'        => 'Your Station Name',
    'genre'       => 'Electronic',                // pick from the 10 existing genres or add a new one
    'stream_url'  => 'https://ice1.somafm.com/<shortname>-128-mp3',
    'description' => 'One-sentence blurb.',
    'art_url'     => 'https://api.somafm.com/img/<shortname>400.jpg',
    'songs_url'   => 'https://somafm.com/songs/<shortname>.json',
),

Step 3 — bump the plugin version

radio.php header Version: + the Stable tag: in readme.txt + a CHANGELOG.md entry.

Step 4 — test it

Reload the plugin in WP admin
Visit the Radio page — your new station should appear under its genre
Pick it → audio should play
Wait 30 seconds → the History tab should log a track if the songs endpoint returned metadata
The 4-button search row should appear next to the logged track

Step 5 — tag the release on Gitea

git tag -a v1.x.0 -m "v1.x.0 — add <station name>"
git push origin v1.x.0

Then upload the updated zip to wp.org SVN (same workflow as any other version bump).

How to retire a station

If SomaFM kills a channel:

Remove the entry from inc/stations.php
Bump the version
Note in the CHANGELOG that the station was retired upstream
Users with that station in their radio_state will fall back to the default on next load (radio_get_state() handles the missing-station case gracefully)

What about non-SomaFM stations?

Today the plugin is SomaFM-only by design. The IDs are prefixed soma- and the architecture assumes the SomaFM metadata-endpoint shape (songs/<id>.json).

If you wanted to add another network (Internet-Radio.com, RadioGarden, Shoutcast directory), the cleanest path is to copy the Tuner's adapter pattern — split inc/stations.php into per-source files plus a registry. That's an architectural change, not a one-line addition.

Want to suggest a station?

Open an issue at https://git.davidtkeane.com/ranger/rangerhq-radio/issues. Curation is intentional, so not every suggestion will land, but good additions are welcome.