Installing and configuring the station

The intended audience of this document is people with basic knowledge of Linux systems. Not necessarily admins or programmers, but those who know how to install a package or edit a text file.

TL;DR (ardj done quickly)

$ sudo apt-get install screen icecast0 ezstream mpg123 sox lame vorbis-tools vorbisgain flac mysql-server mysql-client
$ pip install --user ardj
$ mysql
> CREATE DATABASE ardj DEFAULT CHARSET utf8;
> GRANT ALL PRIVILEGES ON ardj.* TO ardj@localhost IDENTIFIED BY 'ardj';
> ^D
$ ardj db-init
$ ardj run
... [gnu screen runs] ...

Different terminal tab:

$ x-www-browser http://127.0.0.1:8080/ &
$ mplayer http://127.0.0.1:8000/music.mp3

System requirements

ardj is Python software, so in theory it should work on any system that can run Python. However, it was only tested on Ubuntu. It does not need much memory or CPU, you will mostly need HDD space for MP3 files and a lot of outgoing bandwidth. It uses a MySQL database (SQLite supported for constrained systems).

You can successfully run a busy radio station on the smallest available Digital Ocean droplet, for example, that's $5/mo.

This manual does not deal with system wide daemons, init scripts etc. You will only need root access to install some third-party components.

Some theory, or how this all works together

If you aren't interested in the internals of a radio station, you can skip to the next section. This section is for the curious, understanding of this is not required.

The front end of the radio station is the streaming server. It reads an MP3 (or Vorbis) stream from a program called "source" and sends it to all connected listeners. It is very efficient and can deal with thousands of connections, taking almost no resources. It only passes bytes from one program to another. We'll use icecast.

The main component is the source. It's a program which reads your music files, decodes them, applies some effects (like ReplayGain or cross-fade), encodes to the desired format (e.g., 64 kbps MP3) and sends it to the streaming server. This is normally ezstream, sometimes ices -- no big difference. This program typically has two modes of operation: it either picks a random file from a folder, which makes it a very basic music player on shuffle, or it calls a plugin to choose which track to play next. This is how ardj works.

ardj itself is a plugin for ezstream and ices0. It uses a database and a plain text playlist file to create a playlist, which can be very complicated.

There are some background tasks from time to time, like ReplayGain calculation. We use a separate worker for that.

That's it.

Installing third party components

ardj requires few other programs that actually do MP3/Ogg transcoding, streaming and related tasks. They cannot be installed automatically. On Ubuntu you can install them with a single command:

$ sudo apt-get install icecast0 ezstream mpg123 sox lame vorbis-tools vorbisgain flac

Installing ardj

ardj is a python software. The easiest method to install it is pip. Normally you would install it as a user package:

$ pip install --user ardj
...
$ ardj intro

Or you can install it in a virtual environment, to avoid messing with your existing packages:

$ virtualenv env
$ . env/bin/activate
$ pip install --user ardj
...
$ ardj intro

Now ardj and all required python components are ready. The command ardj intro will instruct you briefly how to get up running quickly. This document does the same.

Running the station

To start broadcasting, you need to run the following processes simultaneously:

$ ardj loop icecast
$ ardj loop ezstream
$ ardj loop web-server
$ ardj loop worker

For a test run, you can run them in separate terminal tabs or windows, to see what's going on. There will be more or less output (e.g., more for ezstream, less for icecast). You don't need to understand it, only if it says "ERROR". This can happen if you forgot to install a third party component, like mpg123 which decodes MP3 files.

Now, your radio station is running. It plays some built in music with a voice message telling you to upload more music. You can listen to it by adding this line to your music player:

http://127.0.0.1:8000/music.mp3

For a public station you need these programs to run automatically. There is a handy script which runs all components in the background:

$ ardj run

This wil create a GUN Screen session. You can attach to it anytime using the same command, and see what's going on. You should add this script to your crontab (crontab -e), like this:

@reboot ardj run

Now, if your server reboots, the radio will be started automatically. If any component dies (e.g., you upgrade and kill icecast), it will be restarted immediately.

Test it.

Adding cross-fade

By default ardj uses ezstream to generate the audio stream. It is available in most distros, namely in Ubuntu. However, it does not support cross-fade for some reason.

Ices does, the old version (ices0). However, it was removed from most distros for some reason. You would need to download and compile it manually. It's small and very easy to compile.

There is a version with ReplayGain support added by the author of ardj. You can download it from this website:

http://bitbucket.org/umonkey/ices

When you install it, instead of this command:

ardj loop ezstream

Use this command:

ardj loop ices

Perhaps you'll need a modified GNU Screen config. That's it.

Increase web server performance

The built in web server is not supposed to handle much load. If you plan to open your station to your listeners, so that they could vote on tracks, you need to do more. First, install nginx and uwsgi:

$ sudo apt-get install nginx uwsgi uwsgi-python

Example nginx config (/etc/nginx/sites-enabled/ardj):

server {
  listen 80;
  server_name ardj.local;

  root /home/ardj/.local/lib/python2.7/site-packages/ardj/data/webroot;
  charset utf-8;

  allow 127.0.0.1;
  deny all;

  location / {
    try_files $uri @app;
  }

  location @app {
    uwsgi_read_timeout 60000;
    include uwsgi_params;
    uwsgi_pass unix:/run/uwsgi/app/ardj/socket;

    access_log /var/log/nginx/ardj-access.log;
    error_log /var/log/nginx/ardj-errors.log;
  }
}

Example uwsgi config (/etc/uwsgi/apps-enabled/ardj.ini):

[uwsgi]
master = true
idle = 60
vacuum = true

workers = 1
threads = 5
max-requests = 100
no-orphans = true

uid = ardj
gid = ardj
chdir = /

logfile-chmod = 644
chmod-socket = 666

enable-threads = true

home = /home/ardj
plugins = python
#pythonpath = /home/ardj
module = ardj.uwsgi
env = PYTHON_EGG_CACHE=/home/ardj/.python-eggs
env = PYTHONIOENCODING=utf8
env = PYTHONPATH=src

Change paths according to your setup.

Configuring

ardj creates default configuration files for you. It just works out of the box, if you manage to install it.

To manually configure icecast:

$ ardj icecast-config

To manually configure ezstream:

$ ardj ezstream-config

To manually configure ices0:

$ ardj ices-config

To edit playlist (normally you use the web interface for this):

$ ardj playlist

To edit the main ardj config:

$ ardj config

SQL console:

$ ardj db

Follow the log file:

$ ardj log

What to do next

If you have your station running and broadcasting the built in music, it's time to some of your own. Open the web interface and follow instructions.

If you're planning to allow public access to your radio, it might be a good idea to change some passwords. It's the password used for streaming (see iceast/ezstream configs), and the web interface password, which you need to set up on your own, for example, using http basic auth in nginx.

Comments and questions

If you have problems installing ardj, contact me at hex@umonkey.net.