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

GMediaServer is a UPnP(TM) 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.

A number of media devices have been tested and are confirmed to work with
GMediaServer. Among then are NETGEAR(R) MP101, Linksys(R) WMLS11B and
WML11B, Philips Streamium SL300i and RC9800i, Omnifi DMS1, and SMC EZ
Stream(TM) SMCWAA-B. See below for a full list.

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., 51
Franklin Street, Fifth Floor, Boston, MA 02110-1301, 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:

 * GNU C Library (http://www.gnu.org/software/libc/libc.html) 
 * GNU Core Utilities (http://www.gnu.org/software/coreutils/)

See 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 for communication 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

Check out the --profile option, which allows settings for certain devices
to be automaticly enabled. See the manual page for  more details:

   man ./gmediaserver.1

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

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

 * NETGEAR(R) Wireless Digital Music Player (MP101)

   Profile: mp101
   URL: http://www.netgear.com/products/details/MP101.php
   Notes: You probably need to upgrade the firmware to 1.3.7 or later to
   use GMediaServer with the MP101.

 * Linksys(R) Wireless-B Music System (WMLS11B)

   Profile: generic
   URL:
   http://www.linksys.com/products/product.asp?grid=33&scid=38&prid=631

 * Linksys(R) Wireless-B Media Link for Music (WML11B)

   Profile: generic
   URL: http://www.linksys.com/products/product.asp?grid=33&prid=632
   Notes: It may be necessary to manually select a new song to play when
   the current song  has finished playing. This problem has not been solved
   yet.

 * Philips Streamium SL300i

   Profile: generic
   URL: http://www.streamium.com/products/sl300i/
   Notes: Confirmed to work with GMediaServer with firmware 1.5.2.

 * Philips Streamium RC9800i

   Profile: generic
   URL: http://www.homecontrol.philips.com/

 * Omnifi DMS1

   Profile: dms1
   URL: http://omnifimedia.com/products/omnifi_details.jsp?productId=12542
   Notes: Requires --expire-time=1801 (or greater than 1801).

 * SMC EZ Stream(TM) 11Mbps Wireless Audio Adaptor (SMCWAA-B)

   Profile: generic
   URL:
   http://www.smc.com/index.cfm?event=viewProduct&localeCode=EN_USA&cid=11&
   scid=&pid=1333
   Notes: This devices is similar to the Philips SLA5500 and the Terratec
   Noxon Audio.

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

 * Philips Streamium 400i

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

 * SMC EZ Stream(TM) Universal Wireless Multimedia Receiver (SMCWMR-AG)

 * SMC EZ Stream(TM) 802.11g Wireless Audio Adapter (SMCWAA-G)

 * Terratec Noxon

 * Roku

 * D-Link DSM-320

 * Buffalo LinkTheater

 * Sony STR-LV700R

 * Sony GoVideo 2730

 * LinkSys WMLS11B

 * Sony RoomLink

References
==========

Note that this list of references is not complete.

 * UPnP(TM) Standards (http://www.upnp.org/standardizeddcps/default.asp)

 * The Unofficial M3U and PLS Specification
   (http://forums.winamp.com/showthread.php?threadid=65772)

 * RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1
   (ftp://ftp.isi.edu/in-notes/rfc2616.txt)

 * Shoutcast Metadata Protocol
   (http://www.smackfu.com/stuff/programming/shoutcast.html)

 * The Shoutcast Protocol
   (http://www.gigamonkeys.com/book/practical-a-shoutcast-server.html)

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
==========================

There are some compilation warnings due to bugs in GNU flex and libupnp.
They can safely be ignored.

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.

Trademarks
==========

NETGEAR is a registered trademark of NETGEAR, Inc.

"Linksys" is a registered trademark of The Linksys Group, Inc.

"Philips" is a registered trademark of Koninklijke Philips Electronics N.V.

UPnP(TM) is a trademark of the UPnP(TM) Implementers Corporation.

SMC and SMC EZ Stream(TM) are registered trademarks of SMC Networks Inc.

-
