RangerHQ Tuner Wiki

A lightweight Chrome extension for SomaFM internet radio with track history and one-click search to the big-four music services.


Status	v0.3.0 — LIVE on Chrome Web Store since 2026-06-09
Install	chromewebstore.google.com/detail/bmdmepddehnpbdffkblbjofgkllmpkgp
Latest tag	v0.3.0
Licence	GPL v2 or later
Landing page	https://davidtkeane.com/rangerhq-tuner
Privacy policy	https://davidtkeane.com/rangerhq-tuner/privacy
Family	Sibling to RangerHQ Radio (WordPress)

What it does

RangerHQ Tuner lives in your Chrome toolbar. Click the helmet icon, pick a SomaFM station, music starts. Audio keeps playing after the popup closes because it's hosted in a Manifest V3 offscreen document.

Every track that comes through gets logged to a capped FIFO history. Each entry in the history has four buttons next to it — Spotify, YouTube, Apple Music, Bandcamp — that open the corresponding service's public search results page in a new browser tab. No accounts, no API keys, no third-party SDK; just a way to find the track on whichever music service you actually use.

Optionally, RangerHQ Tuner replaces Chrome's default New Tab Page with a RangerHQ-branded landing that has the player + live clock + station picker + history + favourites.

Quick links

Architecture — how Manifest V3 + the offscreen audio pattern + the source-adapter pattern all fit together
Adding a Radio Source — drop a single file in src/sources/, no other changes needed
Privacy — what's stored (locally only), what's not, what the four search buttons actually do
FAQ — common questions
Family — sibling projects (RangerHQ Radio, RangerHQ Buddy)

Install

From the Chrome Web Store (LIVE)

Install RangerHQ Tuner from the Chrome Web Store → click "Add to Chrome" → pin the helmet icon to your toolbar.

Developer mode (right now)

git clone https://git.davidtkeane.com/ranger/rangerhq-tuner.git

Then in Chrome:

Open chrome://extensions
Toggle Developer mode on
Click Load unpacked
Select the cloned folder
Pin the helmet icon to your toolbar

Source layout

rangerhq-tuner/
├── manifest.json             # Manifest V3, narrow permissions
├── LICENSE                   # GPL v2 or later
├── README.md
├── CHANGELOG.md              # Keep a Changelog format
├── PRIVACY.md                # canonical privacy policy
├── store/                    # Chrome Web Store assets (not in zip)
│   ├── store-icon-128.png
│   ├── promo-tile-440x280.png
│   ├── marquee-1400x560.png
│   └── screenshots/
└── src/
    ├── background/
    │   └── service-worker.js     # message router + storage gateway
    ├── offscreen/
    │   ├── offscreen.html        # hidden audio host
    │   └── offscreen.js          # owns <audio> + 25s metadata polling
    ├── popup/                    # toolbar popup UI
    ├── newtab/                   # New Tab Page override UI
    ├── options/                  # Settings page
    ├── lib/
    │   ├── messages.js           # message type + target constants
    │   ├── history.js            # history + favourites + search URLs
    │   └── playlist-parser.js    # .pls parser
    ├── sources/                  # extensibility seam — see "Adding a Radio Source"
    │   ├── base-source.js        # RadioSource interface contract
    │   ├── somafm.js             # first concrete adapter
    │   └── index.js              # registry
    └── assets/
        ├── icons/                # 16/32/48/128 toolbar PNGs
        └── img/ranger.png        # master helmet logo

Building the Chrome Web Store package

cd rangerhq-tuner
zip -r ../rangerhq-tuner-v0.3.0.zip \
  manifest.json src/ LICENSE \
  -x "*.DS_Store" -x "*/.git/*" -x "*/node_modules/*"

Final size is ~133 KB.

Reporting issues / suggestions

Open an issue on this repo, or email david@davidtkeane.com.