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; while ( 1 ) { my $msg = $mp3->get_message_wait; last if ( $msg->{code} == &XA_MSG_NOTIFY_PLAYER_STATE and $msg->{state} == &XA_PLAYER_STATE_EOF ) } $mp3->close; $mp3->exit; DESCRIPTION This Perl module enables you to playback MPEG music. PREREQUISITES 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/). samples/play.pl uses Term::ReadKey if it's installed. samples/gtk.pl depends on 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 gtk.pl make install SAMPLE SCRIPTS There are two small scripts in the samples directory You can run these script before 'make install' with the runsample script (usage: see above). Both scripts expect a mp3 file 'test.mp3' in the actual directory. play.pl Textmodus playback. Displays the timecode. Simple volume control with '+' and '-' keys. 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. CONSTRUCTOR new my $mp3 = new MPEG::MP3Play; This is the constructor of this class and takes no arguments. CONTROL METHODS The following methods control the audio playback. Internally they send messages to the Xaudio subsystem. This message passing is completely asynchronyous, so no result values (e.g. sucess) are given back by this methods. Instead the Xaudio subsystem sends back acknowledge messages. See the chapter MESSAGE HANDLING for details. open $mp3->open ($filename); Opens the MPEG file $filename. No playback is started at this time. close $mp3->close ($filename); Closes an opened file. exit $mp3->exit The Xaudio thread or process will be canceled. play $mp3->play Starts playing back an opened file. Must be called after $mp3->open. stop $mp3->stop Stops playing back a playing file. The play position rewinds to the beginning. pause $mp3->pause Pauses. $mp3->play will go further at the actual position. seek $mp3->seek ($offset, $range) Sets the play position to a specific value. $offset is the position relative to $range. If $range is 100 and $offset is 50, it will be positioned in the middle of the song. volume $mp3->volume ($pcm_level, $master_level, $balance) Sets volume parameters. $pcm_level is the level of the actual MPEG audio stream. $master_level is the master level of the sound subsystem. Both values must be set between 0 (silence) and 100 (ear breaking loud). A $balance of 50 is the middle, smaller is more left, higher is more right. MESSAGE HANDLING Currently there are two methods to get messages from the Xaudio subsystem. So it is up to you to set up the message handler by using this methods. In the near future MPEG::MP3Play will provide a default message handler which you can customize by overloading the message handler methods. get_message $msg_href = $mp3->get_message If there is a message in the players message queue, it will be returned as a hash reference immediately. This method will not block, if there is no message. It will return undef instead. get_message_wait $msg_href = $mp3->get_message_wait ( [$timeout] ) This method will wait max. $timeout microseconds, if there is no method in the queue. If $timeout is omitted it will block until the next message appears. The message will be returned as a hash reference. The message hash The returned messages are references to hashes. Please refer to the Xaudio SDK documentation for details. The message hashes are build 1:1 out of the structs documented there, using _ as a seperator for nested structs. (Simply use Data::Dumper to learn more about the message hashes ;) TODO - Testing of all methods. - implementation of a simple message handler - OO interface for message handling, with the possibility of overloading the message handlers - full documentation of all handled messages - more details about the messages hashes - support of the full Xaudio API, with input/output modules, etc. Ideas, code and any help are very appreciated. BUGS - samples/gtk.pl throws some Gdk messages on exit. (not really a MPEG::MP3Play bug ;) 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). CHANGES Revision history for Perl extension MPEG::MP3Play. 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. 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 handling at all