NAME
    MPEG::MP3Play - Perl extension for playing back MPEG music

SYNOPSIS
      use MPEG::MP3Play;
      my $mp3 = new MPEG::MP3Play;
      
      $mp3->open ("test.mp3");
      $mp3->play;
      $mp3->message_handler;

DESCRIPTION
    This Perl module enables you to playback MPEG music.

PREREQUISITES
    Xaudio SDK

    MPEG::MP3Play is build against the 3.0 version of the Xaudio SDK
    and uses the async interface of the Xaudio library.

    I don't know if older versions will work properly. The SDK is
    not part of this distribution, so get and install it first
    (http://www.xaudio.com/).

    Perl

    I built and tested this module using Perl 5.005_03. It should
    work also with Perl 5.004_04 and above, but I did not test this.
    If someone builds MPEG::MP3Play successfully with other versions
    of Perl, plesase drop me a note.

    Optionally used Perl modules

      samples/play.pl uses Term::ReadKey if it's installed.
      samples/handler.pl requires Term::ReadKey.
      samples/gtk*.pl require Gtk.

INSTALLATION
    First, generate the Makefile:

      perl Makefile.PL

    You will be prompted for the location of the Xaudio SDK. The
    directory must contain the include and lib subdirectories, where
    the Xaudio header and library files are installed.

      make
      make test
      ./runsample play.pl
      ./runsample handler.pl
      ./runsample gtk.pl
      ./runsample gtkhandler.pl
      make install

SAMPLE SCRIPTS
    There are some small test scripts in the samples directory. You
    can run these scripts before 'make install' with the runsample
    script (or directly with 'perl', after running 'make install').
    For runsample usage: see above.

    All scripts expect a mp3 file 'test.mp3' in the actual
    directory.

    play.pl Textmodus playback. Displays the timecode. Simple volume
            control with '+' and '-' keys.

    handler.pl
            Does exactly the same as play.pl, but uses the builtin
            message handler. You'll see, that this solution is much
            more elegant. *Requires* Term::ReadKey.

            This script is best documented so far.

    gtk.pl  This script demonstrates the usage of MPEG::MP3Play with the
            Gtk module. It produces a simple window with a progress
            bar while playing back the test.mp3 file.

    gtkhandler.pl
            This script does the same as gtk.pl but uses the builtin
            message handler concept instead of implementing message
            handling by itself. Advantage of using the builtin
            message handler: no global variables are necessary
            anymore.

    synopsis.pl
            This one proves that the usage shown in the SYNOPSIS
            *really* works ;)

TODO
      - Testing of all methods.
      - Testing under Win32
      - support of the full Xaudio API, with input/output
        modules, etc.
      - documentation: more details about the messages
        hashes
      - runsample.bat for Win32

    Ideas, code and any help are very appreciated.

BUGS
      - samples/gtk*.pl throw some Gdk messages on exit.
        (not really a MPEG::MP3Play bug, it documents that
         I'm a beginner in coding Gtk+ applications ;)
      - the runsample script currently works only under
        Unix, it will fail under Win32

    If you find bugs please send me a report. I will fix them as
    soon as possible. Also I'm very interested to know, if someone
    write applications based on this module, so don't hesitate to
    send me an email, if you like (or not like ;) this module.

AUTHOR
    Joern Reder, joern@netcologne.de

COPYRIGHT
    Copyright (C) 1999 by Joern Reder, All Rights Reserved.

    This library is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

    The Xaudio SDK is copyright by MpegTV,LLC. Please refer to the
    LICENSE text published on http://www.xaudio.com/.

SEE ALSO
    perl(1), MPEG::MP3Info.

CHANGES
    Revision history for Perl extension MPEG::MP3Play.

    0.04  Sat Aug 07 1999, joern
	- implemented a builtin message handler mechanism.
	  Message corresponding methods will be invoked,
	  so the user can simply supply/overload the message
	  methods.
	- added samples/handler.pl and samples/gtkhandler.pl
	  to demonstrate the use of the builtin message handler.
	- added samples/synopsis.pl. This proves that the
	  usage shown in the SYNOPSIS really works ;)
	- no symbols are exported by default anymore, some
	  Exporter tags are available instead.

	  THIS IS AN INCOMPATIBLE CHANGE.

	  Try 'use MPEG::MP3Play qw(:DEFAULT)' as a first step,
	  but better look into the documentation and see, which
	  symbols you really need to import.
	  
	  I think 'use MPEG::MP3Play qw(:msg :state)' will work
	  in most cases.
	- notification_mask setting
	- player mode setting
	- default message handler for player_state messages
	- fixed some minor documentation typos

    0.03  Thu Aug 05 1999, joern
	- gen_constant generates constants.h included by
	  MP3Play.xs. gen_constant checks defines and enums,
	  not only defines like h2xs does.
	- so now all Xaudio symbols are available
	- gen* scripts moved to the tools directory
	- test.pl now only loads the module
	- there are now more sophisticated test scripts in
	  the samples directory, e.g. a script which uses
	  Gtk+ to play a file showing a progress bar. This
	  demonstrates the connection of the Xaudio
	  message queue to Gdk.
	- almost anything well documented now

    0.02  Tue Aug 03 1999, joern
	- added gen_conv_msg.pl to generate conv_msg.c out
	  of the HTML documention provided by Xaudio
	- conv_msg.c converts XA messages to HVs, for simple
	  handling in Perl
	- test.pl enhanced. Now shows timecode and exits on
	  key pressure (if Term::ReadKey is installed) and
	  on end of file.
	- fixed minor POD formatting errors in MP3Play.pm

    0.01  Sun Jul 25 1999, joern
	- original version; created by h2xs 1.19
	- my first contact with XS, but playing mp3 files works
	  after two hours. I like it! ;)
	- no error/message handling at all
