pgbennett.id3
Class ID3v2Tag

java.lang.Object
  pgbennett.id3.ID3v2Tag

All Implemented Interfaces:

ID3Tag

public class ID3v2Tag
extends java.lang.Object
implements ID3Tag

Description: This class reads and writes id3v2 tags from a file.

Version History

1.11.1 - 2002.1023 by gruni

-Made Sourcecode compliant to the Sun CodingConventions

1.11 - 2002.0127 by helliker

-The getBytes method is public to adhere to the ID3Tag interface.

1.10 - 2002.0125 by helliker

-Uses RandomAccessFile.readInt method to read ints.

1.9 - 2002.0125 by helliker

-Writes tag correctly if the 1st mpeg frame is corrupt.

-Fixed infinite loop in padding calculation.

1.8 - 2002.0124 by helliker

-Throws an exception with an invalid frame size.

1.7 - 2002.0113 by helliker

-Implements new ID3Tag interface.

-Optimized new padding calculation for writing.

1.6 - 2001.1204 by helliker

-Major revisions to size and padding calculations.

-Fixes to write and remove methods.

1.5 - 2001.1129 by helliker

-Fixed file handle leaks

1.4 - 2001.1110 by helliker

-Removed the getPaddingBytes method because it was not needed.

1.3 - 2001.1024 by helliker

-The padding size is updated before writing a tag, not during.

-Created a method to update the padding size.

1.2 - 2001.1019 by helliker

-All set for release.

Constructor Summary

ID3v2Tag(java.io.File mp3, long mpegOffset)
Create an id3v2 tag bound to the file provided as a parameter.

ID3v2Tag(java.io.File mp3, long mpegOffset, boolean emptyTag)

Method Summary

void	copyFrom(ID3Tag tag) Copies information from the ID3Tag parameter and inserts it into this tag.
byte[]	getBytes() Return a binary representation of this object to be written to a file.
byte[]	getFrameData(java.lang.String id) Returns the data found in the frame specified by the id.
java.lang.String	getFrameDataString(java.lang.String id) Returns the textual information contained in the frame specified by the id.
ID3v2Frames	getFrames() Get a collection of all frames in the tag.
ID3v2Header	getHead()
int	getPadding() Returns the current number of padding bytes in this id3v2 tag.
int	getSize() Returns the size of this id3v2 tag.
int	getTotalSize() Returns the actual size of the tag when written.
void	removeFrame(java.lang.String id) Remove the frame with the specified id from the file.
void	removeTag() Remove an existing id3v2 tag from the file passed to the constructor.
void	setCommentFrame(java.lang.String description, java.lang.String comment) Set the data contained in the comments frame (COMM).
void	setGenericFrame(java.lang.String id, byte[] data) Set the data contained in any frame.
void	setGenericFrame(java.lang.String id, java.lang.String data) Set the data contained in any frame.
void	setGenericFrame(java.lang.String id, java.lang.String lang, java.lang.String desc, java.lang.String data)
void	setPictureFrame(ID3v2Picture pic)
void	setTextFrame(java.lang.String id, java.lang.String data) Set the data contained in a text frame.
void	setURLFrame(java.lang.String id, java.lang.String data) Set the data contained in a URL frame.
void	setUserDefinedTextFrame(java.lang.String description, java.lang.String value) Sets the data contained in the user defined text frame (TXXX).
void	setUserDefinedURLFrame(java.lang.String description, java.lang.String value) Sets the data contained in the user defined url frame (WXXX).
boolean	tagExists() Returns true if an id3v2 tag exists in the file that was passed to the constructor and false otherwise
java.lang.String	toString() Return a string representation of this object.
void	updateFrameData(java.lang.String id, byte[] data) Updates the data for the frame specified by id.
void	writeTag() Saves all the information in the tag to the file passed to the constructor.

Methods inherited from class java.lang.Object

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

Constructor Detail

ID3v2Tag

public ID3v2Tag(java.io.File mp3,
                long mpegOffset)
         throws java.io.FileNotFoundException,
                java.io.IOException,
                ID3v2FormatException

Create an id3v2 tag bound to the file provided as a parameter. If a tag exists in the file already, then all the information in the tag will be extracted. If a tag doesn't exist, then this is the file that will be written to when the writeTag method is called.

Parameters:

mp3 - the file to write/read the the tag information to/from

mpegOffset - the byte offset where the mpeg frames begin

Throws:

java.io.FileNotFoundException - if an error occurs

java.io.IOException - if an error occurs

ID3v2FormatException - if an exisiting id3v2 tag isn't correct

ID3v2Tag

public ID3v2Tag(java.io.File mp3,
                long mpegOffset,
                boolean emptyTag)
         throws java.io.FileNotFoundException,
                java.io.IOException,
                ID3v2FormatException

Throws:

java.io.FileNotFoundException

java.io.IOException

ID3v2FormatException

Method Detail

writeTag

public void writeTag()
              throws java.io.FileNotFoundException,
                     java.io.IOException

Saves all the information in the tag to the file passed to the constructor. If a tag doesn't exist, a tag is prepended to the file. If the padding has not changed since the creation of this object and the size is less than the original size + the original padding, then the previous tag and part of the previous padding will be overwritten. Otherwise, a new tag will be prepended to the file.

Specified by:

writeTag in interface ID3Tag

Throws:

java.io.FileNotFoundException - if an error occurs

java.io.IOException - if an error occurs

removeTag

public void removeTag()
               throws java.io.FileNotFoundException,
                      java.io.IOException

