org.farng.mp3.id3
Class ID3v2_3

java.lang.Object
  org.farng.mp3.AbstractMP3FileItem
      org.farng.mp3.AbstractMP3Tag
          org.farng.mp3.id3.AbstractID3
              org.farng.mp3.id3.AbstractID3v2
                  org.farng.mp3.id3.ID3v2_2
                      org.farng.mp3.id3.ID3v2_3

All Implemented Interfaces:

MP3Tag

Direct Known Subclasses:

ID3v2_4

public class ID3v2_3
extends ID3v2_2

The two biggest design goals were to be able to implement ID3v2 without disturbing old software too much and that ID3v2 should be as flexible and expandable as possible.

The first criterion is met by the simple fact that the MPEG decoding software uses a syncsignal, embedded in the audiostream, to 'lock on to' the audio. Since the ID3v2 tag doesn't contain a valid syncsignal, no software will attempt to play the tag. If, for any reason, coincidence make a syncsignal appear within the tag it will be taken care of by the 'unsynchronisation scheme' described in section 5.

The second criterion has made a more noticeable impact on the design of the ID3v2 tag. It is constructed as a container for several information blocks, called frames, whose format need not be known to the software that encounters them. At the start of every frame there is an identifier that explains the frames' format and content, and a size descriptor that allows software to skip unknown frames.

If a total revision of the ID3v2 tag should be needed, there is a version number and a size descriptor in the ID3v2 header.

The ID3 tag described in this document is mainly targeted at files encoded with MPEG-1/2 layer I, MPEG-1/2 layer II, MPEG-1/2 layer III and MPEG-2.5, but may work with other types of encoded audio.

The bitorder in ID3v2 is most significant bit first (MSB). The byteorder in multibyte numbers is most significant byte first (e.g. $12345678 would be encoded $12 34 56 78).

It is permitted to include padding after all the final frame (at the end of the ID3 tag), making the size of all the frames together smaller than the size given in the head of the tag. A possible purpose of this padding is to allow for adding a few additional frames or enlarge existing frames within the tag without having to rewrite the entire file. The value of the padding bytes must be $00.

The ID3v2 tag header, which should be the first information in the file, is 10 bytes as follows:

ID3v2/file identifier		"ID3"
ID3v2 version		$03 00
ID3v2 flags		%abc00000
ID3v2 size		4 * %0xxxxxxx

The first three bytes of the tag are always "ID3" to indicate that this is an ID3v2 tag, directly followed by the two version bytes. The first byte of ID3v2 version is it's major version, while the second byte is its revision number. In this case this is ID3v2.3.0. All revisions are backwards compatible while major versions are not. If software with ID3v2.2.0 and below support should encounter version three or higher it should simply ignore the whole tag. Version and revision will never be $FF.

The version is followed by one the ID3v2 flags field, of which currently only three flags are used.

a - Unsynchronisation

Bit 7 in the 'ID3v2 flags' indicates whether or not unsynchronisation is used (see section 5 for details); a set bit indicates usage.

b - Extended header

The second bit (bit 6) indicates whether or not the header is followed by an extended header. The extended header is described in section 3.2.

c - Experimental indicator

The third bit (bit 5) should be used as an 'experimental indicator'. This flag should always be set when the tag is in an experimental stage.

All the other flags should be cleared. If one of these undefined flags are set that might mean that the tag is not readable for a parser that does not know the flags function.

The ID3v2 tag size is encoded with four bytes where the most significant bit (bit 7) is set to zero in every byte, making a total of 28 bits. The zeroed bits are ignored, so a 257 bytes long tag is represented as $00 00 02 01.

The ID3v2 tag size is the size of the complete tag after unsychronisation, including padding, excluding the header but not excluding the extended header (total tag size - 10). Only 28 bits (representing up to 256MB) are used in the size description to avoid the introducuction of 'false syncsignals'.

