GNUMP3d [GNU MP3/Media Streamer] - FAQ - GNU Project

Frequently Asked Questions

Platform/Distribution Specific

What systems does it run on?

GNUMP3d is written in portable Perl, and should run on any system which is capable of running perl code.

The only additional requirement is a working 'fork' call - which in practice means the system must be either GNU, Unix, or running a recent version of ActiveState Perl port for Microsoft Windows

Supported platforms include:

GNU/Linux - Debian, Gentoo, Mandrake, RedHat, SuSE, etc.
Solaris - Sparc, and Intel.
FreeBSD, NetBSD, and OpenBSD.
Cygwin / Native Microsoft Windows.

What MP3/OGG players are supported?

Any player which supports streaming over HTTP should work just fine, although some will work better than others.

Players which are reported to work well include:

XMMS
WinAmp
Zinf - Zinf Is Not FreeAmp
iTunes

Can you change the bitrate, in real-time?

Yes you can. It's not as flexable as I'd like due to the nature of the serving. Because in the majority of cases it's your MP3/OGG player which fetches the tracks I can't use cookies - they don't XMMS/FreeAmp/WinAmp don't support them.

More documentation will be available online soon.

I've found a security hole...

This software was designed to be secure, and I believe it is. If you believe you've found a problem then please let me know.

There's a specific security page, in the documentation section, which describes the security of this server, and gives a contact address.

Anybody who reports a legitimate security hole within a current release will receive credit and thanks upon our security attacks page. We hope this we encourage responsible disclosure.

Will you add ...?

If you have a suggestion then I'd be happy to hear, simply make a post to the relevent mailing list (after subscribing).

If you have a patch, or a rough idea of how it could be implemented then so much the better!

I have the server setup, but I don't hear anything...

Check that you have the .m3u, .mp3, and .ogg extensions associated with your music player - XMMS, WinAmp, FreeAmp, or whatever else you're using - otherwise you'll just have the files being downloaded and not played.

Where can I find more information?

All of the currently available documentation is listed in the documentation index - if you're not satisfied with the information there, then you should checkout the mailing lists.

Do you have a PGP key, or GPG key?

I have a key which may be used with GNU Privacy Guard (gpg) - you may find it here.

I like this software - can I give you something?

If you want to give me something 'big' then there's a small Amazon wishlist here. If you just wish to express your appreciation just drop me or the mailing lists an email - its always nice to receive feedback, (good or bad).

If you wish to work on the code the contributions are always welcome. Working on any free software is a good way to thank other users.

You're just doing this to solicit freebies, aren't you?

Nope. Accepting donations was suggested by a friend when I was having a hard time looking for a new job. I'm entirely happy to give away the source for free both in terms of speech, and beer.

(I did find a new job BTW ;)

I believe very strongly in the idea of free software, and stand firmly behind the FSF, this software is hopefully a small recompense to the community which has given us such wonderful applications as Apache, Perl, Samba, Squid, and of course the Linux Kernel.

If you choose to donate then that's appreciated but entirely optional. I can quite honestly say that this code will continue to exist under the GPL for the rest of it's life - so it will always remain open.

Do I have to restart the server to update the template files?

No. The theme files are cached but will be re-read when they are modified. The only exception to this is the theme override file which will not be re-read.

This makes it simple to modify the template files in place.

The server uses the wrong hostname, how do I change this?

If you've got the server running, but the hostname which is used in the playlists is wrong - then this section applies to you.

Simply place lines such as the following in your gnump3d.conf file:

#
#  Set the hostname that is used in all the generated links,
# and playlists.
#
#  (This defaults to the name of the server machine, with no
# domain suffix).
#
#  You won't need this unless the machine which is serving on
# MUST be accessed via its fully qualified name.
#
#  See `binding_host' instead if you have a machine which has multiple
# IP addresses
#
hostname = mp3d.foo.org

The server is behind a proxy and gets the hostname wrong in the links, how do I fix this?

The hostname used in the links can be set fairly easily, simply update the configuration file gnump3d.conf paying attention to the following setting:

##
#
# Set this option to rewrite the hostname:port combination in the URLs in
# your playlist.  Most people won't need this unless they are proxying
# their connection or running multiple streaming servers through a load
# balancer or DNS rotor.
#
# Note: If you set this you will almost certainly need to set
#       "use_client_host=0"
##
# host_rewrite = ""

How do I secure my music archive?

You can secure your archive by restricting access to clients based upon their IP address.

Can I change the HTML that's generated?

Yes you can change almost everything!

The server will read in a bunch of template files when it starts, from the directory /usr/share/gnump3d/$THEMENAME/ - edit those and the output will change.

Note that you don't have to restart the server for changes in the template files to take effect, any changes you make will be reflected immediately.

The name of the theme is set in the configuration file -look for a line like 'theme = default' to see some of the available choices.

