Serve Up Your Music with Zeya
Have you always wanted to set up your own music station to stream your latest music collection to your friends or colleagues? Have you been thinking lately of setting up an always-on music streaming server so that you can just open up your web browser and listen to your favorite tracks? A music server is great in a dormitory, laboratory or office where the file server can double up as the music server! I will show you how using Zeya.
Let's get started quickly and stream music real fast. Primarily, we're going to look at Zeya, but we'll also take a brief look at some of the other options that you might consider in addition to Zeya.
A music server serves music, like a web server serves web pages. The Zeya server is written in pure Python. You should preferably use Python 2.6+, but Python 2.5+ should also work. Zeya uses external encoding and decoding software for various audio formats. Hence, you should have the Ogg Vorbis encoder (oggenc) installed on your system and decoders for the 'flac' (flac) and 'mp3' (mpg123) formats if you plan to stream audio files in those formats.
Currently, the Zeya server is officially known to work correctly on Ubuntu 9.04+ and Debian testing. During the course of writing this article, I have also found Zeya working correctly on Arch Linux 2009.08+ release. Since, no distribution specific feature is used by Zeya, it should work on other Linux distributions too.
Zeya is available in Debian testing and unstable and can be installed by using:
# aptitude install zeya
We're going to install Zeya from the source, if you decide to use the Debian package, use the command "zeya" instead of "./zeya.py" when running Zeya (see below).
To get Zeya from source: clone the Zeya source from the git repository (For a basic guide to git version control system, please see the link in the resources section):
$ git clone http://web.psung.name/git/zeya.git
You should now have a 'zeya' sub-directory in which the source code for the Zeya server lives. Before you start Zeya, you should ensure that you have the above mentioned encoders and decoders installed. Usually, they will be available in your distribution's package repository. Once you have gotten them installed, start the Zeya server. Invoke Zeya with the '--path' option to specify the location of your music files on the local filesystem. For example:
$ ./zeya.py --path=/home/r00t/Music/
You should see:
Using 'dir' backend.
Scanning for music in '/home/r00t/Music'...
Listening on port 8080
We'll go over this in more detail, but the important point is that if you see the above output, the Zeya server is up and running. Open a HTML5 capable browser (see below) and navigate to http://127.0.0.1:8080, or http://<IP-Address-of your system>:8080 if you are accessing from a remote machine. Figure 1 shows music playing in the web client.
Zeya uses a HTML5 feature which allows audio embedding, so the browser requirement above is not a typo: you need a browser which supports some of the features slated for HTML5. Currently known to work are Firefox (3.5 or later, 3.6+ recommended), Google Chrome or Chromium (recent builds, 4.0.223+, works best with 22.214.171.124+), and IE 6-8 with the Google Chrome Frame plugin. The install file contains more info on the browser requirements.
No dependency on Flash
If you know a little bit about HTML5 then you know that part of its motivation is to eliminate the need for proprietary plugins for rich media. So, instead of requiring a Flash plugin in your browser, Zeya server uses an audio embedding feature of the HTML5 standard, which allows you to embed a ogg file using the <audio> </audio> tag (Refer to http://www.w3schools.com/html5/tag_audio.asp). The Zeya server decodes music files in non-Ogg formats and encodes your music back as Ogg streams and serves it. (Hence the need for flac and mp3 decoders.)
As you might have already guessed, zeya.py is the starting point of the Zeya server. Currently, zeya.py takes the following options from the command line:
$ ./zeya.py --help
Usage: zeya.py [OPTIONS]
Display this help message.
Specify the backend to use. Acceptable values:
dir: (default) read a directory's contents recursively;
rhythmbox: read from current user's Rhythmbox library
Directory in which to look for music, under --backend=dir.
Specify the bitrate for output streams, in kbits/sec.
Listen for requests on the specified port. (default: 8080)
Require basic HTTP authentication and only allow users named in
the specified file. The file should be in 'htpasswd' format.
The option values are:
- backend: Zeya supports two backends for serving music. You can ask Zeya to
serve music from a directory on your filesystem which contains the music files. By default, Zeya assumes this as the backend and looks for music files in the location from which Zeya server is started. The other option is to tell Zeya to read the music to serve from the current user's Rhythmbox library (in which case you must have a Rhythmbox library).
- path: The 'path' option is used to specify the location for the music files in
case you are using the directory backend.
- port: As you saw above, Zeya binds to port 8080 by default. You may change
that using the option '--port'
bitrate: The bitrate at which audio is streamed to the clients
- basic_auth_file: You can make use of basic HTTP authentication by specifying a
user/password file in 'htpasswd' file format. Enabling this option, you can control who is able to acess the services of Zeya. Once you enable this option, an authentication dialog pops up in the browser and only if the authentication is successful, will Zeya start streaming music.
Zeya's music database
If you are using the directory backend to serve your music, you will notice the file 'zeya.db' in your music directory. This is Zeya's music database. It contains a three tuple (Artist, album, title) for each music file in the directory. It uses this information to load the music library in the client. Zeya uses the TagPy library for obtaining this information from the music files.
Source tour of Zeya
Alphabetically, these are the Python source files and what they do:
- backends.py: The code in this file acts as interface with the supported backends.
All backends should implement the Python interface 'LibraryBackend' defined in this file.
common.py: A small file containing some utility functions
- decoders.py: The code in this file interfaces with the system's decoders
for mp3 and flac files.
directory.py: This implements the directory backend of Zeya.
- options.py: This handles the command line option parsing, error
handling and sets default values for options.
rhythmbox.py: This file implements the Rhythmbox backend
- zeyaclient.py: This is a sample implementation of a non-web, rudimentary
command line client for Zeya.
- zeya.py: This is the main code for Zeya which takes care of
serving music to clients by calling upon various functions from the previous files.
zeyatest.py: This is the Zeya test suite.
- resources/library.html: This is the HTML page for the web based client that you
see when you open the URL to Zeya in your browser.
client functionality for communicating with the Zeya server.
testdata/: This sub-directory contains some test data for the test suite.
doc/: This sub-directory contains the Docbook sources for the Zeya manual pages.
You can also start Zeya at boot time by creating an init style script. For example, on Ubuntu or other systems, which use Upstart you can write an upstart job in '/etc/init'. Write the following lines into a file /etc/init/zeya.conf:
# Start zeya
description "Start Zeya music server"
start on startup
exec python /home/r00t/zeya/zeya.py --path=/home/r00t/Music
This will start the Zeya server at boot time.
Now that we've had a detailed look at Zeya, I will briefly mention some other software in the world of Open Souce which allows you to setup a music server. It's good to know what else is out there!
Music Player Daemon
Music Playing Daemon (mpd) is a daemon that servers music to connected clients. Compared to Zeya, 'mpd' is a more feature rich. mpd is known to run on all the major Linux distributions and other Unix systems such as OpenSolaris, FreeBSD, NetBSD and MacOS X.
Clients for mpd exist as desktop clients, command line utilities and in the form of web applications. It's very popular in the community of music lovers and a number of hacks for doing cool stuff are documented at the project website. For further details on mpd, please see Resources.
GNUMP3D is a streaming server for MP3s, OGG vorbis files, movies and other media formats. It is no longer maintained as of a couple of years back, but the source code is still there to try out. It's completely written in Perl. It's very simple to setup and use, like Zeya.
Please look up the GNUMP3D homepage given in the Resources.
Ampache is a PHP web application which can be setup to serve music over HTTP. It needs an Apache Web server and MySQL database. It can also be setup to act as a client for the Music Playing Daemon (mpd).
Installation and configuration is modereately complex and detailed guidelines can be found at the project website given in the Resources.
Note that each of the above three projects require a Flash browser plugin to be installed at the client side.
A couple of the things I really like about Zeya is its "no - Flash" requirement (non-requirement?) and the simplicity of the design. As a user, I would like more features, hopefully those will come in time.
Please note that Zeya is a work in-process and some minor details might change by the time you read this. If you encounter bugs or desire features, report them on the Zeya mailing list.
- Zeya project homepage: http://web.psung.name/zeya/
- Zeya bug tracking and mailing list: https://launchpad.net/zeya
- Music Playing Daemon: http://mpd.wikia.com/
- GNUMP3D: http://www.gnu.org/software/gnump3d/
- Ampache: http://www.ampache.org
- Everyday git: http://www.kernel.org/pub/software/scm/git/docs/everyday.html
- oggenc: http://linux.die.net/man/1/oggenc
- flac: http://flac.sourceforge.net/
- mpg123: http://www.mpg123.de/
- HTML5: http://dev.w3.org/html5/spec/Overview.html
The author would like to acknowledge his fellow Zeya developers for helping out with initial ideas of the source code and Suryajith for testing Zeya on Arch Linux.