helliker.id3
Class MP3File

java.lang.Object
  |
  +--helliker.id3.MP3File
All Implemented Interfaces:
java.lang.Comparable

public class MP3File
extends java.lang.Object
implements java.lang.Comparable


Field Summary
static int BOTH_TAGS
          Write ID3v1 and ID3v2 tags whether or not they exist.
static int EXISTING_TAGS_ONLY
          Only write and read tags that already exist.
static int ID3V1_ONLY
          Write and read from ID3v1 tags only.
static int ID3V2_ONLY
          Write and read from ID3v2 tags only.
static int NO_TAGS
          Do not write or read from any id3 tags.
 
Constructor Summary
MP3File(java.io.File mp3)
          Create an MP3File object that reads and writes to the specified file.
MP3File(java.io.File mp3, int tagType)
          Create and MP3File object that reads and writes to the specified file.
MP3File(java.lang.String fn)
          Create an MP3File object that reads and writes to the file with the filename fn.
MP3File(java.lang.String fn, int tagType)
          Create an MP3File object that reads and writes to the file with the filename fn.
 
Method Summary
 int compareTo(java.lang.Object o)
          Compare this MP3File to the specified object.
 boolean equals(java.lang.Object o)
          Returns true if the object o is equal to this MP3File.
 java.lang.String getAlbum()
          Returns the album of the mp3 if set and the empty string if not.
 java.lang.String getArtist()
          Returns the artist of the mp3 if set and the empty string if not.
 int getBitRate()
          Returns the bitrate of this mp3 in kbps.
 java.lang.String getComment()
          Returns the comment field of this mp3 if set and the empty string if not.
 java.lang.String getComposer()
          Returns the composer of this mp3 if set and the empty string if not (id3v2 only).
 java.lang.String getCopyrightInfo()
          Returns the copyright info of this mp3 if set and the empty string if not (id3v2 only).
 java.lang.String getEncodedBy()
          Returns who encoded this mp3 if set and the empty string if not (id3v2 only).
 java.lang.String getFileName()
          Returns the filename of this MP3File.
 long getFileSize()
          Return the filesize of this MP3File (in bytes).
 byte[] getFrameDataBytes(java.lang.String id)
          Returns the data contained in the frame specified by the id (id3v2 only) .
 java.lang.String getFrameDataString(java.lang.String id)
          Returns the textual information contained in the frame specifed by the id.
 java.lang.String getGenre()
          Returns the genre of this mp3 if set and the empty string if not.
 java.lang.String getMPEGChannelMode()
          Return the channel mode of the mpeg.
 java.lang.String getMPEGEmphasis()
          Returns the emphasis of this mp3.
 java.lang.String getMPEGLayer()
          Returns a string specifying the layer of the mpeg.
 java.lang.String getMPEGVersion()
          Returns a string specifying the version of the mpeg.
 int getNumTracks()
          Although not a standard, sometimes track numbers are expressed as "x/y" where x is the track number and y is the total number of tracks on an album.
 java.lang.String getOriginalArtist()
          Returns the original artist of this mp3 if set and the empty string if not (id3v2 only).
 java.lang.String getParent()
          Returns the parent directory of this MP3File.
 java.lang.String getPath()
          Return the absolute path of this MP3File.
 long getPlayingTime()
          Returns the length (in seconds) of the playing time of this mp3.
 java.lang.String getPlayingTimeString()
          Return a formatted version of the getPlayingTime method.
 int getSampleRate()
          Returns the sample rate of this mp3 in Hz.
 int getTaggingType()
          Returns the currently set tagging type.
 java.lang.String getTitle()
          Returns the title of this mp3 if set and the empty string if not.
 int getTrack()
          Returns an integer value of the track number.
 java.lang.String getTrackString()
          Returns the track exactly as the track field of the id3 tag reads.
 java.lang.String getUserDefinedURL()
          Returns the user defined url of this mp3 if set and the empty string if not (id3v2 only).
 java.lang.String getYear()
          Returns the year of this mp3 if set and the empty string if not.
 boolean id3v1Exists()
          Returns true if an id3v1 tag currently exists.
 boolean id3v2Exists()
          Returns true if an id3v2 tag currently exists.
 boolean isMP3()
          Returns true if this file is an mp3.
 boolean isMPEGCopyrighted()
          Returns true if this mpeg is copyrighted.
 boolean isMPEGOriginal()
          Returns true if this mpeg is the original.
 boolean isMPEGPrivate()
          Returns true if the private bit is set in this mpeg.
 boolean isMPEGProtected()
          Returns true if this mpeg is protected by CRC.
 boolean isVBR()
          Returns true if this mp3 is a variable bitrate file.
 void removeTags(int type)
          Removes id3 tags from the file.
 void setAlbum(java.lang.String album)
          Set the album of this mp3.
 void setArtist(java.lang.String artist)
          Set the artist of this mp3.
 void setComment(java.lang.String comment)
          Add a comment to this mp3.
 void setComposer(java.lang.String composer)
          Set the composer of this mp3 (id3v2 only).
 void setCopyrightInfo(java.lang.String copyright)
          Add some copyright information to this mp3 (id3v2 only).
 void setEncodedBy(java.lang.String encBy)
          Set who encoded the mp3 (id3v2 only).
 void setFrameData(java.lang.String id, byte[] data)
          Set the data of the frame specified by the id (id3v2 only).
 void setGenre(java.lang.String genre)
          Set the genre of this mp3.
 void setOriginalArtist(java.lang.String artist)
          Set the original artist of this mp3 (id3v2 only).
 void setTaggingType(int newType)
          Set the tagging type.
 void setTextFrame(java.lang.String id, java.lang.String data)
          Set the text of the text frame specified by the id (id3v2 only).
 void setTitle(java.lang.String title)
          Set the title of this mp3.
 void setTrack(int track)
          Set the track number of this mp3.
 void setTrack(java.lang.String track)
          Set the track number with a String.
 void setUserDefinedText(java.lang.String desc, java.lang.String text)
          Add a field of miscellaneous text (id3v2 only).
 void setUserDefinedURL(java.lang.String desc, java.lang.String url)
          Add a link to this mp3 (id3v2 only).
 void setYear(java.lang.String year)
          Set the year of this mp3.
 java.lang.String toString()
          Return a string representation of this object.
 void writeTags()
          Writes the current state of the id3 tags to the file.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

