com.beaglebuddy.id3.v23.frame_body

## Class ID3v23FrameBodyAttachedPicture

- java.lang.Object
- - com.beaglebuddy.util.Utility
  - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility
    - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody
      - - com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyAttachedPicture

-     public class ID3v23FrameBodyAttachedPicture
      extends ID3v23FrameBody

  An attached picture frame body is associated with an ID3v2.3 `APIC` `frame` which is used to include pictures in the .mp3 file. This allows you to include album covers, band pictures, band logos, etc. right in the .mp3 file. The attached picture frame body contains the following fields:

  Attached Picture Frame Body Fields
  | Field | Description
  --- | --- | ---
  1. | `encoding` | character set used to `encode` the description field.
  2. | mimeType | the MIME type and subtype for the image, such as image/jpg or image/gif. In the event that the MIME media type name is omitted, "image/" will be implied.
  3. | `pictureType` | indicates which of the 21 pre-defined `picture types` the attached image is.
  4. | description | short description (maximum of 64 characters) of the picture. This field is optional and may be left blank.
  5. | image | raw binary data of the actual image.

  There may be more than one attached picture frame in an ID3v2.3 `tag`, but only one with the same description field. There may only be one attached picture frame with the picture type declared as picture type `SMALL_ICON` and `OTHER_ICON` respectively.

  example: ``

       import java.io.IOException;
       import java.util.List;

       import com.beaglebuddy.mp3.MP3;
       import com.beaglebuddy.id3.enums.PictureType;
       import com.beaglebuddy.id3.enums.v23.FrameType;
       import com.beaglebuddy.id3.pojo.AttachedPicture;
       import com.beaglebuddy.id3.v23.ID3v23Frame;
       import com.beaglebuddy.id3.v23.ID3v23Tag;
       import com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyAttachedPicture;

       public class Pictures
       {
          public static void main(String[] args)
          {
             try
             {
                // read in the mp3 file
                MP3 mp3 = new MP3("c:\\music\\bon jovi\\livin on a prayer.mp3");

                // if there was any invalid information (ie, frames) in the .mp3 file, then display the errors to the user
                if (mp3.hasErrors())
                {
                   mp3.displayErrors(System.out);      // display the errors that were found
                   mp3.save();                         // discard the invalid information (frames) and
                }                                      // save only the valid frames back to the .mp3 file

                // get a list of all the types of pictures stored in your mp3
                List<AttachedPicture> pictures = mp3.getPictures();

                // print out the picture's type and the optional description of the picture
                for(AttachedPicture picture : pictures)
                   System.out.println("picture type = " + picture.getPictureType() + "   -    " + picture.getDescription());

                // add a picture of the band's album cover to the ID3v2.3 tag
                AttachedPicture   picture   = new AttachedPicture(PictureType.FRONT_COVER, "c:\\music\\bon jovi\\livin on a prayer.album_cover.jpg");
                ID3v23Tag         iD3v23Tag = mp3.getID3v23Tag();
                ID3v23Frame       frame     = new ID3v23Frame(FrameType.ATTACHED_PICTURE, new ID3v23FrameBodyAttachedPicture(picture));
                List<ID3v23Frame> frames    = iD3v23Tag.getFrames();
                frames.add(frame);

                // save the ID3v2.3 tag to the .mp3 file
                mp3.save();

                // display the internal details of the mp3 file
                System.out.println(mp3);
             }
             catch (IOException ex)
             {
                // an error occurred reading/saving the .mp3 file.
                // you may try to read it again to see if the error still occurs.
                ex.printStackTrace();
             }
          }
       }

  See Also:
    `ID3v23Frame`, ID3 tag version 2.3.0 standard, wikipedia history of ID3 tags

