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.

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

    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 folded hash 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.

    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.

    sample
        Returns the sample rate in Hz.

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

    framerate
        Should this frame describe the stream, the framerate would be the
        return value from this method.

    broken
        This returns true if the CRC computation failed for a protected
        layer I or III frame. It will always return false on unprotected
        frames.

    pad Wether or not the frame was padded.

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

TIED HANDLE USAGE
    You can also read frame objects via the <HANDLE> 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.08 October 21st 2003
    Johan Vromans cought a glitch in asbin, which surfaced in 0.08 - 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.