MPEG::Audio::Frame - a class for weeding out MPEG audio frames out of a file handle.
use MPEG::Audio::Frame; open FILE,"file.mp3"; while(my $frame = MPEG::Audio::Frame->read(\*FILE)){ print $frame->offset(), ": ", $frame->bitrate(), "Kbps/", $frame->sample()/1000, "KHz\n"; # or something. }
A very simple, pure Perl module which allows parsing out data from mp3 files, or streams, and chunking them up into different frames. You can use this to accurately determine the length of an mp3, filter nonaudio data, or chunk up the file for streaming via datagram. Virtually anything is possible.
MPEG::Audio::Frame supports various types of MPEG data.
Any type of MPEG1 audio is supported, including the backwards compatible multichannel extensions to MPEG-1. See t/20-mpeg1-*.t.
MPEG 2 has a variation on the multichannel extension, which is not backwards compatible. It still structurally resembles MPEG 1, but there is no publically documented method for telling apart MPEG-2 MC from MPEG-2 LSF.
There is another type of MPEG 2, which is more similar to MPEG 2.5, called MPEG-2 low sampling frequency. It the only type of MPEG-2 supported. See t/20-mpeg2-22050.
This unofficial standard is also supported. Since it is unofficial, and sometimes causes problems when streams contain garbage between frames, it can be disabled.
There is a test, t/20-mpeg2-test30.t, which fails if MPEG 2.5 is allowed. It is not included in the distribution because MPEG-2 multichannel is not supported and those tests are just failing bloat. Ask me about darcs access if you're curious.
There are two types of methods in this module, aside from the constructor read.
read
The first kind are accessors, which return the value of a certain header field, like version, which will return the actual integer value of the bits of that field.
version
The second kind is sorts of queries on the accessible data. For example, is_mono checks to see of the channels accessor returns the value for mono.
is_mono
channels
This is the constructor method. It receives a reference to a filehandle, and reads the next (hopefully) valid frame it can find on the stream. Please make sure use binmode if you're on a funny platform - the module doesn't know the difference, and shouldn't change stuff, IMHO.
The offset where the frame was found in the handle, as reported by tell().
Returns the binary data extracted from the handle. This is (definately|probably) a valid MPEG 1 or 2 audio frame.
asbin is also called via the overloaded operator "", so if you treat the frame object like a string, you'd get the binary data you'd get by calling asbin directly.
Returns the content of the frame, minus the header and the crc. This is (definately|probably) a valid MPEG 1 or 2 audio frame entity.
Returns a list of integers in list context, or a 4 byte long binary string in scalar context. The hash represents the header, split into it's parts, with bits translated into '0' and '1'. The binary string is (definately|probably) a valid MPEG 1 or 2 audio frame header.
Returns the bytes of the checksum, as extracted from the handle. This is (definately) a valid checksum, unless there was none in the frame, in which case it will be undef. It (definately|probably) applies to the frame.
Returns the value of the MPEG version bits.
Returns the value of the layer bits.
Returns the length, in bytes, of the entire frame. This is the length of the content, plus the four bytes of the header, and the two bytes of the crc, if applicable.
Returns the bitrate in kilobits. Note that 128Kbps means 128000, and not 131072. This not the actual integer value from the header.
This returns true if the bit rate is free. Since free bit rate files have a constant rate, that is anything. The bitrate must be known in advance for the file to be parsable.
See $MPEG::Audio::Frame::free_bitrate.
$MPEG::Audio::Frame::free_bitrate
Returns the sample rate in Hz, not the integer value from the header.
Returns the length, in floating seconds, of the frame.
Given a constant rate file, of frames like this one, the value returned would be the number of such frames needed to get one second of audio.
Returns the integer value of the channels bits.
Wether or not the frame was padded.
Returns the value of the private bit.
Returns the vavlue of the copyright bit.
Returns the value of the original home bit.
The mode extension bits. It is used to specify type of joint stereo to use in layer III, and the bands to apply intensity stereo to on layers I and II.
Returns the value of the emphasis bits,
This returns true if the CRC computation failed for a protected layer I or III frame. It will always return false on unprotected frames, because we can't know if they're bad or not.
crc_ok is the opposite.
crc_ok
Whether not the frame has a checksum.
Dual channel is not stereo, but two separate mono channels.
Stereo means 'normal' stereo... That is two channels.
Some kind of variation on two channel audio that isn't dual_channel.
dual_channel
Joint stereo is a type of stereo.
Neither of the below joint stereo variations.
Intensity and MS stereo apply to layer III.
Intensity stereo is a type of joint stereo.
Note that this method also dies on layers I or II. This is behavior might change if I change my mind and decide that this is stupid.
Since layers I and II joint stereo is always implemented in terms of intensity stereo, however, I reckoned it was more appropriate to make this apply only to the layer III case, to provide stricter error checking.
Both intensity and ms stereo.
Intensity stereo without ms stereo.
See above.
These methods all query whether the mode extension field specifies band N to 31. They only apply to layers I and II.
The whether the version is equal to N.
Same for layers.
This tells MPEG::Audio::Frame to let non-critical data invalidations pass. The emphasize value, for example, has an invalid value, 2, which is meaningless to MPEG::Audio::Frame.
2
This does not apply to any of the header values used to actually mine the data, and any invalid values in these fields (like the MPEG version, or the bitrate) cause the current header start to be skipped under the assumption that it is simply not MPEG data.
This really only applies to the emphasis header field.
This is the bitrate to assume when frames are marked with the 'free' bit rate.
This is undefined by default.
When true, as is the default, MPEG-2.5 is supported. If that causes trouble, it can be disabled.
You can also read frame objects via the readline operator by tying a filehandle to this package in the following manner:
tie *MP3, 'MPEG::Audio::Frame',*FH; while(<MP3>){ print "frame at ", $_->offset(), "\n"; }
Way cool.
Yasuhiro Sasama submitted a patch to properly handle MPEG2.5 files.
Dropped support for MPEG-2 multichannel in favour of MPEG-2 LSF. No one seems to support MC. If you know how to tell them apart, or have the money to pay the ISO guys for the MC/LSF docs, and would like support for them in this module, contact me. Otherwise it doesn't look like it's going to happen.
Completely rehauled everything internal. Now nearly 50% faster (thanks Devel::DProf and Devel::Cover). NOTE! This introduces an incompatible change! $frame->header will no longer return a hash of string values, but an array of integers.
Test suite redone and expanded. Some "official" test files included.
Repackaged with Module::Build, and various goodnesses.
Trashed the useless README
Perl 5.005_04 compatibility.
Wrapped pod.
Johan Vromans cought a glitch in asbin, which surfaced in 0.07 - now fixed.
Made broken compute the CRC on demand instead of always.
Cryptographically signed distribution.
Fixed some doc errors, thanks to Nikolaus Schusser and Suleyman Gulsuner.
Fixed CRC computation on little endian machines.
Added overloading of object to asbin by default.
Added real CRC checking for layers III and I (layer II is a longer story).
Fixed the calculation of frame lengths when a CRC is present, thanks to Johan Vromans.
Reimplemented offset method, which came out of sync whilst working on various copies, thanks to Jeff Anderson.
offset
Some minor documentation and distribution fixes were made.
Yuval Kojman <nothingmuch@altern.org>
Copyright (c) 2003 Yuval Kojman. All rights reserved This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install MPEG::Audio::Frame, copy and paste the appropriate command in to your terminal.
cpanm
cpanm MPEG::Audio::Frame
CPAN shell
perl -MCPAN -e shell install MPEG::Audio::Frame
For more information on module installation, please visit the detailed CPAN module installation guide.