Mp3dings 
20100427

helliker.id3
Class MP3File

java.lang.Object
  extended by helliker.id3.MP3File
All Implemented Interfaces:
Comparable

public class MP3File
extends Object
implements Comparable

Description: This class is a container of all the tags and data that can be extracted from the mp3 specified by the file. If there are no id3 tags present, tags will be created by using mutators and saving the data.


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(File mp3)
          Create an MP3File object that reads and writes to the specified file.
MP3File(File mp3, int tagType)
          Create and MP3File object that reads and writes to the specified file.
MP3File(String fn)
          Create an MP3File object that reads and writes to the file with the filename fn.
MP3File(String fn, int tagType)
          Create an MP3File object that reads and writes to the file with the filename fn.
 
Method Summary
 int compareTo(Object o)
          Compare this MP3File to the specified object.
 boolean equals(Object o)
          Returns true if the object o is equal to this MP3File.
 String getAlbum()
          Returns the album of the mp3 if set and the empty string if not.
 String getArtist()
          Returns the artist of the mp3 if set and the empty string if not.
 APICImage getAttachedPicture()
           
 long getAudioOffset()
           
 int getBitRate()
          Returns the bitrate of this mp3 in kbps.
 String getComment()
          Returns the comment field of this mp3 if set and the empty string if not.
 String getComposer()
          Returns the composer of this mp3 if set and the empty string if not (id3v2 only).
 String getCopyrightInfo()
          Returns the copyright info of this mp3 if set and the empty string if not (id3v2 only).
 String getEncodedBy()
          Returns who encoded this mp3 if set and the empty string if not (id3v2 only).
 String getFileName()
          Returns the filename of this MP3File.
 long getFileSize()
          Return the filesize of this MP3File (in bytes).
 byte[] getFrameDataBytes(String id)
          Returns the data contained in the frame specified by the id (id3v2 only) .
 String getFrameDataString(String id)
          Returns the textual information contained in the frame specifed by the id.
 String getGenre()
          Returns the genre of this mp3 if set and the empty string if not.
 byte[] getHash(String algorithm)
           
 String getMPEGChannelMode()
          Return the channel mode of the mpeg.
 String getMPEGEmphasis()
          Returns the emphasis of this mp3.
 String getMPEGLayer()
          Returns a string specifying the layer of the mpeg.
 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.
 String getOriginalArtist()
          Returns the original artist of this mp3 if set and the empty string if not (id3v2 only).
 String getParent()
          Returns the parent directory of this MP3File.
 String getPath()
          Return the absolute path of this MP3File.
 int getPlayingTime()
          Returns the length (in seconds) of the playing time of this mp3.
 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.
 int getTagSize()
          Return the current size of the tag(s) in bytes.
 int getTagSize(int type)
          Returns the current size of the tag(s) in bytes.
 String getTitle()
          Returns the title of this mp3 if set and the empty string if not.
 Integer getTrack()
          Returns an integer value of the track number.
 String getTrackString()
          Returns the track exactly as the track field of the id3 tag reads.
 String getUserDefinedURL()
          Returns the user defined url of this mp3 if set and the empty string if not (id3v2 only).
 ID3v2Tag getV2Tag()
           
 String getYear()
          Returns the year of this mp3 if set and the empty string if not.
 boolean hashEquals(String algorithm, MP3File f)
           
 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.
static void removeLeadingGarbage(File mp3)
          Removes all non-audio data from the start of the specified file.
 void removeTags(int type)
          Removes id3 tags from the file.
 void removeTags(int type, boolean forceMpegOffset)
          Removes id3 tags from the file.
 void setAlbum(String album)
          Set the album of this mp3.
 void setAnalyzeVBRFiles(boolean b)
          Sets whether to analyze VBR files without XING or VBRI header.
 void setArtist(String artist)
          Set the artist of this mp3.
 void setAttachedPicture(APICImage pic)
           
 void setComment(String comment)
          Add a comment to this mp3.
 void setComposer(String composer)
          Set the composer of this mp3 (id3v2 only).
 void setCopyrightInfo(String copyright)
          Add some copyright information to this mp3 (id3v2 only).
 void setEncodedBy(String encBy)
          Set who encoded the mp3 (id3v2 only).
 void setFrameData(String id, byte[] data)
          Set the data of the frame specified by the id (id3v2 only).
 void setGenre(String genre)
          Set the genre of this mp3.
 void setOriginalArtist(String artist)
          Set the original artist of this mp3 (id3v2 only).
 void setTaggingType(int newType)
          Set the tagging type.
 void setTextFrame(String id, String data)
          Set the text of the text frame specified by the id (id3v2 only).
 void setTitle(String title)
          Set the title of this mp3.
 void setTrack(int track)
          Set the track number of this mp3.
 void setTrack(String track)
          Set the track number with a String.
 void setUserDefinedText(String desc, String text)
          Add a field of miscellaneous text (id3v2 only).
 void setUserDefinedURL(String desc, String url)
          Add a link to this mp3 (id3v2 only).
 void setYear(String year)
          Set the year of this mp3.
 String toString()
          Return a string representation of this object.
 void writeTags()
          Writes the current state of the id3 tags to the file.
 void writeTags(boolean forceMpegOffset)
           
 
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(String fn)
        throws NoMPEGFramesException,
               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:
FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs

MP3File

public MP3File(File mp3)
        throws NoMPEGFramesException,
               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:
FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs

MP3File

public MP3File(String fn,
               int tagType)
        throws NoMPEGFramesException,
               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:
FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs

MP3File

public MP3File(File mp3,
               int tagType)
        throws NoMPEGFramesException,
               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:
FileNotFoundException - if an error occurs
NoMPEGFramesException - if an error occurs
IOException - if an error occurs
ID3v2FormatException - if an error occurs
CorruptHeaderException - if an error occurs
Method Detail

getPlayingTime

public int getPlayingTime()
Returns the length (in seconds) of the playing time of this mp3.

Returns:
the playing time (in seconds) of this mp3
See Also:
setAnalyzeVBRFiles(boolean)

getPlayingTimeString

public 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 String getPath()
Return the absolute path of this MP3File.

Returns:
the absolute path of this MP3File

getParent

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

Returns:
the parent directory of this MP3File

getFileName

public 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.

setAnalyzeVBRFiles

public void setAnalyzeVBRFiles(boolean b)
Sets whether to analyze VBR files without XING or VBRI header.

See Also:
getPlayingTime(), getBitRate()

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
See Also:
setAnalyzeVBRFiles(boolean)

getSampleRate

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

Returns:
the sample reate of this mp3 in Hz

getMPEGEmphasis

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

Returns:
the emphasis of this mp3

getMPEGLayer

public 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 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 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 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:
FileNotFoundException - if an error occurs
IOException - if an error occurs

removeTags

public void removeTags(int type,
                       boolean forceMpegOffset)
                throws 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:
FileNotFoundException - if an error occurs
IOException - if an error occurs

removeLeadingGarbage

public static void removeLeadingGarbage(File mp3)
                                 throws NoMPEGFramesException,
                                        IOException,
                                        CorruptHeaderException
Removes all non-audio data from the start of the specified file. A corrupt ID3V2Tag cannot be removed via removeTags(int) because trying to construct an instance of this class on the file will throw an exception. In this case you can try this static method which will remove all non-audio Data from mp3.

Throws:
NoMPEGFramesException
IOException
CorruptHeaderException

writeTags

public void writeTags()
               throws 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:
FileNotFoundException - if an error occurs
IOException - if an error occurs

writeTags

public void writeTags(boolean forceMpegOffset)
               throws IOException
Throws:
IOException

setTitle

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

Parameters:
title - the title of the mp3

setAlbum

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

Parameters:
album - the album of the mp3

setArtist

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

Parameters:
artist - the artist of the mp3

setComment

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

Parameters:
comment - a comment to add to the mp3

setGenre

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

Parameters:
genre - the genre of the mp3

setYear

public void setYear(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(String track)
Set the track number with a String.

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

setComposer

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

Parameters:
composer - the composer of this mp3

setOriginalArtist

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

Parameters:
artist - the original artist of this mp3

setCopyrightInfo

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

Parameters:
copyright - copyright information related to this mp3

setUserDefinedURL

public void setUserDefinedURL(String desc,
                              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(String desc,
                               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(String encBy)
Set who encoded the mp3 (id3v2 only).

Parameters:
encBy - who encoded the mp3

setTextFrame

public void setTextFrame(String id,
                         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(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 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 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 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 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 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 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 Integer 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 null 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 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 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

getAttachedPicture

public APICImage getAttachedPicture()
                             throws ID3v2FormatException
Throws:
ID3v2FormatException

setAttachedPicture

public void setAttachedPicture(APICImage pic)

getOriginalArtist

public 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 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 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 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 String getFrameDataString(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(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

getTagSize

public int getTagSize()
Return the current size of the tag(s) in bytes. What size is returned depends on the type of tagging specified in the constructor.

Returns:
the size of the tag(s) in bytes

getAudioOffset

public long getAudioOffset()

getTagSize

public int getTagSize(int type)
Returns the current size of the tag(s) in bytes. What size is returned depends on the type of tagging specified. The possible values for the type is: BOTH_TAGS, ID3V1_ONLY, ID3V2_ONLY, EXISTING_TAGS_ONLY, NO_TAGS. If BOTH_TAGS or EXISTING_TAGS_ONLY is used and both tags exist, then the size of the two tags added will be returned.

Parameters:
type - the tagging type
Returns:
the size of the tag(s) in bytes

toString

public 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 Object
Returns:
a string representation of this object

equals

public boolean equals(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 Object
Parameters:
o - the object to compare
Returns:
true if the object o is equal to this MP3File

compareTo

public int compareTo(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 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

getHash

public byte[] getHash(String algorithm)
               throws IOException,
                      NoSuchAlgorithmException
Throws:
IOException
NoSuchAlgorithmException

hashEquals

public boolean hashEquals(String algorithm,
                          MP3File f)
                   throws IOException,
                          NoSuchAlgorithmException
Throws:
IOException
NoSuchAlgorithmException

getV2Tag

public ID3v2Tag getV2Tag()

Mp3dings 
20100427