# Simple Radio Forty Two — Mode d'emploi

*Version 2.2.0*

Simple Radio Forty Two intègre un lecteur radio sur votre site. Vous gérez une liste de flux dans l'admin WordPress ; les visiteurs choisissent une station, lancent la lecture et, si la source le permet, voient artiste et titre. Sur beaucoup de téléphones, l'écran verrouillé peut piloter la lecture tant que l'onglet du lecteur reste ouvert.

## Démarrage

1. Activez l'extension.
2. Ouvrez **Simple Radio → Settings**. Gardez les stations par défaut ou ajoutez les vôtres (nom, URL HTTPS du flux, type).
3. Placez le lecteur sur une page **soit** :
   - avec le shortcode `[sr42_radio]`,
   - soit avec le bloc **Simple Radio Forty Two** (inséreur → Média).

Les deux utilisent les mêmes réglages. Il n'y a pas de liste de stations par bloc : un changement dans Settings met à jour toutes les instances.

## Types de stations

| Type | Ce que l'extension attend |
|---|---|
| *Icecast / MPC* | URL de montage directe. Les métadonnées sont lues sur Icecast `status-json.xsl` lorsque l'URL contient `/podcast` (remplacé par `/status-json.xsl`). D'autres URL Icecast peuvent quand même jouer, avec le libellé « Direct Live ». |
| *SomaFM* | URL de flux SomaFM. Le slug de canal est extrait du chemin (`secretagent-128-mp3` → `secretagent`) ; les métadonnées viennent de `somafm.com/songs/{channel}.json`. |
| *Radio Paradise* | N'importe quelle URL RP ; le now-playing vient toujours de l'API publique Radio Paradise (canal principal). |

Enregistrez le formulaire après modification. Les lignes sans nom ou sans URL sont ignorées.

## Trouver des stations (Radio Browser)

Sur **Simple Radio → Settings**, **Find stations** interroge l’annuaire public [Radio Browser](https://www.radio-browser.info/) et remplit **les lignes du formulaire en dessous** (jusqu’à 10 flux : nom, URL, type). Fais défiler la liste si tu en as demandé beaucoup.

Exemples :

- `France Inter`
- `jazz la nuit en France`
- `ambient`

Le formulaire est rempli ; **rien n’est écrit** tant que tu n’as pas cliqué Save Changes. Relis les URL : elles viennent d’un annuaire communautaire.

La recherche part vers les miroirs `radio-browser.info` (User-Agent = ce plugin + l’URL du site, exigé par leur API).

**L’IA assemble, l’annuaire fournit.** Sans IA, jusqu’à 10 résultats remplissent le formulaire. Avec WordPress 7 Connectors + Enable AI :

1. Le modèle planifie 1 à 3 recherches (nom / genre / pays).
2. Radio Browser renvoie un vivier de vrais flux.
3. Le modèle en prend des URL **de ce vivier uniquement** (autant que demandé, max 10), dans l’ordre d’écoute. Le reste est jeté.

Même contrat que les patterns de thème : vocabulaire d’abord (l’annuaire), puis assemblage. Pas d’hôte inventé.

Abilities (`manage_options`) : `simple-radio-forty-two/list-stations` et `simple-radio-forty-two/propose-stations` (recherche, ne sauvegarde pas).

## Apparence

**Simple Radio → Styling** permet de régler le titre et les URL d'images (fond, disque, lecture, pause). L'aperçu à droite se met à jour pendant la saisie ; **Save Changes** écrit les options du lecteur public.

Laissez un champ vide pour l'image fournie avec l'extension.

## Contrôles côté site

- **Station** — liste déroulante. Le dernier choix est stocké dans le navigateur (`localStorage`) et restauré à la visite suivante.
- **Lecture / Pause** — vrais boutons, libellés pour les lecteurs d'écran, utilisables au clavier. Un verrou court (400 ms) limite les double-taps.
- **Volume** — curseur, également mémorisé dans `localStorage`.
- **Listen in VLC** — affiche l'URL du flux courant pour la copier dans un lecteur externe.

Sur le flux Icecast Radio 42 fourni, un tampon d'environ cinq secondes (« Please wait… ») s'affiche au premier chargement. Les autres stations le sautent.

## Media Session (écran verrouillé)

Si le navigateur implémente l'API Media Session (souvent Chrome Android et Safari iOS récents) :

- L'écran verrouillé / les commandes casque affichent le titre et l'artiste, plus l'illustration du lecteur (votre image « round », ou l'icône de l'extension).
- Lecture et pause correspondent au lecteur de la page.
- Précédent / suivant changent de station dans la liste.

Cela ne dure **que tant que le document reste ouvert** (l'onglet peut être en arrière-plan, le téléphone verrouillé). Fermer l'onglet arrête le flux.

## Lecture après une navigation

Si vous quittez une page pendant la lecture, l'extension enregistre un drapeau « vouloir lire » dans `sessionStorage`. La page suivante qui contient le lecteur **tente** `audio.play()`.

Les navigateurs modernes traitent cela comme de l'autoplay : ça échoue souvent jusqu'à un nouveau tap sur Lecture. Station et volume sont quand même restaurés. C'est le comportement attendu, pas un oubli. Une extension ne peut pas maintenir légalement un flux live à travers un rechargement WordPress complet sans geste utilisateur (un « radio en arrière-plan » via Service Worker serait un autre produit).

## Bloc Gutenberg

Le bloc est défini dans `blocks/radio/block.json` (`apiVersion` 2) et rendu en PHP (`sr42_render_block` → la même sortie que le shortcode). L'éditeur affiche un placeholder, pas un flux live (il faut le script public et un geste utilisateur).

`supports.multiple` est à false : un bloc par contenu suffit ; le shortcode non plus n'est pas conçu pour deux lecteurs sur la même page (identifiants HTML partagés).

## Permissions

Les écrans stations et apparence demandent `manage_options`. L'API REST des métadonnées est publique (`GET /wp-json/sr42/v1/meta`) pour que le lecteur puisse rafraîchir les titres.

## Questions fréquentes

**Il n'y a pas de widget sous Apparence → Widgets.** C'est normal. Utilisez un widget Shortcode avec `[sr42_radio]`, ou le bloc Gutenberg dans une zone de widgets en blocs.

**Où est passé l'effet laser doré du volume ?** Retiré en 2.1.0. Surchargez `.radio_container` dans votre thème pour un look custom.

**Pourquoi l'autoplay a échoué après un clic dans le menu ?** Une navigation complète crée un nouveau document. Voir « Lecture après une navigation ».