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
musicus (1.11 or later) - 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.
- <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 in such instances as when it dies.
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
These 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 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 actually started playing.
getpos
Fired after a successful "getpos" call, first argument is the position in the file.
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 a "getinfocurr" command. I have no idea why this happens and help would be appreciated.
ACKNOWLEDGEMENTS
This component is 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 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.