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 generally the same as play.pl, but uses the builtin message handler. You'll see, that this solution is much more elegant. It *requires* Term::ReadKey. This script makes use of the debugging facility and 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 ;) BASIC CONCEPT The concept of the Xaudio async API is based on forking an extra process (or thread) for the MPEG decoding and playing. The parent process controls this process by sending and recieving messages. This message passing is asynchronous. This module interface provides methods for sending common messages to the MPEG process, eg. play, pause, stop. Also it implements a message handler to process the messages sent back. Eg. every message sent to the subprocess will be acknowledged by sending back an XA_MSG_NOTIFY_ACK message (or XA_MSG_NOTIFY_NACK on error). Error handling must be set up by handling this messages. You will find detailed information about the interface of this module in its POD documentation. 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, I fear 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 a bug please send me a report. I will fix this 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.07 Wed Sep 08 1999, joern - Bugfix: $mp3->get_message was broken in Version 0.06, among other things the gtk* samples suffered from this bug and did not function - the creation of the message hash in MP3Play.xs and conv_msg.c is now much more elegant. Thanks to Dan Sugalski for the hint. 0.06 Mon Sep 06 1999, joern - fixed a memory leak in the get_message* methods. Thanks to Gene Senyszyn for the detailed bug report 0.05 Mon Aug 09 1999, joern - debugging implemented by providing default handlers for XA_MSG_NOTIFY_ACK and _NACK. - samples/handler.pl uses debugging for demonstration purposes 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