Remove an existing id3v2 tag from the file passed to the constructor.

Specified by:

removeTag in interface ID3Tag

Throws:

java.io.FileNotFoundException - if an error occurs

java.io.IOException - if an error occurs

getBytes

public byte[] getBytes()

Return a binary representation of this object to be written to a file. This is in the format of the id3v2 specifications. This includes the header, extended header (if it exists), the frames, padding (if it exists), and a footer (if it exists).

Specified by:

getBytes in interface ID3Tag

Returns:

a binary representation of this id3v2 tag

setTextFrame

public void setTextFrame(java.lang.String id,
                         java.lang.String data)

Set the data contained in a text frame. This includes all frames with an id that starts with 'T' but excludes "TXXX". If an improper id is passed, then nothing will happen.

Parameters:

id - the id of the frame to set the data for

data - the data for the frame

setURLFrame

public void setURLFrame(java.lang.String id,
                        java.lang.String data)

Set the data contained in a URL frame. This includes all frames with an id that starts with 'W' but excludes "WXXX". If an improper id is passed, then nothing will happen.

Parameters:

id - the id of the frame to set the data for

data - the data for the frame

setUserDefinedTextFrame

public void setUserDefinedTextFrame(java.lang.String description,
                                    java.lang.String value)

Sets the data contained in the user defined text frame (TXXX).

Parameters:

description - a description of the data

value - the data for the frame

setUserDefinedURLFrame

public void setUserDefinedURLFrame(java.lang.String description,
                                   java.lang.String value)

Sets the data contained in the user defined url frame (WXXX).

Parameters:

description - a description of the url

value - the url for the frame

setCommentFrame

public void setCommentFrame(java.lang.String description,
                            java.lang.String comment)

Set the data contained in the comments frame (COMM).

Parameters:

description - a description of the comment

comment - the comment

setGenericFrame

public void setGenericFrame(java.lang.String id,
                            java.lang.String data)

Set the data contained in any frame. Can be used generically with any frame. The data bytes should have any zero values, language codes, etc. included according to the specification. Recommend 0 for encoding and eng for language.

Parameters:

id - the id of the frame to set the data for

data - the data for the frame

setGenericFrame

public void setGenericFrame(java.lang.String id,
                            java.lang.String lang,
                            java.lang.String desc,
                            java.lang.String data)

setPictureFrame

public void setPictureFrame(ID3v2Picture pic)
                     throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

setGenericFrame

public void setGenericFrame(java.lang.String id,
                            byte[] data)
                     throws java.io.UnsupportedEncodingException

Set the data contained in any frame. Can be used generically with any frame. The data bytes should have any zero values, language codes, etc. included according to the specification. Recommend 0 for encoding and eng for language.

Parameters:

id - the id of the frame to set the data for

data - the data for the frame

Throws:

java.io.UnsupportedEncodingException

removeFrame

public void removeFrame(java.lang.String id)

Remove the frame with the specified id from the file. If there is no frame with that id nothing will happen.

Parameters:

id - the id of the frame to remove. Extended id in the case of frames that support it.

updateFrameData

public void updateFrameData(java.lang.String id,
                            byte[] data)
                     throws java.io.UnsupportedEncodingException

Updates the data for the frame specified by id. If no frame exists for the id specified, a new frame with that id is created.

Parameters:

id - the id of the frame to update

data - the data for the frame

Throws:

java.io.UnsupportedEncodingException

getFrameDataString

public java.lang.String getFrameDataString(java.lang.String id)
                                    throws ID3v2FormatException

Returns the textual information contained in the frame specified by the id. Not every type of frame has textual information. If an id is specified that will not work, the empty string is returned.

Parameters:

id - the id of the frame to get text from or extended id.

Returns:

the text information contained in the frame. if an extended id is supplied the returned data excludes it.

Throws:

ID3v2FormatException - if an error is encountered parsing data

getFrameData

public byte[] getFrameData(java.lang.String id)

Returns the data found in the frame specified by the id. If the frame doesn't exist, then a zero length array is returned.

Parameters:

id - the id of the frame to get the data from or extended id.

Returns:

the data found in the frame. If an extended id is supplied it is included in the data.

tagExists

public boolean tagExists()

Returns true if an id3v2 tag exists in the file that was passed to the constructor and false otherwise

Returns:

true if an id3v2 tag exists in the file passed to the ctor

getSize

public int getSize()

Returns the size of this id3v2 tag. This includes only the frames, extended header, and padding. For the size of the entire tag including the header and footer, use getTotalSize method.

Returns:

the size (in bytes) of the id3v2 frames, extended header, footer

getTotalSize

public int getTotalSize()

Returns the actual size of the tag when written. Includes the header, extended header, frames, padding, and footer.

Returns:

the size (in bytes) of the entire id3v2 tag

getPadding

public int getPadding()

Returns the current number of padding bytes in this id3v2 tag.

Returns:

the current number of padding bytes in this id3v2 tag

toString

public java.lang.String toString()

Return a string representation of this object. This includes all data contained in all parts of this tag.

Overrides:

toString in class java.lang.Object

Returns:

a string representation of this object

getFrames

public ID3v2Frames getFrames()

Get a collection of all frames in the tag.

Returns:

collection based on a Map

getHead

public ID3v2Header getHead()

copyFrom

public void copyFrom(ID3Tag tag)

Copies information from the ID3Tag parameter and inserts it into this tag. Previous data will be overwritten. [NOT IMPLEMENTED]

Specified by:

copyFrom in interface ID3Tag

Parameters:

tag - the tag to copy from