com.beaglebuddy.id3.v23

## Class ID3v23TagHeader

- java.lang.Object
- - com.beaglebuddy.id3.v23.ID3v23TagHeader

-     public class ID3v23TagHeader
      extends java.lang.Object

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

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

  An ID3v2.3 tag header has the following fields:

  ID3v2.3 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_3`
  2. | tagSize | holds the total size of the ID3v2.3 tag, not including the header. Simply put, since the tag header is 10 bytes long, the tagSize = total tag size - 10.
  3. | unsynchronization | flag used for correcting false synchronization bytes that occur in the ID3v2.3 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 ID32.x 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 ID32.x tag, it will think it has found the synch signal and try to play the ID32.x tag back as music, which it isn't. Thus, the Id32.x 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 unsynchronisation scheme of the ID3v2.3 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.3 tag is in an experimental stage.

  See Also:
    ID3 tag version 2.3.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.3 tag header

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23TagHeader()` The default constructor is called when creating a new ID3v2.3 tag header.
    `ID3v23TagHeader(java.io.InputStream inputStream)` This constructor is called when reading in an existing ID3v2.3 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.3 tag header.
    `int` | `getTagSize()` gets the size of the ID3v2.3 tag excluding the tag header, ie (total tag size - 10).
    `ID3TagVersion` | `getVersion()` gets the version of the tag, which is always `ID3V2_3`.
    `boolean` | `isDirty()` indicates whether or not the tag header's fields have been modified.
    `boolean` | `isExperimentalIndicator()` Indicates whether the ID3v2.3 tag is in an experimental stage.
    `boolean` | `isExtendedHeaderPresent()` indicates whether the optional extended header is present.
    `boolean` | `isUnsynchronization()` gets whether unsynchronization was used to correct false synchronization bytes in the ID3v2.3 tag.
    `void` | `save(java.io.OutputStream outputStream)` save the ID3v2.3 tag header to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the ID3v2.3 tag header to the .mp3 file.
    `void` | `setBuffer()` if the ID3v2.3 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.3 tag is in an experimental stage.
    `void` | `setExtendedHeaderPresent(boolean extendedHeaderPresent)` sets whether the optional extended header is present.
    `void` | `setTagSize(int tagSize)` sets the size of the ID3v2.3 tag excluding the tag header, ie (total tag size - 10).
    `void` | `setUnsynchronization(boolean unsynchronization)` sets whether unsynchronization is used.
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.3 tag header showing the values of all the tag header's fields as well as the extended header's fields if it is present.

    - ### 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.3 tag header
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### ID3v23TagHeader

          public ID3v23TagHeader()

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

    - #### ID3v23TagHeader

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

      This constructor is called when reading in an existing ID3v2.3 tag header from an .mp3 file.
      Parameters:
        `inputStream` - input stream pointing to the tag header, after the ID3v2.3 id bytes, in the .mp3 file.
      Throws:
        `java.io.IOException` - if the tag header can not be read 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_3`.
      Returns:
        the version of the tag, which is always `ID3V2_3`.

    - #### getTagSize

          public int getTagSize()

      gets the size of the ID3v2.3 tag excluding the tag header, ie (total tag size - 10).
      Returns:
        the size of the ID3v2.3 tag excluding the standard tag header. That is, total tag size - 10.
      See Also:
        `setTagSize(int)`

    - #### setTagSize

          public void setTagSize(int tagSize)

      sets the size of the ID3v2.3 tag excluding the tag header, ie (total tag size - 10).
      Parameters:
        `tagSize` - the size of the ID3v2.3 tag excluding the tag header.
      See Also:
        `getTagSize()`

    - #### getSize

          public int getSize()

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

    - #### isUnsynchronization

          public boolean isUnsynchronization()

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

    - #### setUnsynchronization

          public void setUnsynchronization(boolean unsynchronization)

      sets whether unsynchronization is used.
      Parameters:
        `unsynchronization` - boolean indicating whether unsynchronization is used.
      See Also:
        `isUnsynchronization()`, ID3v2.3 unsynchronization scheme

    - #### isExperimentalIndicator

          public boolean isExperimentalIndicator()

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

    - #### setExperimentalIndicator

          public void setExperimentalIndicator(boolean experimentalIndicator)

      sets whether the ID3v2.3 tag is in an experimental stage.
      Parameters:
        `experimentalIndicator` - boolean indicating whether the ID3v2.3 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 access it via the `ID3v23Tag.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. if false, then the extendedHeader is set to null. otherwise, the extendedHeader is initialized to default values.
      Parameters:
        `extendedHeaderPresent` - boolean indicating whether the optional extended header is present.
      See Also:
        `isExtendedHeaderPresent()`

    - #### setBuffer

          public void setBuffer()

      if the ID3v2.3 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.3 tag header to the .mp3 file.
      Parameters:
        `outputStream` - output stream pointing to the starting location of the ID3v2.3 tag header within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.3 tag header to the .mp3 file.

    - #### save

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

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

    - #### toString

          public java.lang.String toString()

      gets a string representation of the ID3v2.3 tag header showing the values of all the tag header's fields as well as the extended header's fields if it is present.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the ID3v2.3 tag header.