An ID3v2 tag can be detected with the following pattern:
$49 44 33 yy yy xx zz zz zz zz
Where yy is less than $FF, xx is the 'flags' byte and zz is less than $80.

Version:

$Revision: 3 $

Author:

Eric Farng

Field Summary

protected int	crcData
protected boolean	crcDataFlag
protected boolean	experimental
protected boolean	extended
protected int	paddingSize

Fields inherited from class org.farng.mp3.id3.ID3v2_2

compression, unsynchronization

Constructor Summary

ID3v2_3()
Creates a new ID3v2_3 object.

ID3v2_3(AbstractMP3Tag mp3tag)
Creates a new ID3v2_3 object.

ID3v2_3(ID3v2_3 copyObject)
Creates a new ID3v2_3 object.

ID3v2_3(java.io.RandomAccessFile file)
Creates a new ID3v2_3 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() Get the song's album title.
java.lang.String	getAuthorComposer() Get the author/composer.
java.lang.String	getIdentifier()
java.lang.String	getLeadArtist() Get the lead artist.
int	getSize()
java.lang.String	getSongComment() Get a song comment.
java.lang.String	getSongGenre() Get the genre.
java.lang.String	getSongLyric() Get the song lyrics.
java.lang.String	getSongTitle() Get the song title.
java.lang.String	getTrackNumberOnAlbum() Get the track number.
java.lang.String	getYearReleased() Get the year the song was released.
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.
boolean	seek(java.io.RandomAccessFile file) Looks for this tag.
void	setAlbumTitle(java.lang.String albumTitle)
void	setAuthorComposer(java.lang.String authorComposer)
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	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.id3.AbstractID3v2

append, appendDuplicateFrameId, byteArrayToSize, clearFrameMap, decrementPaddingCounter, delete, getDuplicateBytes, getDuplicateFrameId, getEmptyFrameBytes, getFileReadBytes, getFrame, getFrameCount, getFrameIterator, getFrameOfType, getInvalidFrameBytes, getMajorVersion, getPaddingCounter, getPaddingSize, getRevision, hasFrame, hasFrameOfType, incrementDuplicateBytes, incrementEmptyFrameBytes, incrementInvalidFrameBytes, incrementPaddingCounter, iterator, overwrite, removeFrame, removeFrameOfType, resetPaddingCounter, setFileReadBytes, setFrame, setMajorVersion, setPaddingSize, setRevision, sizeToByteArray, values

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

Field Detail

crcDataFlag

protected boolean crcDataFlag

experimental

protected boolean experimental

extended

protected boolean extended

crcData

protected int crcData

paddingSize

protected int paddingSize

Constructor Detail

ID3v2_3

public ID3v2_3()

Creates a new ID3v2_3 object.

ID3v2_3

public ID3v2_3(ID3v2_3 copyObject)

Creates a new ID3v2_3 object.

ID3v2_3

public ID3v2_3(AbstractMP3Tag mp3tag)

Creates a new ID3v2_3 object.

ID3v2_3

public ID3v2_3(java.io.RandomAccessFile file)
        throws TagException,
               java.io.IOException

Creates a new ID3v2_3 object.

Throws:

TagException

java.io.IOException

Method Detail

getIdentifier

public java.lang.String getIdentifier()

Overrides:

getIdentifier in class ID3v2_2

getSize

public int getSize()

Overrides:

getSize in class ID3v2_2

append

