Fetch and play internet radio stations directly from the command line
- Play radio stations from the SHOUTcast and SomaFM directories.
- Manage a list of favorite radio stations.
- Use multiple audio players like arradio-player, mpv, vlc and ffplay to play internet radio stations.
- Optional UI (fzf pseudo-user interface) with color theme support.
- IPTV support for playing TV streams from M3U playlists.
- Common tools found on most UNIX systems: (bash, cut, grep, sed, head, cat)
- XML tools are required to parse URL responses from SHOUTcast and SomaFM directories
- External audio player. This program does not play URL streams directly, this is delegated to an external audio player that should be installed on the system. The following ones are detected automatically if installed.
- (optional) External command for the User Interface: fzf
To install arradio paste that in a macOS Terminal or Linux shell prompt:
curl -fsSL https://raw.githubusercontent.com/sepen/arradio/master/arradio | bash -s install- The one-liner command from above installs arradio to its default
$HOME/.arradio - It will place some files under that prefix, so you'll need to set your PATH like this
export PATH=$HOME/.arradio/bin:$PATH - The installation explains what it will do, and you will see all that information. Consider adding this line to your ~/.bashrc or ~/.bash_profile or make sure to export this PATH before running arradio. The installation explains what it will do.
- The one-liner installation method found on arradio uses Bash. Notably, zsh, fish, tcsh and csh will not work.
arradio is being actively developed, and you might want to upgrade it once in a while. Please follow the instruction below:
arradio upgradearradio help
Usage:
arradio [command] <flags>
Commands:
install Install arradio itself
upgrade Upgrade arradio itself
list List top streams (enabled services only)
search [string] Search across enabled services
play [stream-id] Play to specified stream
info [stream-id] Show info for a stream
fadd [stream-id] Add to favorites
fdel [stream-id] Remove from favorites
flist List favorites
ui Start UI (fzf required)
tlist List installed UI themes
env Show environment variables
version Show version
help Show this help
Flags:
-s, --services [csv] Limit services (shoutcast,somafm,iptv)
-l, --limit [num] Output limit (default: 50)
-o, --output [fmt] Format simple|wide (default: simple)
-p, --player [cmd] Player command (default: mpv)
-t, --theme [name] UI theme (default: basic)
-b, --no-color Disable colors
-n, --no-cache Disable cache
-d, --debug Debug messagesThe configuration file, by default located at $HOME/.arradio/config, uses a simple variable: value format.
Lines starting with # are treated as comments.
Example:
# ~/.arradio/config
player_cmd: mpv --no-video # Command used to play streams
ui_theme: retrowave # Name of the UI theme
output_limit: 200 # Maximum number of results to display
output_filter: wide # Filter type for output
no_cache: 1 # Disable caching when set to 1 NOTE: This file is not created by default, so if you need to make changes to the default values, consider creating this configuration file. You can grab an example from here
Configuration values can come from several sources:
- As an environment variable
- As a value in the config file
- As a command line optional flag
The previous order also indicates the order of precedence to take. For example, to override the default UI theme:
export ARRADIO_UI_THEME=nord
arradio uiThe above can be also override by setting a value in the config file:
# ~/.arradio/config
ui_theme: purpleLastly all from above can be override as an optional flag through the command line:
arradio ui --theme molokaiIPTV support in arradio is controlled by the enable_iptv option in your config file (~/.arradio/config).
When enabled, the UI lists IPTV streams as another “service” (like SHOUTcast or SomaFM).
It expects M3U playlists (or compatible formats), which arradio parses to present channels.
Playback is handled by your configured player (player_cmd, e.g., mpv, vlc, etc) but make sure your player_cmd does not include options that disable video output (such as --no-video), otherwise IPTV channels won’t show video correctly.
Example configuration enabling IPTV and pointing to an M3U playlist:
# ~/.arradio/config
player_cmd: mpv
output_limit: 500
enable_iptv: 1
iptv_url: https://raw.githubusercontent.com/iptv-org/iptv/refs/heads/master/streams/es.m3uLook for radio stations with the words rock and metal and limit the list to only 5 stations with wide output format:
arradio search rock -l 5
STATION GENRE NAME
99498012 Rock ROCK ANTENNE
99497966 Heavy Metal ROCK ANTENNE Heavy Metal (Germany)
99497948 80s ANTENNE BAYERN 80er Hits
1542116 Pop POWERHITZ.COM - THE OFFICEMIX
99497950 Rock ANTENNE BAYERN Classic RockTo play a radio station then use the stream-id from first column:
arradio play 99498012By default this is empty but you can mantain a list of favorite radio stations.
To list my favourites:
arradio flist
STATION GENRE NAME
1210771 Funk GENERATION SOUL DISCO FUNK RADIO [HD]
1340450 Misc AlienWare
1528122 Jazz JAZZGROOVE.org - The Jazz Groove
1862204 Drum and Bass DnBRadio.com
99497996 Pop ANTENNE BAYERN
99500354 Classic Rock Classic Rock 109 - True Classic Rock!
99504568 Downtempo Nordic Lodge - Copenhagen
99518870 Salsa RADIO PANAMERICANA WEB
99540705 Rock PureRock.US - America Pure Rock
99568323 Dance Dance Wave Retro!
99571797 Techno Minimal Mix Radio
99576960 Reggae Roots Legacy RadioTo add a radio station you can do it in several ways.
Maybe you already have a stream-id from a previous search. In this case just run something like:
arradio fadd 99498012You can also add radio stations from other locations. All you need is a valid stream URL. For that just create a new file under favorites directory like that:
cat > $HOME/.arradio/favorites/downtuned << __EOF__
id: downtuned
br: 128
genre: Rock
info: Groovy Music Sanctuary (https://www.downtunedmag.com)
url: http://195.242.237.14:8020/stream
__EOF__Similar to adding a stream-id to favorites, you can remove it with something like:
arradio fdel 99498012arradio can run in pseudo-terminal User Interface mode. You just need to have fzf installed and then you can run the following command to start UI mode:
arradio uiarradio can perfectly work in UI mode without any theme installed. In this case it will use a black and white interface. But maybe you prefer to use a theme with fancy colors.
The themes are provided separately and their installation and upgrade will be manual. To see the current themes available in this repository go to ui-themes.
Most themes also have a 256-color (8-bit) variant for terminals that do not support 24-bit truecolor. These 8-bit variants have names ending with 8. For example, retrowave has the 8-bit variant retrowave8.
You can use any theme, but for optimal appearance, choose the 24-bit version if your terminal supports truecolor; otherwise, use the 8-bit variant.
| Name | Screenshot | Description |
|---|---|---|
| adwaita | Dark foundation with calm blues, natural greens, and gentle yellow accents | |
| basic | Simple, portable color scheme optimized for compatibility with 256-color terminals | |
| chalkboard | |
Dark board-like background with off-white text and subtle neon accents |
| dracula | Dark, high-contrast palette of purples, pinks, and teals for vivid clarity | |
| gruvbox | Warm retro palette of earthy browns, oranges, and yellows based on morhetz/gruvbox | |
| molokai | Focused dark palette with vibrant accents for coding or browsing based on tomasr/molokai | |
| neoninferno | Blazing neon accents over a subtle charcoal-purple background | |
| nord | Cool, north-inspired tones of blue, gray, and icy white based on arcticicestudio/nord-vim | |
| partypop | |
Ultra-bright, festive colors with clear contrasts for a playful vibe |
| purple | Deep purple scheme with soft highlights for a moody yet elegant feel | |
| rasta | Bold red, gold, and green on a dark base for reggae-inspired energy | |
| retroblast | Bright primaries and neon tones evoking ZX Spectrum and arcade classics | |
| retrowave | Deep blue background with neon pinks and cyan highlights for synthwave feels | |
| seoul | Light, balanced scheme with subtle contrasts for clean readability based on junegunn/seoul256.vim | |
| seouldark | Dark, understated scheme with smooth contrasts for extended use based on junegunn/seoul256.vim |
This is an example about installing some themes:
url="https://raw.githubusercontent.com/sepen/arradio/master/ui-themes"
themes="dracula neoninferno partypop"
cd $HOME/.arradio/ui-themes
for theme in $themes; do curl -fsSL -O $url/$theme; done
cd -To list all available themes locally, run:
arradio tlist
THEME PALETTE DESCRIPTION
basic 8-bit Simple, portable color scheme optimized for compatibility with 256-color terminals
chalkboard 24-bit Dark board-like background with off-white text and subtle neon accents
dracula 24-bit Dark, high-contrast palette of purples, pinks, and teals for vivid clarity
neoninferno 24-bit Blazing neon accents over a subtle charcoal-purple background
partypop 24-bit Ultra-bright, festive colors with clear contrasts for a playful vibe
rasta 24-bit Bold red, gold, and green on a dark base for reggae-inspired energy
retroblast 24-bit Bright primaries and neon tones evoking ZX Spectrum and arcade classics
retrowave 24-bit Deep blue background with neon pinks and cyan highlights for synthwave feelsBy default, arradio reads the default theme from your configuration file:
# ~/.arradio/config
ui_theme: gruvboxYou can also temporarily override the theme directly from the command line when launching arradio:
arradio ui -t gruvbox