com.beaglebuddy.id3.v24

## Class ID3v24TagHeader

- java.lang.Object
- - com.beaglebuddy.id3.v24.ID3v24TagHeader

-     public class ID3v24TagHeader
      extends java.lang.Object

  This class provides methods for reading and writing the ID3V2.4 tag header. The ID3v2.4 tag header is 10 bytes long and is the first information in the `ID3v2.4 tag`.

  The structure of an .mp3 file containing an ID3v2.4 tag is shown below.

  An Id3v2.4 tag header has the following fields:

  ID3v2.4 Tag Header Fields
  | Field | Description
  --- | --- | ---
  1. | `version` | indicates which version of the ID3v2.x tag specification is stored in the .mp3 file. This value is always `ID3V2_4`
  2. | tagSize | holds the total size of the ID3v2.4 tag, not including the header and, if present, the footer. Simply put, since the tag header is 10 bytes long, the tagSize = total tag size - 10. If the footer is present, then the tagSize = total tag size - 20.
  3. | unsynchronization | flag used for correcting false synchronization bytes that occur in the ID3v2.4 tag header. To understand why unsyncronization is used, it's helpful to understand a little about the format of .mp3 files as well as how an .mp3 file is played by a media player. MP3 audio data is stored in an .mp3 file as a series of frames (not to be confused with the frames that are found in the ID3v2.4 tag in the .mp3 file). Each .mp3 audio frame contains a small bit of digital music encoded in the MP3 format as well as some meta data about the frame itself. At the beginning of each MP3 audio frame are 11 bits (sometimes 12) all set to 1. This is called the synch signal, and it's the pattern a media player looks for when attempting to play an .mp3 file or stream. If the player finds this 11/12 bit sequence, then it knows it has found an MP3 audio frame which can be decoded and played back. Thus, if an MP3 player finds a synch signal (11/12 bit sequence of all 1's) within the ID3v2.4 tag, it will think it has found the synch signal and try to play the ID3v2.4 tag back as music, which it isn't. Thus, the ID3v2.4 tag may need to be unsynchonized so that MP3 players properly skip over the tag and only try to play proper MP3 audio frames. See sec 6.1 - unsynchronisation scheme of the ID3v2.4 spec
  4. | extendedHeaderPresent | flag indicating whether an `extended header` is present. If so, then the extended header will contain more version specific data.
  5. | experimentalIndicator | flag indicating that the ID3v2.4 tag is in an experimental stage.
  6. | footerPresent | flag indicating whether a `footer` is present. If so, then the footer follows the frames, and no padding is present.

  See Also:
    ID3 tag version 2.4.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `TAG_HEADER_SIZE` size (in bytes) of the standard ID3v2.4 tag header

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24TagHeader()` The default constructor is called when creating a new ID3v2.4 tag header.
    `ID3v24TagHeader(java.io.InputStream inputStream)` This constructor is called when reading in an existing ID3v2.4 tag header from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getSize()` gets the total number of bytes in the ID3v2.4 tag header.
    `int` | `getTagSize()` gets the size of the ID3v2.4 tag excluding the tag header and, if present, the tag footer.
    `ID3TagVersion` | `getVersion()` gets the version of the tag, which is always `ID3V2_4`.
    `boolean` | `isDirty()` indicates whether or not the tag header's fields have been modified.
    `boolean` | `isExperimentalIndicator()` Indicates whether the ID3v2.4 tag is in an experimental stage.
    `boolean` | `isExtendedHeaderPresent()` indicates whether the optional `extended header` is present.
    `boolean` | `isFooterPresent()` Indicates whether the ID3v2.4 tag has a footer which follows the padding.
    `boolean` | `isUnsynchronization()` gets whether unsynchronization was used to correct false synchronization bytes in the ID3v2.4 tag.
    `void` | `save(java.io.OutputStream outputStream)` save the ID3v2.4 tag header to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the ID3v2.4 tag header to the .mp3 file.
    `void` | `setBuffer()` if the ID3v2.4 tag header's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setExperimentalIndicator(boolean experimentalIndicator)` sets whether the ID3v2.4 tag is in an experimental stage.
    `void` | `setExtendedHeaderPresent(boolean extendedHeaderPresent)` sets whether the optional `extended header` is present.
    `void` | `setFooterPresent(boolean footerPresent)` sets whether the ID3v2.4 tag footer is present.
    `void` | `setTagSize(int tagSize)` sets the size of the ID3v2.4 tag excluding the tag header, and if present, the tag footer.
    `void` | `setUnsynchronization(boolean unsynchronization)` sets whether unsynchronization is used.
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.4 tag header showing the values of the standard ID3v2.4 tag header's fields.

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

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

- - ### Field Detail

    - #### TAG_HEADER_SIZE

          public static final int TAG_HEADER_SIZE

      size (in bytes) of the standard ID3v2.4 tag header
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ID3v24TagHeader

          public ID3v24TagHeader()

      The default constructor is called when creating a new ID3v2.4 tag header. The default values used are:
      - tag size is 0 bytes
      - unsynchronization
      - no extended header present
      - experimental indicator is false
      - no footer present

    - #### ID3v24TagHeader

          public ID3v24TagHeader(java.io.InputStream inputStream)
                          throws java.io.IOException

      This constructor is called when reading in an existing ID3v2.4 tag header from an .mp3 file.
      Parameters:
        `inputStream` - input stream pointing to the end of the standard ID3v2.4 tag header in the .mp3 file.
      Throws:
        `java.io.IOException` - if the tag header can not be loaded from the .mp3 file.

  - ### Method Detail

    - #### isDirty

          public boolean isDirty()

      indicates whether or not the tag header's fields have been modified.
      Returns:
        whether or not the tag header has been modified.
      See Also:
        `setBuffer()`

    - #### getVersion

          public ID3TagVersion getVersion()

      gets the version of the tag, which is always `ID3V2_4`.
      Returns:
        the version of the tag, which is always `ID3V2_4`.

    - #### getTagSize

          public int getTagSize()

      gets the size of the ID3v2.4 tag excluding the tag header and, if present, the tag footer.
      Returns:
        the size of the ID3v2.4 tag excluding the standard tag header. That is, (total tag size - 10). If a tag footer is present, then the value returned is (total tag size - 20).
      See Also:
        `setTagSize(int)`

    - #### setTagSize

          public void setTagSize(int tagSize)

      sets the size of the ID3v2.4 tag excluding the tag header, and if present, the tag footer. That is, if a tag footer is not present, then the tag size should be set to (total tag size - 10). If a tag footer is present, then the tag size should be set to (total tag size - 20).
      Parameters:
        `tagSize` - the size of the ID3v2.4 tag excluding the tag header and, if present, the tag footer.
      See Also:
        `getTagSize()`

    - #### getSize

          public int getSize()

      gets the total number of bytes in the ID3v2.4 tag header.
      Returns:
        the total number of bytes in the ID3v2.4 tag header.

    - #### isUnsynchronization

          public boolean isUnsynchronization()

      gets whether unsynchronization was used to correct false synchronization bytes in the ID3v2.4 tag.
      Returns:
        whether unsynchronization was used to correct false synchronization bytes in the ID3v2.4 tag.
      See Also:
        `setUnsynchronization(boolean)`, section 6.1 - unsynchronization scheme in the ID3v2.4 specification

    - #### setUnsynchronization

          public void setUnsynchronization(boolean unsynchronization)

      sets whether unsynchronization is used.
      Parameters:
        `unsynchronization` - boolean indicating whether unsynchronization is used.
      See Also:
        `isUnsynchronization()`, section 6.1 - unsynchronization scheme in the ID3v2.4 specification

    - #### isExperimentalIndicator

          public boolean isExperimentalIndicator()

      Indicates whether the ID3v2.4 tag is in an experimental stage.
      Returns:
        whether the ID3v2.4 tag is in an experimental stage.
      See Also:
        `setExperimentalIndicator(boolean)`

    - #### setExperimentalIndicator

          public void setExperimentalIndicator(boolean experimentalIndicator)

      sets whether the ID3v2.4 tag is in an experimental stage.
      Parameters:
        `experimentalIndicator` - boolean indicating whether the ID3v2.4 tag is in an experimental stage.
      See Also:
        `isExperimentalIndicator()`

    - #### isExtendedHeaderPresent

          public boolean isExtendedHeaderPresent()

      indicates whether the optional `extended header` is present. If it is, then you may acess it via the `ID3v24Tag.getExtendedHeader()` method.
      Returns:
        whether the optional `extended header` is present.
      See Also:
        `setExtendedHeaderPresent(boolean)`

    - #### setExtendedHeaderPresent

          public void setExtendedHeaderPresent(boolean extendedHeaderPresent)

      sets whether the optional `extended header` is present.
      Parameters:
        `extendedHeaderPresent` - boolean indicating whether the optional `extended header` is present.
      See Also:
        `isExtendedHeaderPresent()`

    - #### isFooterPresent

          public boolean isFooterPresent()

      Indicates whether the ID3v2.4 tag has a footer which follows the padding.
      Returns:
        whether the ID3v2.4 tag contains a footer and follows the padding.
      See Also:
        `setFooterPresent(boolean)`

    - #### setFooterPresent

          public void setFooterPresent(boolean footerPresent)

      sets whether the ID3v2.4 tag footer is present.
      Parameters:
        `footerPresent` - boolean indicating whether the footer is present.
      See Also:
        `isFooterPresent()`

    - #### setBuffer

          public void setBuffer()

      if the ID3v2.4 tag header's values have been modified, then resize the raw binary buffer and store the new values there. When finished, reset the dirty flag to indicate that the buffer is up to date, and the tag header is now ready to be saved to the .mp3 file.

    - #### save

          public void save(java.io.OutputStream outputStream)
                    throws java.io.IOException

      save the ID3v2.4 tag header to the .mp3 file.
      Parameters:
        `outputStream` - output stream pointing to the starting location of the ID3v2.4 tag header within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.4 tag header to the .mp3 file.

    - #### save

          public void save(java.io.RandomAccessFile file)
                    throws java.io.IOException

      save the ID3v2.4 tag header to the .mp3 file.
      Parameters:
        `file` - random access file pointing to the starting location of the ID3v2.4 tag header within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.4 tag header to the .mp3 file.

    - #### toString

          public java.lang.String toString()

      gets a string representation of the ID3v2.4 tag header showing the values of the standard ID3v2.4 tag header's fields.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the ID3v2.4 tag header.