BOTH_TAGS

public static final int BOTH_TAGS
Write ID3v1 and ID3v2 tags whether or not they exist. Precedence for reading will be given to id3v2 tags.

See Also:
Constant Field Values

ID3V2_ONLY

public static final int ID3V2_ONLY
Write and read from ID3v2 tags only. An ID3v2 tag will be created if an attempt is made to write.

See Also:
Constant Field Values

ID3V1_ONLY

public static final int ID3V1_ONLY
Write and read from ID3v1 tags only. An ID3v1 tag will be created if an attempt is made to write.

See Also:
Constant Field Values

NO_TAGS

public static final int NO_TAGS
Do not write or read from any id3 tags.

See Also:
Constant Field Values

EXISTING_TAGS_ONLY

public static final int EXISTING_TAGS_ONLY
Only write and read tags that already exist. Existing tags can be updated but new tags will not be created.

See Also:
Constant Field Values
Constructor Detail

MP3File

public MP3File(java.lang.String fn)
        throws java.io.FileNotFoundException,
               NoMPEGFramesException,
               java.io.IOException,
               ID3v2FormatException,
               CorruptHeaderException
Create an MP3File object that reads and writes to the file with the filename fn. This assumes that you only want to read and write id3 tags that already exist in the file.

Parameters:
fn - the filename of the mp3
Throws:
java.io.FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
java.io.IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs

MP3File

public MP3File(java.io.File mp3)
        throws java.io.FileNotFoundException,
               NoMPEGFramesException,
               java.io.IOException,
               ID3v2FormatException,
               CorruptHeaderException
Create an MP3File object that reads and writes to the specified file. This assumes that you only want to read and write id3 tags tha already exist in the file.

Parameters:
mp3 - the file of the mp3
Throws:
java.io.FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
java.io.IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs

MP3File

public MP3File(java.lang.String fn,
               int tagType)
        throws java.io.FileNotFoundException,
               NoMPEGFramesException,
               java.io.IOException,
               ID3v2FormatException,
               CorruptHeaderException
Create an MP3File object that reads and writes to the file with the filename fn. The id3 tags that are read from and written are dependant upon the tagType argument. This could be either: BOTH_TAGS, ID3V2_ONLY, ID3V1_ONLY, NO_TAGS, or EXISTING_TAGS_ONLY.

