I agree to the use of cookies in accordance with the Sourcefabric Privacy Policy.

Support our media development efforts

Please note: due to the quarantine measures required by the coronavirus outbreak, we are unable to answer the phone in our Prague office. Please send an email to [email protected] and someone will get back to you as soon as possible.

Who, what, when, where and why

Get the latest news about Sourcefabric software, solutions and ideas.


Schedule stream recordings from the command line, Part 2


In a follow up to Schedule stream recordings from the command line, Part 1, which analyzed some of the options to record streams, I would like to shift focus to another important aspect of stream recording, configuration.

How to configure and schedule stream recording

In my previous post I assessed which application to use for recording live streams. I decided in favour of the VLC player, running from the command line. In this post I will go into more detail on how best to configure VLC to do the job of recording and transcoding streams. I will also explain a simple but efficient way to schedule a recording on Linux using the "at" command. I finish this post by putting it all together in a bash script that I frequently use to schedule and record shows from web radio streams: streamplan.sh

Install VLC

sudo apt-get install vlc
sudo apt-get install libavcodec-extra-53

The second package is suggested by VLC for transcoding, which I will discuss later.

Using VLC to record mp3 streams

Now let's record some streams. The first example is the German talk radio using a variable bitrate, the second is the stream from NPR using a constant bitrate. Both streams will record 20 seconds worth of audio.

cvlc "http://www.deutschlandradio.de/streaming/dkultur.m3u" 
--sout file/mp3:DLF-test.mp3
cvlc "http://www.npr.org/streams/mp3/nprlive24.pls" --sout file/mp3:NPR-test.mp3

What happens? To run VLC on the command line on Linux you use "cvlc". This is followed by the stream URL. And following "--sout" we specify that we are recording a file in mp3 with the filename given after ":" .

You can use the absolute path along with the filename and the file will be written to that location on your machine, given VLC has the rights to write the file.

To stop the recording process, press "Ctrl+C" in the terminal window where VLC is running.

Make VLC stop automatically after recording

As I mentioned in my previous post, the ways in which VLC can be told to stop after a certain number of seconds look good in writing, but behave strangely in action. The command line help lists two options to terminate VLC with parameters from the command line:

--run-time=/ The stream will run this duration (in seconds).
--stop-time= / The stream will stop at this position (in seconds).

While "run-time" is meant to kill VLC after running for a given number of seconds, "stop-time" looks into the file VLC is playing and stops at a position of the file given in seconds.

Dealing with a continuous live stream (and not a file with a beginning and an end), it seems that "run-time" is the command to use. But it turns out that all players I looked at had issues with stopping the process automatically; this goes for VLC as well.

After digging through support requests, tutorials and discussions, I concluded that the only bullet-proof way to terminate VLC meant using both commands.

The following examples will record 20 seconds worth of audio and then automatically stop.

cvlc "http://www.deutschlandradio.de/streaming/dkultur.m3u" 
--sout file/mp3:DLF-test.mp3 --run-time=20 --stop-time=20 vlc://quit
cvlc "http://www.npr.org/streams/mp3/nprlive24.pls" 
--sout file/mp3:NPR-test.mp3 --run-time=20 --stop-time=20 vlc://quit

Look in the folder and you will see two files with very different sizes. NPR is about 80 kB in size, DLF about 320 kB. This is due to the compression of the stream. DLF streams in stereo with 128 kbps and a sample rate of 44100 Hz while NPR streams in mono with 32 kbps and a sample rate of 22050 Hz.

In the previous post I mentioned that stopping VLC after a given duration gets unexpected results. The two lines listed above are examples of this strange behaviour. While the second command line records the NPR stream as expected and quits after 20 seconds, the first line command line records 20 seconds of the DLF stream and then records 20 seconds again, overwriting the original stream. I haven't tested this properly, but I blame the variable bitrate (DLF). We will deal with this issue later.

Schedule your stream recording with the "at" command

