rangerhq-tuner/README.md

# RangerHQ Tuner

[![version](https://img.shields.io/badge/version-v0.3.0-6dbf7a?style=flat-square)](https://git.davidtkeane.com/ranger/rangerhq-tuner/src/tag/v0.3.0)
[![license](https://img.shields.io/badge/license-GPL%20v2%2B-2a7d3e?style=flat-square)](LICENSE)
[![manifest V3](https://img.shields.io/badge/manifest-V3-orange?style=flat-square&logo=googlechrome&logoColor=white)](manifest.json)
[![Chrome Web Store](https://img.shields.io/badge/Chrome%20Web%20Store-in%20review-f4e9b7?style=flat-square&logo=googlechrome&logoColor=2a7d3e)](#)
[![last commit](https://img.shields.io/gitea/last-commit/ranger/rangerhq-tuner?gitea_url=https%3A%2F%2Fgit.davidtkeane.com&style=flat-square&color=6dbf7a)](https://git.davidtkeane.com/ranger/rangerhq-tuner/commits/branch/main)
[![languages](https://img.shields.io/gitea/languages/count/ranger/rangerhq-tuner?gitea_url=https%3A%2F%2Fgit.davidtkeane.com&style=flat-square&color=2a7d3e)](https://git.davidtkeane.com/ranger/rangerhq-tuner)
[![no telemetry](https://img.shields.io/badge/telemetry-none-6dbf7a?style=flat-square)](PRIVACY.md)
[![made in Dublin](https://img.shields.io/badge/made%20in-Dublin%2C%20Ireland-2a7d3e?style=flat-square)](https://davidtkeane.com)

Lightweight indie internet radio player for Chrome. Plays SomaFM in any browser tab. Manifest V3, vanilla JS, no telemetry.

Sibling to [rangerhq-radio](https://git.davidtkeane.com/ranger/rangerhq-radio) (the WordPress version).

## Tier 1 — MVP (current)

- ✅ Manifest V3 + Offscreen API audio
- ✅ Loads all SomaFM channels from `channels.json`
- ✅ Pick a station, click Play, audio runs in background
- ✅ Volume + state persisted across popup open/close
- ✅ Catalogue cached 6h in `chrome.storage.local`
- ✅ Source-adapter pattern in place for future networks

## Install (developer mode)

1. Open `chrome://extensions`
2. Toggle **Developer mode** on (top right)
3. Click **Load unpacked** → pick this folder (`rangerhq-tuner/`)
4. Pin the extension to your toolbar (puzzle icon → pin)
5. Click the toolbar icon → pick a SomaFM station → ▶ Play

## Project layout

```
rangerhq-tuner/
├── manifest.json
└── src/
    ├── background/service-worker.js   # message router, no audio here
    ├── offscreen/offscreen.{html,js}  # the <audio> element host (MV3 needs this)
    ├── popup/popup.{html,css,js}      # the toolbar UI
    ├── sources/                       # extensibility seam
    │   ├── base-source.js             # RadioSource interface (JSDoc)
    │   ├── somafm.js                  # first concrete adapter
    │   └── index.js                   # registry
    ├── lib/                           # shared utilities
    └── assets/icons/                  # 16/32/48/128 PNGs
```

## License

GPL-2.0-or-later — matches the rest of the RangerHQ family.