NAME
POE::Component::Player::Musicus - a POE wrapper for the musicus audio player
SYNOPSIS
use POE qw(Component::Player::Musicus);
$musicus = POE::Component::Player::Musicus->new();
$musicus->play("test.mp3");
POE::Kernel->run();DESCRIPTION
This POE component is used to manipulate the musicus player from within a POE application.
REQUIREMENTS
POE::Component::Child (1.39 or later)
musicus (1.11 or later required) - http://muth.org/Robert/Musicus/
METHODS
An object oriented interface is provided as follows:
new %hash
Used to initialise the system and create a module instance. The optional hash may contain any of the following keys:
- alias
-
Indicates the name of a session to which events will be posted. Default: main.
- path
-
Path to your XMMS plugins. Default: /usr/lib/xmms.
- output
-
Output plugin. Default: libOSS.so.
- musicus
-
Location of musicus executable. Default: musicus.
- delay
-
Some plugins can get confused if you send multiple getpos and setpos commands in quick succession (libmpg123 is the only one I've found so far) and musicus will lock up. This option will ensure a minumum delay of any number of microseconds between commands. It defaults to no delay. This uses POE's timed event interface, which means you will have higher precision in your delays if you have Time::HiRes installed, but it will work without it. In my personal experience, 100000 has been a safe number for a delay, but this is likely to change from machine to machine.
- <event-name>
-
Any event fired by this module can be mapped to a name of choice. This is useful for differentiating this component's events from some other component's e.g.
done => "musicus_done"will cause the component to fire a musicus_done event at the main session, instead of the usual done. For a comprehensive listing of events fired, please refer to the "EVENTS" section below.
start
This method starts the player. While it should not be necessary to ever call this method directly since the new() method calls it automatically, this method allows for restarting the player.
play <path>
This method requires a single parameter specifying the full path name of an audio file to play.
quit stop pause unpause
None of these methods take any parameters and will do exactly as their name implies.
getpos
Tells Musicus to send back the current position. Will cause a "getpos" event to fire.
getinfocurr
Tells Musicus to send back the current song information. Will cause a "getinfocurr" event to fire.
getinfo <file>
Tells Musicus to send back information about the file specified. Will cause a "getinfo" event to fire.
getlength
Tells Musicus to send back the length of the current file. Will cause a "getlength" event to fire.
getvol
Tells Musicus to send back the current volume. Will cause a "getvol" event to fire.
version
Tells Musicus to send back its version string. Will cause a "version" event to fire.
setvol <integer> <integer>
Causes Musicus to set the left and right channel volume to the numbers specified. Will cause a "setvol" event to fire.
setpos <integer>
Causes Musicus to jump to the specified location in the file.
xcmd <string>
This method allows for the sending of arbitrary commands to the player in the unlikely case that this component doesn't support something you want to do.
EVENTS
Events are fired at the session as configured in the new method by alias. The names of the event handlers may be changed from their defaults by using they name of the event listed below as they key and the name of the event you want it to be called as the value in the new.
ready
Fired when the player has successfully started. You do not need to wait for this event to start sending commands.
done / died
Fired upon termination or abnormal ending of the player. This event is inherited from POE::Component::Child, see those docs for more details.
error
Fired upon encountering an error. This includes not only errors generated during execution of the player but also generated by the player itself in an interactive basis i.e. any @ ERROR lines generated on stderr by the process. For parameter reference please see POE::Component::Child documentation, with the following caveat: for @ ERROR type errors, err is set to -1, syscall is set to the command type that failed, and error contains the player error string.
stop pause unpause
These events are fired whenever any of the named actions occur.
quit
This event is fired when the player has received the quit command and is about to exit.
version
Fired after the "version" method is called, first argument is the Musicus version string.
setvol
Fired after a successful "setvol" call.
play
Fired after a song has been loaded, first argument is the input plugin that will be used to play it. Note that Musicus doesn't check to make sure it can actually play the file before returning this, it would probably be best to call "getpos" after you get this event to make sure that the song really started playing.
getpos
Fired after a successful "getpos" call, first argument is the position in the file. XMMS plugins are expected to return either the position if the song is still playing, -1 if it has stopped, or -2 if there was an output failure such as not being able to open the output device.
getinfocurr
Fired after a successful "getinfocurr" call, first argument is a hashref with the following keys: file, length, artist, title, album, track, year, date, genre, and comment. The file value is the same as the argument that was supplied to "play".
getinfo
Fired after a successful "getinfo" call. The format is the same as "getinfocurr". The file value is the same as the argument supplied to the "getinfo" method.
setpos
Fired after a successful "setpos", first argument is the position playback has been set to.
getlength
Fired after a successful "getlength", first argument is the length of the audio file.
AUTHOR
Curtis "Mr_Person" Hawthorne <mrperson@cpan.org>
BUGS
If the XMMS MAD plugin is used, Musicus may mysteriously die on the "getinfocurr" command. I have no idea why this happens and help would be appreciated.
ACKNOWLEDGEMENTS
This component was based on POE::Component::Player::Mpg123 by Erick Calder, which is distributed under the MIT License.
Development would not have been possible without the generous help of Robert Muth, creator of Musicus (http://www.muth.org/Robert/).
Some ideas for the getinfo/getinfocurr processing were taken from a patch submitted by Mike Schilli (http://www.perlmeister.com).
LICENSE AND COPYRIGHT
Copyright (c) 2004-2006 Curtis "Mr_Person" Hawthorne. This product is distributed under the MIT License. A copy of this license was included in a file called LICENSE. If for some reason, this file was not included, please see http://www.opensource.org/licenses/mit-license.html to obtain a copy of this license.