|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.tffenterprises.music.tag.ID3v1
public class ID3v1
ID3v1 is an implementation of the so-called ID3v1.1 standard. An object can be constructed from a 125-byte array, from another instance of an ID3 subclass or from scratch. If the construction of the object necessitated any string cleaning and/or data sanitization, the isChanged() method will return true on the fresh object (otherwise it will return false, until a later change is made). The ID3v1 object can output itself as a string or as a 125-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 ID3v1 class; it is the responsibility of the user. (The TaggedFile class is a compliant user). Standard practice for ID3v1.1 tags is to insert the string "TAG" 128 bytes from the end of a file, followed by the 125 bytes of actual information returned by ID3v1.toBytes() method.
Field Summary | |
---|---|
private java.lang.String |
album
The name of the album or set from which the track was extracted. |
private static int |
ALBUM_LENGTH
Byte length of the album-name field in ID3v1. |
private static int |
ALBUM_OFFSET
Byte offset of the album-name field in ID3v1. |
private java.lang.String |
artist
The name of the artist or performer featured on the track. |
private static int |
ARTIST_LENGTH
Byte length of the artist field in ID3v1. |
private static int |
ARTIST_OFFSET
Byte offset of the artist field in ID3v1. |
private boolean |
changed
Flag indicating whether or not the tag has been changed. |
private java.lang.String |
comment
A comment relevant to the track. |
private static int |
COMMENT_LENGTH
Byte length of the comment field in ID3v1. |
private static int |
COMMENT_OFFSET
Byte offset of the comment field in ID3v1. |
static java.lang.String |
ENCODING
The recommended character encoding for an ID3v1 tag |
private byte |
genre
A byte representing the genre of the track. |
static java.lang.String |
GENRE_NONE
A recommended string that means "no genre" |
private static int |
GENRE_OFFSET
Byte offset of the genre byte in ID3v1. |
private static int |
ID3_11_OFFSET
Byte offset of the ID3v1.1 marker byte. |
static java.lang.String |
PREFIX
The string that announces the ID3v1 tag in a tagged file. |
static int |
TAG_LENGTH
The length of an ID3v1 tag. |
private java.lang.String |
title
The title of the track represented by this tag. |
private static int |
TITLE_LENGTH
Byte length of the title field in ID3v1. |
private static int |
TITLE_OFFSET
Byte offset of the title field in ID3v1. |
private byte |
track
The track's position within the set to which it belongs. |
private static int |
TRACK_OFFSET
Byte offset of the track byte in ID3v1.1. |
private short |
year
The year during which the track was recorded or released. |
private static int |
YEAR_LENGTH
Byte length of the year field in ID3v1. |
private static int |
YEAR_OFFSET
Byte offset of the year field in ID3v1. |
Constructor Summary | |
---|---|
ID3v1()
Default constructor. |
|
ID3v1(byte[] tagBytes)
Constructor from an array of bytes. |
|
ID3v1(ID3Tag oldTag)
Constructor copying data from another Tag implementor. |
|
ID3v1(java.io.InputStream in)
Constructor from an InputStream. |
Method Summary | |
---|---|
static boolean |
CheckFileForTag(java.io.RandomAccessFile raFile)
Verify whether a given file contains an ID3v1 tag. |
private java.lang.String |
cleanString(byte[] bytes,
int offset,
int length)
This will return a "proper" substring from the defined portion of the byte array. |
private java.lang.String |
cleanString(java.lang.String res,
int length)
Returns a "proper" substring of the string passed as an argument, up to a maximum length of length characters. |
java.lang.Object |
clone()
Clone the ID3v1 tag |
boolean |
equals(java.lang.Object obj)
Compare the ID3v1 tag for equality with another ID3v1 tag. |
java.lang.String |
getAlbum()
Return the name of the album or set on which this track can be found |
java.lang.String |
getArtist()
Return the name of the artist or performer featured on the track represented by this tag |
byte[] |
getBytes()
Get a byte array equivalent to the tag's representation in a file, using the default ID3 string encoding. |
byte[] |
getBytes(java.lang.String encoding)
Get a byte array equivalent to the tag's representation in a file, using the given string encoding. |
java.util.zip.Checksum |
getChecksum()
Obtain a Checksum object representing this instance. |
java.lang.String |
getComment()
Return a comment attached to the track. |
byte |
getGenre()
Return a byte representing the genre of the track. |
static int |
GetTagLength(java.io.RandomAccessFile raFile)
Get the length of the ID3v1 tag in this particular file. |
static long |
GetTagOffset(java.io.RandomAccessFile raFile)
Obtain the offset at which an ID3v1 would be located if there were one in the given file. |
java.lang.String |
getTitle()
Return the title of the track represented by this tag |
byte |
getTrackNumber()
Return the track's position out of its set, as an integer. |
short |
getYear()
Return the year during which the track was recorded or released, or -1 if there is no such information available. |
int |
hashCode()
Obtain a hash code for this ID3v1 tag. |
boolean |
isChanged()
Returns whether or not the tag has been changed. |
private void |
parseBytes(byte[] tagBytes)
Extract tag information out of a byte array. |
void |
setAlbum(java.lang.String album)
Set the title of the album or set of which the track is extracted. |
void |
setArtist(java.lang.String artist)
Set the name of the artist or performer featured on the track |
void |
setChanged(boolean changed)
Sets or clears the "changed" bit. |
void |
setComment(java.lang.String comment)
Attach a comment relevant to the track. |
void |
setGenre(byte genre)
Set the byte representing the genre of the track. |
void |
setGenre(java.lang.String genre)
Set the byte representing the genre of the track, using the String representation of the genre. |
void |
setTitle(java.lang.String title)
Set the title of the track represented by this tag. |
void |
setTrackNumber(byte track)
Set the position of the track within its set. |
void |
setYear(short year)
Set the year during which the track was recorded or released. |
java.lang.String |
toString()
Get a String representation of the tag. |
static short |
ValidateYear(short year)
Sanitize the year during which the track was recorded or released. |
void |
writeTo(java.io.OutputStream out)
Write this tag to an output stream, using the default ID3 string encoding. |
void |
writeTo(java.io.OutputStream out,
java.lang.String encoding)
Write this tag to an output stream, using the given string encoding. |
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 TAG_LENGTH
public static final java.lang.String ENCODING
public static final java.lang.String GENRE_NONE
private static final int TITLE_LENGTH
private static final int ARTIST_LENGTH
private static final int ALBUM_LENGTH
private static final int COMMENT_LENGTH
private static final int YEAR_LENGTH
private static final int TITLE_OFFSET
private static final int ARTIST_OFFSET
private static final int ALBUM_OFFSET
private static final int YEAR_OFFSET
private static final int COMMENT_OFFSET
private static final int ID3_11_OFFSET
private static final int TRACK_OFFSET
private static final int GENRE_OFFSET
private java.lang.String title
private java.lang.String artist
private java.lang.String album
private short year
private java.lang.String comment
private byte track
private byte genre
private boolean changed
Constructor Detail |
---|
public ID3v1()
public ID3v1(ID3Tag oldTag)
oldTag
- the ID3 instance from which to copy this ID3v1 object.public ID3v1(byte[] tagBytes) throws java.lang.IllegalArgumentException
tagBytes
- an array of 125 bytes containing the data from
which the ID3v1 tag is to be extracted.
java.lang.IllegalArgumentException
- if the array is not 125 bytes long.public ID3v1(java.io.InputStream in) throws java.lang.IllegalArgumentException, java.io.IOException
in
- a correctly-positioned instance of InputStream from which the
ID3v1 tag is to be extracted.
java.lang.IllegalArgumentException
- if there are less than 125 bytes
left in stream.
java.io.IOException
- if an I/O error occurs during the parsing.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 an I/O error occurs during the parsing.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 an I/O error occurs during the parsing.public static int GetTagLength(java.io.RandomAccessFile raFile)
raFile
- the file for which to get the tag length.
public void setTitle(java.lang.String title)
setTitle
in interface ID3Tag
title
- the title of the track represented by this tag.public java.lang.String getTitle()
getTitle
in interface ID3Tag
public void setArtist(java.lang.String artist)
setArtist
in interface ID3Tag
artist
- the name of the artist or performer featured on the track.public java.lang.String getArtist()
getArtist
in interface ID3Tag
public void setAlbum(java.lang.String album)
setAlbum
in interface ID3Tag
album
- the title of the album or set of which the track
is extracted.public java.lang.String getAlbum()
getAlbum
in interface ID3Tag
public void setComment(java.lang.String comment)
setComment
in interface ID3Tag
comment
- a comment relevant to the track.public java.lang.String getComment()
getComment
in interface ID3Tag
public void setTrackNumber(byte track)
setTrackNumber
in interface ID3Tag
track
- the position of the track within its set.public byte getTrackNumber()
getTrackNumber
in interface ID3Tag
public void setGenre(byte genre)
setGenre
in interface ID3Tag
genre
- the byte representing the genre of the track.public void setGenre(java.lang.String genre)
genre
- the String representing the genre of the track.public byte getGenre()
getGenre
in interface ID3Tag
public void setYear(short year)
setYear
in interface ID3Tag
year
- the year during which the track was recorded or released.public short getYear()
getYear
in interface ID3Tag
public boolean isChanged()
isChanged
in interface ID3Tag
public void setChanged(boolean changed)
setChanged
in interface ID3Tag
changed
- true to set the changed bit, false to unset it.public byte[] getBytes()
getBytes
in interface ID3Tag
public byte[] getBytes(java.lang.String encoding) throws java.io.UnsupportedEncodingException
The implementation of this method assumes a 1-byte encoding, but then again so does the ID3v1 so-called standard. This should not be considered as a bug, but it should be taken into consideration.
encoding
- the string encoding to be used in converting the tag
to bytes.
java.io.UnsupportedEncodingException
- if the encoding is unsupported.public void writeTo(java.io.OutputStream out) throws java.io.IOException
out
- the OutputStream instance to which this tag will be written.
java.io.IOException
- if an I/O error occurs.public void writeTo(java.io.OutputStream out, java.lang.String encoding) throws java.io.UnsupportedEncodingException, java.io.IOException
The implementation of this method assumes a 1-byte encoding, but then again so does the ID3v1 so-called standard. This should not be considered as a bug, but it should be taken into consideration.
out
- the OutputStream instance to which this tag will be
written.encoding
- the character encoding to be used.
java.io.IOException
- if an I/O error occurs.
java.io.UnsupportedEncodingException
- if the named encoding isn't
supported.public java.util.zip.Checksum getChecksum()
This method is used by the hashCode() method. A subclass only needs to update the checksum with its extra data. The name of the class is already taken into account.
public java.lang.String toString()
toString
in interface ID3Tag
toString
in class java.lang.Object
public java.lang.Object clone()
clone
in class java.lang.Object
public boolean equals(java.lang.Object obj)
equals
in class java.lang.Object
obj
- another ID3v1 tag to be compared
public final int hashCode()
The implementation of this method utilises the getChecksum() method of ID3v1. Subclasses should override the getChecksum() method and update the checksum with their local data. The changes will be reflected in the returned hash code.
hashCode
in class java.lang.Object
private void parseBytes(byte[] tagBytes) throws java.lang.IllegalArgumentException
tagBytes
- a byte array from which to read the tag information.
java.lang.IllegalArgumentException
- if the byte array has an incorrect size.private java.lang.String cleanString(byte[] bytes, int offset, int length)
bytes
- the bytes being converted to characters.offset
- index of the first byte to convert.length
- number of Bytes to convert.
private java.lang.String cleanString(java.lang.String res, int length)
res
- the String to be cleaned up. If this parameter is null,
an empty string is returned.length
- the maximum length of the resulting String.
public static short ValidateYear(short year)
-1
if it didn't make any
sense. Given that Edison invented recording in 1877, no value prior to that makes sense given what the "Year" field of ID3v1 is supposed to mean.
Turning to probable values, we will assume that people are not
using shortcuts for very distant dates. Thus, values smaller than
25
will be interpreted as being later than 1999,
while values from 26
to 99
will be
interpreted as being during the twentieth century.
year
- a year number, as input by a user.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |