amp MPEG audio decoder readme file (version 0.7.5)
(C) Tomislav Uzelac  1996,1997

Ported to Win32, modified for C++, and adapted for use in HTML TADS
by Michael J. Roberts, October 1998.  Changes copyright 1998 Michael J.
Roberts.

amp is free software and can be _used_ freely by anyone. If you want to
do anything else with it, be sure to check the Legal section of this
document for legal issues.

THERE IS NO WARRANTY FOR THIS PROGRAM. Please check out the Legal section
of this document.

1. Introduction
2. Installation
3. Running
4. Feedback
5. Contributing
6. Legal
7. Notes on the Win32 C++ version


1. Introduction

amp (Audio Mpeg Player) is an MPEG audio decoder which I originally started 
putting together as a side project of the MPEG hardware design project at 
FER/Zagreb - just to confirm my knowledge of the standard. It works with
both MPEG1 and MPEG2 audio streams (except for the multichannel extensions
defined in MPEG2), layers 2 and 3. 

There is a gui for amp, written in Tcl/Tk by Edouard Lafargue. It is 
available at the amp home site ftp://ftp.rasip.fer.hr

Another gui supported is the Sajber Jukebox, written by Joel Lindholm.

The following people contributed their time and knowledge to amp:
Karl Anders Oygard, Ilkka Karvinen, Lutz Vieweg, Dan Nelson,
Edouard Lafargue, Andrew Richards, George Colouris,
Dmitry Boldyrev, Andy Lo A Foe, Thomas Sailer, Justin Frankel

amp home location is
	ftp://ftp.rasip.fer.hr/pub/mpeg/

and the mailing list: send 'HELP' in the body of the message to:
	multimedia@rasip.fer.hr

If you want to find out more about MPEG, best places to start are
	http://www.mpeg.org
	http://www.mpeg2.de 


2. Installation

Installation should be simple enough if amp was ported to your system,
just do a 

./configure
make 

You can edit the makefile further to suit your system. If configure fails 
to make a usable Makefile, you'll _have_ to edit it yourself.

Linux users should try real-time playing support, as described
in doc/realtime.txt. Some people that might pass on this feature are
those with slower machines (i.e. 486's), or SMP systems (see the
doc/linuxrealtime.txt file). 
Some versions of the linux C library produce an error when compiling
amp with realtime support. A quick fix is to edit /usr/include/sched.h
and replace _P in the offending line with __P.

./configure --enable-realtime
make
chown root.root amp
chmod u+s amp

... this requires /dev/dsp to be both world readable and writeable. If you
have a special group for people allowed to use the sound device (for
instance, a group called sound), you can do a:

chmod g+s amp

or make your audio card world read/writeable (not recomended)

chmod o+rw /dev/dsp*

3. Running:

'amp -h' gives you usage & options. If your computer is on the slower
side, direct playback might not work, but you can decode it
to .wav or raw pcm and play it later.


4. Feedback

Send in your makefiles, opinions, bugreports, fixes; anything related to this
program. You can also send me unlimited amounts of money, sugar, milk, etc.

If you find any mpeg audio files that amp has trouble decoding, please tell
me about this via e-mail <tuzelac@rasip.fer.hr>.


5. Contributing

Please contribute to amp. If you want to know what is going on in amp 
development, you can join the developers mailing list

	mpeg_audio_developers@rasip.fer.hr

There are certain debugging facilities that I made in amp, but are disabled
in the current release (they are neither nice nor user-friendly). If anyone
enhances them (they are in dump.c) to the point that they're actually
usable I'll be happy to include the changes in the release. I think this
kind of debug output would be very useful to people studying these audio
algorithms.


6. Legal

This software can be used freely for any purpose. It can be distributed
freely, as long as it is not sold commercially without permission from
Tomislav Uzelac <tuzelac@rasip.fer.hr>. However, including this software
on CD_ROMs containing other free software is explicitly permitted even 
when a modest distribution fee is charged for the CD, as long as this
software is not a primary selling argument for the CD.

Building derived versions of this software is permitted, as long as they
are not sold commercially without permission from Tomislav Uzelac 
<tuzelac@rasip.fer.hr>. Any derived versions must be clearly marked as
such, and must be called by a name other than amp. Any derived versions
must retain this copyright notice.

/* This license is itself copied from Tatu Ylonen's ssh package. It does 
 * not mention being copyrighted itself :)
 */

THERE IS NO WARRANTY FOR THIS PROGRAM - whatsoever. You use it entirely
at your risk, and neither Tomislav Uzelac, nor FER will be liable for
any damages that might occur to your computer, software, etc. in
consequence of you using this freeware program.


Tomislav Uzelac
<tuzelac@rasip.fer.hr>

------------------------------------------------------------------------------

7. Notes on the Win32 C++ version

This is a port of the original amp 0.7.6 unix sources to Win32 for use
in HTML TADS.  I modified the original sources in several important ways
to make it easier to use the MPEG player as a library rather than as a
stand-alone program:

  - The entire library is now wrapped as a C++ class (CMpegAmp).  This
    should reduce the possibility of a namespace conflict when this code
    is linked into another program.  A few const static arrays remain
    as static variables in the root namespace, but their names should
    be sufficiently obscure that the chances of a collision are low.
    Note that all methods are non-virtual, so the only run-time overhead
    this introduces is the addition of the implicit 'this' parameter
    in each function call.

  - All of the arrays of constant data are now explicitly declared as
    const.  This change isn't stricly necessary, but it makes me feel 
    more confident that I really have moved all of the mutable static
    variables into member variables

  - All non-const static and global variables are now member variables
    in the C++ class.  This means all state is now encapsulated in the
    class object.

  - The system-specific code is isolated in a separate subclass,
    CMpegAmpW32.

  - CMpegAmpW32 has a few convenience functions that make it easy to
    use the class to play an MPEG file programmatically.

For Win32, the code uses DirectSound to control the sound device.
Although the regular Win32 multimedia sound functions (WaveOutOpen,
etc) would also work, DirectSound has two advantages: first, HTML
TADS uses it for "WAV" output, making DirectSound the more natural
interface for use with HTML TADS; second, DirectSound can mix
multiple wave files together for simultaneous play, whereas the
multimedia interfaces cannot directly do this.  In addition,
Microsoft has indicated that DirectSound is the preferred audio
interface on Windows.

Because this version is derived from the amp 0.7.6 sources, the
original author's copyright and license terms apply to this derived
software.  I have added a copyright notice to my changes, but you may
use this derived version under the same conditions as the original
code; see the "Legal" section above for details.

Michael J. Roberts, October 1998
<mjr_@hotmail.com>