- - ### Field Summary

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `buffer, dirty, frameType`

    - ### Fields inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `nextNullTerminatorIndex, nullTerminatorIndex`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ID3v23FrameBodyAttachedPicture()` The default constructor is called when creating a new frame.
    `ID3v23FrameBodyAttachedPicture(AttachedPicture picture)` This constructor is called when creating a new frame.
    `ID3v23FrameBodyAttachedPicture(Encoding encoding, java.lang.String mimeType, PictureType pictureType, java.lang.String description, byte[] image)` This constructor is called when creating a new frame.
    `ID3v23FrameBodyAttachedPicture(java.io.InputStream inputStream, int frameBodySize)` This constructor is called when reading in an existing frame from an .mp3 file.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `AttachedPicture` | `getAttachedPicture()` gets the picture stored in the frame.
    `java.lang.String` | `getDescription()` gets the description of the attached image.
    `Encoding` | `getEncoding()` gets the character encoding of the description field.
    `byte[]` | `getImage()` gets the raw binary data of the attached image.
    `java.lang.String` | `getMimeType()` gets the mime type of the attached imaged.
    `PictureType` | `getPictureType()` gets the type of image.
    `void` | `parse()` parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
    `void` | `setAttachedPicture(AttachedPicture attachedPicture)` sets the picture stored in the frame.
    `void` | `setBuffer()` If the frame body's values have been modified, then resize the raw binary buffer and store the new values there.
    `void` | `setDescription(java.lang.String description)` sets the description of the attached image.
    `void` | `setEncoding(Encoding encoding)` sets the character encoding of the description field.
    `void` | `setImage(byte[] image)` sets the raw binary data of the attached image.
    `void` | `setImage(java.io.File file)` loads the image and saves the raw binary data of the image.
    `void` | `setMimeType(java.lang.String mimeType)` sets the mime type of the attached image.
    `void` | `setPictureType(PictureType pictureType)` sets the picture type of the attached image.
    `java.lang.String` | `toString()` gets a string representation of the attached picture frame body showing all of the frame's fields and their values.

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBody

      `getFrameType, getNextNullTerminator, getSize, isDirty, save, save`

    - ### Methods inherited from class com.beaglebuddy.id3.v23.frame_body.ID3v23FrameBodyUtility

      `getNextNullTerminator, pricesToString, stringToBytes`

    - ### Methods inherited from class com.beaglebuddy.util.Utility

      `bytesToInt, bytesToInt, bytesToShort, bytesToShort, bytesToSynchsafeInt, bytesToSynchsafeShort, formateDate, hex, hex, hex, intToBytes, littleEndianBytesToInt, pad, shortToBytes, synchsafeIntToBytes`

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

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

- - ### Constructor Detail

    - #### ID3v23FrameBodyAttachedPicture

          public ID3v23FrameBodyAttachedPicture()

      The default constructor is called when creating a new frame. The default values used are:
      - ISO-8859-1 encoding
      - image/ mime type
      - other as the picture type - see `setPictureType(com.beaglebuddy.id3.enums.PictureType)`
      - "picture" as the description
      - no image

    - #### ID3v23FrameBodyAttachedPicture

          public ID3v23FrameBodyAttachedPicture(AttachedPicture picture)

      This constructor is called when creating a new frame.
      Parameters:
        `picture` - the attached picture which holds all the information about the picture being added.

    - #### ID3v23FrameBodyAttachedPicture

          public ID3v23FrameBodyAttachedPicture(Encoding encoding,
                                        java.lang.String mimeType,
                                        PictureType pictureType,
                                        java.lang.String description,
                                        byte[] image)

      This constructor is called when creating a new frame.
      Parameters:
        `encoding` - character set used to encode the description field.
        `mimeType` - MIME type of the image.
        `pictureType` - type of picture. see `setPictureType(com.beaglebuddy.id3.enums.PictureType)`
        `description` - description of the image.
        `image` - raw binary data of image.

    - #### ID3v23FrameBodyAttachedPicture

          public ID3v23FrameBodyAttachedPicture(java.io.InputStream inputStream,
                                        int frameBodySize)
                                         throws java.io.IOException

      This constructor is called when reading in an existing frame from an .mp3 file. This is then followed by a call to the parse() method.
      Parameters:
        `inputStream` - input stream pointing to a attached picture frame body in the .mp3 file.
        `frameBodySize` - size (in bytes) of the frame's body.
      Throws:
        `java.io.IOException` - if there is an error while reading the frame body.

  - ### Method Detail

    - #### parse

          public void parse()
                     throws java.lang.IllegalArgumentException

      parses the raw bytes of the frame body and stores the parsed values in the frame's fields.
      Overrides:
        `parse` in class `ID3v23FrameBody`
      Throws:
        `java.lang.IllegalArgumentException` - if an invalid value is detected while parsing the frame body's raw bytes.

    - #### getEncoding

          public Encoding getEncoding()

      gets the character encoding of the description field.
      Returns:
        the character encoding of the description field.
      See Also:
        `setEncoding(Encoding)`

    - #### setEncoding

          public void setEncoding(Encoding encoding)

      sets the character encoding of the description field.
      Parameters:
        `encoding` - the character set used to encode the description field. Only ISO 8859-1 and UTF-16 are allowed.
      See Also:
        `getEncoding()`

    - #### getMimeType

          public java.lang.String getMimeType()

      gets the mime type of the attached imaged.
      Returns:
        the mime type of the attached inmage.
      See Also:
        `setMimeType(String)`

    - #### setMimeType

          public void setMimeType(java.lang.String mimeType)

      sets the mime type of the attached image.
      Parameters:
        `mimeType` - the mime type of the attached image.
      See Also:
        `getMimeType()`

    - #### getPictureType

          public PictureType getPictureType()

      gets the type of image.
      Returns:
        the picture type of the attached image.
      See Also:
        `setPictureType(PictureType)`

    - #### setPictureType

          public void setPictureType(PictureType pictureType)

      sets the picture type of the attached image. There are 21 picture types as listed below:

      Picture Type | Description
      --- | ---
      0 | Other
      1 | 32x32 pixels 'file icon' (PNG only)
      2 | Other file icon
      3 | Cover (front)
      4 | Cover (back)
      5 | Leaflet page
      6 | Media (e.g. lable side of CD)
      7 | Lead artist/lead performer/soloist
      8 | Artist/performer
      9 | Conductor
      10 | Band/Orchestra
      11 | Composer
      12 | Lyricist/text writer
      13 | Recording Location
      14 | During recording
      15 | During performance
      16 | Movie/video screen capture
      17 | A bright coloured fish
      18 | Illustration
      19 | Band/artist logotype
      20 | Publisher/Studio logotype

      Parameters:
        `pictureType` - one of the 21 defined picture types.
      See Also:
        `getPictureType()`

    - #### getDescription

          public java.lang.String getDescription()

      gets the description of the attached image.
      Returns:
        the description of the attached image.
      See Also:
        `setDescription(String)`

    - #### setDescription

          public void setDescription(java.lang.String description)

      sets the description of the attached image.
      Parameters:
        `description` - the description of the attached image.
      See Also:
        `getDescription()`

    - #### getImage

          public byte[] getImage()

      gets the raw binary data of the attached image.
      Returns:
        the raw binary data of the attached image.
      See Also:
        `setImage(byte[])`

    - #### setImage

          public void setImage(byte[] image)

      sets the raw binary data of the attached image.
      Parameters:
        `image` - the raw binary data of the attached image.
      Throws:
        `java.lang.IllegalArgumentException` - if the image is null or an empty array.
      See Also:
        `getImage()`, `setImage(File)`

    - #### setImage

          public void setImage(java.io.File file)
                        throws java.io.IOException

      loads the image and saves the raw binary data of the image.
      Parameters:
        `file` - a file pointing to the image
      Throws:
        `java.io.IOException` - if the image file can not be read.
      See Also:
        `getImage()`, `setImage(byte[])`

    - #### getAttachedPicture

          public AttachedPicture getAttachedPicture()

      gets the picture stored in the frame.
      Returns:
        the picture stored in the frame.
      See Also:
        `setAttachedPicture(AttachedPicture)`

    - #### setAttachedPicture

          public void setAttachedPicture(AttachedPicture attachedPicture)

      sets the picture stored in the frame.
      Parameters:
        `attachedPicture` - the picture stored in the frame.
      See Also:
        `getAttachedPicture()`

    - #### setBuffer

          public void setBuffer()

      If the frame body'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 frame is now ready to be saved to the .mp3 file.
      Overrides:
        `setBuffer` in class `ID3v23FrameBody`

    - #### toString

          public java.lang.String toString()

      gets a string representation of the attached picture frame body showing all of the frame's fields and their values.
      Overrides:
        `toString` in class `java.lang.Object`
      Returns:
        a string representation of the frame body.