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.
$ 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
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.
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.
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
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.
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.
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.
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.
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
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.
If you have problems installing ardj, contact me at hex@umonkey.net.