/ 
MPEG-Audio-Frame-0.10
River stage one • 3 direct dependents • 3 total dependents
/ MPEG::Audio::Frame

NAME

MPEG::Audio::Frame - a class for weeding out MPEG audio frames out of a file handle.

SYNOPSIS

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.
}

DESCRIPTION

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 FORMAT SUPPORT

MPEG::Audio::Frame supports various types of MPEG data.

MPEG-1

Any type of MPEG1 audio is supported, including the backwards compatible multichannel extensions to MPEG-1. See t/20-mpeg1-*.t.

MPEG-2 Multichannel

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.

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.

MPEG-2.5

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.

METHODS

There are two types of methods in this module, aside from the constructor 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.

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.

read GLOB

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.

offset

The offset where the frame was found in the handle, as reported by tell().

asbin

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.

content

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.

crc

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.

version

Returns the value of the MPEG version bits.

layer

Returns the value of the layer bits.

length

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.

bitrate

Returns the bitrate in kilobits. Note that 128Kbps means 128000, and not 131072. This not the actual integer value from the header.

free_bitrate

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.

sample

Returns the sample rate in Hz, not the integer value from the header.

seconds

Returns the length, in floating seconds, of the frame.

framerate

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.

channels

Returns the integer value of the channels bits.

pad

Wether or not the frame was padded.

private

Returns the value of the private bit.

Returns the vavlue of the copyright bit.

home

Returns the value of the original home bit.

modext

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.

emphasis
emph
emphasize
emphasise

Returns the value of the emphasis bits,

broken
crc_ok

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.

has_crc

Whether not the frame has a checksum.

mono
dual_channel

Dual channel is not stereo, but two separate mono channels.

stereo

Stereo means 'normal' stereo... That is two channels.

any_stereo

Some kind of variation on two channel audio that isn't dual_channel.

joint_stereo

Joint stereo is a type of stereo.

normal_joint_stereo

Neither of the below joint stereo variations.

Intensity and MS stereo apply to layer III.

intensity_stereo

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.

intensity_and_ms_stereo

Both intensity and ms stereo.

intensity_stereo_only

Intensity stereo without ms stereo.

ms_stereo
ms_and_intensity_stereo
ms_stereo_only

See above.

band_4
band_8
band_12
band_16

These methods all query whether the mode extension field specifies band N to 31. They only apply to layers I and II.

mpeg1
mpeg2
mpeg25

The whether the version is equal to N.

layer1
layer2
layer3

Same for layers.

PACKAGE VARIBLES

$MPEG::Audio::Frame::lax

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.

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.

$MPEG::Audio::Frame::free_bitrate

This is the bitrate to assume when frames are marked with the 'free' bit rate.

This is undefined by default.

$MPEG::Audio::Frame::mpeg25

When true, as is the default, MPEG-2.5 is supported. If that causes trouble, it can be disabled.

TIED HANDLE USAGE

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.

HISTORY

0.09 January 13th 2005

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.

0.08 October 21st 2003

Johan Vromans cought a glitch in asbin, which surfaced in 0.07 - now fixed.

0.07 October 19th 2003

Made broken compute the CRC on demand instead of always.

Cryptographically signed distribution.

0.06 October 17th 2003

Fixed some doc errors, thanks to Nikolaus Schusser and Suleyman Gulsuner.

Fixed CRC computation on little endian machines.

0.05 August 3rd 2003

Added overloading of object to asbin by default.

Added real CRC checking for layers III and I (layer II is a longer story).

0.04 August 2nd 2003

Fixed the calculation of frame lengths when a CRC is present, thanks to Johan Vromans.

0.03 April 19th 2003

Reimplemented offset method, which came out of sync whilst working on various copies, thanks to Jeff Anderson.

0.02 April 18th 2003

Some minor documentation and distribution fixes were made.

AUTHOR

Yuval Kojman <nothingmuch@altern.org>

COPYRIGHT

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.