GNUMP3d - The GNU Streaming MP3 / OGG Vorbis Server.
Homepage: http://www.gnump3d.org/
Version : 1.0
Author : Steve Kemp <skx@tardis.ed.ac.uk>
Contents
--------
This README file is split into the following sections.
Please read it all before reporting bugs, or problems:
Introduction
Supported Platforms
Building
Configuration
Running
Customization
Documentation
Mailing Lists
Reporting Bugs
License (GPL)
Alternative Solutions
Thanks
Comments / Suggestions / Patches?
Introduction
------------
This server attempts to provide an attractive interface to browsing
and streaming a large MP3 or OGG collection via your web browser.
It allows MP3's and OGG vorbis files to be served to any media player
which supports audio streaming. Supported players include XMMS, FreeAmp
and WinAmp.
The streaming is very versatile; individual files may be played directly,
whole directory trees can be streamed, you may even choose to listen to
audio files which match a particular pattern.
The display of files is built up in real-time; which means that
you don't need to restart the server when adding music to your
collection.
Supported Platforms
-------------------
This software was developed under Debian GNU/Linux, and
should build on any similar GNU/Linux development platform.
Because the software was written with portability in mind and
has recently been updated to use the GNU Autoconf tools it
should also build and run under other flavours of Unix.
(If it doesn't compile and run under your platform then please
consider this a bug and report it as such).
GNUMP3d has been built, and tested on the following platforms:
GNU/Linux FreeBSD OpenBSD
NetBSD Solaris Cygwin(*)
(Cygwin support has traditionally been weak - if you need assistance
let me know...)
Building
--------
For complete instructions on the build and installation procedure
please see the included file 'INSTALL'.
Configuration
-------------
When the server starts it looks for the global configuration file,
which defaults to $PREFIX/etc/gnump3d/gnump3d.conf - typically this
will be /usr/local/etc/gnump3d/gnump3d.conf
You may supply the location of an alternative configuration file
via the '--config' command line option.
NOTE:
You will definately need to edit the config file prior to running
the server for the first time.
Running
-------
Simply run the binary, 'gnump3d' after installing, and editting
the configuration file.
Once the server is started point a web browser at the host and
port which you have specified, and browse/stream away.
After you have verified that the server works you may wish to
run it in the background. A simple way of doing this is to
specify '--background' when you start the server. A more complex
means of doing this is to create, or install, a startup file
for the server - so that it will start automatically whenever your
machine boots.
NOTE: If the server is running in the background you will
not see any error messages that are generated; so don't do this
if you're having problems.
Customization
-------------
The appearance of the server may be changed by switching to a new
theme. The themes may be browsed and selected from the HTML pages
which are generated - if you wish to change the default theme please
see the configuration variable 'theme' in gnump3d.conf for details.
You may freely modify the theme files themselves, or create a new
theme to change the appearence of the server.
(Theme files are stored in a directory with the name of the theme in
the $PREFIX/etc/gnump3d/ directory).
Documentation
-------------
There are two sets of documentation included with this software:
1. End user documentation - which is included in the form of
this document and the supplied man pages.
The man pages should be installed when you install the software,
if you need help on something try the following commands:
man gnump3d
man gnump3d.conf
man gnump3d-top
man gnump3d-config
2. Source code documentation - which you'll find in 'src/html/'.
This is automatically generated, and is designed to be as thorough
as possible.
A top level description of the server internals is included in the
file 'src/README-C++' and brief instructions on plugin development in
the file 'HACKING'
Mailing Lists
-------------
There are two mailing lists which you can turn to if you'd like
help, assistance, or discussion on this software.
Full details of these are given on the project's website, at
the following URL:
http://www.gnump3d.org/lists.html
Reporting Bugs
--------------
For a bug report to be useful it needs to contain as
much information as possible.
A simple means of giving all the relevent information is
to use the integrated bug reporting plugin. (Obviously you
can't use this if the bug you wish to report concerns
plugins ;).
To use the bug reporting plugin simply point your webbrowser
at:
http://server:port/bug/
Enter the text of your report into the text area, and click
on the submit button.
If you're not using the bug reporting plugin simply send
me an email. To assure prompt attention please include the
following information:
1. Your operating system, and version:
Run 'uname -a', and 'arch' and send me the results.
2. The version of GNUMP3d you're using.
Run 'gnump3d --version' and send me the results.
2a. The output of 'gnump3d --dump-plugins' if you're having
problems with the plugin support.
3. The browser/client/MP3 player you're using.
If you can send a patch that would be great; if not the more
detailed your report is the better.
License
-------
As the name might suggest, this software is distributed under
the terms of the GNU Public License, version 2.
Please find a copy of the GNU Public License included with the
source archive in the file COPYING.
Alternative Solutions
---------------------
Here's a brief list of alternative solutions which
you may want to investigate if this software doesn't
quite meet your needs.
Edna - http://edna.sourceforge.net/
This is very similar to this application, in fact this server
was intially modelled after Edna.
Edna lacks searching facilities, tag display for OGG files, and
is written in Python.
Ample - http://ample.sourceforge.net/
This is a simple server which is comparable to Shoutcast.
KPlaylist - http://www.kplaylist.com/
This is a PHP-based solution which allows you to add individual
files to your playlist via your web browser then play it.
KPlaylist requires a database backend.
Thanks
------
I'm indebted towards many people who sent me bugfixes, corrections,
interesting questions and suggestions.
It is with their help that this software is what it is today, and I
can't thank them highly enough. Any remaining bugs are of course
entirely my fault.
Comments / Suggestions / Patches?
---------------------------------
I optimistically welcome comments, feedback, suggestions, updated
Makefiles, documentation corrections and patches.
If you really like the software consider purchasing something from
the wishlist you'll find displayed at http://www.gnump3d.org/
Steve
---
<skx@tardis.ed.ac.uk>
$Revision: 1.45 $