Parameters:
fn - the filename of the mp3
tagType - determines what type of tags to write and read from
Throws:
java.io.FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
java.io.IOException - if an error occurs
CorruptHeaderException - if an error occurs
ID3v2FormatException - if an error occurs

MP3File

public MP3File(java.io.File mp3,
               int tagType)
        throws java.io.FileNotFoundException,
               NoMPEGFramesException,
               java.io.IOException,
               ID3v2FormatException,
               CorruptHeaderException
Create and MP3File object that reads and writes to the specified file. The id3 tags that are read from and written are dependant upon the tagType argument. This could be either: BOTH_TAGS, ID3V2_ONLY, ID3V1_ONLY, NO_TAGS, or EXISTING_TAGS_ONLY.

Parameters:
mp3 - the file of the mp3
tagType - determines what type of tags to write and read from
Throws:
java.io.FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
java.io.IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs
Method Detail

getPlayingTime

public long getPlayingTime()
Returns the length (in seconds) of the playing time of this mp3. This will not return an accurate value for VBR files.

Returns:
the playing time (in seconds) of this mp3

getPlayingTimeString

public java.lang.String getPlayingTimeString()
Return a formatted version of the getPlayingTime method. The string will be formated "m:ss" where 'm' is minutes and 'ss' is seconds.

Returns:
a formatted version of the getPlayingTime method

getPath

public java.lang.String getPath()
Return the absolute path of this MP3File.

Returns:
the absolute path of this MP3File

getParent

public java.lang.String getParent()
Returns the parent directory of this MP3File.

Returns:
the parent directory of this MP3File

getFileName

public java.lang.String getFileName()
Returns the filename of this MP3File.

Returns:
the filename of this MP3File

getFileSize

public long getFileSize()
Return the filesize of this MP3File (in bytes).

Returns:
the filesize of this MP3File (in bytes)

id3v2Exists

public boolean id3v2Exists()
Returns true if an id3v2 tag currently exists.

Returns:
true if an id3v2 tag currently exists

id3v1Exists

public boolean id3v1Exists()
Returns true if an id3v1 tag currently exists.

Returns:
true if an id3v1 tag currently exists

isMP3

public boolean isMP3()
Returns true if this file is an mp3. This means simply that an MPEGAudioFrameHeader was found and the layer is 3.

Returns:
true if this file is an mp3

isVBR

public boolean isVBR()
Returns true if this mp3 is a variable bitrate file.

Returns:
true if this mp3 is a variable bitrate file.

getBitRate

public int getBitRate()
Returns the bitrate of this mp3 in kbps. If the file is a VBR file then the average bitrate is returned.

Returns:
the bitrate of this mp3 in kbps

getSampleRate

public int getSampleRate()
Returns the sample rate of this mp3 in Hz.

Returns:
the sample reate of this mp3 in Hz

getMPEGEmphasis

public java.lang.String getMPEGEmphasis()
Returns the emphasis of this mp3.

Returns:
the emphasis of this mp3

getMPEGLayer

public java.lang.String getMPEGLayer()
Returns a string specifying the layer of the mpeg. Ex: Layer III

Returns:
a string specifying the layer of the mpeg

getMPEGVersion

public java.lang.String getMPEGVersion()
Returns a string specifying the version of the mpeg. This can either be 1.0, 2.0, or 2.5.

Returns:
a string specifying the version of the mpeg

getMPEGChannelMode

public java.lang.String getMPEGChannelMode()
Return the channel mode of the mpeg. Ex: Stereo

Returns:
the channel mode of the mpeg

isMPEGCopyrighted

public boolean isMPEGCopyrighted()
Returns true if this mpeg is copyrighted.

Returns:
true if this mpeg is copyrighted

isMPEGOriginal

public boolean isMPEGOriginal()
Returns true if this mpeg is the original.

Returns:
true if this mpeg is the original

isMPEGProtected

public boolean isMPEGProtected()
Returns true if this mpeg is protected by CRC.

Returns:
true if this mpeg is protected by CRC

isMPEGPrivate

public boolean isMPEGPrivate()
Returns true if the private bit is set in this mpeg.

Returns:
true if the private bit is set in this mpeg

removeTags

public void removeTags(int type)
                throws java.io.FileNotFoundException,
                       java.io.IOException
