Streaming music with GNUMP3d

Posted by Steve on Tue 19 Jul 2005 at 14:28

If you have a large music collection then streaming it across a LAN, or the internet, is a logical thing to do with it. There are several different streaming servers available in the Debian package archives, here we'll have a look at GNUMP3d.

I've postponed writing about this for a long time, because I'm fairly biased, but I'll try not to let that affect me too much - clearly this is the best multimedia streamer in the world ;)

The GNU MP3/Media Streamer is a simple application which makes it possible to navigate through your audio and video collection via a browser, and stream playlists across a network.

Initially written as an alternative to the Python based Edna software it has evolved a lot since then.

The software supports browsing, searching, and streaming all via your browser with support for MP3, OGG Vorbis, WMA and many other types of audio files.

Installing the software is as simple as running:

apt-get install gnump3d

This will download the software and start the debconf based configuration. When the software is installed it will ask you three questions:

• The directory containing all your media, /var/music by default.
• The port number the server should listen upon, 8888 by default.
• The user the daemon should run as, gnump3d by default.

Each of those settings can be changed as you wish - either initially, or by later running:

dpkg-reconfigure gnump3d

It is suggested that you leave the server running as a dedicated user, although if you wish you could change this. (A common change is create a dedicated musical archive with ownership set to user and group music, then add the gnump3d user to that group).

Once the server has started it will create an index of the tags contained within your music. This tag database will be updated once a day via a cronjob located in /etc/cron.daily/gnump3d - to ensure it is constantly up to date.

Once the media is indexed then the server itself will start, and you can point your browser to http://localhost:8888/ to view your audio collection.

The interface is designed to be clean and simple to navigate, and several different themes are available. To change the theme you wish to use simply click upon the "Preferences" link.

If you wish you to customise the server you can examine and modify the configuration file /etc/gnump3d/gnump3d.conf. This file is commented fairly extensively.

The most common things users change are:

• The default theme.
• The security options.
• The downsampling support.

The default theme can be changed simply by adjusting the following section in the configuration file:

##
#
#  All the output the server produces is generated with the help of
# some HTML template files, these are referred to throughout the
# program and each collection of templates is referred to collectively
# as a 'theme'.
#
#  This next option allows you to specify which theme should be used
# by default.  (Any client can select one of the available themes by
# the use of cookies).
#
theme = Tabular

The security options of the server are two-fold. You can either:

• Restrict access to the server via a password file - less secure.
• Restrict access to the server via IP address - recommended.

To restrict access by username and password simply create a file called .password within the root of your music archive, containing lines of the form:

username1:password1
username2:password2

This will prompt visitors for usernames and password. However if a visitor knows the structure of your archive they can directly download music without being prompted. This is because the server will always stream/serve media without authentication as very few audio players support it. The password option only protects your server from people viewing the HTML interface, and provides a small measure of security by obscurity.

The recommended way to protect your archive is to restrict the machine(s) which can access the server by IP address.

To that end there are two settings which can be used allowed_clients and denied_clients. These two settings are colon-seperated lists of IP addresses which are either allowed to connect or denied access respectively.

The commented out examples show how they can be used:

#
#  Only people on the same subnet, (class C):
# allowed_clients = 192.168.2.0/24

#
#  Allow access to everybody on the LAN and one remote address
#
# allowed_clients = 192.168.1.0/24; 194.194.194.194

Downsampling of media is supported if you have a tool installed upon your server machine which can do the job, such as lame.

To enable downsampling you need to setup a couple of different options:

• First of all you must enable the downsampling option.
• Then specify the hosts for which it is enabled.
• Finally specify the commands required to do the job.

To enable downsampling set "downsample_enabled = 1". This will enable the support.

Once that's done you'll need to decide who gets their media downsampled. The way this is specified is by IP address - with two distinct groups. There are clients who always get their media downsampled, and clients who never have their music degraded.

The most common scenario is when the music server is installed upon a gateway. There the clients on the local LAN side of the gateway should never have their music downsampled, whilst those accessing it from the remote side should always have it reduced.

To do this is very simple, we start by saying "downsample to all clients", then modify that to ensure the local clients get the full bitstream:

downsample_clients = ALL
no_downsample_clients = 192.168.0.0/24

Again these configuration settings are commented in the configuration file.

Finally you need to setup the quality levels - these can be changed by the end user, so if you wish to mandate a particular quality level you should set all of them to the same.

The default quality level is "medium", and is altered via the default_quality option.

For each quality level, and each file type, you must specify a program the stream should be piped through.

The configuration options vary as they are designed to be flexible for different media types. They are constructed by the following "formula":

downsample_"quality level"_"file suffix"

The examples given are fairly good though:

default_quality       = medium
downsample_high_mp3   = /usr/bin/lame  --mp3input -b 56 $FILENAME -
downsample_medium_mp3 = /usr/bin/lame  --mp3input -b 32 $FILENAME -
downsample_low_mp3    = /usr/bin/lame  --mp3input -b 16 $FILENAME -

Here the clients are presented with three different quality levels, 16, 32, and 56 bit streams. They can choose which level they get by altering the preferences in their browser - by default they receive the 32 bit stream.

If you wish to ensure they only ever get the low quality stream set:

downsample_high_mp3   = /usr/bin/lame  --mp3input -b 16 $FILENAME -
downsample_medium_mp3 = /usr/bin/lame  --mp3input -b 16 $FILENAME -
downsample_low_mp3    = /usr/bin/lame  --mp3input -b 16 $FILENAME -

This article can be found online at the Debian Administration website at the following bookmarkable URL:

• http://www.debian-administration.org/articles/189

This article is copyright 2005 Steve - please ask for permission to republish or translate.