org.farng.mp3
Class AbstractMP3Tag

java.lang.Object
  org.farng.mp3.AbstractMP3FileItem
      org.farng.mp3.AbstractMP3Tag

All Implemented Interfaces:

MP3Tag

Direct Known Subclasses:

AbstractID3, AbstractLyrics3, FilenameTag

public abstract class AbstractMP3Tag
extends AbstractMP3FileItem
implements MP3Tag

Introduction to tags

There are three types of tags found in an MP3 file found in this order:

1. ID3v2
2. <MP3 Data>
3. Lyrics3
4. ID3v1

In addition, there are different versions for each tag:

1. ID3v2
   • ID3v2.2
   • ID3v2.3
   • ID3v2.4
2. Lyrics3
   • Lyrics3v1
   • Lyrics3v2
3. ID3v1
   • ID3v1.0
   • ID3v1.1

Compiling:

If you have ant, there is a build.xml. Type "ant help" for build options.
If you get from CVS, you can use IntelliJ and read jid3lib.ipr

Reading:

 File sourceFile;
 MP3File mp3file = new MP3File(sourceFile);
 

You can also read specific tags:

 ID3v1_1 tag = new ID3v1_1(sourceFile);
 ID3v1 tag = new ID3v1(sourceFile);
 ID3v2_4 tag = new ID3v2_4(sourceFile);
 ID3v2_3 tag = new ID3v2_3(sourceFile);
 ID3v2_2 tag = new ID3v2_2(sourceFile);
 Lyrics3v2 tag = new Lyrics3v2(sourceFile);
 Lyrics3v1 tag = new Lyrics3v1(sourceFile);
 

Creating:

 MP3File mp3file = new MP3File();
 TagOptionSingleton.getInstance().setDefaultSaveMode(TagConstant.MP3_FILE_SAVE_OVERWRITE);
 

 // setup id3v1
 id3v1.setAlbum("albumTitle");
 

 // setup id3v2
 AbstractID3v2Frame frame;
 AbstractID3v2FrameBody frameBody;
 frameBody = new FrameBodyTALB((byte) 0, "albumTitle");
 frame = new ID3v2_4Frame(frameBody);
 id3v2.setFrame(frame);
 

 // setup lyrics3v2
 Lyrics3v2Field field;
 AbstractLyrics3v2FieldBody fieldBody;
 fieldBody = new FieldBodyEAL("albumTitle");
 field = new Lyrics3v2Field(fieldBody);
 lyrics3.setField(field);
 

 // setup filename tag
 frameBody = new FrameBodyTALB((byte) 0, "albumTitle");
 frame = new ID3v2_4Frame(frameBody);
 filenameId3.setFrame(frame);
 TagOptionSingleton.getInstance().setFilenameTagSave(true);
 

Things to note:

• The default save mode is "write but do not delete." This means each field in the object will be saved, but existing fields in the file on disk will not be deleted. The other two are "only append" or "delete and write from scratch."

Editing Part 1:

There are convience methods defined in AbstractMP3Tag to edit common data fields. Not all tags have all fields listed here.

 public abstract String getSongTitle();
 public abstract String getLeadArtist();
 public abstract String getAlbumTitle();
 public abstract String getYearReleased();
 public abstract String getSongComment();
 public abstract String getSongGenre();
 public abstract String getTrackNumberOnAlbum();
 public abstract String getSongLyric();
 public abstract String getAuthorComposer();
 public abstract void setSongTitle(String songTitle);
 public abstract void setLeadArtist(String leadArtist);
 public abstract void setAlbumTitle(String albumTitle);
 public abstract void setYearReleased(String yearReleased);
 public abstract void setSongComment(String songComment);
 public abstract void setSongGenre(String songGenre);
 public abstract void setTrackNumberOnAlbum(String trackNumberOnAlbum);
 public abstract void setSongLyric(String songLyrics);
 public abstract void setAuthorComposer(String authorComposer);
 

Editing Part 2:

If the field you want is not listed above, you can use these methods.

 id3v1 = mp3file.getID3v1Tag();
 id3v2 = mp3file.getID3v2Tag();
 lyrics3 = mp3file.getLyrics3Tag();
 

ID3v1 tags have fixed fields and use accessor methods to change it's properties.

ID3v2 tags have multiple frames. Use this to set the title of the tag.

 frame = id3v2.getFrame("TIT2");
 ((FrameBodyTIT2) frame.getBody()).setText("New Title");
 

Lyrics3 tags have multiple fields. Use this to set the title of the tag.

 field = lyrics3.getField("ETT");
 ((FieldBodyETT) field.getBody()).setTitle("New Title");
 

Writing:

 mp3file.save();
 

You can also save each individual tag through each tags' save() method.

Version:

$Revision: 3 $

Author:

Eric Farng

Constructor Summary

protected	AbstractMP3Tag() Creates a new AbstractMP3Tag object.
protected	AbstractMP3Tag(AbstractMP3Tag copyObject) Creates a new AbstractMP3Tag object.

Method Summary

