The 4 Buttons (Spotify / YouTube / Apple Music / Bandcamp)

The four small buttons that appear next to every track in your History tab are the headline interactivity feature of RangerHQ Radio. This page explains the pattern in detail because it's the pattern that the entire RangerHQ family inherits.

What they do

When SomaFM is playing and a song you like comes on, you usually want to:

Save it to a Spotify playlist
Watch the music video on YouTube
Add it to your Apple Music library
Buy it on Bandcamp to actually support the artist

Each of those services has a public search results URL that takes an arbitrary query string. RangerHQ Radio puts four small buttons next to every history track that link to the corresponding service's public search URL with the artist + title pre-filled. Click one, the service opens in a new browser tab, results are right there.

That's it. No deeper integration. No accounts. No SDK.

The exact URLs

function radio_search_urls( $artist, $title ) {
    $enc = rawurlencode( trim( $artist . ' ' . $title ) );
    return array(
        'spotify'  => 'https://open.spotify.com/search/' . $enc,
        'youtube'  => 'https://www.youtube.com/results?search_query=' . $enc,
        'apple'    => 'https://music.apple.com/search?term=' . $enc,
        'bandcamp' => 'https://bandcamp.com/search?q=' . $enc,
    );
}

These are byte-for-byte the same URLs that RangerHQ Tuner uses in src/lib/history.js. The pattern was born here, in the WordPress version, and ported to Chrome.

Why "link out" rather than "play in-place"?

This is the architectural decision that earns every other property of the plugin. Embedding Spotify / YouTube / Apple Music players inside the plugin would require:

Service	What integration would cost
Spotify	OAuth 2.0 + premium-account-gated Web Playback SDK + your-IP and listening-history flowing to Spotify even when you're not actively using them
YouTube	Either the YouTube IFrame Player (which shows video, not just audio — different product) or the YouTube Data API (10,000 quota units/day free tier + an API key that becomes public in a WordPress plugin)
Apple Music	MusicKit JS + a public API key + Apple-account auth + the user must have Apple Music to play anything
Bandcamp	No public playback API exists. Their "embed player" widget per-album is the only path, requires per-track embeds, doesn't work for search results

Cost summary: OAuth + premium gating + API keys leaking through the WordPress source + privacy reset (now we're touching your accounts on four services) + Plugin Check / Web Store review storms.

The 4-button link-out pattern costs nothing. Public search URLs are universally accessible, no auth, no API key, no quota, no SDK, no third-party JavaScript loaded into your wp-admin. The plugin stays under 50 KB. The reviewer can verify the URLs in five seconds.

The trade-off you accept

You don't get one-click play. You get one-click search, and then YOU pick the result. That's a slightly worse UX for the case where the service's #1 result is exactly the track you wanted (which is most of the time).

But you get a dramatically better product on every other axis:

✅ Works on a free Spotify / Apple Music / YouTube account
✅ Works if you have NO account on those services
✅ Doesn't ship your listening history to four music platforms
✅ Doesn't break when Spotify deprecates a SDK version
✅ Doesn't require WordPress admin to maintain API keys
✅ Passes wp.org / Chrome Web Store review cleanly

For a free open-source plugin where the alternative is "don't ship it at all because of all the auth complexity," the 4-button pattern is the right call.

Discoverability

When you read the plugin description on wp.org or the davidtkeane.com landing page, the 4-button affordance is what makes people install. Most WP plugins for "audio in admin" just play radio. RangerHQ Radio plays radio AND helps you find your favourites elsewhere — that's the differentiator.

Where this pattern came from

The pattern was already common in dedicated music-discovery sites (last.fm, hypem.com, etc.) that link out to streaming services. RangerHQ Radio adapted it to "you heard this on the radio I'm playing in your wp-admin — here's where to find it later." Same idea, different surface.

Where this pattern went next

RangerHQ Tuner (the Chrome browser sibling) ported the exact same URL builder + the exact same 4-button UI row to a JavaScript module. Look at src/lib/history.js in the tuner repo — searchUrls() is the same function. The two implementations evolve together.

When future RangerHQ family members need this affordance (e.g. a hypothetical RangerHQ Discord bot that posts "Now playing on the WP admin" and provides search links), they should mirror the same URL templates from this page. One canonical source of truth, ported as needed.

Customising the buttons

For now, the four services are hard-coded in radio_search_urls(). There's no admin UI to add/remove them.

If you'd like to:

Remove a service (e.g. you don't want Apple Music): Edit inc/history.php and the rendering loop in radio_render_history_page() to drop that key.
Add a service (e.g. Tidal, Deezer, Discogs, Genius): Add a new URL template to radio_search_urls() and a new link in the rendering loop. Pull requests welcome — see Reporting issues.