The ultimate way to listen to online radio in text mode

This post was moved from where it was originally posted. The database mentioned here is not online anymore, email me if you want it.

Mon Nov 8 10:52:13 PM CET 2021

There are many ways to listen to radio from a Linux console. I dare call this way the ultimate way. In some respects it is the best way so far. This is a BASH script I wrote, plus a csv file with about 35,000 radio stations. Just download this tar gz file and unzip the script and the csv file to ~/bin. Or put them in whatever folder you want and change the parameters accordingly. Don’t forget to make the script executable, with chmod +x ~/bin/radio.

This script depends on VLC as a media player and on csvsql, part of the csvkit set written in python. While changing VLC and use a different media player is relatively easy to tweak in the script, using MySQL or other database utility instead of csvsql would require major modifications. Up to you.

The csv file contains the about 30,000 radio stations from the web site Radio Sure, plus another handsome heap of about 5,000 I added from other sources. It may well be the largest radio station database ever.

Using the script

There are two ways of using the script: without arguments, or with one argument. If used with one argument, the argument is the name of the radio station. In this case, the control is returned immediately to the shell, and all the various processes are launched in the background. The name of the station is taken from the csv file. In the csv file, each entry contains two fields for the name of the radio station, one long, probably the full name of the radio station, and which can contain spaces, the other a short name, a handle, without spaces, to be used to invoke VLC to play the radio station as an argument provided to the radio script.

If the script is called without arguments, a prompt listen$ will show. The application is controlled through commands the user has to type.

You can use the select keyword, or its alias s, followed by the id (number) of the radio station. The script then displays info about said radio station. That particular radio station is considered selected, so the command play or its alias p will attempt to play said radio station.

The play command will return the prompt immediately, and in the background it will first check if the URL of its stream is up, and only if it is up will it play the radio station. This is useful since in a previous version I didn’t release to the public, attempting to play a radio station first closed the current VLC instance, if any, then played the requested stream. If VLC was playing a different radio station, and the newly requested station was down, the user ended up listening to neither.

When the user types the play command, the script first invokes VLC muted in the background to check if the stream is on, and only upon success will it fire up VLC to play the requested audio stream. VLC will be executed without any kind of user interface. The user should use an external application to set the volume. I use alsamixer or a python script called pulsemixer.

To stop listening, the user can type the off command. It will shut down VLC, and return the cursor for the user to type the next command.

To exit the application, type quit, or its aliases q or :q. Note that exiting with quit will not shut down VLC, which will continue playing in the background. If you’re in the shell and want to stop listening, just type pkill vlc.

Now you have to know how to invoke VLC with a meaningfull ID number for a radio station. Remember, there are about 35,000 of them available. Type sql and a new prompt will appear. There you have to type a valid SQL request. To simplify the user’s experience, a line is suggested, which can easily be edited to provide a valid SQL request. Some knowledge of SQL is required.

The output of the sql query is shown through less with the -F flag. There you can pick the ID number of the radio station you want to listen to and first select it, then play it.

In the csv file there is the “status” field. It will indicate if the stream is on or off, and will be accompanied by a timestamp. The status field will be updated whenever VLC is invoked. If the stream is on, VLC will play the stream, and the script will update the status field, including the current date as the latest when the stream was found active. If the stream is off, the status line will refelct that fact accordingly, including a timestamp.

The user can also use the command update, which will invoke VLC only once, in the background and muted, to check if the stream is active, but neither upon success nor failure will it invoke VLC a second time to play the stream. It will only update the status field.

The user can browse the over 35,000 radio stations with the commands next and its alias + or previous and its alias -.

There is also the modify command. It will prompt the user to type the number of the field whose contents they wish to modify, then they will be prompted for the new contents of said field. This is useful to add a short name so that radio can be invoked non interactively in the future to play said radio station.

With the add command you can add a new radio station. You will be promted for every field. Be sure you have the URL of the stream.

Modifications do not need to be saved. The csv file is modified in place every time the update, modify or add commands are invoked.

Installing csvsql

I use Debian. I will instruct Debian users. Users of other flavours of Linux do it yourselves.

Install python and pip, like so:

sudo apt-get install python-dev python-pip python-setuptools build-essential
sudo pip install csvkit

In some of my computers, pip complained that agate is not installed. So do:

sudo pip install agate

Sometimes in an old computer with an old kernel an older version should be installed instead, like so:

sudo pip install csvkit==0.8.0

If the installation appears to be successful but running the tools fails, try updating your version of Python setuptools:

sudo pip install --upgrade setuptools
sudo pip install --upgrade csvkit

If your installation complains that you need to upgrade pip, upgrade it like so:

sudo -H pip install --upgrade pip


sudo -H pip3 install --upgrade pip

The application csvsql is invoked with just csvsql. However, sometimes some annoying warnings about locales will show up persistently. In some computers it suffices with invoking csvsql with:

python -W ignore /usr/local/bin/csvsql

to turn off the warnings. But sometimes this is not enough. I still have to figure out what that depends on. By default, my BASH script invokes csvsql with that -W flag. Sometimes it is that flag what causes an annoying behaviour. It varies a lot depending on the PC, the kernel, the version of Debian, and the version of csvsql itself. I guess. The app csvsql behaves very differently in different environments.

Enjoy the script

This is my third attempt at providing a comfortable experience to listen to radio streams using the command line. Some years ago, I did a naive interface using, sigh, dialog. Then I used a BASH script that combined csvsql non-interactively. Upon that I built the interactive interface I am presenting now to the public. Use it, enjoy it, distribute it. Today is January the 12th, 2020. Thanks to for providing this html space. Be excellent to each other. E-mail yours truly at