
			mpeg3play version 0.9.6
			     April 6, 1997


Home page:  The Solaris Helpers Page at
            http://home1.swipnet.se/%7Ew-10694/helpers.html

Authors:    ISO/MPEG working groups, Fraunhofer Institute and
	    Johan Hagman <Johan.Hagman@mailbox.swipnet.se>


mpeg3play is an MPEG layer 2 and layer 3 audio decoder/player for Unix,
based on public ISO/MPEG audio decoder source code.

The original software is a slow but portable MPEG audio to AIFF decoder,
impossible to use as a real-time player. I have optimized the source to
make it possible to use the decoder for real-time playback and have
modified it for output to the Solaris/SunOS audio device. Only 16-bit
(CD-quality) audio devices are currently supported. The various data files
that the original decoder needs at runtime are also integrated to make it
a self-contained executable.

Version 0.9 for Solaris/SPARC was the initial release of the player, but
it can currently also be compiled for Linux (since version 0.9.1), HPUX
(version 0.9.3), Amiga (version 0.9.4), IBM AIX (version 0.9.5) and
FreeBSD, Solaris/x86, SunOS 4.x (version 0.9.6). Many thanks to the
following people for their suggestions, optimizations and porting efforts

   Tim Newsome <drz@froody.bloke.com>		   Linux
   Damien Clermonte <clermond@esiee.fr>		   HPUX
   Troels Walsted Hansen <troels@stud.cs.uit.no>   Amiga
   Terje Malmedal <terje.malmedal@usit.uio.no>	   AIX
   Dan Nelson <dnelson@emsphone.com>		   FreeBSD
   Michael Cheng <mcheng@faraday.dialix.com.au>    Amiga
   Fredrik Hubinette <hubbe@lysator.liu.se>        Linux

The -h (help) command line option shows the usage:

% mpeg3play -h
+---------------------------------------+
|   mpeg3play version 0.9.6, 6-Apr-97   |
+---------------------------------------+
This is an MPEG audio layer 2 and layer 3 decoder/player
based on public ISO/MPEG audio decoder source code. Solaris
port and optimizations by Johan.Hagman@mailbox.swipnet.se.

Copyright (C) 1996, 1997 by Johan Hagman.
This program is free software.

usage: mpeg3play [-v] [-h] [-f] [-o outfile.aiff] filename
  -v          enable verbose mode
  -h          display program help information
  -f          fork off new player and return
  -o outfile  write an AIFF output PCM sound file
  filename    bit stream of encoded audio ("-" means stdin)

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

PLATFORM-SPECIFIC INFORMATION

Solaris/SPARC:

The Solaris/SPARC binary available from the Solaris Helpers page includes
some assembly optimizations in addition to the C optimizations in the source
distribution.

Linux and FreeBSD:

mpeg3play 0.9.6 (and later versions) tries to nice -11 in order to raise
the priority of the mpeg3play process above i.e. graphics operations
and obtain better sound quality. To take advantage of this, you must run
mpeg3play as root or install it as setuid root.

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

ABOUT THE SOURCE CODE

mpeg3play is developed on Solaris 2.4 using Sun SPARCompiler C 4.0.

A number of customization flags can be set in the makefile:

FSINGLE		Use single precision math.
OPTIMIZE	Select optimized C routines. If this is not defined,
		the original, slow code is selected.
BUILTIN_TABLES	Build lookup tables into the binary. Must always be
		defined with this source distribution.
DETECT_CLIP	Check and correct clipped samples. Slows down the player
		somewhat, but sounds better with (too) loud audio samples.
ASM_OPTIMIZE	Select optimized assembly functions. As shipped, the
		following function is expected to be optimized in
		some external file: II_dequantize_sample()
INT_MATH	Select integer math routines. A somewhat optimized integer
		math version of the function SubBandSynthesis() is included
		in decode.c. But fp math is faster than integer math on CPUs
		like SPARC and Pentium, so this is normally not a good way
		to optimize anyway.
		
This is a runtime profile that lists the most important functions to
optimize for playback of layer 3 audio:

