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.

Setting up 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 "./" 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

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:

$ ./ --path=/home/r00t/Music/

You should see:

Using 'dir' backend.
Scanning for music in '/home/r00t/Music'...
Loading library...
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, 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.


Figure 1. Zeya's 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, and IE 6-8 with the Google Chrome Frame plugin. The install file contains more info on the browser requirements.

As you can see, the very basic features of a music playing client - play, pause, go next, go previous and search are present. As I write this article, a 'shuffle' feature has also been added. Most features are part of the client and not part of the server. The client is written in JavaScript.

A Closer look at Zeya from a user's perspective

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 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, is the starting point of the Zeya server. Currently, takes the following options from the command line:

$ ./ --help
Usage: [OPTIONS]

  -h, --help
      Display this help message.

      Specify the backend to use. Acceptable values:
        dir:      (default) read a directory's contents recursively;
                  see --path
       rhythmbox: read from current user's Rhythmbox library

      Directory in which to look for music, under --backend=dir.
      (Default: ./)

  -b, --bitrate=N
      Specify the bitrate for output streams, in kbits/sec.
      (default: 64)

  -p, --port=PORT
      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.

Zeya internals

Source tour of Zeya

Now that we've looked at Zeya from a user's perspective, I would like to take you on a tour of the source code of Zeya. An intermediate knowledge of Python, basic JavaScript and HTML, simple client-server computing concepts and you are good to go. Needless to say, you will derive the maximum benefit from this section if you browse through the source code along with this article. Let's get started.

Alphabetically, these are the Python source files and what they do:

  • The code in this file acts as interface with the supported backends.

    All backends should implement the Python interface 'LibraryBackend' defined in this file.

  • A small file containing some utility functions

  • The code in this file interfaces with the system's decoders

    for mp3 and flac files.

  • This implements the directory backend of Zeya.

  • This handles the command line option parsing, error

    handling and sets default values for options.

  • This file implements the Rhythmbox backend

  • This is a sample implementation of a non-web, rudimentary

    command line client for Zeya.

  • This is the main code for Zeya which takes care of

    serving music to clients by calling upon various functions from the previous files.

  • 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.

  • resources/zeya.js: This is a JavaScript file which implements the web based

    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.

Starting Zeya at boot time

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/ --path=/home/r00t/Music

This will start the Zeya server at boot time.

Other Music Server software

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.

Presenting Zeya

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.


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.

Load Disqus comments