STUMBLE ◎ RADIO

The actual TUI, shown with demonstration stations and listening data.

What it is

Stumble Radio is a terminal radio player for curious ears. Search the world’s radio stations, stumble into something new, and keep your favourites close. Built with Python and SQLite, with a local station catalogue for fast search. Use the keyboard or mouse; the layout adapts to smaller terminals.

Install

Install Stumble Radio and its audio dependencies with one command:

curl -fsSL https://raw.githubusercontent.com/mugendi/stumble-radio/master/install.sh | sh

This simple installer checks that your system has all the needed tools installed such as curl, tar, mpv, FFmpeg, and uv, and explains why each is needed. It does not need root access nor does it install these tools for you.

When done, run stumble-radio in a terminal.

Windows users need WSL with working audio. See the getting started guide for requirements and manual installation methods.

Press s to Stumble, t to Teleport, Ctrl+F to search, Ctrl+O for Podmoro, and ? for help.

Installation, audio dependencies and first launch · Troubleshooting · Development

Why

I enjoy music as I work. I actually find it hard to work in absolute silence. I have always wanted a good terminal music/radio player, and I have tested several without ever being very happy with them. I once even tried building my own player, Geek Play, but abandoned the project when a close collaborator, Joseph Ndung’u, passed on.

Many times I just listen to Radio Garden. But that means adding one more browser tab, which sometimes disconnects. I also think the search and station sorting features can be greatly enhanced.

Finally, I got researching. With the aid of AI, it is now much easier to build a real terminal radio with a tonne of features. Here is what Stumble Radio can do.

Features

Listen, record and drift off

Truly battery included. Stumble Ration inclides all the playback features I have ever wanted from a radio/music player baked in.

• Play/pause, previous/next station, volume controls, and broadcaster song metadata.
• Tune a five-band equalizer and up to +12 dB gain, with presets, live preview and saved settings; automatic loudness leveling starts enabled by default.
• Save and restore your master volume automatically between sessions.
• Record the original audio while continuing to browse or pausing your listening.
• Retry interrupted streams and resume when the internet comes back.
• Automatically skip dead or silent stations during random discovery.
• Set a sleep countdown with a fade, then stop playback and recording.

Playback, recording, sleep and keyboard controls →

Discover somewhere new

This is probably my most favorite feature. I start the radio, teleport to a random place and then stumble upon amazing stations that I end up adding to my favorites. And I can even set shuffle mode to Music Only so that I am roaming the world discovering only channels that focus mostly on music.

Even better, I can perform an advanced search like 'tag:country country:US' which finds country radio stations in US and then do my teleporting and stumbling within this exclusive list.

It is truly interesting.

• Stumble: random radio that learns from quick skips and longer listens.
• Teleport: spin through country names, land somewhere, and listen there.
• Shuffle modes: Anywhere, Music-only, Talk/News, Your language, and Nearby.

Stumble, Teleport and shuffle modes →

Find exactly what you want

One of the features I have always wished Radio Garden did a better job at. Now you can perform truly advanced full text search.

• Filter by name, country, region, genre/format, language, codec, bitrate, HTTPS, stream health, or geographic radius.
• Combine search operators, phrases, AND (+), OR (|) and parentheses.
• See every active filter, clear them in one click, and click any header to sort.
• Sort by votes, recent directory plays, name, country and more, with matching favourites first.

Search syntax, all filters and worked examples →

Keep your own dial

Discovered a gem? Favourite it, always be in a position to step back and find stations you love.

• Save favourites and browse Explore, Favourites, History, or Unheard.
• Right-click a station to save notes and personal tags; search remembered details like "happy tunes".
• Keep the currently playing station pinned above results with a clear ▶ marker, ready to favourite with f.
• Open a compact, searchable Quick tune picker.
• Browse a local SQLite catalogue, quietly updated in the background.
• See one row per identical stream URL, keeping your favourites and history intact.

Favourites, browsing, catalogue sync and storage →

See where you have been

As you play music, discover new tunes and develop new tastes, you habits change too. This feature allows you to see what you are spending most time listening to.

• Open your listening journal for time per station, top stations and recent sessions.
• Collect a radio passport of countries heard and track country/genre diversity.

Listening journal and radio passport →

Find that song again

If you are like me, and if you happen to teleport around as much as I do, then you know that situation where you remember listening to Lupe Fiasco song but cannot remember what channel it was. This feature keeps a track of your listening history and allows you to jump back and rediscover gems for up to 1 year! Simply press l (Last Play) and search for "Lupe..."!

• Last Play Search: search remembered artists, songs or stations you heard.
• See where and when you heard each track, newest first, and tune that station.
• Search a local full-text index; plays older than one year are removed automatically.

Last Play Search →

Why PODMORO in a radio app?

Wait, I can explain. And I believe it makes sense too.

Okay, now this is important; for your health. Stumble Radio bakes in a Podmoro scheduler so you can receive periodic musc interruptions reminding you to hug your cat. Even better is that you get to record and customize your reminders yourself, in your own voice or have your loved one'd voice remind you. You will likely heed to that voice more.

• PODMORO: custom focus/break profiles, weekly schedules and daily focus totals.
• Interrupt the music with your own MP3 voice prompts — or let the built-in announcer (Alan or Jenny, generated locally with Piper) fill empty folders for you.
• Add water, stretch, eye-break or custom command folders; preview clips and captions.
• Pause, skip, extend, snooze or silence reminders without losing your place.

Podmoro, scheduling and step-by-step sound setup →

Contributing

Bug reports, ideas, and pull requests are welcome. For local setup, project structure, and development checks, see the development guide.

Coming soon

We can still do better with catrgorizing these radio stations. Also the radio browser api that we rely on has a lot of repeated channels (about 12k), misspellings and more. We need cleaner data.

I plan to embark on this task soon. If you know another (cleaner) free api, please share.

License

Stumble Radio is available under the MIT License.

Station directory provided by the Radio Browser community.