Audio::MPC - Perl extension for decoding musepack-encoded files
use Audio::MPC; use Fcntl qw/:seek/; my $mpc = Audio::MPC->new("file.mpc") or die Audio::MPC->errstr; open OUT, ">", "file.wav" or die $!; seek OUT, WAV_HEADER_SIZE, SEEK_SET; # leave space for wave-header my $total; while ((my $num_bytes = $mpc->decode(my $buf)) > 0) { $total += $num_bytes; print OUT $buf; } # insert wave-header for $total bytes of data seek OUT, 0, SEEK_SET; print OUT $mpc->wave_header($total); close OUT;
This module is a wrapper around libmpcdec that allows for decoding musepack-encoded digital audio.
Musepack is a lossy audio-compression format optimized for higher bitrates. See http://www.musepack.net/ for details.
These construct a new Audio::MPC object. The compressed audio-data will either come from file, filehandle-ref or from an Audio::MPC::Reader object (see "Audio::MPC::Reader" further below for details).
Audio::MPC
Returns the newly created object or undef in case of an error. In this case, check Audio::MPC->errstr.
undef
Audio::MPC->errstr
Reads data from the audio-stream and puts the decoded PCM-samples into buffer which must not be readonly. The PCM data will be stereo (that is, two channels) and 44.1 kHZ with each sample 16 bit wide.
The optional second argument specifies the byte-order of each sample. If not specified, MPC_LITTLE_ENDIAN is assumed.
Returns the length of buffer, "0 but true" if the stream was succesfully decoded with no more samples left and false in case of an error.
This class method returns a string telling you what kind of error occured. Currently, only use this method after the constructor new failed to return a new object.
new
Returns a wave file header suitable for length bytes of data. The optional second argument specifies the byte-order of the wave file and should match the byte-order you specified in your calls to decode. If ommitted, MPC_LITTLE_ENDIAN is assumed.
decode
See "SYNOPSIS" for an example on how to use the decode and wave_header couple.
wave_header
Seeks to the sample-th sample in the audio-stream.
Returns true on success, false otherwise.
Seeks to the specified position in seconds.
Returns the length of the audio-stream in seconds.
Returns the sample frequency of the stream.
Returns number of channels of the stream.
Returns byte offset of the header's position in the stream.
Returns this stream's version.
Returns bitrate per second of this stream. I have yet to find a file where this method will not return 0.
Returns the average bitrate per second of this stream.
Returns the number of frames in this stream.
Returns the number of samples in this stream. Unfortunately, this value cannot be used to precalculate the size of the resulting PCM stream.
Returns the maximum band-index used in this file (in the range 0 .. 31).
Returns true if intensitiy stereo is on. However, nowhere it is explained what intensity stereo is.
intensity stereo
Returns true if mid/side stereo is on.
This appears to be supported only on version 4 throughout 6 streams.
Returns an integer specifying the quality profile of this stream.
Returns the name of the quality profiled used for this stream.
Returns the replay gain title value.
Returns the replay gain album value.
Returns the peak title loudness level.
Returns the peak album loudness level.
Returns true if this stream is gapless.
Returns the number of valid samples in the last frame.
Returns the version of the encoder this stream was encoded with.
Returns the name of the encoder this was stream was encoded with.
Returns the offset to the file tags.
Returns the total length of the underlying file.
Aside from a filename or a reference to a filehandle, Audio::MPC->new can also be fed an Audio::MPC::Reader object. Such an object is a collection of callback functions that get called by the decoding engine on the various file operations, such as reading data or seeking in them.
Audio::MPC->new
Audio::MPC::Reader
Constructs a new Audio::MPC::Reader object:
open my $fh, "file.mpc" or die $!; my $reader = Audio::MPC::Reader->new( $fh, read => \&my_read, seek => \&my_seek, tell => \&my_tell, get_size => \&my_get_size, canseek => \&canseek, userdata => { }, # arbitrary user data associated with the reader ); my $mpc = Audio::MPC->new( $reader );
filehandle is the only mandatory argument. If any of the other fields (or even all of them) remain unspecified, Audio::MPC::Reader will use its own default handlers.
Each handler receives the Audio::MPC::Reader object as its first argument. To get at the filehandle, you call the fh method on this object. Call userdata to retrieve the user data you associated with this reader.
fh
userdata
The purpose and calling-convention for each handler is as follows:
This is called when the decoder wants to acquire more data to decode. reader is the object as returned by Audio::MPC::Reader->new and size denotes the number of bytes that should be read from the stream. The function is expected to return the data read from the underlying filehandle.
Audio::MPC::Reader->new
sub my_read { my ($reader, $size) = @_; read $reader->fh, my ($buf), $size; return $buf; }
offset is the byte position to seek to. The function is expected to return true if the seek operation was succesful:
sub my_seek { my ($reader, $offset) = @_; return seek $reader->fh, $offset, SEEK_SET; }
The function is expected to return the filepointer's current position in the stream:
sub my_tell { my $reader = shift; return tell $reader->fh; }
The function is expected to return the size of the complete data-stream:
sub my_get_size { my $reader = shift; return -s $reader->fh; }
The function is expected to return a true value if the underlying filehandle is seekable. However, experiments showed that non-seekable streams cannot be decoded and are therefore not handled at all:
sub canseek { my $reader = shift; return seek $reader->fh, 0, SEEK_CUR; # test if seek succeeded }
These symbols are exported by default:
WAV_HEADER_SIZE MPC_LITTLE_ENDIAN MPC_BIG_ENDIAN
I am not aware of any outright bugs yet.
A limitation of libmpcdec seems to be that you cannot decode from STDIN as it is not seekable. It should however be possible to craft your own Audio::MPC::Reader object which maintains an internal character buffer as userdata that can be used to fake up a seekable filehandle.
http://www.musepack.net/
This is version 0.04.
Tassilo von Parseval, <tassilo.von.parseval@rwth-aachen.de>
libmpcdec support patch by Sylvain Cresto, <scresto@gmail.com>
Copyright (C) 2005, 2006 by Tassilo von Parseval
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.4 or, at your option, any later version of Perl 5 you may have available.
5 POD Errors
The following errors were encountered while parsing the POD:
Expected text after =item, not a bullet
To install Audio::MPC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Audio::MPC
CPAN shell
perl -MCPAN -e shell install Audio::MPC
For more information on module installation, please visit the detailed CPAN module installation guide.