org.farng.mp3.lyrics3
Class Lyrics3v2

java.lang.Object
  org.farng.mp3.AbstractMP3FileItem
      org.farng.mp3.AbstractMP3Tag
          org.farng.mp3.lyrics3.AbstractLyrics3
              org.farng.mp3.lyrics3.Lyrics3v2

public class Lyrics3v2

extends AbstractLyrics3

What is Lyrics3 v2.00?

The Lyrics3 v2.00 tag is more complicated than the previous Lyrics3 tag but has a lot more capabilities. Just like the old Lyrics3 tag it resides between the audio and the ID3 tag, which must be present. The tag uses only text for everything from content to size descriptors, which are represented as numerical strings. This makes it easier to implement a Lyrics3 v2.00 reader. At least if BASIC is your language of choice.

The Lyrics3 block, after the MP3 audio and before the ID3 tag, begins with the word "LYRICSBEGIN" after which a number of field records follows. The Lyrics3 block ends with a six character size descriptor and the string "LYRICS200". The size value includes the "LYRICSBEGIN" and "LYRICS200" strings.

Lyrics2 v2.00 uses somthing called fields to represent information. The data in a field can consist of ASCII characters in the range 01 to 254 according to the standard. As the ASCII character map is only defined from 00 to 128 ISO-8859-1 might be assumed. Numerical fields are 5 or 6 characters long, depending on location, and are padded with zeroes.

Only the size of the tag sets the limit for how many fields may be present. All fields uses a simple structure that includes a three character field ID, six characters describing the size of the information and the actual information. This makes it possible to read unknown fields and write them back when saving the tag. There are no required fields in the tag, but at least one field must exist. Fields can appear in any order in the tag, except the indication field which must be the first field if used. Fields that include more then one line uses [CR][LF] delimiters between lines.

Defined fields

The following list is a list of currently defined field IDs. More fields might be added if needed on newer versions of the Lyrics3 v2.00 specifications. Unknown fields should be ignored.

ID	Max size	Description
IND	00002	Indications field. This is always two characters big in v2.00, but might be bigger in a future standard. The first byte indicates wether or not a lyrics field is present. "1" for present and "0" for otherwise. The second character indicates if there is a timestamp in the lyrics. Again "1" for yes and "0" for no.
LYR	99999	Lyrics multi line text. Timestamps can be used anywhere in the text in any order. Timestamp format is [mm:ss] (no spaces allowed in the timestamps).
INF	99999	Additional information multi line text.
AUT	00250	Lyrics/Music Author name.
EAL	00250	Extended Album name.
EAR	00250	Extended Artist name.
ETT	00250	Extended Track Title.
IMG	99999	Link to an image files (BMP or JPG format). Image lines include filename, description and timestamp separated by delimiter - two ASCII chars 124 ("||"). Description and timestamp are optional, but if timestamp is used, and there is no description, two delimiters ("||||") should be used between the filename and the timestamp. Multiple images are allowed by using a [CR][LF] delimiter between each image line. No [CR][LF] is needed after the last image line. Number of images is not limited (except by the field size). Filename can be in one of these formats: Filename only - when the image is located in the same path as the MP3 file (preferred, since if you move the mp3 file this will still be correct) Relative Path + Filename - when the image is located in a subdirectory below the MP3 file (i.e. images\cover.jpg) Full path + Filename - when the image is located in a totally different path or drive. This will not work if the image is moved or drive letters has changed, and so should be avoided if possible (i.e. c:\images\artist.jpg) Description can be up to 250 chars long. Timestamp must be formatted like the lyrics timestamp which is "[mm:ss]". If an image has a timestamp, then the visible image will automatically switch to that image on the timestamp play time, just the same as the selected lyrics line is switched based on timestamps.

The extended Album, Artist and Track are an extension to the fields in the ID3v1 tag - which are limited to 30 chars. If these extended fields exist, make sure their first 30 chars are exactly the same as the ones in the ID3v1 tag. If they are the same, display the extended field. If not, display the one from the ID tag. These 'mismatched' extended fields, should be removed when saving the lyrics tag.