Removes id3 tags from the file. The argument specifies which tags to remove. This can either be BOTH_TAGS, ID3V1_ONLY, ID3V2_ONLY, or EXISTING_TAGS_ONLY.

Parameters:
type - specifies what tag(s) to remove
Throws:
java.io.FileNotFoundException - if an error occurs
java.io.IOException - if an error occurs

writeTags

public void writeTags()
               throws java.io.FileNotFoundException,
                      java.io.IOException
Writes the current state of the id3 tags to the file. What tags are written depends upon the tagType passed to the constructor.

Throws:
java.io.FileNotFoundException - if an error occurs
java.io.IOException - if an error occurs

setTitle

public void setTitle(java.lang.String title)
Set the title of this mp3.

Parameters:
title - the title of the mp3

setAlbum

public void setAlbum(java.lang.String album)
Set the album of this mp3.

Parameters:
album - the album of the mp3

setArtist

public void setArtist(java.lang.String artist)
Set the artist of this mp3.

Parameters:
artist - the artist of the mp3

setComment

public void setComment(java.lang.String comment)
Add a comment to this mp3.

Parameters:
comment - a comment to add to the mp3

setGenre

public void setGenre(java.lang.String genre)
Set the genre of this mp3.

Parameters:
genre - the genre of the mp3

setYear

public void setYear(java.lang.String year)
Set the year of this mp3.

Parameters:
year - of the mp3

setTrack

public void setTrack(int track)
Set the track number of this mp3.

Parameters:
track - the track number of this mp3

setTrack

public void setTrack(java.lang.String track)
              throws java.lang.NumberFormatException
Set the track number with a String.

Parameters:
track - the track number of this mp3
Throws:
java.lang.NumberFormatException - if the String can't be parsed as an integer

setComposer

public void setComposer(java.lang.String composer)
Set the composer of this mp3 (id3v2 only).

Parameters:
composer - the composer of this mp3

setOriginalArtist

public void setOriginalArtist(java.lang.String artist)
Set the original artist of this mp3 (id3v2 only).

Parameters:
artist - the original artist of this mp3

setCopyrightInfo

public void setCopyrightInfo(java.lang.String copyright)
Add some copyright information to this mp3 (id3v2 only).

Parameters:
copyright - copyright information related to this mp3

setUserDefinedURL

public void setUserDefinedURL(java.lang.String desc,
                              java.lang.String url)
Add a link to this mp3 (id3v2 only). This includes a description of the url and the url itself.

Parameters:
desc - a description of the url
url - the url itself

setUserDefinedText

public void setUserDefinedText(java.lang.String desc,
                               java.lang.String text)
Add a field of miscellaneous text (id3v2 only). This includes a description of the text and the text itself.

Parameters:
desc - a description of the text
text - the text itself

setEncodedBy

public void setEncodedBy(java.lang.String encBy)
Set who encoded the mp3 (id3v2 only).

Parameters:
encBy - who encoded the mp3

setTextFrame

public void setTextFrame(java.lang.String id,
                         java.lang.String data)
Set the text of the text frame specified by the id (id3v2 only). The id should be one of the static strings specifed in ID3v2Frames class. All id's that begin with 'T' (excluding "TXXX") are considered text frames.

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

setFrameData

public void setFrameData(java.lang.String id,
                         byte[] data)
Set the data of the frame specified by the id (id3v2 only). The id should be one of the static strings specified in ID3v2Frames class.

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

getArtist

public java.lang.String getArtist()
                           throws ID3v2FormatException
Returns the artist of the mp3 if set and the empty string if not.

Returns:
the artist of the mp3
Throws:
ID3v2FormatException - if the data of the field is incorrect

getAlbum

public java.lang.String getAlbum()
                          throws ID3v2FormatException
Returns the album of the mp3 if set and the empty string if not.

Returns:
the album of the mp3
Throws:
ID3v2FormatException - if the data of the field is incorrect

getComment

public java.lang.String getComment()
                            throws ID3v2FormatException
Returns the comment field of this mp3 if set and the empty string if not.

Returns:
the comment field of this mp3
Throws:
ID3v2FormatException - if the data of the field is incorrect

getGenre

public java.lang.String getGenre()
                          throws ID3v2FormatException
Returns the genre of this mp3 if set and the empty string if not.

Returns:
the genre of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getTitle

public java.lang.String getTitle()
                          throws ID3v2FormatException
