com.beaglebuddy.mpeg

## Class MPEGFrameHeader

- java.lang.Object
- - com.beaglebuddy.mpeg.MPEGFrameHeader

-     public class MPEGFrameHeader
      extends java.lang.Object

  The audio portion of an .mp3 file is stored in MPEG audio frames as shown below. Each `MPEG audio frame` begins with an MPEG frame header. The header has a fixed length of 4 bytes, and optionally contains a 2 byte CRC directly following it, before the `side information`.

  See Also:
    ISO / IEC 11172-3, MPEG Audio Frame Header, MPEG Basics, MPEG Audio Layer I/II/III frame header

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `FRAME_HEADER_SIZE` mpeg audio frame headers are 4 bytes (32 bits) in length

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `MPEGFrameHeader()` default constructor.
    `MPEGFrameHeader(byte[] bytes, java.io.InputStream inputStream)` constructor used for parsing existing .mp3 files.
    `MPEGFrameHeader(java.io.InputStream inputStream)` constructor used for parsing existing .mp3 files.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getBitrate()` gets the bit rate (in kilobits per second - kbps), which specifies how many kb are used to represent the audio data for each second of playback.
    `ChannelMode` | `getChannelMode()` gets the channel mode (mono or stereo) of this .mp3 file.
    `java.lang.String` | `getCodec()` gets the Codec used to encode the .mp3 file.
    `byte[]` | `getCRC()` gets the optional CRC for the mpeg audio frame.
    `int` | `getFrameSize()` gets the size (in bytes) of the mpeg audio frame.
    `int` | `getFrequency()` gets the frequency (in herz - hz), which specifies how many times per second the audio is sampled and stored as a number in the .mp3 file.
    `Layer` | `getLayer()` gets the MPEG layer of this .mp3 file.
    `java.lang.String` | `getModeExtension()` sets the description of the mode extension of this mpeg audio frame.
    `MPEGVersion` | `getMPEGVersion()` gets the MPEG version of this .mp3 file.
    `int` | `getNumSamples()` gets the number of audio samples stored in the mpeg audio frame.
    `int` | `getSideInfoSize()` get the size (in bytes) of the `side information` that directly follows the MPEG frame header in the `mpeg audio frame`.
    `int` | `getSize()` gets the size of the mpeg audio frame header and includes the optional CRC if present.
    `boolean` | `isCopyrighted()` gets whether this audio is copyrighted.
    `boolean` | `isOriginalMedia()` gets whether this .mp3 file was created from the original media.
    `boolean` | `isProtectedByCRC()` gets whether this mpeg audio frame has a CRC.
    `java.lang.String` | `toString()` gets a string representation of the mpeg audio frame header.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FRAME_HEADER_SIZE

          public static final int FRAME_HEADER_SIZE

      mpeg audio frame headers are 4 bytes (32 bits) in length
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MPEGFrameHeader

          public MPEGFrameHeader()

      default constructor.

    - #### MPEGFrameHeader

          public MPEGFrameHeader(java.io.InputStream inputStream)
                          throws java.io.IOException,
                                 ParseException

      constructor used for parsing existing .mp3 files. This constructor is called when reading in an existing mpeg frame header from an .mp3 file. It parses the raw binary data of the mpeg frame header and stores the values in the corresponding data members.
      Parameters:
        `inputStream` - input stream to read in the mpeg audio frame from the binary .mp3 file.
      Throws:
        `java.io.IOException` - if there is an error while reading the mpeg frame header.
        `ParseException` - if an invalid value is detected while parsing the mpeg frame header's raw bytes.
      See Also:
        MPEG Audio Frame Header, The Anatomy of an MP3 File

    - #### MPEGFrameHeader

          public MPEGFrameHeader(byte[] bytes,
                         java.io.InputStream inputStream)
                          throws java.io.IOException,
                                 ParseException

      constructor used for parsing existing .mp3 files. This constructor is called when searching for the 1st mpeg audio frame header from an .mp3 file or when re-synching the audio stream. It parses the raw binary data of the mpeg frame header and stores the values in the corresponding data members.
      Parameters:
        `bytes` - bytes read in from the previous attempt to find the mpeg frame header.
        `inputStream` - input stream to read in the mpeg audio frame CRC from the binary .mp3 file.
      Throws:
        `java.io.IOException` - if there is an error while reading the mpeg frame header.
        `ParseException` - if an invalid value is detected while parsing the mpeg frame header's raw bytes.
      See Also:
        MPEG Audio Frame Header, The Anatomy of an MP3 File

  - ### Method Detail

    - #### getSize

          public int getSize()

      gets the size of the mpeg audio frame header and includes the optional CRC if present.
      Returns:
        the size of the mpeg audio frame header including the optional CRC if present.

    - #### getMPEGVersion

          public MPEGVersion getMPEGVersion()

      gets the MPEG version of this .mp3 file.
      Returns:
        the MPEG version of this .mp3 file.

    - #### getLayer

          public Layer getLayer()

      gets the MPEG layer of this .mp3 file.
      Returns:
        the MPEG layer of this .mp3 file.

    - #### getCodec

          public java.lang.String getCodec()

      gets the Codec used to encode the .mp3 file.
      Returns:
        the Codec used to encode the .mp3 file.

    - #### getBitrate

          public int getBitrate()

      gets the bit rate (in kilobits per second - kbps), which specifies how many kb are used to represent the audio data for each second of playback.
      Returns:
        the bite rate in kbit/s for this .mpeg audio frame. A value of 0 means free format, while a value of -1 means an invalid value. All other values are actual valid bit rates.

    - #### getFrequency

          public int getFrequency()

      gets the frequency (in herz - hz), which specifies how many times per second the audio is sampled and stored as a number in the .mp3 file. CD audio is sampled at 44.1 khz, which means 44,100 samples per second.
      Returns:
        the sampling frequency (in hz) used to convert the analog audio to a digital .mp3 file. A value of -1 indicates an invalid value due to the MPEG version

    - #### getChannelMode

          public ChannelMode getChannelMode()

      gets the channel mode (mono or stereo) of this .mp3 file.
      Returns:
        the channel mode (mono or stereo) of this .mp3 file.

    - #### getModeExtension

          public java.lang.String getModeExtension()

      sets the description of the mode extension of this mpeg audio frame.
      Returns:
        a description of the mode extension of this mpeg audio frame.

    - #### isProtectedByCRC

          public boolean isProtectedByCRC()

      gets whether this mpeg audio frame has a CRC.
      Returns:
        whether this mpeg audio frame has a CRC or not.

    - #### isCopyrighted

          public boolean isCopyrighted()

      gets whether this audio is copyrighted.
      Returns:
        whether this audio is copyrighted or not.

    - #### isOriginalMedia

          public boolean isOriginalMedia()

      gets whether this .mp3 file was created from the original media.
      Returns:
        whether this .mp3 file was created from the original media or whether it is a copy.

    - #### getNumSamples

          public int getNumSamples()

      gets the number of audio samples stored in the mpeg audio frame.
      Returns:
        the number of audio samples stored in the mpeg audio frame.

    - #### getFrameSize

          public int getFrameSize()

      gets the size (in bytes) of the mpeg audio frame.
      Returns:
        the size of the mpeg audio frame. (in bytes).

    - #### getSideInfoSize

          public int getSideInfoSize()

      get the size (in bytes) of the `side information` that directly follows the MPEG frame header in the `mpeg audio frame`.
      Returns:
        the size (in bytes) of the side information that directly follows the MPEG frame header in the MPEG audio frame.

    - #### getCRC

          public byte[] getCRC()

      gets the optional CRC for the mpeg audio frame.
      Returns:
        the CRC for the mpeg audio frame if present, and null otherwise.

    - #### toString

          public java.lang.String toString()

      gets a string representation of the mpeg audio frame header.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the mpeg audio frame header.