How do I build a theme?

Create a directory in /usr/share/gnump3d/ with the name of your theme 'foo', and copy all the files from /usr/share/gnump3d/default into it. Edit those files to suit your tastes - then set theme=foo in your gnump3d.conf file.

There's a more detailed explaination upon the theme creation page - after reading that you might want to look at the advanced theming page.

What variables are expanded in the templates?

The template files, which are mentioned above, can contain special variables which are expanded upon display.

The following variables are supported:

Text	Expansion
$DIRECTORY	The directory the user has browsed to
$HOSTNAME	The name of the host upon which the server is running.
$HOST	The name of the host upon which the server is running, minus any trailing domain.
$VERSION	The version of the server

There are more which control where the output will appear - these will be documented soon.

Can I load themes from other directories?

You can specify a different base directory for the themes by setting the following option in the gnump3d.conf file:

#
# Specify a different root directory for loading the themes from,
# (this defaults to /usr/share/gnump3d).
#
theme_directory = /home/mp3/themes/

What are plugins, why are they used?

Plugins are nothing more than external libraries which contain code the main program, gnump3d, can call.

They are used to simplify the main code, and keep certain tricky or complicated, functions out of the main code where they would get in the way.

A good example of this is the search plugin. By moving out all the searching code from the main program it becomes easier for somebody to read the short plugin and add, for example, the ability to search by genre.

For more information on creating a plugin see the later question How do I write a plugin?

What are the special URLS?

There are several special URL's which are handled by external plugins.

(If you have installed extra plugins in addition to those which come with the server you may have more special URLs not listed here).

URL	Meaning
/bug/	This is the integrated bug reporting plugin.
/last/	Will display the last 20 tracks which have been served, along with the directory they were served from.
/now/	Will show you all the songs that are playing at the moment.
/random/	Will present a list of 20/40/50 random tracks and allow you to play them, or regenerate another selection.
/stats/	Will show the most popular songs, directories, and active users
/search/	Will show the search from read from the search.html template.
/search?q=foo	Will perform a search for the term "foo"
/search?p=foo	Will return a playlist containing the results of searching for "foo"
/prefs/	Will list the preferences page, allowing you to change theme, and more.

I don't see any statistics

First of all check that accesses to your server are being logged correctly into the file you have specified with the 'access_log' configuration directive.

If this is correct ensure that you have the "gnump3d-top" script installed.

"gnump3d-top" is a Perl script, so test running it from the command line, running 'gnump3d-top --help' should give you a few ideas as to whats going on.

If you have the script installed and apparently working there are two thing to check:

Is the logfile is specified in the gnump3d.conf file as an absolute path?
Are you changing to user 'nobody' in the config file; and if so can that user read the stats file?

How do I write a plugin?

Please see the plugin section of the developer notes, and the plugin tutorial.

I installed the RPM but the server won't start

This is almost certainly a problem with the logfile you're trying to use not existing.

There are two solutions to this:

Create the directory where the logfile is going to be written : mkdir /var/log/gnump3d
Change the logfile setting in the 'gnump3d.conf' file to point to a directory which already exists, eg. 'logfile = /var/log/gnump3d.log'.

Will the Perl server run under Windows?

Yes, see the instructions in the README.Windows file - and ask upon the lists if you have problems.

Updated Will the Perl server run as a service under Windows?

Not natively no.

However with some help from the Windows NT resource kit you can make it do so - there are some minimal instructions online below:

Making Perl code run as a Windows service.

GoneCrazy was kind enough to send complete details of how to install this server as a service on Windows using the free (lite) FireDaemon tool:

Complete Service Installation Guide from GoneCrazy

How can I make the server run at startup on Mac OS X?

Thanks to a contribution from Eric Lawrence some files, and instructions, are included with the current release.

Please see instructions in the README.MacOSX file.

Why did you switch to perl?

Originally I started coding in Perl because I wanted something fast, and simple to develop in, so that I could experiment with different database formats.

However sooner than I realised I had recreated almost all the major pieces of code necessary to have a standalone GNUMP3d server.

Partly this is because I'm familiar with perl, but partly it's because scripting languages are traditionaly quick to develop in.

Staying with perl, and moving away from the C++ codebase is a big step, but I believe it is worthwhile because:

This is a network server, which is limitted more by network bandwidth than execution speed.
None of the nasty threading problems or memory management needs to be so difficult.
Perl is a very mature and stable language for developing in

A more detailed explaination of the server's evolution is given in the history page.

How can I help with version 2.x development?

In the same way that people have previously helped:

Giving interesting, and useful, feedback, or suggestions.
Designing Logos.
Designing Themes.

Plus I still appreciate patches and code submissions; hopefully switching to perl will make this easier for other developers - as a lot of people are familiar with the language.