com.beaglebuddy.id3.v24

## Class ID3v24TagFooter

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

-     public class ID3v24TagFooter
      extends java.lang.Object

  This class provides methods for reading and writing the ID3V2.4 tag footer. The ID3v2.4 tag footer is 10 bytes long and is the last information in the `ID3v2.4 tag`. It is an optional part of the ID3v2.4 tag, and if present, is found just before the audio portion of the .mp3 file. If an ID3v2.4 tag footer is present, then no padding can appear in the ID3v2.4 tag. That is, either padding may be present or the footer may be present, but not both.

  If the Id3v2.4 tag is found at the end of the file instead of the beginning, then a footer is required. This is because it would be prohibitively difficult to find the beginning of the ID3v2.4 tag. Thus, to speed up the process of locating an ID3v2.4 tag when searching from the end of a file, a footer must be added to the tag.

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

  An Id3v2.4 tag footer 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_FOOTER`
  2. | tagSize | holds the total size of the ID3 tag, not including the header or the footer. Simply put, since the tag header and footer are each 10 bytes long, the tagSize = total tag size - 20.
  3. | unsynchronization | flag used for correcting false synchronization bytes that occur in the ID3v2.4 tag footer. 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. This field is always true.

  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_FOOTER_SIZE` size (in bytes) of the standard ID3v2.4 tag footer

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v24TagFooter()` The default constructor is called when creating a new ID3v2.4 tag footer.
    `ID3v24TagFooter(ID3v24TagHeader header)` The constructor is called when creating a new ID3v2.4 tag footer which should be identical to an ID3v2.4 tag header except for the id bytes.
    `ID3v24TagFooter(java.io.InputStream inputStream)` This constructor is called when reading in an existing ID3v2.4 tag footer 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 footer.
    `int` | `getTagSize()` gets the size of the ID3v2.4 tag excluding the tag header and the footer.
    `ID3TagVersion` | `getVersion()` gets the version of the tag, which is always `ID3V2_4_FOOTER`.
    `boolean` | `isDirty()` indicates whether or not the tag footer'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 frames.
    `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 footer to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the ID3v2.4 tag footer to the .mp3 file.
    `void` | `setBuffer()` if the ID3v2.4 tag footer'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` | `setTagSize(int tagSize)` sets the size of the ID3v2.4 tag excluding this tag header and footer.
    `void` | `setUnsynchronization(boolean unsynchronization)` sets whether unsynchronization is used.
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.4 tag footer showing the values of the ID3v2.4 tag footer's fields.

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

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

- - ### Field Detail

    - #### TAG_FOOTER_SIZE

          public static final int TAG_FOOTER_SIZE

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

  - ### Constructor Detail

    - #### ID3v24TagFooter

          public ID3v24TagFooter()

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

    - #### ID3v24TagFooter

          public ID3v24TagFooter(ID3v24TagHeader header)

      The constructor is called when creating a new ID3v2.4 tag footer which should be identical to an ID3v2.4 tag header except for the id bytes.
      Parameters:
        `header` - the ID3v2.4 tag header whose values will be used to initialize the footer.

    - #### ID3v24TagFooter

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

      This constructor is called when reading in an existing ID3v2.4 tag footer from an .mp3 file.
      Parameters:
        `inputStream` - input stream pointing to the beginning of the standard ID3v2.4 tag footer in the .mp3 file.
      Throws:
        `java.io.IOException` - if the tag footer can not be loaded from the .mp3 file.
        `ParseException` - if the footer is read in, but the footer's id bytes are not correct.

  - ### Method Detail

    - #### isDirty

          public boolean isDirty()

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

    - #### getVersion

          public ID3TagVersion getVersion()

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

    - #### getTagSize

          public int getTagSize()

      gets the size of the ID3v2.4 tag excluding the tag header and the footer.
      Returns:
        the size of the ID3v2.4 tag excluding the tag header and the footer. Since both the tag header and the tag footer are each 10 bytes long, 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 this tag header and footer. Since both the tag header and the tag footer are each 10 bytes long, this value should be set to (total tag size - 20).
      Parameters:
        `tagSize` - the size of the ID3v2.4 tag excluding the tag header and the footer.
      See Also:
        `getTagSize()`

    - #### getSize

          public int getSize()

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

    - #### 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 frames.
      Returns:
        whether the ID3v2.4 tag contains a footer and follows the frames.

    - #### setBuffer

          public void setBuffer()

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

    - #### save

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

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

    - #### toString

          public java.lang.String toString()

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