radiosh

A minimalist, lightning-fast terminal radio player written in Bash.

Features a searchable station database, favorite management, and Vim-style navigation.

Features

• Online Search — Instantly search thousands of stations via the Radio-Browser API
• Favorites — Save your favorite stations to a local M3U playlist
• Vim-Style Navigation — Use h, j, k, l to navigate menus (powered by fzf)
• Popularity Sorting — Online search results are automatically sorted by votes/popularity
• Easy Installation — Comes with a built-in installer for quick setup

Prerequisites

radiosh needs these tools at runtime:

• fzf — Fuzzy finder for the interface
• mpv — The engine that plays the audio stream
• jq — To process API search results
• curl — To fetch station data

Installation

Clone the repository:

git clone git@github.com:JeromeTDev/radiosh.git
cd radiosh

Make the script executable:

chmod +x radiosh

Run the built-in installer:

./radiosh --install

This validates the required dependencies and copies the script to ~/.local/bin/radiosh.

If dependencies are missing, install them first with:

./radiosh --install-deps

Supported package managers for automatic dependency installation are apt-get, dnf, pacman, zypper, and brew.

If you prefer, you can also install the dependencies manually using your system package manager and then run ./radiosh --install again.

Update your PATH (if not already done):

Bash/Zsh:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # or ~/.zshrc

Fish:

fish_add_path ~/.local/bin

Usage

Simply type radiosh in your terminal to start:

radiosh

• Select a saved favorite to play immediately
• Select __ONLINE_SEARCH__ to find new stations
• Press y after playing an online station to add it to your favorites

CLI Options

radiosh --help
radiosh --install
radiosh --install-deps

• --help shows the available command-line options
• --install checks dependencies and installs radiosh to ~/.local/bin
• --install-deps installs missing runtime dependencies using a supported package manager

Configuration

Favorites are stored as a standard M3U playlist at:

~/.config/mpv/radio.m3u

License

MIT License — see LICENSE for details.