Now that we have a command line that records a stream and stops after a given duration, we can schedule our first recording. To do so, use the "at" command, which schedules commands to be executed once in the future at a specified time. (If you plan to record events periodically at fixed times, you should familiarise yourself with cron.)

"At" is a neat way to tell your machine to do something "at" a certain time and date. There are a number of ways to specify time, but we will use the format:

at hh:mm YYYY-MM-DD

e.g. the April 1, 2015 at 10:15 pm would be:

at 22:15 2015-04-01

If you type this line in the terminal and hit return, the cursor line starts with "at>" and you can schedule one or more commands. Once you are done, press Control-D at the beginning of the line and you will return to the prompt.

Recording 20 seconds of NPR on the first of April 2015 at 10:15pm would look like this in your terminal:

$ at 22:15 2015-04-01
warning: commands will be executed using /bin/sh
at> cvlc "http://www.npr.org/streams/mp3/nprlive24.pls" 
--sout file/mp3:/path/to/NPR-test.mp3 --run-time=20 --stop-time=20 vlc://quit
job 117 at Wed Apr 1 22:15:00 2015

Congratulations! You just scheduled your first stream recording! One thing is important: replace the relative path of the local file with an absolute path to which you want to record the file, like your home directory.

You can see the job ID right here in the last line. If you make a mistake, you can remove this scheduled process by typing:

at -r 117

Displaying a list of all scheduled tasks, type:


Kill the recording with sleep and pkill

As mentioned before, the way VLC terminates itself does not always work as expected. Here's a more reliable way to kill the recording:

  1. Start the recording with a run-time that is longer than what you actually need
  2. Kill the recording in a second scheduled "at" process using pkill

Firstly, install pkill as part of the procps package

sudo apt-get install procps

Now you can schedule the above command and replace the 20 seconds with 200 seconds or more if you want. As the second command, type:

echo "sleep 20; pkill vlc" | at 22:15 2015-04-01

What this does: At the same time you start the recording with "at", a second process is started. It sleeps for 20 seconds and then kills the vlc process.

Transcoding the recorded stream to mp3

Let's take a closer look at the simple recording command we use:

cvlc "http://www.deutschlandradio.de/streaming/dkultur.m3u" 
--sout file/mp3:DLF-test.mp3

It says "mp3" twice. It is tempting to replace "mp3" with "ogg" and hope it will transcode the stream from one format into another. If you try this, you can even open the resulting .ogg file in VLC and play it. But it has not been transcoded. If you check the audio information on the file, it will still give you the mp3 information you originally had. VLC is just smart enough to play the file even though it has the wrong file ending, technically speaking.

Most audio players play MP3, but not all play OGG or Windows Media files. So let's alter our command to automatically transcode any stream into MP3. The following example will grab the Windows Media stream of BBC Radio 5 Live and transcode it into an MP3-file in stereo with 128 kbps and a sample rate of 44100 Hz; "dst" is followed by the local filename, but you can also use an absolute path.

cvlc --sout "#transcode{acodec=mp3,ab=128,channels=2,samplerate=44100}
:std{access=file,mux=mp3,dst=BBC5.mp3}" http://bbc.co.uk/radio/listen/live/r5l.asx

As you can see, this command does not terminate after a certain time. It just keeps running until the drive is full. I tried to use run-time and stop-time in relation to the transcoding, but that did not work at all.

To use the transcoding option of VLC when recording live streams, we have to use the alternative way of killing the recording process described above.

Based on this little research, I put together streamplan.sh which is a command line tool to schedule and record streams. You can download or fork the script streamplan.sh from https://github.com/MiczFlor/streamplan.

As a prerequisite, you will need to install the id3v2 command line tool to alter ID3 tags in the recorded file, plus your choice of recorder, such as cvlc and pkill to stop the recording. On Debian or Ubuntu, you can do this with the command:

sudo apt-get install id3v2 vlc-nox procps

Please let me know if you find the script useful, and post your own stream recording tips in the Airtime Hacks forum!

  • Take Airtime Pro for a test spin. This month we are offering one month free with streaming. Just use the promo code wrd2014 for World Radio Day.