com.beaglebuddy.ape

## Class APETag

- java.lang.Object
- - com.beaglebuddy.ape.APETag

-     public class APETag
      extends java.lang.Object

  This class provides methods for reading the optional APEv1 and APEv2 tags. The APE tag was meant to provide the same functionality as the ID3v2.x tag, but was not widely adopted. The ID3v2.x tag, on the other hand, is a formal specification and is supported by all .mp3 players. The APEv1 tag can only be found at the end of an .mp3 file, after the `mpeg audio`, and if an `ID3v1 tag` is present, before the ID3v1 tag. Version 2 of the APE Specification added an optional header to the tag, thus allowing an APE tag to be located at the beginning of an .mp3 file where the `ID3v23 tag` would normally be. See the format of an .mp3 file shown below.

  An APE tag consists of a collection of key/value pairs which are stored in `items`. While the key part of an `item` is always a String, the value may be a String or it may be raw binary data, such as an image file. The sample code shown below demonstrates how to read the values stored in an APE tag. The APE specification(s) have defined a standardized list of keys, but users are not restricted to this list.

  The APE tag is an obsolete tag that really should just be removed from your .mp3 files. See the CleanMP3Files.java file provided in the sample code to see how this is done.

       import java.io.IOException;
       import com.beaglebuddy.mp3.MP3;
       import com.beaglebuddy.ape.APETag;
       import com.beaglebuddy.ape.APEItem;

       public class APEExample
       {
          public static void main(String[] args)
          {
             try
             {
                MP3 mp3 = new MP3("c:/mp3/Wild Cat.mp3");

                if (mp3.hasAPETag())                   // if the mp3 file has an APE tag
                {                                      // then display the data in it
                   APETag apeTag = mp3.getAPETag();
                   System.out.println("mp3 contains an " + apeTag.getVersionString() + " tag");
                   System.out.println(apeTag);
                   for(APEItem item : apeTag.getItems())
                   {
                      if (item.isValueText())
                         System.out.println(item.getKey() + " - " + item.getTextValue());
                      else
                         System.out.println(item.getKey() + " - " + "binary data: " + item.getBinaryValue().length + " bytes.");
                   }
                }
             }
             catch (IOException ex)
             {
                System.out.println("An error occurred while reading the mp3 file.");
             }
          }
       }

  See Also:
    APEv1 Specification, APEv2 Specification

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `APETag(java.io.RandomAccessFile file)` constructor used to read in a APEv2 tag from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `getFilePosition()` get the position (in bytes) within the .mp3 file where the APE tag starts.
    `APEFooter` | `getFooter()` get the optional footer in the APE tag.
    `APEHeader` | `getHeader()` get the optional header in the APE tag.
    `java.util.List<APEItem>` | `getItems()` get the list of items in the APE tag.
    `int` | `getSize()` get the size (in bytes) of the APE tag.
    `int` | `getVersion()` get the version of the APE tag.
    `java.lang.String` | `getVersionString()` get the version of the APE tag as a String.
    `java.lang.String` | `toString()` gets a string representation of the APE tag.

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

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

- - ### Constructor Detail

    - #### APETag

          public APETag(java.io.RandomAccessFile file)
                 throws java.io.IOException,
                        ParseException

      constructor used to read in a APEv2 tag from an .mp3 file.
      Parameters:
        `file` - random access file to read in the APE tag from an .mp3 file.
      Throws:
        `java.io.IOException` - if there is an error while reading the APE tag.
        `ParseException` - if a APE tag can not be found or if an invalid value is detected while parsing the APE tag.

  - ### Method Detail

    - #### getSize

          public int getSize()

      get the size (in bytes) of the APE tag.
      Returns:
        the size (in bytes) of the APE tag.

    - #### getFilePosition

          public int getFilePosition()

      get the position (in bytes) within the .mp3 file where the APE tag starts.
      Returns:
        the position (in bytes) within the .mp3 file where the APE tag starts.

    - #### getVersion

          public int getVersion()

      get the version of the APE tag.
      Returns:
        the version of the APE tag.

    - #### getVersionString

          public java.lang.String getVersionString()

      get the version of the APE tag as a String.
      Returns:
        the version of the APE tagas a String.

    - #### getHeader

          public APEHeader getHeader()

      get the optional header in the APE tag. The header is only found in APEv2 tags.
      Returns:
        the header in the APE tag, or null if it is not present,.

    - #### getItems

          public java.util.List<APEItem> getItems()

      get the list of items in the APE tag.
      Returns:
        the list of items in the APE tag.

    - #### getFooter

          public APEFooter getFooter()

      get the optional footer in the APE tag. The footer is found in both APEv1 and APEv2 tags.
      Returns:
        the footer in the APE tag, or null if it is not present,.

    - #### toString

          public java.lang.String toString()

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