com.beaglebuddy.mpeg

## Class XingHeader

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

-     public class XingHeader
      extends java.lang.Object

  The Xing header is found in `variable bit rate` encoded .mp3 files and is identified with an id of "Xing". It is an optional header, and if present, will be found within the first MPEG audio frame directly following the MPEG side information. It can sometimes also be found in `constant bit rate` encoded .mp3 files, but in this case it will have an id of "Info" in order to distinguish it from its variable bit rate encoded counterpart. The format of a variable bit rate encoded .mp3 file is shown below.

  See Also:
    Xing Header Format

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `HEADER_MAX_SIZE` Xing headers are at most 120 bytes long
    `static int` | `HEADER_MIN_SIZE` Xing headers are at least 8 bytes long

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XingHeader()` default constructor.
    `XingHeader(byte[] bytes, int index)` constructor.
    `XingHeader(java.io.InputStream inputStream)` constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `BitrateType` | `getBitrateType()` gets the type of bit rate used to encode the .mp3 file.
    `java.lang.String` | `getId()` gets the id, which is either "Info" or "Xing"
    `int` | `getNumBytes()` gets the optional number of bytes value which specifies the total number of bytes in the .mp3 file.
    `int` | `getNumFrames()` gets the optional number of frames value which specifies the total number of mpeg audio frames in the .mp3 file.
    `int` | `getQuality()` gets the optional quality value, which has a range of [0 - 100], where 0 is the best and 100 is the worst.
    `int` | `getSize()` gets the size (in bytes) of the Xing header.
    `byte[]` | `getTableOfContents()` gets the optional table of contents which specifies entries used for seeking mpeg audio frames within the .mp3 file.
    `int` | `getTOCOffset(int entry)` Using the table of contents, this method returns the offset from the beginning of the .mp3 file where the desired mpeg audio frame is located.
    `boolean` | `isNumBytesPresent()` gets whether the optional number of bytes value is specified in the Xing header.
    `boolean` | `isNumFramesPresent()` gets whether the optional number of frames value is specified in the Xing header.
    `boolean` | `isQualityIndicatorPresent()` gets whether the optional quality value is specified in the Xing header.
    `boolean` | `isTableOfContentsPresent()` gets whether the optional table of contents table is specified in the Xing header.
    `java.lang.String` | `toString()` get a string representation of the Xing header.

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

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

- - ### Field Detail

    - #### HEADER_MIN_SIZE

          public static final int HEADER_MIN_SIZE

      Xing headers are at least 8 bytes long
      See Also:
        Constant Field Values

    - #### HEADER_MAX_SIZE

          public static final int HEADER_MAX_SIZE

      Xing headers are at most 120 bytes long
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XingHeader

          public XingHeader()

      default constructor.

    - #### XingHeader

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

      constructor.
      Parameters:
        `inputStream` - input stream pointing to the Xing header in an mpeg audio frame in an .mp3 file.
      Throws:
        `java.io.IOException` - if there is an error while reading the Xing header from the .mp3 file.
        `ParseException` - if an invalid value is detected while parsing the Xing header's raw bytes.

    - #### XingHeader

          public XingHeader(byte[] bytes,
                    int index)
                     throws ParseException

      constructor.
      Parameters:
        `bytes` - the raw bytes of an MPEG audio frame.
        `index` - the offset into the bytes of the MPEG audio frame where the Xing header begins.
      Throws:
        `ParseException` - if an invalid value is detected while parsing the Xing header's raw bytes.

  - ### Method Detail

    - #### getSize

          public int getSize()

      gets the size (in bytes) of the Xing header.
      Returns:
        the size (in bytes) of the Xing header.

    - #### getBitrateType

          public BitrateType getBitrateType()

      gets the type of bit rate used to encode the .mp3 file.
      Returns:
        the type of bit rate used to encode the .mp3 file.

    - #### getId

          public java.lang.String getId()

      gets the id, which is either "Info" or "Xing"
      Returns:
        the Xing header id.

    - #### isNumFramesPresent

          public boolean isNumFramesPresent()

      gets whether the optional number of frames value is specified in the Xing header. If so, then the `getNumFrames()` method may be called.
      Returns:
        whether the number of frames value is specified in the Xing header.

    - #### isNumBytesPresent

          public boolean isNumBytesPresent()

      gets whether the optional number of bytes value is specified in the Xing header. If so, then the `getNumBytes()` method may be called.
      Returns:
        whether the number of bytes value is specified in the Xing header.

    - #### isTableOfContentsPresent

          public boolean isTableOfContentsPresent()

      gets whether the optional table of contents table is specified in the Xing header. If so, then the `getTableOfContents()` method may be called.
      Returns:
        whether the table of contents value is specified in the Xing header.

    - #### isQualityIndicatorPresent

          public boolean isQualityIndicatorPresent()

      gets whether the optional quality value is specified in the Xing header. If so, then the `getQuality()` method may be called.
      Returns:
        whether the quality value is specified in the Xing header.

    - #### getNumFrames

          public int getNumFrames()
                           throws java.lang.IllegalStateException

      gets the optional number of frames value which specifies the total number of mpeg audio frames in the .mp3 file. This method may only be called if the `isNumFramesPresent()` method returns true.
      Returns:
        the number of mpeg audio frames in the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the method `isNumFramesPresent()` does not return true.

    - #### getNumBytes

          public int getNumBytes()
                          throws java.lang.IllegalStateException

      gets the optional number of bytes value which specifies the total number of bytes in the .mp3 file. This method may only be called if the `isNumBytesPresent()` method returns true.
      Returns:
        the number of bytes in the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the method `isNumBytesPresent()` does not return true.

    - #### getTableOfContents

          public byte[] getTableOfContents()
                                    throws java.lang.IllegalStateException

      gets the optional table of contents which specifies entries used for seeking mpeg audio frames within the .mp3 file. This method may only be called if the `isTableOfContentsPresent()` method returns true.
      Returns:
        the table of contents which specifies entries used for seeking mpeg audio frames within the .mp3 file.
      Throws:
        `java.lang.IllegalStateException` - if the method `isTableOfContentsPresent()` does not return true.

    - #### getTOCOffset

          public int getTOCOffset(int entry)
                           throws java.lang.IllegalStateException

      Using the table of contents, this method returns the offset from the beginning of the .mp3 file where the desired mpeg audio frame is located. In order to call this
      Parameters:
        `entry` - the desired entry in table of contents. Since the table of contents has 100 entries, the entry must be 0 <= entry < 100.
      Returns:
        the offset within the .mp3 file
      Throws:
        `java.lang.IllegalStateException` - if the methods `isTableOfContentsPresent()` and `isNumBytesPresent()` do not both return true.
        `java.lang.IllegalArgumentException` - if the specified entry is out of range, ie 0 <= n < 100.

    - #### getQuality

          public int getQuality()
                         throws java.lang.IllegalStateException

      gets the optional quality value, which has a range of [0 - 100], where 0 is the best and 100 is the worst. This method may only be called if the `isQualityIndicatorPresent()` method returns true.
      Returns:
        the quality of the mpeg audio frame.
      Throws:
        `java.lang.IllegalStateException` - if the method `isQualityIndicatorPresent()` does not return true.

    - #### toString

          public java.lang.String toString()

      get a string representation of the Xing header.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the Xing header.