# Simple Radio Forty Two — User Guide

*Version 2.2.0*

Simple Radio Forty Two embeds a radio player on your site. You manage a list of streams in the WordPress admin; visitors pick a station, hit play, and (when the source allows it) see artist and title. On many phones, the lock screen can control playback while the player tab stays open.

## Getting started

1. Activate the plugin.
2. Open **Simple Radio → Settings**. Keep the default stations or add your own (name, HTTPS stream URL, type).
3. Put the player on a page with **either**:
   - the shortcode `[sr42_radio]`, or
   - the **Simple Radio Forty Two** block (inserter → Media).

Both use the same settings. There is no per-block station list: change Settings and every instance updates.

## Station types

| Type | What the plugin expects |
|---|---|
| *Icecast / MPC* | Direct mount URL. Metadata is read from Icecast `status-json.xsl` when the URL contains `/podcast` (replaced by `/status-json.xsl`). Other Icecast URLs may still play but show “Direct Live”. |
| *SomaFM* | A SomaFM stream URL. The channel slug is taken from the path (`secretagent-128-mp3` → `secretagent`) and metadata from `somafm.com/songs/{channel}.json`. |
| *Radio Paradise* | Any RP stream URL; now-playing always comes from Radio Paradise’s public API (main channel). |

Save the settings form after edits. Empty name or URL rows are dropped.

## Find stations (Radio Browser)

On **Simple Radio → Settings**, **Find stations** queries the public [Radio Browser](https://www.radio-browser.info/) directory and fills **rows in the form below** (up to 10 working streams: name, URL, type). Scroll the list if you asked for many.

Examples:

- `France Inter`
- `late-night jazz in France`
- `ambient`

The form is filled; **nothing is written** until you click Save Changes. Review the URLs: they come from a community directory, not from the plugin author.

The search string is sent to `radio-browser.info` API mirrors (User-Agent identifies this plugin and your site URL, as their API requires).

**AI assembles, the directory supplies.** Without AI, up to 10 directory hits fill the form. With WordPress 7 Connectors + Enable AI:

1. The model plans 1–3 directory searches (name / genre / country).
2. Radio Browser returns a pool of real streams.
3. The model picks URLs **from that pool only** (as many as you asked, max 10), in listening order. Unknown URLs are dropped.

Same contract as the theme patterns: vocabulary first (the directory), then assembly. No invented hosts.

Abilities (`manage_options`): `simple-radio-forty-two/list-stations` and `simple-radio-forty-two/propose-stations` (search, does not save).

## Styling

**Simple Radio → Styling** lets you set the title and image URLs (background, vinyl/round, play, pause). The right-hand preview updates as you type; **Save Changes** writes the options used on the public player.

Leave a field empty to use the bundled default image.

## Front-end controls

- **Station** — dropdown. The last choice is stored in the browser (`localStorage`) and restored on the next visit.
- **Play / Pause** — real buttons, labelled for screen readers, usable with the keyboard. A short click-lock (400 ms) reduces double-taps.
- **Volume** — range input, also remembered in `localStorage`.
- **Listen in VLC** — shows the current stream URL so you can copy it into an external player.

On the bundled Radio 42 Icecast URL, a five-second “Please wait…” buffer runs on first load. Other stations skip it.

## Media Session (lock screen)

If the browser implements the Media Session API (typical on current Android Chrome and iOS Safari in recent versions):

- The lock screen / headset UI shows the current title and artist, plus the player artwork (your round image, or the plugin icon).
- Play and pause map to the on-page player.
- Previous / next skip stations in the dropdown.

This only lasts **while that document is still open** (the tab may be in the background or the phone locked). Closing the tab stops the audio.

## Playback after you navigate

If you leave a page while playing, the plugin stores a “want play” flag in `sessionStorage`. The next page that contains the player will **try** `audio.play()`.

Modern browsers treat that as autoplay: it often fails until the visitor taps Play again. The station and volume are still restored. That is expected, not a bug. A plugin cannot legally keep a live stream going across a full WordPress page load without a user gesture (and a Service Worker “background radio” would be a different product).

## Gutenberg block

The block is defined in `blocks/radio/block.json` (`apiVersion` 2) and rendered in PHP (`sr42_render_block` → the same shortcode output). The editor shows a placeholder, not a live stream (streams need the front-end script and a user gesture).

`supports.multiple` is false: one block per post is enough; use the shortcode if you truly need two players (they share the same element IDs, so two copies on one page are not supported).

## Permissions

Station and styling screens require `manage_options`. Metadata REST is public (`GET /wp-json/sr42/v1/meta`) so the front-end player can refresh titles.

## Frequently asked questions

**There is no widget under Appearance → Widgets.** Correct. Use a Shortcode widget with `[sr42_radio]`, or the Gutenberg block in a block-based widget area.

**Can I restyle the gold laser slider?** That effect was removed in 2.1.0. Override `.radio_container` in your theme if you want a custom look.

**Why did autoplay fail after I clicked a menu link?** Full navigation starts a new document. See “Playback after you navigate”.