abstract void	append(AbstractMP3Tag abstractMP3Tag) This method does nothing, but is called by subclasses for completeness
abstract void	append(java.io.RandomAccessFile file) Appends this tag to the given file.
abstract void	delete(java.io.RandomAccessFile file) removes the specific tag the easiest way.
boolean	equals(java.lang.Object obj) Determines whether another object is equal to this tag.
boolean	isSubsetOf(AbstractMP3Tag abstractMP3Tag) Returns true if this tag is a subset of the argument.
abstract void	overwrite(AbstractMP3Tag abstractMP3Tag) This method does nothing, but is called by subclasses for completeness
abstract void	overwrite(java.io.RandomAccessFile file) Overwrites this tag to the given file.
abstract boolean	seek(java.io.RandomAccessFile file) Looks for this tag.
abstract void	setAlbumTitle(java.lang.String albumTitle)
abstract void	setAuthorComposer(java.lang.String authorComposer)
abstract void	setLeadArtist(java.lang.String leadArtist)
abstract void	setSongComment(java.lang.String songComment)
abstract void	setSongGenre(java.lang.String songGenre)
abstract void	setSongLyric(java.lang.String songLyrics)
abstract void	setSongTitle(java.lang.String songTitle)
abstract void	setTrackNumberOnAlbum(java.lang.String trackNumberOnAlbum)
abstract void	setYearReleased(java.lang.String yearReleased)
abstract void	write(AbstractMP3Tag abstractMP3Tag) This method does nothing, but is called by subclasses for completeness

Methods inherited from class org.farng.mp3.AbstractMP3FileItem

getIdentifier, getSize, isSubsetOf, read, write

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.farng.mp3.MP3Tag

getAlbumTitle, getAuthorComposer, getLeadArtist, getSongComment, getSongGenre, getSongLyric, getSongTitle, getTrackNumberOnAlbum, getYearReleased, iterator

Constructor Detail

AbstractMP3Tag

protected AbstractMP3Tag()

Creates a new AbstractMP3Tag object.

AbstractMP3Tag

protected AbstractMP3Tag(AbstractMP3Tag copyObject)

Creates a new AbstractMP3Tag object.

Method Detail

append

public abstract void append(java.io.RandomAccessFile file)
                     throws java.io.IOException,
                            TagException

Appends this tag to the given file. Append means any information this tag contains will be added to the file's corresponding tag, but it will not replace any fields that the file already has. If the file does not have this specific tag, a new one will be created.

Parameters:

file - MP3 file to append to.

Throws:

java.io.IOException - on any I/O error

TagException - on any exception generated by this library.

delete

public abstract void delete(java.io.RandomAccessFile file)
                     throws java.io.IOException

removes the specific tag the easiest way.
ID3v1 - cuts the length of the tag
lyrics3 -cuts the length of the tag, then writes the id3v1 tag if it existed
id3v2 - just overwrites the ID3 tag indicator at the start of the tag

Parameters:

file - MP3 file to append to.

Throws:

java.io.IOException - on any I/O error

overwrite

public abstract void overwrite(java.io.RandomAccessFile file)
                        throws java.io.IOException,
                               TagException

Overwrites this tag to the given file. Overwrite means any information this tag contains will replace any existing fields in the file's corresponding tag. If the file does not have this specific tag, a new one will be created.

Parameters:

file - MP3 file to overwrite

Throws:

java.io.IOException - on any I/O error

TagException - on any exception generated by this library.

seek

public abstract boolean seek(java.io.RandomAccessFile file)
                      throws java.io.IOException

Looks for this tag. returns true if found. If found, the file pointer is right after the tag start indicator i.e. "TAG" "LYRICSBEGIN" "ID3" + 2

Parameters:

file - MP3 file to overwrite

Returns:

returns true if found, false otherwise.

Throws:

java.io.IOException - on any I/O error

isSubsetOf

public boolean isSubsetOf(AbstractMP3Tag abstractMP3Tag)

Returns true if this tag is a subset of the argument. Both tags are converted into ID3v2_4 tags, and then compared frame by frame.

Parameters:

abstractMP3Tag - superset tag

Returns:

true if this tag is a subset of the argument

append

public abstract void append(AbstractMP3Tag abstractMP3Tag)

This method does nothing, but is called by subclasses for completeness

Parameters:

abstractMP3Tag - tag to overwrite

equals

public boolean equals(java.lang.Object obj)

Determines whether another object is equal to this tag. It just compares if they are the same class, then calls super.equals(object).

Overrides:

equals in class AbstractMP3FileItem

Parameters:

obj - object to determine equality of

Returns:

true if this object and its body are equal

overwrite

public abstract void overwrite(AbstractMP3Tag abstractMP3Tag)

This method does nothing, but is called by subclasses for completeness

Parameters:

abstractMP3Tag - tag to overwrite

write

public abstract void write(AbstractMP3Tag abstractMP3Tag)

This method does nothing, but is called by subclasses for completeness

Parameters:

abstractMP3Tag - tag to write to

setSongTitle

public abstract void setSongTitle(java.lang.String songTitle)

setLeadArtist

public abstract void setLeadArtist(java.lang.String leadArtist)

setAlbumTitle

public abstract void setAlbumTitle(java.lang.String albumTitle)

setYearReleased

public abstract void setYearReleased(java.lang.String yearReleased)

setSongComment

public abstract void setSongComment(java.lang.String songComment)

setSongGenre

public abstract void setSongGenre(java.lang.String songGenre)

setTrackNumberOnAlbum

public abstract void setTrackNumberOnAlbum(java.lang.String trackNumberOnAlbum)

setSongLyric

public abstract void setSongLyric(java.lang.String songLyrics)

setAuthorComposer

public abstract void setAuthorComposer(java.lang.String authorComposer)