de.vdheide.mp3
Class ID3v2

java.lang.Object
  de.vdheide.mp3.ID3v2

public class ID3v2

extends java.lang.Object

Instances of this class contain an ID3v2 tag

Notes:

1. There are two ways of detecting the size of padding used:
   1. The "Size of padding" field in the extended header
   2. Detecting all frames and substracting the tag's actual length from its' length in the header.
   Method a) is used in preference, so if a wrong padding size is stated in the extended header, all bad things may happen.
2. Although the ID3v2 informal standard does not state it, this class will only detect an ID3v2 tag if is starts at the first byte of a file.
3. There is no direct access to the header and extended header. Both are read, created and written internally.

   Field Summary

   static byte	REVISION ID3v2 revision
   static byte	VERSION ID3v2 version

   Constructor Summary

   ID3v2(java.io.File file)
   Provides access to file's ID3v2 tag

   ID3v2(java.io.InputStream in)
   Provides access to ID3v2 tag.

   Method Summary

   void	addFrame(ID3v2Frame frame) Add a frame
   java.util.Vector	getFrame(java.lang.String id) Return all frame with ID id
   java.util.Vector	getFrames() Get all frames
   boolean	getUseCRC()
   boolean	getUsePadding()
   boolean	getUseUnsynchronization()
   boolean	hasTag() Test if file already has an ID3v2 tag
   void	removeFrame(ID3v2Frame frame) Remove a frame.
   void	removeFrame(java.lang.String id) Remove all frames with a given id.
   void	removeFrame(java.lang.String id, int number) Remove a spefic frames with a given id.
   void	removeFrames() Remove all frames
   void	setUseCRC(boolean use_crc) Enables / disables use of CRC
   void	setUsePadding(boolean use_padding) Enables or disables use of padding (enabled by default)
   void	setUseUnsynchronization(boolean use_unsynch) Enables / disables use of unsynchronization
   static byte[]	synchronize(byte[] in) This method undoes the effect of the unsynchronization scheme by replacing $FF $00 by $FF
   static byte[]	unsynchronize(byte[] in) Unsynchronizes an array of bytes by replacing $FF 00 with $FF 00 00 and %11111111 111xxxxx with %11111111 00000000 111xxxxx.
   void	update() Write changes to file

   Methods inherited from class java.lang.Object

   equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

   Field Detail

   VERSION

   public static final byte VERSION

   ID3v2 version

   See Also:

   Constant Field Values

   REVISION

   public static final byte REVISION

   ID3v2 revision

   See Also:

   Constant Field Values

   Constructor Detail

   ID3v2

   public ID3v2(java.io.InputStream in)
         throws java.io.IOException,
                ID3v2IllegalVersionException,
                ID3v2WrongCRCException,
                ID3v2DecompressionException

   Provides access to ID3v2 tag. When used with an InputStream, no writes are possible (update will fail with an IOException, so make sure you just read.

   Parameters:

   in - Input stream to read from. Stream position must be set to beginning of file (i.e. position of ID3v2 tag).

   Throws:

   java.io.IOException - If I/O errors occur

   ID3v2IllegalVersionException - If file contains an IDv2 tag of higher version than VERSION.REVISION

   ID3v2WrongCRCException - If file contains CRC and this differs from CRC calculated from the frames

   ID3v2DecompressionException - If a decompression error occured while decompressing a compressed frame

   ID3v2

   public ID3v2(java.io.File file)
         throws java.io.IOException,
                ID3v2IllegalVersionException,
                ID3v2WrongCRCException,
                ID3v2DecompressionException

   Provides access to file's ID3v2 tag

   Parameters:

   file - File to access

   Throws:

   java.io.IOException - If I/O errors occur

   ID3v2IllegalVersionException - If file contains an IDv2 tag of higher version than VERSION.REVISION

   ID3v2WrongCRCException - If file contains CRC and this differs from CRC calculated from the frames

   ID3v2DecompressionException - If a decompression error occured while decompressing a compressed frame

   Method Detail

   synchronize

   public static byte[] synchronize(byte[] in)

   This method undoes the effect of the unsynchronization scheme by replacing $FF $00 by $FF

   Parameters:

   in - Array of bytes to be "synchronized"

   Returns:

   Changed array or null if no "synchronization" was necessary

   unsynchronize

   public static byte[] unsynchronize(byte[] in)

   Unsynchronizes an array of bytes by replacing $FF 00 with $FF 00 00 and %11111111 111xxxxx with %11111111 00000000 111xxxxx.

   Parameters:

   in - Array of bytes to be "unsynchronized"

   Returns:

   Changed array or null if no change was necessary

   setUsePadding

   public void setUsePadding(boolean use_padding)

   Enables or disables use of padding (enabled by default)

   Parameters:

   use_padding - True if padding should be used

   getUsePadding

   public boolean getUsePadding()

   Returns:

   True if padding is used

   setUseCRC

   public void setUseCRC(boolean use_crc)

   Enables / disables use of CRC

   Parameters:

   use_crc - True if CRC should be used

   getUseCRC

   public boolean getUseCRC()

   Returns:

   True if CRC is used

   setUseUnsynchronization

   public void setUseUnsynchronization(boolean use_unsynch)

   Enables / disables use of unsynchronization

   Parameters:

   use_unsynch - True if unsynchronization should be used

   getUseUnsynchronization

   public boolean getUseUnsynchronization()

   Returns:

   True if unsynchronization should be used

   hasTag

   public boolean hasTag()

   Test if file already has an ID3v2 tag

   Returns:

   true if file has IDv2 tag

   getFrames

   public java.util.Vector getFrames()
                              throws NoID3v2TagException

   Get all frames

   Returns:

   Vector of all frames

   Throws:

   NoID3v2TagException - If file does not contain ID3v2 tag

   getFrame

   public java.util.Vector getFrame(java.lang.String id)
                             throws NoID3v2TagException,
                                    ID3v2NoSuchFrameException

   Return all frame with ID id

   Parameters:

   id - Frame ID

   Returns:

   Requested frames

   Throws:

   NoID3v2TagException - If file does not contain ID3v2Tag

   ID3v2NoSuchFrameException - If file does not contain requested ID3v2 frame

   addFrame

   public void addFrame(ID3v2Frame frame)

   Add a frame

   Parameters:

   frame - Frame to add

   removeFrame

   public void removeFrame(ID3v2Frame frame)
                    throws NoID3v2TagException,
                           ID3v2NoSuchFrameException

   Remove a frame.

   Parameters:

   frame - Frame to remove

   Throws:

   NoID3v2TagException - If file does not contain ID3v2Tag

   ID3v2NoSuchFrameException - If file does not contain requested ID3v2 frame

   removeFrame

   public void removeFrame(java.lang.String id)
                    throws NoID3v2TagException,
                           ID3v2NoSuchFrameException

   Remove all frames with a given id.

   Parameters:

   id - ID of frames to remove

   Throws:

   NoID3v2TagException - If file does not contain ID3v2Tag

   ID3v2NoSuchFrameException - If file does not contain requested ID3v2 frame

   removeFrame

   public void removeFrame(java.lang.String id,
                           int number)
                    throws NoID3v2TagException,
                           ID3v2NoSuchFrameException

   Remove a spefic frames with a given id. A number is given to identify the frame if more than one frame exists

   Parameters:

   id - ID of frames to remove

   number - Number of frame to remove (the first frame gets number 0)

   Throws:

   NoID3v2TagException - If file does not contain ID3v2Tag

   ID3v2NoSuchFrameException - If file does not contain requested ID3v2 frame

   removeFrames

   public void removeFrames()

   Remove all frames

   update

   public void update()
               throws java.io.IOException

   Write changes to file

   Throws:

   java.io.IOException - If an I/O error occurs or the object was created from an InputStream and an update should be executed