When saving the extended fields, make sure to copy the first 30 chars of each field to the ID3 tag matching fields. It is recommended NOT to save extended fields at all, if they are not larger then 30 chars.

Version:

$Revision: 1.5 $

Author:

Eric Farng

Constructor Summary

Lyrics3v2()
Creates a new Lyrics3v2 object.

Lyrics3v2(AbstractMP3Tag mp3tag)
Creates a new Lyrics3v2 object.

Lyrics3v2(Lyrics3v2 copyObject)
Creates a new Lyrics3v2 object.

Lyrics3v2(java.io.RandomAccessFile file)
Creates a new Lyrics3v2 object.

Method Summary

void	append(AbstractMP3Tag tag) This method does nothing, but is called by subclasses for completeness
boolean	equals(java.lang.Object obj) Determines whether another object is equal to this tag.
java.lang.String	getAlbumTitle()
java.lang.String	getAuthorComposer()
Lyrics3v2Field	getField(java.lang.String identifier) Gets the value of the frame identified by identifier
int	getFieldCount()
java.lang.String	getIdentifier() ID string that usually corresponds to the class name, but can be displayed to the user.
java.lang.String	getLeadArtist()
int	getSize()
java.lang.String	getSongComment()
java.lang.String	getSongGenre()
java.lang.String	getSongLyric()
java.lang.String	getSongTitle()
java.lang.String	getTrackNumberOnAlbum()
java.lang.String	getYearReleased()
boolean	hasField(java.lang.String identifier)
java.util.Iterator	iterator()
void	overwrite(AbstractMP3Tag tag) This method does nothing, but is called by subclasses for completeness
void	read(java.io.RandomAccessFile file) import java.io.IOException; import java.io.RandomAccessFile; read from current file pointer position.
void	removeField(java.lang.String identifier)
boolean	seek(java.io.RandomAccessFile file) Looks for this tag.
void	setAlbumTitle(java.lang.String albumTitle)
void	setAuthorComposer(java.lang.String authorComposer)
void	setField(Lyrics3v2Field field)
void	setLeadArtist(java.lang.String leadArtist)
void	setSongComment(java.lang.String songComment)
void	setSongGenre(java.lang.String songGenre)
void	setSongLyric(java.lang.String songLyrics)
void	setSongTitle(java.lang.String songTitle)
void	setTrackNumberOnAlbum(java.lang.String trackNumberOnAlbum)
void	setYearReleased(java.lang.String yearReleased)
java.lang.String	toString()
void	updateField(java.lang.String identifier)
void	write(AbstractMP3Tag tag) This method does nothing, but is called by subclasses for completeness
void	write(java.io.RandomAccessFile file) Method to write this object to the file argument at is current file pointer position.

Methods inherited from class org.farng.mp3.lyrics3.AbstractLyrics3

append, delete, overwrite

Methods inherited from class org.farng.mp3.AbstractMP3Tag

isSubsetOf

Methods inherited from class org.farng.mp3.AbstractMP3FileItem

isSubsetOf

Methods inherited from class java.lang.Object

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

Constructor Detail

Lyrics3v2

public Lyrics3v2()

Creates a new Lyrics3v2 object.

Lyrics3v2

public Lyrics3v2(Lyrics3v2 copyObject)

Creates a new Lyrics3v2 object.

Lyrics3v2

public Lyrics3v2(AbstractMP3Tag mp3tag)

Creates a new Lyrics3v2 object.

Lyrics3v2

public Lyrics3v2(java.io.RandomAccessFile file)
          throws TagNotFoundException,
                 java.io.IOException

Creates a new Lyrics3v2 object.

Method Detail

setField

public void setField(Lyrics3v2Field field)

getField

public Lyrics3v2Field getField(java.lang.String identifier)

Gets the value of the frame identified by identifier

Parameters:

identifier - The three letter code

Returns:

The value associated with the identifier

getFieldCount

public int getFieldCount()

getIdentifier

public java.lang.String getIdentifier()

Description copied from class: AbstractMP3FileItem

ID string that usually corresponds to the class name, but can be displayed to the user. It is not indended to identify each individual instance.

Specified by:

getIdentifier in class AbstractMP3FileItem

Returns:

ID string

getSize

public int getSize()

Specified by:

getSize in class AbstractMP3FileItem

append

public void append(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Specified by:

append in class AbstractMP3Tag

Parameters:

tag - tag to overwrite

equals

public boolean equals(java.lang.Object obj)

Description copied from class: AbstractMP3Tag

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 AbstractMP3Tag

hasField

public boolean hasField(java.lang.String identifier)

iterator

public java.util.Iterator iterator()

Specified by:

iterator in class AbstractMP3Tag

overwrite

public void overwrite(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Specified by:

overwrite in class AbstractMP3Tag

Parameters:

tag - tag to overwrite

read

public void read(java.io.RandomAccessFile file)
          throws TagNotFoundException,
                 java.io.IOException

Description copied from class: AbstractMP3FileItem

import java.io.IOException; import java.io.RandomAccessFile; read from current file pointer position.

Specified by:

read in class AbstractMP3FileItem

Parameters:

file - file to read from

Throws:

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

TagNotFoundException

removeField

public void removeField(java.lang.String identifier)

seek

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

Description copied from class: AbstractMP3Tag

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

Specified by:

seek in class AbstractMP3Tag

Parameters:

file - MP3 file to overwrite

Returns:

returns true if found, false otherwise.

Throws:

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

toString

public java.lang.String toString()

updateField

public void updateField(java.lang.String identifier)

write

public void write(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Specified by:

write in class AbstractMP3Tag

Parameters:

tag - tag to write to

write

public void write(java.io.RandomAccessFile file)
           throws java.io.IOException

Description copied from class: AbstractMP3FileItem

Method to write this object to the file argument at is current file pointer position.

Specified by:

write in class AbstractMP3FileItem

Parameters:

file - file to write to

Throws:

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

getSongTitle

public java.lang.String getSongTitle()

Specified by:

getSongTitle in class AbstractMP3Tag

getLeadArtist

public java.lang.String getLeadArtist()

Specified by:

getLeadArtist in class AbstractMP3Tag

getAlbumTitle

public java.lang.String getAlbumTitle()

Specified by:

getAlbumTitle in class AbstractMP3Tag

getYearReleased

public java.lang.String getYearReleased()

Specified by:

getYearReleased in class AbstractMP3Tag

getSongComment

public java.lang.String getSongComment()

Specified by:

getSongComment in class AbstractMP3Tag

getSongGenre

public java.lang.String getSongGenre()

Specified by:

getSongGenre in class AbstractMP3Tag

getTrackNumberOnAlbum

public java.lang.String getTrackNumberOnAlbum()

Specified by:

getTrackNumberOnAlbum in class AbstractMP3Tag

getSongLyric

public java.lang.String getSongLyric()

Specified by:

getSongLyric in class AbstractMP3Tag

getAuthorComposer

public java.lang.String getAuthorComposer()

Specified by:

getAuthorComposer in class AbstractMP3Tag

setSongTitle

public void setSongTitle(java.lang.String songTitle)

Specified by:

setSongTitle in class AbstractMP3Tag

setLeadArtist

public void setLeadArtist(java.lang.String leadArtist)

Specified by:

setLeadArtist in class AbstractMP3Tag

setAlbumTitle

public void setAlbumTitle(java.lang.String albumTitle)

Specified by:

setAlbumTitle in class AbstractMP3Tag

setYearReleased

public void setYearReleased(java.lang.String yearReleased)

Specified by:

setYearReleased in class AbstractMP3Tag

setSongComment

public void setSongComment(java.lang.String songComment)

Specified by:

setSongComment in class AbstractMP3Tag

setSongGenre

public void setSongGenre(java.lang.String songGenre)

Specified by:

setSongGenre in class AbstractMP3Tag

setTrackNumberOnAlbum

public void setTrackNumberOnAlbum(java.lang.String trackNumberOnAlbum)

Specified by:

setTrackNumberOnAlbum in class AbstractMP3Tag

setSongLyric

public void setSongLyric(java.lang.String songLyrics)

Specified by:

setSongLyric in class AbstractMP3Tag

setAuthorComposer

public void setAuthorComposer(java.lang.String authorComposer)

Specified by:

setAuthorComposer in class AbstractMP3Tag