granularity: each sample hit covers 2 byte(s) for 0.05% of 22.21 seconds

   %  cumulative    self              self    total          
 time   seconds   seconds    calls  ms/call  ms/call name    
 23.4       5.20     5.20   170928     0.03     0.03  SubBandSynthesis [3]
 14.8       8.48     3.28   303872     0.01     0.01  inv_mdct [6]
 12.6      11.28     2.80     9496     0.29     0.29  III_dequantize_sample [7]
  9.8      13.45     2.17     9496     0.23     0.39  III_hufman_decode [4]
  6.8      14.95     1.50      676     2.22     2.22  _write [10]
  6.7      16.43     1.48     4748     0.31     0.31  III_stereo [11]
  3.6      18.18     0.80  1052029     0.00     0.00  huffman_decoder [9]
  3.2      18.88     0.71  4775924     0.00     0.00  hget1bit [12]
  1.5      20.25     0.34     9496     0.04     0.04  III_antialias [15]
  1.4      20.56     0.31   303872     0.00     0.01  III_hybrid [5]
  1.4      20.86     0.30     9496     0.03     0.03  III_reorder [16]
  1.4      21.16     0.30     4748     0.06     0.37  out_fifo [8]
  0.9      21.36     0.21   767752     0.00     0.00  getbits [14]
  0.5      21.61     0.12   214608     0.00     0.00  hgetbits [22]
  0.5      21.72     0.11     9001     0.01     0.01  _memcpy [23]
  0.5      21.82     0.10       93     1.08     1.08  _read [24]
  0.5      21.92     0.10        7    14.29    14.29  _ioctl [25]
  0.4      22.00     0.08   659390     0.00     0.00  hputbuf [26]
  0.1      22.10     0.02    72752     0.00     0.00  get1bit [33]
  0.1      22.12     0.02     9496     0.00     0.01  III_get_scale_factors [18]
  0.1      22.14     0.02      182     0.11     0.83  refill_buffer [17]
  0.0      22.15     0.01   179285     0.00     0.00  hsstell [38]
  0.0      22.16     0.01    25371     0.00     0.00  _memset [40]
  0.0      22.17     0.01    10010     0.00     0.00  __tan [41]
  0.0      22.18     0.01     2768     0.00     0.00  __cos [42]
  0.0      22.19     0.01     2374     0.00     0.03  III_get_side_info [27]
  0.0      22.20     0.01        4     2.50     2.50  _smalloc [43]
  0.0      22.20     0.01                            huffman_coder [47]
  0.0      22.21     0.01                            look_ahead [48]
  0.0      22.21     0.01                            update_CRC [49]
  0.0      22.21     0.00     9496     0.00     0.00  initialize_huffman [44]
  0.0      22.21     0.00     4748     0.00     0.00  main_data_slots [53]
  0.0      22.21     0.00     2375     0.00     0.00  end_bs [54]
  0.0      22.21     0.00     2374     0.00     0.00  decode_info [37]
  0.0      22.21     0.00     2374     0.00     0.00  hdr_to_frps [55]
  0.0      22.21     0.00     2374     0.00     0.00  seek_sync [51]
  0.0      22.21     0.00     2374     0.00     0.00  sstell [56]


And this is the corresponding profile for playback of layer 2 files:

granularity: each sample hit covers 2 byte(s) for 0.06% of 16.12 seconds

   %  cumulative    self              self    total          
 time   seconds   seconds    calls  ms/call  ms/call name    
 44.0       7.09     7.09   245376     0.03     0.03  SubBandSynthesis [3]
 17.6       9.92     2.83    40896     0.07     0.07  II_dequantize_sample [5]
 13.6      12.12     2.20      968     2.27     2.27  _write [6]
  8.9      13.56     1.44    40896     0.04     0.05  II_buffer_sample [7]
  4.7      14.32     0.76  2363383     0.00     0.00  getbits [8]
  4.2      14.99     0.67    40897     0.02     0.07  out_fifo [4]
  2.6      15.41     0.42    40896     0.01     0.01  II_denormalize_sample [9]
  0.6      15.93     0.10        7    14.29    14.29  _ioctl [12]
  0.1      16.07     0.02     3408     0.01     0.05  II_decode_scale [10]
  0.1      16.09     0.02                            look_ahead [23]
  0.1      16.10     0.01     3408     0.00     0.00  decode_info [24]
  0.1      16.11     0.01      349     0.03     0.11  refill_buffer [15]
  0.0      16.12     0.01                            create_syn_filter [28]
  0.0      16.12     0.00    20448     0.00     0.00  get1bit [31]
  0.0      16.12     0.00     3409     0.00     0.00  end_bs [32]
  0.0      16.12     0.00     3409     0.00     0.00  seek_sync [29]
  0.0      16.12     0.00     3409     0.00     0.00  sstell [33]
  0.0      16.12     0.00     3408     0.00     0.01  II_decode_bitalloc [16]
  0.0      16.12     0.00     3408     0.00     0.00  hdr_to_frps [34]
  0.0      16.12     0.00     3408     0.00     0.00  pick_table [35]
  0.0      16.12     0.00     2048     0.00     0.00  __cos [278]
  0.0      16.12     0.00     1917     0.00     0.00  __libmopt__rem_pio2 [279]
  0.0      16.12     0.00      959     0.00     0.00  __libmopt__k_cos_ [280]
  0.0      16.12     0.00      959     0.00     0.00  sound_write [36]
  0.0      16.12     0.00      958     0.00     0.00  __libmopt__k_sin_ [281]
  0.0      16.12     0.00      523     0.00     0.00  _memcpy [282]
  0.0      16.12     0.00      351     0.00     0.08  fread [17]


The original source code for the decoder can be found in the file
ftp://ftp.tnt.uni-hannover.de/pub/MPEG/audio/mpeg2/software/
technical_report/dist08.tar.gz

To make it easier to update and improve mpeg3play, I would like to be
notified of enhancements to this source, so that they can be merged
into future versions of mpeg3play.

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

KNOWN PROBLEMS

- Audio streaming through Netscape sometimes fail (probably a caching
  issue, try to clear the Netscape cache if this happens).

- Cannot play some 16kbps mono files. This is probably due to the very
  crude implementation of bitstream synchword detection.  It may not be
  able to correctly decode valid bitstreams which have false synchword
  patterns in the ancillary data portion of the bitstream.

- mpeg3play makes the Linux audio driver leak memory (presumably by not
  cleaning up nicely once it's done).

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

HISTORY

16-Dec-96  0.9	  - The initial Solaris/SPARC release.

30-Jan-97  0.9.1  - Code cleanups to remove compiler warnings, audio device
		    initialization moved to its own function, implementation
		    of SubBandSynthesis was slightly changed.
		  - The source was ported to Linux.

31-Jan-97  0.9.2  - Some additional optimizations, single precision floats
		    (-DFSINGLE) now works on Linux.

2-Feb-97   0.9.3  - The source was ported to HPUX 9.05, minor optimizations.

16-Feb-97  0.9.4  - System-dependent audio routines were moved into separate
		    files audio-<platform>.c.
		  - Amiga is now supported.
		  - SubBandSynthesis was optimized to reduce the CPU load from
		    65% to 56% for a typical layer 3 file.

23-Feb-97  0.9.5  - Several functions were optimized to reduce the CPU load
		    by another 12% to 25% (on Solaris, with my test files).
		  - Support for IBM AIX was added.

6-Apr-97   0.9.6  - A simple man page was included.
		  - Makefile and audio routine changes to support three more
		    operating systems: FreeBSD, Solaris/x86, SunOS 4.x
		  - Command line switch -r added for Amiga (only) to enable
		    raw audio output.
		  - SNDCTL_DSP_SETFRAGMENT ioctl and nice(-11) for Linux
		    and FreeBSD to improve sound quality.
		  - SubBandSynthesis optimizations, implemented using a
		    fast cosine transform. This change reduces the CPU load
		    by about 10% to 20%.

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

   Copyright (C) 1996, 1997 by Johan Hagman

mpeg3play is distributed "as is" at no additional charge. It can
be used freely for any purpose, but may not be sold commercially.

Johan Hagman disclaims all warranties with regard to this software,
including all implied warranties of merchantability and fitness.
In no event will Johan Hagman be liable for direct, incidental or
consequential damages resulting from loss of data or business
opportunities, resulting from mpeg3play, or any part of same,
either alone or in conjunction with other programs.
