|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.tffenterprises.music.tag.ID3v2
public final class ID3v2
ID3v2 is an implementation of the ID3v2 informal standard. An object can be constructed from a byte array, from another instance of an ID3 subclass, or from scratch. The ID3v2 object can output itself as a string or as a byte array ready to be written into a file. Writing the tag into a file at its proper location is not the responsibility of the ID3v2 class; it is the responsibility of its user. The com.tffenterprises.music.io.TaggedFile class is such a compliant user. Standard practice for ID3v2 tags is to insert the string "ID3" at the the beginning of a file, followed by a header and a variable-length number of bytes. The toBytes() instance method will output an array of bytes including the header, the data and the padding (used for future addition of information).
Field Summary | |
---|---|
private boolean |
changed
Whether this tag has been changed. |
private int |
fileLength
How many bytes the tag occupies in the file, excluding the header and footer. |
private Flags |
flags
The Flags object. |
private java.util.Hashtable |
frameTable
A hashtable containing all the tag's information frames. |
static int |
HEADER_LENGTH
The byte length of an ID3v2 header. |
private int |
minimalLength
The minimum number of bytes the tag can occupy in the file, excluding the header and footer. |
private int |
paddingLength
How many bytes were skipped after the frame data. |
static java.lang.String |
PREFIX
The prefix to an ID3v2 tag. |
Constructor Summary | |
---|---|
ID3v2()
Default constructor. |
|
ID3v2(byte[] byteArray)
Constructs an ID3v2 object from a byte array. |
|
ID3v2(ID3Tag tag)
Constructs an ID3v2 tag using the data contained in another Tag implementor. |
|
ID3v2(java.io.InputStream in)
Constructs an ID3v2 object from an InputStream. |
|
ID3v2(short version)
Constructs an ID3v2 tag using the version supplied as a parameter. |
Method Summary | |
---|---|
Frame |
addFrame(Frame frame)
Add a given frame to this ID3v2 tag. |
static boolean |
CheckFileForTag(java.io.RandomAccessFile raFile)
Checks for the presence of an ID3v2 tag in a file. |
static byte[] |
CheckFileForTagVersion(java.io.RandomAccessFile raFile)
Checks for the presence of an ID3v2 tag and returns its version. |
java.lang.Object |
clone()
Returns a clone of this ID3v2 tag. |
boolean |
equals(java.lang.Object other)
Compares this ID3v2 tag with another object. |
java.lang.String |
getAlbum()
Returns the title of the album or set on which this track can be found. |
java.lang.String |
getArtist()
Returnsthe name of the artist or performer featured on the track represented by this tag. |
byte[] |
getBytes()
Returns a byte array equivalent to the tag's representation in a file, without the prefix. |
byte[] |
getBytes(int length)
Returns a byte array equivalent to the tag's representation in a file, padded to the given length, but without the prefix. |
java.util.zip.Checksum |
getChecksum()
Returns a Checksum of all this tag's data. |
java.lang.String |
getComment()
Returns the comment attached to the track. |
int |
getFileLength()
Returns the byte length occupied by this tag in its original file. |
Flags |
getFlags()
Returns the Flags object for this ID3v2 tag. |
Frame |
getFrameOfType(java.lang.String theID)
Returns a frame of an appropriate class to handle a frame with the given ID. |
java.lang.String |
getFrameTextForID(java.lang.String theID)
Returns the text for the TextFrame with the ID passed as a parameter. |
byte |
getGenre()
Returns a byte representing the genre of the track. |
Frame |
getKeyedFrameOfType(java.lang.String theID,
java.lang.String theDescription)
|
int |
getMinimalLength()
Returns the minimal length that could be occupied by this tag in a file (including the prefix). |
Frame |
getNewFrameOfType(java.lang.String theID)
Retruns a new frame of an appropriate class to handle the data for a given ID. |
static int |
GetTagLength(java.io.RandomAccessFile raFile)
Get the length of the ID3v2 tag, including header bytes, in the specified file. |
static long |
GetTagOffset(java.io.RandomAccessFile raFile)
Obtains the offset at which an ID3v2 tag would be located if there were one in the given file. |
java.lang.String |
getTitle()
Returnsthe title of the track represented by this tag. |
byte |
getTrackNumber()
Return the track's position out of its set, as an integer. |
short |
getVersion()
Returns the version number of the format of this tag. |
short |
getYear()
Returns the year during which the track was recorded. |
int |
hashCode()
Returns a hash code for this ID3v2 tag. |
boolean |
isChanged()
Returns true if the tag has been changed, false otherwise. |
private void |
parseFrames(AccountingInput acc,
java.io.InputStream in,
int len)
Parse the frames. |
private void |
parseMetaFrame(MetaFrame meta)
Obtain the frames that were embedded in a MetaFrame. |
private void |
parseStream(java.io.InputStream in)
Parse the InputStream in which the ID3v2 information is embedded. |
Frame |
removeFrame(Frame frame)
Removes the given frame from this tag, and returns the removed frame, or null if the referenced frame wasn't part of this tag. |
void |
setAlbum(java.lang.String album)
Sets the title of the album or set on which this track can be found. |
void |
setArtist(java.lang.String artist)
Sets the name of the artist or performer featured on the track represented by this tag. |
void |
setChanged(boolean changed)
Sets or clears the "changed" bit. |
void |
setComment(java.lang.String comment)
Attaches a comment to the track. |
void |
setComment(java.lang.String comment,
java.lang.String description)
|
void |
setFrameTextForID(java.lang.String theID,
java.lang.String theText)
Sets the text for the TextFrame frame with the ID passed as a parameter. |
void |
setGenre(byte genre)
Sets the byte representing the genre of the track. |
private void |
setKeyedFrameText(java.lang.String theID,
java.lang.String description,
java.lang.String text)
Sets the value text for a TXXX or COMM frame with an empty description. |
void |
setTitle(java.lang.String title)
Sets the title of the track represented by this tag. |
void |
setTrackNumber(byte trackNumber)
Sets the position of the track within its set. |
void |
setYear(short year)
Sets the year during which the track was recorded or released. |
java.lang.String |
toString()
Returns a String representation of this ID3v2 tag. |
void |
updateChecksum(DataOutputChecksum checksum)
Updates a checksum with this tag's data |
private void |
writeFrameBytes(java.io.OutputStream os)
Writes this tag's frames to the given OutputStream. |
void |
writeTo(java.io.OutputStream out)
Writes a representation of tag to the given OutputStream. |
void |
writeTo(java.io.OutputStream out,
int length)
Writes a representation of this tag to the given OutputStream, padded to the given length. |
Methods inherited from class java.lang.Object |
---|
finalize, getClass, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final java.lang.String PREFIX
public static final int HEADER_LENGTH
private java.util.Hashtable frameTable
private Flags flags
private transient int fileLength
private transient int minimalLength
private transient int paddingLength
private transient boolean changed
Constructor Detail |
---|
public ID3v2()
public ID3v2(short version) throws TagDataFormatException
version
- The version of the ID3v2 specification to be used.
TagDataFormatException
- if the version can't be used.public ID3v2(byte[] byteArray) throws TagDataFormatException, java.io.IOException, java.lang.IllegalArgumentException
byteArray
- The byte array.
TagDataFormatException
- if the byte array contains
malformed data, in most cases.
java.io.IOException
- if the byte array contains
malformed data, in other cases.
java.lang.IllegalArgumentException
- if the byte array does not contain
a valid ID3v2 tag.public ID3v2(java.io.InputStream in) throws TagDataFormatException, java.io.IOException, java.lang.IllegalArgumentException
in
- The InputStream from which the ID3v2 information should be read.
TagDataFormatException
- if the byte array contains
malformed data.
java.io.IOException
- if such an error occurs on the
input stream.
java.lang.IllegalArgumentException
- if the byte array does not contain
a valid ID3v2 tag.public ID3v2(ID3Tag tag)
tag
- The tag which provides initial data for this ID3v2 tag.Method Detail |
---|
public static boolean CheckFileForTag(java.io.RandomAccessFile raFile) throws java.io.IOException
raFile
- the file to check for the presence of a tag.
java.io.IOException
- if there is a problem reading from the file.public static byte[] CheckFileForTagVersion(java.io.RandomAccessFile raFile) throws java.io.IOException
raFile
- the file to check for the presence of a tag.
java.io.IOException
- if there is a problem reading from the file.public static long GetTagOffset(java.io.RandomAccessFile raFile) throws java.io.IOException
raFile
- the file from which to extract the offset.
java.io.IOException
- if there is a problem reading from the file.
Since there is no file reading going on in this
method yet, this should not happen.public static int GetTagLength(java.io.RandomAccessFile raFile) throws java.io.IOException
raFile
- the file for which to get the tag length.
java.io.IOException
- if there is a problem reading from the file.public java.lang.Object clone()
clone
in class java.lang.Object
public void updateChecksum(DataOutputChecksum checksum)
checksum
- the checksum to updatepublic final java.util.zip.Checksum getChecksum()
Checksum
of all this tag's data.
Checksum
of all of this tag's data.public final int hashCode()
hashCode
in class java.lang.Object
public boolean equals(java.lang.Object other)
equals
in class java.lang.Object
other
- The other object.
public java.lang.String toString()
toString
in interface ID3Tag
toString
in class java.lang.Object
public java.lang.String getFrameTextForID(java.lang.String theID)
theID
- the frame ID to be used to obtain the text.
public Flags getFlags()
Flags
object for this ID3v2 tag.
Flags
object for this ID3v2 tag.public void setFrameTextForID(java.lang.String theID, java.lang.String theText)
theID
- the frame ID to be used to find a frame and set its text.theText
- the frame text to use for the frame.private void setKeyedFrameText(java.lang.String theID, java.lang.String description, java.lang.String text)
theID
- the frame ID to be used to find a frame and set its text.theText
- the frame text to use for the frame.public Frame getFrameOfType(java.lang.String theID)
theID
- the frame id for which to find a frame.
public Frame getKeyedFrameOfType(java.lang.String theID, java.lang.String theDescription)
public Frame getNewFrameOfType(java.lang.String theID)
theID
- the frame id for which to create a new frame.
public java.lang.String getTitle()
getTitle
in interface ID3Tag
public void setTitle(java.lang.String title)
setTitle
in interface ID3Tag
title
- the track title.public java.lang.String getArtist()
getArtist
in interface ID3Tag
public void setArtist(java.lang.String artist)
setArtist
in interface ID3Tag
artist
- the artist/performer name.public java.lang.String getAlbum()
getAlbum
in interface ID3Tag
public void setAlbum(java.lang.String album)
setAlbum
in interface ID3Tag
album
- the album/set title.public java.lang.String getComment()
getComment
in interface ID3Tag
public void setComment(java.lang.String comment)
setComment
in interface ID3Tag
comment
- the comment.public void setComment(java.lang.String comment, java.lang.String description)
public byte getTrackNumber()
getTrackNumber
in interface ID3Tag
public void setTrackNumber(byte trackNumber) throws java.lang.IllegalArgumentException
setTrackNumber
in interface ID3Tag
trackNumber
- the position of the track within its set.
java.lang.IllegalArgumentException
- if trackNumber <= 0.public byte getGenre()
getGenre
in interface ID3Tag
public void setGenre(byte genre) throws java.lang.IllegalArgumentException
setGenre
in interface ID3Tag
genre
- the byte representing the genre of the track.
java.lang.IllegalArgumentException
- if genre < -1public short getYear()
getYear
in interface ID3Tag
public void setYear(short year)
setYear
in interface ID3Tag
year
- during which the track was recorded or released.
java.lang.IllegalArgumentException
- if year < -1public boolean isChanged()
isChanged
in interface ID3Tag
public void setChanged(boolean changed)
setChanged
in interface ID3Tag
changed
- true to set the changed bit, false to clear it.public byte[] getBytes()
getBytes
in interface ID3Tag
public byte[] getBytes(int length)
length
- PREFIX.length()
if length is positive, or of the minimal
tag length if length is non-positive. A null byte array will be
returned if the tag cannot fit in the given length, or if there is a
problem determining the representation of the tag.
length
- The number of bytes to which the tag length should be
padded. If this number is non-positive, the tag will not be padded.
public void writeTo(java.io.OutputStream out) throws java.io.IOException
out
- OutputStream to which the tag should be written.
java.io.IOException
- if there is a problem with the OutputStream.public void writeTo(java.io.OutputStream out, int length) throws java.io.IOException
out
- OutputStream to which the tag should be written.length
- The desired length. If this is not positive, the tag
will be written with minimal length.
java.io.IOException
- if there is a problem with the OutputStream.private void writeFrameBytes(java.io.OutputStream os) throws java.io.IOException
os
- the OutputStream to which the tag's frames should be written.
java.io.IOException
- if there is a problem with the OutputStream.public short getVersion()
public int getFileLength()
In an ideal world, this is the larger of the length of the tag in the file from which it was read and the minimal length of the tag. This length includes the prefix.
public int getMinimalLength()
public Frame addFrame(Frame frame)
frame
- the frame to be added to the ID3v2 tag.
frame
, or null.public Frame removeFrame(Frame frame)
frame
- the frame to be removed from this tag.
private void parseStream(java.io.InputStream in) throws java.io.IOException, java.lang.IllegalArgumentException, TagDataFormatException
in
- the InputStream in which the ID3v2 information is embedded.
java.lang.IllegalArgumentException
- if the stream does not contain a
valid tag, or an ill-encoded tag.
java.io.IOException
- if an I/O error occurs.
TagDataFormatException
private void parseFrames(AccountingInput acc, java.io.InputStream in, int len) throws java.io.IOException, PaddingException
ins
and acc
are really ultimately referring to the same object, but to allow for some
flexibility, it's passed separately with a different type declaration.
acc
- an instance of AccountingInputin
- an InputStream.len
- the number of bytes to be converted to frames.
java.io.IOException
- if such an error occurs on the input stream.
PaddingException
private void parseMetaFrame(MetaFrame meta)
meta
- a MetaFrame that embeds other frames.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |