MPEG::Audio::Frame(3)

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.

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

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