POE::Wheel::Audio::Mad is an attempt to bring a naitive perl mpeg
decoder into a perl session. This module was written to work as
a POE Wheel due to it's nature -- it simply playes mpeg streams --
you have to do the job of controlling the player and handling
updates. This really isn't your traditional wheel.

If defined to a true value, this will cause the decoder to
physically close the output device when stream decoding is
in the paused state. This frees up the device for use by
other applications. Default: false.

Specifies the sampling rate to open the dsp device at. If a
stream is not at this sampling rate Audio::Mad::Resample will
be used to up/down-sample the stream to match. Any standard
sampling rate can be used.

Specifies the denominator to use when returning the stream
progress index. The duration in seconds is divided by this
number to determine playing unit size, as each "unit" is
passed a progress message is generated indicating how many
units have been played.

POE::Wheel::Audio::Mad brings with it a large amount of
states that get defined in your session. Most of these
states are used for controlling the decoder behaviour
or for querying information, and they are listed below.
All of these states take a single hashref as their
argument, the keys and expected values (if any) are
listed as well.

integer indiciating the denominator to use when determining
relative file offsets. default: the current value of the
decoder option 'decoder_progress_range', see OPTIONS.

For example:
to seek 25% past the beginning (if the stream is 500 seconds
long, this would start playing at 125 seconds):
$kernel->yield('decoder_seek', { position => 25, range => 100 });
to seek to a specific second, use the desired second as
the position, and the number of seconds in the stream
as the range:
$kernel->yield('decoder_seek', { position => 125, range => 500 });

string indicating the key, or the name of the option
that you wish to set. If you are changing decoder
options, this is just the name of the option as listed
above. If you are manipulating the mixer, possible
values are: 'volume', 'pcm', or 'balance'.

This wheel will send messages back to your session via the state
you specified in the option 'message_event'. This state will
be passed decoder messages, one at a time, in hashref format.
This hashref always has only two keys: id, and data. 'id' is
the identifier for the message. Every message id used by the
decoder is listed below. data is the payload corresponding to
this type of event. It could possibly be of any type or value,
or possibly blank, but it will always be defined.

Emitted when a shutdown has been specifically asked for, usually
by yielding to 'decoder_shutdown'. After all files have been
closed, the output device shutdown, and resources freed this
state will be emitted to let users know the wheel is ready to
be destroyed.

Emitted when the decoder has been asked to open a file,
but couldn't find the file or locate a valid mepg stream
within the file. the data packet contains a string with
a short message about the error.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself with the exception that you must also feel bad if you don't email me with your opinions of this module.