GMediaServer - Introduction
===========================

GMediaServer is a UPnP music media server. It implements the server
component that provides UPnP media devices with information on available
audio files. GMediaServer uses the built-in http server of libupnp to
stream the audio files to clients.

The following media devices have been tested and are confirmed to work with
GMediaServer:

   Netgear MP101 (http://www.netgear.com/products/details/MP101.php)

Other UPnP media devices (including software based) may work as well - see
below for a more detailed list of supported devices. For a quick start, see
the Usage and Known Bugs sections below.

GMediaServer is written in C by Oskar Liljeblad. It should compile and run
on any modern POSIX compatible system such as Linux. GMediaServer is a
console based application which is usually run in the background.

GMediaServer is free software - it is licensed under the terms of the GNU
General Public License (GPL).

This project is in an early stage of development. Many essential features
are planned for the future. With your help, we will make a media server
that can compete with the proprietary (and Windows-only) servers bundled
with media device hardware.

Copyright and License
=====================

GMediaServer is copyright (C) 2005 Oskar Liljeblad.

This program is free software; you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2 of the License, or (at your option)
any later version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc., 59
Temple Place, Suite 330, Boston, MA  02111-1307  USA

Note that GMediaServer links with libupnp, which is licensed under the
terms of a modified BSD license (i.e. the original BSD license without the
advertising clause). This license is compatible with the GNU GPL.
GMediaServer optionally links with id3lib, which is licensed under the
terms of the GNU General Public License.

The source code of this project may contain files from other projects, and
files generated by other projects, including:

 * GNU Autoconf (http://www.gnu.org/software/autoconf/)
 * GNU Automake (http://sources.redhat.com/automake/)
 * GNU gettext (http://www.gnu.org/software/gettext/)
 * Gnulib (http://www.gnu.org/software/gnulib/)
 * Flex (http://www.gnu.org/software/flex/)
 * GNU Bison (http://www.gnu.org/software/bison/)
 * Autoconf Macro Archive (http://ac-archive.sourceforge.net/)

Such files are licensed under the terms of the GNU General Public License
or a license compatible with the GNU GPL (as listed on
http://www.gnu.org/licenses/license-list.html). See each file for copyright
details.

The Swedish translations in the po directory may contain translations from
other projects, including:  C Library
(http://www.gnu.org/software/libc/libc.html)  Core Utilities
(http://www.gnu.org/software/coreutils/)  <pSee the specific message file
(PO file) for copyright of those messages.

Requirements
============

The following programs are required to build GMediaServer:

 * GNU C Compiler (gcc), 2.95 or later.

   GMediaServer uses some features specific to gcc 2.95, such as macros
   with variable number of arguments. The GNU C Compiler is part of the GNU
   Compiler Collection which can be downloaded from http://gcc.gnu.org/. In
   Debian and many other distributions the package is called gcc.

The following libraries are required to build and run GMediaServer:

 * Linux SDK for UPnP Devices (libupnp), 1.2.1 or later

   The libupnp library is used to communicate using the UPnP protocol.
   libupnp can be downloaded from http://upnp.sourceforge.net/.

   Debian packages for libupnp are currently available in testing (and
   unstable). The runtime package is called libupnp0, and the package
   required when building libupnp-dev. Packages for stable (woody) can be
   downloaded from http://detroit.ddo.jp/debian/woody/. The runtime package
   is called libupnp1, and the development package libupnp1-dev.

The following libraries are optional:

 * ID3v1/ID3v2 Tagging Library (id3lib), 3.8 or later

   This library allows GMediaServer to retrieve ID3 information from MP3
   files. id3lib can be downloaded from http://id3lib.sourceforge.net/.

   The Debian package for id3lib is currently available in testing (and
   unstable) and is called libid3-3.8.3. libid3-3.8.3-dev is required when
   building. The version available in stable (woody) - 3.7.13 - is too old.
   However, there are numerous sites providing backports of 3.8 and later
   to stable. One such site is
   http://www.iua.upf.es/mtg/clam/download/debian/woody/.

Building and Installation
=========================

Compile GMediaServer by running configure and then make. This should
produce an executable gmediaserver in the src subdirectory, which can be
used right away. No extra files need to be installed.

If you want to install GMediaServer on your system, run make install. This
will copy the executable into the appropriate directory (/usr/local/bin by
default).

For more information regarding configure and make, see the INSTALL
document.

Usage
=====

GMediaServer runs from the console only. It supports the usual --help
option which displays usage and option information. GMediaServer expects a
directory argument, specifying where audio files are stored. You should
probably also use the -i (--interface) option to specify which interface
GMediaServer should listen on. The first times you run GMediaServer it
would also be a good idea to increase the verbosity. Example:

   ./gmediaserver -ieth1 -v4 /audio

At the moment, there is no manual page for GMediaServer.

Supported Devices
=================

The following media devices have been tested and are confirmed to work with
GMediaServer:

 * Netgear MP101

   URL: http://www.netgear.com/products/details/MP101.php

The following devices may work, but have not been tested:

 * Philips Streamium 300i, 400i

   URL: http://www.streamium.com/

 * SMC EZ-Stream

 * Terratec Noxon

 * Roku

 * D-Link DSM-320

 * Buffalo LinkTheater

 * Sony STR-LV700R

 * Sony GoVideo 2730

 * LinkSys WMLS11B

 * Sony RoomLink

Homepage
========

Web site and file area for GMediaServer is hosted on Savannah:

   http://www.nongnu.org/GMediaServer/

The latest version of GMediaServer should always be available on this site.

Feedback
========

The author of GMediaServer and this document, Oskar Liljeblad, can be
contacted by e-mail on the following address:

   oskar@osk.mine.nu (mailto:oskar@osk.mine.nu)

Please send bug reports, suggestions, ideas or comments in general to me.

If you would like to get involved with this project, please don't hesitate
to contact me! All contributions are welcomed.

Known bugs and limitations
==========================

Unfortunately the Netgear MP101 is quite buggy, even with the latest
firmware (1.3.7 as of writing this). Numerous forum posts on the internet
can confirm this. For me, it seems to hang randomly when browsing or when
just about to play a song. I have yet to discover what is causing this.

If you need to listen on more than one interface, you will have to start
multiple instances of the media server.

GMediaServer keeps information on all audio files in memory. If your audio
collection is huge, this might be a problem.

As GMediaServer is in an early stage of development, many essential
features are unimplemented.

Things to do
============

Please see the TODO document.

-
