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.

zeyaf1.png148.75 KB


Comment viewing options

Select your preferred way to display the comments and click "Save settings" to activate your changes.

Great article and software....

Anonymous's picture

except I can't get it to play more than a fraction of a second of audio in either the builetin 3.6.3 firefox for Ubuntu or google chrome 5.0 beta. Whenever I go to play a new song it even opens up a new connection to pulse audio over the ALSA plugin, but no cigar for streaming the music.

From home?

gumBO's picture

Many ISP's frown on the use of serving multimedia from a home environment. Good luck to those of you who are able to achieve this without having your internet account throttled.


Ed316's picture

If you want something much easier to setup and probably with much more options, try AmpJuke, I use it for music streaming for more than a year and my friends and I love it.

Playlist support

Amit Saha (author)'s picture

Zeya now supports 'm3u' and 'PLS' playlist as inputs, as well. So now you have more backends to stream your music from.


Striped Penguin's picture

I think you have an error in your article. MPD is not really a music streaming service. It lets you control and play music on the host from a remote machine. You can setup icecast and maybe 1 or 2 other forms of streaming music, but by default it is NOT a streaming music server.

'mpd' is the 'daemon' part

Amit Saha's picture

..which runs on the remote machine. What you run on your client machine is the mpd client, often 'mpc' or any other client. 'mpd' is therefore a music streaming daemon.

I don't understand what you mean by "default it is NOT a streaming music server...". 'mpd' is meant to serve music. Isn't it? Icecast is just another form of input it takes. It can serve music from your local filesystem as well.

have you ever used mpd? MPD

Anonymous's picture

have you ever used mpd? MPD does NOT stream music. it plays music, on the computer running the daemon. If you connect with a remote computer to the server, and change songs for example, the song will change and play on the computer running the daemon. You wont hear any music on the client machine. (Which is not very useful if you're away from home.)

MPD can be partnered with icecast, as was said already, to be used as a streaming solution. Icecast is a music streamer.

Depends your definition of

Anonymous's picture

Depends your definition of "streaming server". MPD can send its output to pulseaudio, which doesn't necessarily have to be running on the same box as the server. So you could have your mpd server in the closet and it could "stream" the music across your local network to your office desktop machine running pulseaudio. This actually works well for me in a single-user situation.


Chris S's picture

Ampache has clients for many mobile phones including Palm WebOS, Google Android, and MS Windows Mobile. None of these clients require flash. I use the Palm Pre client and I'm able to stream music from home wherever I go.

How about an android client?

Anonymous's picture

How about an android client?

Good to see your article

Vandana's picture

Good to see your article here... quite interesting!


Amit Saha's picture

Hi Vandana: Thanks for the fab!