Returns the title of this mp3 if set and the empty string if not.

Returns:
the title of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getTrackString

public java.lang.String getTrackString()
                                throws ID3v2FormatException
Returns the track exactly as the track field of the id3 tag reads.

Returns:
the track of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getTrack

public int getTrack()
             throws ID3v2FormatException
Returns an integer value of the track number. If a track field of an id3v2 tag has a '/' the number before the '/' will be returned. Returns -1 if there is an error parsing the track field.

Returns:
an int value of the track number
Throws:
ID3v2FormatException - if an error occurs

getNumTracks

public int getNumTracks()
                 throws ID3v2FormatException
Although not a standard, sometimes track numbers are expressed as "x/y" where x is the track number and y is the total number of tracks on an album. This method will attempt to return the y value. Returns -1 if there is an error parsing the field or if there is no id3v2 tag.

Returns:
the total number of tracks of the related album
Throws:
ID3v2FormatException - if an error occurs

getYear

public java.lang.String getYear()
                         throws ID3v2FormatException
Returns the year of this mp3 if set and the empty string if not.

Returns:
the year of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getComposer

public java.lang.String getComposer()
                             throws ID3v2FormatException
Returns the composer of this mp3 if set and the empty string if not (id3v2 only).

Returns:
the composer of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getOriginalArtist

public java.lang.String getOriginalArtist()
                                   throws ID3v2FormatException
Returns the original artist of this mp3 if set and the empty string if not (id3v2 only).

Returns:
the original artist of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getCopyrightInfo

public java.lang.String getCopyrightInfo()
                                  throws ID3v2FormatException
Returns the copyright info of this mp3 if set and the empty string if not (id3v2 only).

Returns:
the copyright info of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getUserDefinedURL

public java.lang.String getUserDefinedURL()
                                   throws ID3v2FormatException
Returns the user defined url of this mp3 if set and the empty string if not (id3v2 only).

Returns:
the user defined url of this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getEncodedBy

public java.lang.String getEncodedBy()
                              throws ID3v2FormatException
Returns who encoded this mp3 if set and the empty string if not (id3v2 only).

Returns:
who encoded this mp3
Throws:
ID3v2FormatException - if the data of this field is incorrect

getFrameDataString

public java.lang.String getFrameDataString(java.lang.String id)
                                    throws ID3v2FormatException
Returns the textual information contained in the frame specifed by the id. If the frame does not contain any textual information or does not exist, then the empty string is returned (id3v2 only). The id should be one of the static strings defined in the ID3v2Frames class.

Parameters:
id - the id of the frame to get data from
Returns:
the textual information of the frame
Throws:
ID3v2FormatException - if the data of the frame is incorrect

getFrameDataBytes

public byte[] getFrameDataBytes(java.lang.String id)
Returns the data contained in the frame specified by the id (id3v2 only) . If the frame does not exist, a zero length array will be returned. The id should be one of the static strings defined in the ID3v2Frames class.

Parameters:
id - the id of the frame to get data from
Returns:
the data contained in the frame

getTaggingType

public int getTaggingType()
Returns the currently set tagging type.

Returns:
the current tagging type

setTaggingType

public void setTaggingType(int newType)
Set the tagging type. This determines what type of id3 tags are read/written. This should be one of the constants defined by this class: BOTH_TAGS, ID3V1_ONLY, ID3V2_ONLY, EXISTING_TAGS_ONLY, NO_TAGS

Parameters:
newType - the new tagging type

toString

public java.lang.String toString()
Return a string representation of this object. This includes all the information contained within the mpeg header and id3 tags as well as certain file attributes.

Overrides:
toString in class java.lang.Object
Returns:
a string representation of this object

equals

public boolean equals(java.lang.Object o)
Returns true if the object o is equal to this MP3File. This is true if the mp3s share the same path.

Overrides:
equals in class java.lang.Object
Parameters:
o - the object to compare
Returns:
true if the object o is equal to this MP3File

compareTo

public int compareTo(java.lang.Object o)
Compare this MP3File to the specified object. This comparson does a simple compare of the two paths. If the other object is not an mp3, compareTo will always return a positive number.

Specified by:
compareTo in interface java.lang.Comparable
Parameters:
o - the object to compare to this one
Returns:
a positive number if this object is greater than the other, 0 if the object are equal, or a negative number if this object is less than the other