POE::Wheel::Audio::Mad - POE Wheel implementing in-session non-blocking mpeg stream playing
use POE; use POE::Wheel::Audio::Mad; POE::Session->create( inline_states => { _start => \&am_start, message => \&am_message } ); sub am_start { my ($kernel, $heap) = @_[KERNEL, HEAP]; ## you may also specify decoder options, listed below.. $heap->{wheel} = new POE::Wheel::Audio::Mad ( message_event => 'message' ); $kernel->yield( 'decoder_open', { filename => '/path/to/some/stream.mp3', play => 1 }); } sub am_message { my ($kernel, $message) = @_[KERNEL, ARG0]; if ($message->{id} eq 'INPUT_EOF_WARNING') { print "finished..\n"; undef $heap->{wheel}; } elsif ($message->{id} eq 'DECODER_FRAME_DATA') { if (defined($message->{data}->{played})) { print "\rplayed: $message->{data}->{played}"; } } } $poe_kernel->run(); exit();
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.
These options may be specified as part of the call to the new() constructor, and affect decoder behaviour.
*REQUIRED* Specifies which event in your session will be receiving event messages from the decoder. See section MESSAGES below for more information on what this will mean.
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.
If defined to a true value, this will cause the decoder to physically close the output device when stream decoding is in the stopped state. Default: true.
Specifies the complete path to the dsp device to open for playing decoded audio. Default: '/dev/dsp'
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 complete path to the mixer device to open for manipulating sound levels. Default: '/dev/mixer'
Specifies the balance to set the mixer to once opened. Any value between 0 (full left) and 100 (full right) may be used. Default: 50 (center)
Specifies the master volume to set the mixer to once opened. Any value between 0 (mute) and 100 (full volume) may be used. Default: 50
Specifies the pcm volume to set the mixer to once opened. Any value between 0 (mute) and 100 (full volume) may be used. Default: 60
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.
If defined to a true value, this will cause the decoder to immediatly begin playing a stream once an 'open' command has been issued for it.
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.
When called, this state will halt all current decoding activities, clean up it's internal state, release resources, and send a message indicating the shutdown was successful.
Opens a stream, scans it for validity and information, then prepares the decoder to begin playing. Possible keys are:
string containing the full pathname to the stream to be opened. required.
boolean indicating wether the decoder should begin playing the stream as soon as it's opened. default: [decoder_play_on_open]
Starts or resumes playing of the currently opened stream.
Pauses playing on the current stream. Decoding is halted, the input file remains open, and the current file position is preserved.
Stops playing on the current stream. Decoding is halted, the input file remains open, but the current file position is set to the beginning of the stream.
Seeks to a new position in the stream, and resumes playing at the new position. The keys used are:
integer specifying the relative position to seek to. required.
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 });
Updates decoder options (above) and manipulates mixer values. The following keys are all required to be present:
string indicating which subsystem you wish to manipulate. currently this is either 'option' for changing decoder options, or 'pcm' for manipulating the mixer.
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'.
value you wish to be assigned to the specified subsystem and key.
For example: to alter a decoder option, such as deactivating decoder_play_on_open: $kernel->yield('decoder_set', { type => 'option', key => 'decoder_play_on_open', value => 0 }); to change the mixer volume, such as setting the pcm volume to 75: $kernel->yield('decoder_set', { type => 'mixer', key => 'pcm', value => 75 });
Causes the decoder to output information about one of it's subsystems. You must specify a single key:
The name of a subsystem you would like to coherce into reporting state information. You may select one of: 'decoder', 'input', or 'dsp'. See section MESSAGES for help in parsing state information.
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 is asked to play, but no input file is open.
Emitted when the decoder is asked to pause, but the decoder is not currently playing.
Emitted when the decoder is asked to stop, but the decoder is not currently playing, or currently has an input file open.
Emitted when the decoder changes state. The data packet is a hashref containing information about the new state.
Currently the only key defined in the data packet, it a textual description of the current decoder state. Possible values are: 'CLOSED', 'STOPPED', 'PLAYING', 'PAUSED'.
Emitted periodically while the decoder is processing a stream. The data packet is a hashref which could contain one of the following keys:
an integer indicating the number of seconds that have been played in the stream. this gets printed every 500ms for better accuracy, as such, the value may not change each time it is printed.
an integer indicating relative position within the stream. the option 'decoder_progress_range' is used as a denominator and applied to the length (in bytes) of the stream.
Emitted when the decoder crosses an unrecoverable error while processing frames in the stream. the data packet contains a string with a short message about the error.
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.
Emitted when the decoder has successfully shutdown an input stream, and is ready to open a new input stream. the data packet contains a string with the name of the file that was closed.
Emitted when the decoders input subsystem has changed state. The data packet is a hashref, and could contain any of the following keys:
a string containing a description of the input systems new state. possible values are: 'OPEN' or 'CLOSED'.
a string containing the name of the file the input system has just changed state on. If state was 'OPEN', this file was just opened, if 'CLOSED', this file was just closed.
Emitted when new information about an input stream has just become available. Usually immediately after the stream has been opened. the data packet is a hasref, and could contain any of the following:
The number of frames calculated to be in this stream.
Boolean indicating wether the stream is variable or constant bitrate. false=CBR, true=VBR.
The number of bytes calculated to be in the stream.
The duration of the stream in HH:MM:SS.DDD format.
The calculated bitrate of this stream, as an integer.
The mean bitrate of this stream, as an integer.
The sampling rate of this stream.
The stereo mode of this stream.
The layer of this stream.
The frame flags for this stream.
The duration of each individual frame in this stream.
The number of frames in this stream, according to the Xing header.
The number of bytes in this stream, according to the Xing header.
Emitted when the decoder has come across an end-of-file contidition on the input stream file. the data packet is a string, and contains the name of the input stream file.
Emitted when the decoder has failed to call a close(2) on the input stream filehandle.
Emitted when the decoder has acquired the output device. the data packet is a string containing the path name of the device that has been opened.
Emitted when the decoder has failed to acquire an output device. It either failed to open the device, or set it's paramaters. the data packet is a string describing the error.
Emitted when the output device has changed state. the data packet is a hashref containing information about the new state.
Currently the only defined key in the data packet, it contains a textual description of the output subsystems state. Possible values are: 'CLOSED', 'OPEN'.
perl(1)
POE::Component::Audio::Mad::Dispatch(3) POE::Component::Audio::Mad::Handle(3)
Audio::Mad(3) Audio::OSS(3)
Mark McConnell, <mischke@cpan.org>
Copyright 2003 by Mark McConnell
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.
To install POE::Wheel::Audio::Mad, copy and paste the appropriate command in to your terminal.
cpanm
cpanm POE::Wheel::Audio::Mad
CPAN shell
perl -MCPAN -e shell install POE::Wheel::Audio::Mad
For more information on module installation, please visit the detailed CPAN module installation guide.