com.beaglebuddy.id3.v23

## Class ID3v23Tag

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

-     public class ID3v23Tag
      extends java.lang.Object

  This class provides methods for reading and writing an ID3V2.3 tag. It provides direct low level access to the actual ID3v2.3 tag embedded in an .mp3 file. The tag is where all the information about the .mp3 file is stored. Information such as the song title, the track number, the lyrics of the song, the band who recorded the song, etc. are stored inside the tag. As shown below, a tag is composed of the four parts: `header`, `extended header`,`frames`, and padding.

  ID3v2.3 Tag Fields
  Field | Description
  --- | ---
  `header` | Holds the ID3 tag identifier, the total tag size, etc.
  `extendedHeader` | Optional field which is present only if the extendedHeaderPresent flag is set in the `header`. This extended header has fields which are not vital to the reading of the ID3v2.3 tag.
  `frames` | List of frames that contains the actual information about the .mp3 file.
  padding | Unused area filled with 0's which allows the tag to grow without having to re-write the whole .mp3 file. For example, if the user adds a frame specifying the track number, then the tag can take some space from the padding in order to add the frame and doesn't need to re-write the entire .mp3 file.

  It is beyond the scope of this class description to explain the complete details of the ID3v2.3 tag. However, if you need more information about the format of the ID3v2.3 tag, please visit the official ID3v2.3 website.

  See Also:
    ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags, Gigamonkeys ID3 Tag parser

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DEFAULT_PADDING_SIZE` amount of padding (in bytes) that will be added when the ID3v2.3 tag runs out of room for frames and needs to be resized.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23Tag()` default constructor.
    `ID3v23Tag(java.io.InputStream inputStream)` constructor.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `ID3v23Frame` | `addFrame(FrameType frameType)` add a default constructed ID3v2.3 frame of the specified type to the ID3v2.3 tag.
    `ID3v23Frame` | `addFrame(ID3v23Frame frame)` add the specified ID3v2.3 frame to the ID3v2.3 tag.
    `ID3v23TagExtendedHeader` | `getExtendedHeader()` get the optional ID3v2.3 tag extended header.
    `ID3v23Frame` | `getFrame(FrameType frameType)` finds the first ID3v2.3 frame in the ID3v2.3 tag with the specified ID3v2.3 frame id.
    `java.util.List<ID3v23Frame>` | `getFrames()` gets the list of frames stored in the ID3v2.3 tag.
    `java.util.List<ID3v23Frame>` | `getFrames(FrameType frameType)` finds all the ID3v2.3 frames in the ID3v2.3 tag with the specified ID3v2.3 frame id.
    `ID3v23TagHeader` | `getHeader()` gets the ID3v2.3 tag's header.
    `java.util.List<ID3v23Frame>` | `getInvalidFrames()` gets the list of the invalid frames encountered while reading in the ID3v2.3 tag.
    `byte[]` | `getPadding()` gets the amount of padding at the end of the ID3v2.3 tag.
    `int` | `getSize()` gets the size (in bytes) of the ID3v2.3 tag in the .mp3 file.
    `ID3TagVersion` | `getVersion()` gets the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.
    `boolean` | `isDirty()` gets whether the ID3v2.3 tag has been modified since the last time it was saved.
    `ID3v23Frame` | `removeFrame(FrameType frameType)` removes the first ID3v2.3 frame with the specified ID3v2.3 frame id from the ID3v2.3 tag.
    `void` | `removeFrames()` removes all the ID3v2.3 frames from the ID3v2.3 tag.
    `java.util.List<ID3v23Frame>` | `removeFrames(FrameType frameType)` removes all the ID3v2.3 frames with the specified ID3v2.3 frame id from the ID3v2.3 tag.
    `void` | `save(java.io.OutputStream outputStream)` save the ID3v2.3 tag to the .mp3 file.
    `void` | `save(java.io.RandomAccessFile file)` save the ID3v2.3 tag to the .mp3 file.
    `void` | `setBuffer()` if the tag's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setExtendedHeader(ID3v23TagExtendedHeader extendedHeader)` sets the optional ID3v2.3 extended header as well as the `tag header`'s extendedHeaderPresent flag.
    `void` | `setFrames(java.util.List<ID3v23Frame> frames)` sets the list of frames and stores them in the ID3v2.3 tag.
    `void` | `setHeader(ID3v23TagHeader header)` sets the ID3v2.3 tag's header.
    `void` | `setPadding(int size)` sets the amount of padding that should be reserved at the end of the ID3v2.3 tag.
    `java.lang.String` | `toString()` gets a string representation of the ID3v2.3 tag.

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

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

