view release on metacpan or  search on metacpan

lib/Audio/MPC.pm  view on Meta::CPAN

1;
__END__

=for changes stop

=head1 NAME

Audio::MPC - Perl extension for decoding musepack-encoded files

=head1 SYNOPSIS

    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;
	
=head1 DESCRIPTION

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 L<http://www.musepack.net/> for details.

=for readme stop

=head1 METHODS

=over 4

=item B<new> (file)

=item B<new> (filehandle-ref)

=item B<new> (Audio::MPC::Reader)

These construct a new C<Audio::MPC> object. The compressed audio-data will
either come from I<file>, I<filehandle-ref> or from an I<Audio::MPC::Reader>
object (see L</"Audio::MPC::Reader"> further below for details). 

Returns the newly created object or C<undef> in case of an error. In this case,
check C<< Audio::MPC->errstr >>.

=item B<decode> (buffer, [ MPC_LITTLE_ENDIAN || MPC_BIG_ENDIAN ])

Reads data from the audio-stream and puts the decoded PCM-samples into
I<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, I<MPC_LITTLE_ENDIAN> is assumed.

Returns the length of I<buffer>, "0 but true" if the stream was succesfully
decoded with no more samples left and false in case of an error.

=item B<errstr>

This class method returns a string telling you what kind of error occured.
Currently, only use this method after the constructor C<new> failed to return a
new object.

=item B<wave_header> (length, [ MPC_LITTLE_ENDIAN || MPC_BIG_ENDIAN ])

Returns a wave file header suitable for I<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 C<decode>. If ommitted, 
I<MPC_LITTLE_ENDIAN> is assumed.

See L</"SYNOPSIS"> for an example on how to use the C<decode> and
C<wave_header> couple.

=item B<seek_sample> (sample)

Seeks to the I<sample>-th sample in the audio-stream. 

Returns true on success, false otherwise.

=item B<seek_seconds> (second)

Seeks to the specified position in seconds.

Returns true on success, false otherwise.

=item B<length>

Returns the length of the audio-stream in seconds.

=item B<frequency>

Returns the sample frequency of the stream.

=item B<channels>

Returns number of channels of the stream.

=item B<header_pos>

Returns byte offset of the header's position in the stream.

=item B<version>

Returns this stream's version.

=item B<bps>

Returns bitrate per second of this stream. I have yet to find
a file where this method will not return 0.

=item B<average_bps>

Returns the average bitrate per second of this stream.

=item B<frames>

lib/Audio/MPC.pm  view on Meta::CPAN

	userdata    => { }, # arbitrary user data associated with the reader
    );

    my $mpc = Audio::MPC->new( $reader );

I<filehandle> is the only mandatory argument. If any of the other fields (or
even all of them) remain unspecified, C<Audio::MPC::Reader> will use its own
default handlers.

Each handler receives the C<Audio::MPC::Reader> object as its first argument.
To get at the filehandle, you call the C<fh> method on this object. Call
C<userdata> to retrieve the user data you associated with this reader.

The purpose and calling-convention for each handler is as follows:

=item * read (reader, size)

This is called when the decoder wants to acquire more data to decode. I<reader> is
the object as returned by C<< Audio::MPC::Reader->new >> and I<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.

    sub my_read {
	my ($reader, $size) = @_;
	read $reader->fh, my ($buf), $size;
	return $buf;
    }

=item * seek (reader, offset)

I<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;
    }

=item * tell (reader)

The function is expected to return the filepointer's current position in the stream:

    sub my_tell {
	my $reader = shift;
	return tell $reader->fh;
    }

=item * get_size (reader)

The function is expected to return the size of the complete data-stream:

    sub my_get_size {
	my $reader = shift;
	return -s $reader->fh;
    }

=item * canseek (reader)

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
    }

=back

=head1 EXPORT

These symbols are exported by default:

    WAV_HEADER_SIZE
    MPC_LITTLE_ENDIAN
    MPC_BIG_ENDIAN

=head1 BUGS AND LIMITATIONS

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
C<Audio::MPC::Reader> object which maintains an internal character buffer as
userdata that can be used to fake up a seekable filehandle.

=for readme continue

=begin readme

=head1 INSTALLATION

To install this module type the following:

   perl Makefile.PL
   make
   make test
   make install

=head1 DEPENDENCIES

Due to a subtle but unpleasant interaction between C++ method overloading and
the perl internals, you need at least perl5.8.0. 

You need a working C++ compiler and libmpcdec as available from L<http://www.musepack.net/>.
Furthermore:

    Test::More
    Test::LongString

=end readme

=begin changes

=head1 Revision history for Perl extension Audio::MPC

=over 4

=item * 0.04  Tue Mar  7 11:44:00 CEST 2006
 
    - updated to use libmpcdec who replaces libmusepack