public void append(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Overrides:

append in class ID3v2_2

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 ID3v2_2

Parameters:

obj - object to determine equality of

Returns:

true if this object and its body are equal

overwrite

public void overwrite(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Overrides:

overwrite in class ID3v2_2

Parameters:

tag - tag to overwrite

read

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

Description copied from class: AbstractMP3FileItem

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

Overrides:

read in class ID3v2_2

Parameters:

file - file to read from

Throws:

TagException - on any exception generated by this library.

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

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

Overrides:

seek in class ID3v2_2

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()

Overrides:

toString in class ID3v2_2

write

public void write(AbstractMP3Tag tag)

Description copied from class: AbstractMP3Tag

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

Overrides:

write in class ID3v2_2

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.

Overrides:

write in class ID3v2_2

Parameters:

file - file to write to

Throws:

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

getSongTitle

public java.lang.String getSongTitle()

Description copied from interface: MP3Tag

Get the song title.

Specified by:

getSongTitle in interface MP3Tag

Overrides:

getSongTitle in class ID3v2_2

Returns:

song title

getLeadArtist

public java.lang.String getLeadArtist()

Description copied from interface: MP3Tag

Get the lead artist.

Specified by:

getLeadArtist in interface MP3Tag

Overrides:

getLeadArtist in class ID3v2_2

Returns:

lead artist

getAlbumTitle

public java.lang.String getAlbumTitle()

Description copied from interface: MP3Tag

Get the song's album title.

Specified by:

getAlbumTitle in interface MP3Tag

Overrides:

getAlbumTitle in class ID3v2_2

Returns:

album title

getYearReleased

public java.lang.String getYearReleased()

Description copied from interface: MP3Tag

Get the year the song was released.

Specified by:

getYearReleased in interface MP3Tag

Overrides:

getYearReleased in class ID3v2_2

Returns:

year

getSongComment

public java.lang.String getSongComment()

Description copied from interface: MP3Tag

Get a song comment.

Specified by:

getSongComment in interface MP3Tag

Overrides:

getSongComment in class ID3v2_2

Returns:

comment

getSongGenre

public java.lang.String getSongGenre()

Description copied from interface: MP3Tag

Get the genre.

Specified by:

getSongGenre in interface MP3Tag

Overrides:

getSongGenre in class ID3v2_2

Returns:

genre

getTrackNumberOnAlbum

public java.lang.String getTrackNumberOnAlbum()

Description copied from interface: MP3Tag

Get the track number.

Specified by:

getTrackNumberOnAlbum in interface MP3Tag

Overrides:

getTrackNumberOnAlbum in class ID3v2_2

Returns:

track number

getSongLyric

public java.lang.String getSongLyric()

Description copied from interface: MP3Tag

Get the song lyrics.

Specified by:

getSongLyric in interface MP3Tag

Overrides:

getSongLyric in class ID3v2_2

Returns:

song lyrics

getAuthorComposer

public java.lang.String getAuthorComposer()

Description copied from interface: MP3Tag

Get the author/composer.

Specified by:

getAuthorComposer in interface MP3Tag

Overrides:

getAuthorComposer in class ID3v2_2

Returns:

author/composer

setSongTitle

public void setSongTitle(java.lang.String songTitle)

Overrides:

setSongTitle in class ID3v2_2

setLeadArtist

public void setLeadArtist(java.lang.String leadArtist)

Overrides:

setLeadArtist in class ID3v2_2

setAlbumTitle

public void setAlbumTitle(java.lang.String albumTitle)

Overrides:

setAlbumTitle in class ID3v2_2

setYearReleased

public void setYearReleased(java.lang.String yearReleased)

Overrides:

setYearReleased in class ID3v2_2

setSongComment

public void setSongComment(java.lang.String songComment)

Overrides:

setSongComment in class ID3v2_2

setSongGenre

public void setSongGenre(java.lang.String songGenre)

Overrides:

setSongGenre in class ID3v2_2

setTrackNumberOnAlbum

public void setTrackNumberOnAlbum(java.lang.String trackNumberOnAlbum)

Overrides:

setTrackNumberOnAlbum in class ID3v2_2

setSongLyric

public void setSongLyric(java.lang.String songLyrics)

Overrides:

setSongLyric in class ID3v2_2

setAuthorComposer

public void setAuthorComposer(java.lang.String authorComposer)

Overrides:

setAuthorComposer in class ID3v2_2