- - ### Field Detail

    - #### DEFAULT_PADDING_SIZE

          public static int DEFAULT_PADDING_SIZE

      amount of padding (in bytes) that will be added when the ID3v2.3 tag runs out of room for frames and needs to be resized.

  - ### Constructor Detail

    - #### ID3v23Tag

          public ID3v23Tag()

      default constructor. Called when creating a new ID3v2.3 tag.

    - #### ID3v23Tag

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

      constructor. Called when reading an existing ID3v2.3 tag from an .mp3 file. If any invalid frames are encountered while parsing the ID3v2.3 tag, then the frames are simply tagged as invalid, and are added to the list of `invalid frames`. See the `ID3v23FrameHeader` class for more details on the Beaglebuddy MP3 library's error handling.
      Parameters:
        `inputStream` - input stream mp3 file whose ID3v2.3 tag is to be read.
      Throws:
        `java.io.IOException` - if there was an error while loading the ID3v2.3 tag from the .mp3 file.

  - ### Method Detail

    - #### getHeader

          public ID3v23TagHeader getHeader()

      gets the ID3v2.3 tag's header.
      Returns:
        the ID3v2.3 tag header.
      See Also:
        `setHeader(ID3v23TagHeader)`

    - #### setHeader

          public void setHeader(ID3v23TagHeader header)

      sets the ID3v2.3 tag's header.
      Parameters:
        `header` - the ID3v2.3 tag's header.
      See Also:
        `getHeader()`

    - #### getExtendedHeader

          public ID3v23TagExtendedHeader getExtendedHeader()
                                                    throws java.lang.IllegalStateException

      get the optional ID3v2.3 tag extended header. This method may only be called when the `tag header's` extendedHeaderPresent flag is set.
      Returns:
        the optional ID3v2.3 extended header. If not present, then null is returned.
      Throws:
        `java.lang.IllegalStateException` - if the extendedHeaderPresent flag is not set.
      See Also:
        `setExtendedHeader(ID3v23TagExtendedHeader)`, `ID3v23TagHeader.isExtendedHeaderPresent()`, `ID3v23TagHeader.setExtendedHeaderPresent(boolean)`

    - #### setExtendedHeader

          public void setExtendedHeader(ID3v23TagExtendedHeader extendedHeader)

      sets the optional ID3v2.3 extended header as well as the `tag header`'s extendedHeaderPresent flag.
      Parameters:
        `extendedHeader` - an optional ID3v23 extended header.
      See Also:
        `getExtendedHeader()`, `ID3v23TagHeader.isExtendedHeaderPresent()`, `ID3v23TagHeader.setExtendedHeaderPresent(boolean)`

    - #### addFrame

          public ID3v23Frame addFrame(FrameType frameType)

      add a default constructed ID3v2.3 frame of the specified type to the ID3v2.3 tag.
      Parameters:
        `frameType` - type of ID3v2.3 frame to add to the ID3v2.3 tag.
      Returns:
        the new ID3v2.3 frame that was added to the ID3v2.3 tag.

    - #### addFrame

          public ID3v23Frame addFrame(ID3v23Frame frame)

      add the specified ID3v2.3 frame to the ID3v2.3 tag.
      Parameters:
        `frame` - ID3v2.3 frame to add to the ID3v2.3 tag.
      Returns:
        the new ID3v2.3 frame that was added to the ID3v2.3 tag.

    - #### getFrame

          public ID3v23Frame getFrame(FrameType frameType)

      finds the first ID3v2.3 frame in the ID3v2.3 tag with the specified ID3v2.3 frame id.
      Parameters:
        `frameType` - type of ID3v2.3 frame to search for.
      Returns:
        the first ID3v2.3 frame with the given ID3v2.3 frame id found in the ID3v2.3 tag, or null if no frame with the specified id can be found.

    - #### getFrames

          public java.util.List<ID3v23Frame> getFrames()

      gets the list of frames stored in the ID3v2.3 tag.
      Returns:
        a list of the frames.
      See Also:
        `setFrames(List)`

    - #### getFrames

          public java.util.List<ID3v23Frame> getFrames(FrameType frameType)

      finds all the ID3v2.3 frames in the ID3v2.3 tag with the specified ID3v2.3 frame id.
      Parameters:
        `frameType` - type of ID3v2.3 frames to retrieve from the ID3v2.3 tag.
      Returns:
        a list of all the ID3v2.3 frames with the given ID3v2.3 frame id that were found in the ID3v2.3 tag, or an empty collection of size 0 if no ID3v2.3 frame with the specified ID3v2.3 id can be found.

    - #### removeFrame

          public ID3v23Frame removeFrame(FrameType frameType)

      removes the first ID3v2.3 frame with the specified ID3v2.3 frame id from the ID3v2.3 tag.
      Parameters:
        `frameType` - type of type ID3v2.3 frame to remove from the ID3v2.3 tag.
      Returns:
        the ID3v2.3 frame in the ID3v2.3 tag with the given ID3v2.3 frame id that was removed, or null if no ID3v2.3 frame with the specified id was found.

    - #### removeFrames

          public java.util.List<ID3v23Frame> removeFrames(FrameType frameType)

      removes all the ID3v2.3 frames with the specified ID3v2.3 frame id from the ID3v2.3 tag.
      Parameters:
        `frameType` - type of ID3v2.3 frame to remove from the ID3v2.3 tag.
      Returns:
        a list of all the ID3v2.3 frames with the given ID3v2.3 frame id that were removed from the ID3v2.3 tag, or an empty collection of size 0 if no ID3v2.3 frames with the specified ID3v2.3 id could be found.

    - #### removeFrames

          public void removeFrames()

      removes all the ID3v2.3 frames from the ID3v2.3 tag.

    - #### setFrames

          public void setFrames(java.util.List<ID3v23Frame> frames)

      sets the list of frames and stores them in the ID3v2.3 tag.
      Parameters:
        `frames` - a list of ID3v2.3 frames containing information about the .mp3 song.
      See Also:
        `getFrames()`

    - #### getInvalidFrames

          public java.util.List<ID3v23Frame> getInvalidFrames()

      gets the list of the invalid frames encountered while reading in the ID3v2.3 tag.
      Returns:
        a list of the invalid frames.
      See Also:
        `setFrames(List)`

    - #### getPadding

          public byte[] getPadding()

      gets the amount of padding at the end of the ID3v2.3 tag. This padding dictactes how much room remains for the frames to expand within the ID3v2.3 tag before the ID3v2.3 tag has to be resized and thus the .mp3 file rewritten.
      Returns:
        the length of the padding after the ID3v2.3 tag.
      See Also:
        `setPadding(int)`

    - #### setPadding

          public void setPadding(int size)

      sets the amount of padding that should be reserved at the end of the ID3v2.3 tag.
      Parameters:
        `size` - the size (in bytes) of the new padding.
      See Also:
        `getPadding()`

    - #### getSize

          public int getSize()

      gets the size (in bytes) of the ID3v2.3 tag in the .mp3 file. This includes the tag header, frames, and padding.
      Returns:
        the size of the ID3v2.3 tag.

    - #### getVersion

          public ID3TagVersion getVersion()

      gets the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.
      Returns:
        the version of the ID3 tag stored in the .mp3 song which holds all of the information about the .mp3 file.

    - #### isDirty

          public boolean isDirty()

      gets whether the ID3v2.3 tag has been modified since the last time it was saved.
      Returns:
        whether the ID3v2.3 tag has been modified.

    - #### setBuffer

          public void setBuffer()

      if the tag's values have been modified, then resize the raw binary buffer and store the new values there. When finished, the dirty flag is reset to indicate that the buffer is up to date, and the tag 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 to the .mp3 file.
      Parameters:
        `outputStream` - output stream pointing to the starting location of the ID3v2.3 tag within the .mp3 file.
      Throws:
        `java.io.IOException` - if there was an error writing the ID3v2.3 tag to the .mp3 file.

    - #### save

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

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

    - #### toString

          public java.lang.String toString()

      gets a string representation of the ID3v2.3 tag.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the ID3v2.3 tag.