org.metasyntactic.id3.v2.frame
Class Frame

java.lang.Object
  |
  +--org.metasyntactic.id3.v2.frame.Frame

All Implemented Interfaces:

Id3v2Constants

Direct Known Subclasses:

APIC, COMM, TextInformationFrame, TXXX, URLLinkFrame, WXXX

public abstract class Frame

extends java.lang.Object

implements Id3v2Constants

All ID3v2 frames consists of one frame header followed by one or more fields containing the actual information. The header is always 10 bytes and laid out as follows:

 Frame ID      $xx xx xx xx  (four characters)
 Size      4 * %0xxxxxxx
 Flags         $xx xx

The frame ID is made out of the characters capital A-Z and 0-9. Identifiers beginning with "X", "Y" and "Z" are for experimental frames and free for everyone to use, without the need to set the experimental bit in the tag header. Bear in mind that someone else might have used the same identifier as you. All other identifiers are either used or reserved for future use.

The frame ID is followed by a size descriptor containing the size of the data in the final frame, after encryption, compression and unsynchronisation. The size is excluding the frame header ('total frame size' - 10 bytes) and stored as a 32 bit synchsafe integer.

In the frame header the size descriptor is followed by two flag bytes. These flags are described in section 4.1.

There is no fixed order of the frames' appearance in the tag, although it is desired that the frames are arranged in order of significance concerning the recognition of the file. An example of such order: UFID, TIT2, MCDI, TRCK ...

A tag MUST contain at least one frame. A frame must be at least 1 byte big, excluding the header.

If nothing else is said, strings, including numeric strings and URLs [URL], are represented as ISO-8859-1 [ISO-8859-1] characters in the range $20 - $FF. Such strings are represented in frame descriptions as , or if newlines are allowed. If nothing else is said newline character is forbidden. In ISO-8859-1 a newline is represented, when allowed, with $0A only.

Frames that allow different types of text encoding contains a text encoding description byte. Possible encodings:

 $00   ISO-8859-1 [ISO-8859-1]. Terminated with $00.
 $01   UTF-16 [UTF-16] encoded Unicode [UNICODE] with BOM. All
 strings in the same frame SHALL have the same byteorder.
 Terminated with $00 00.
 $02   UTF-16BE [UTF-16] encoded Unicode [UNICODE] without BOM.
 Terminated with $00 00.
 $03   UTF-8 [UTF-8] encoded Unicode [UNICODE]. Terminated with $00.

Strings dependent on encoding are represented in frame descriptions as , or if newlines are allowed. Any empty strings of type $01 which are NULL-terminated may have the Unicode BOM followed by a Unicode NULL ($FF FE 00 00 or $FE FF 00 00).

The three byte language field, present in several frames, is used to describe the language of the frame's content, according to ISO-639-2 [ISO-639-2]. The language should be represented in lower case. If the language is not known the string "XXX" should be used.

All URLs [URL] MAY be relative, e.g. "picture.png", "../doc.txt".

If a frame is longer than it should be, e.g. having more fields than specified in this document, that indicates that additions to the frame have been made in a later version of the ID3v2 standard. This is reflected by the revision number in the header of the tag.

Field Summary

protected boolean	compressed This flag indicates whether or not the frame is compressed.
protected boolean	dataLengthIndicator This flag indicates that a data length indicator has been added to the frame.
protected boolean	discardOnFileAlteration This flag tells the tag parser what to do with this frame if it is unknown and the file, excluding the tag, is altered.
protected boolean	discardOnTagAlteration This flag tells the tag parser what to do with this frame if it is unknown and the tag is altered in any way.
protected boolean	encrypted This flag indicates whether or not the frame is encrypted.
protected byte[]	frameID
protected boolean	groupInformation This flag indicates whether or not this frame belongs in a group with other frames.
protected boolean	readOnly This flag, if set, tells the software that the contents of this frame are intended to be read only.
protected boolean	unsynchronised This flag indicates whether or not unsynchronisation was applied to this frame.

Fields inherited from interface org.metasyntactic.id3.v2.Id3v2Constants

ISO_8859_1, JAVA_ISO_8859_1, JAVA_US_ASCII, JAVA_UTF_16, JAVA_UTF_16_BIG_ENDIAN, JAVA_UTF_8, MAJOR_VERSION, MAX_ENCODING, MIN_ENCODING, REVISION_NUMBER, UTF_16, UTF_16_BIG_ENDIAN, UTF_8

Constructor Summary

protected

Frame()

Method Summary

int	getSize() Returns the data length of this frame.
int	getTotalSize() Returns the total size of this frame (the header plus the content)
boolean	hasDataLengthIndicator()
boolean	isCompressed()
boolean	isDiscardedOnFileAlteration()
boolean	isDiscardedOnTagAlteration()
boolean	isEncrypted()
boolean	isPartOfGroup()
boolean	isReadOnly()
boolean	isUnsynchronized()
static Frame	read(java.io.PushbackInputStream in) Reads in single frame from the passed in stream.
abstract void	readContent(java.io.PushbackInputStream in, int length) Subclasses must implement this method so that they can restore the contents of their fields from the stream
java.lang.String	toString()
void	write(java.io.OutputStream out) Writes out this frame to the outputstream.
abstract void	writeContent(java.io.OutputStream out) This is called as the last step of write(OutputStream).

Methods inherited from class java.lang.Object

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

Field Detail

frameID

protected byte[] frameID

discardOnTagAlteration

protected boolean discardOnTagAlteration

This flag tells the tag parser what to do with this frame if it is unknown and the tag is altered in any way. This applies to all kinds of alterations, including adding more padding and reordering the frames.

discardOnFileAlteration

protected boolean discardOnFileAlteration

This flag tells the tag parser what to do with this frame if it is unknown and the file, excluding the tag, is altered. This does not apply when the audio is completely replaced with other audio data.

readOnly

protected boolean readOnly

This flag, if set, tells the software that the contents of this frame are intended to be read only. Changing the contents might break something, e.g. a signature. If the contents are changed, without knowledge of why the frame was flagged read only and without taking the proper means to compensate, e.g. recalculating the signature, the bit MUST be cleared.

groupInformation

protected boolean groupInformation

This flag indicates whether or not this frame belongs in a group with other frames. If set, a group identifier byte is added to the frame. Every frame with the same group identifier belongs to the same group.

compressed

protected boolean compressed

This flag indicates whether or not the frame is compressed. A 'Data Length Indicator' byte MUST be included in the frame. 0 Frame is not compressed. 1 Frame is compressed using zlib [zlib] deflate method. If set, this requires the 'Data Length Indicator' bit to be set as well.

encrypted

protected boolean encrypted

This flag indicates whether or not the frame is encrypted. If set, one byte indicating with which method it was encrypted will be added to the frame. See description of the ENCR frame for more information about encryption method registration. Encryption should be done after compression. Whether or not setting this flag requires the presence of a 'Data Length Indicator' depends on the specific algorithm used. 0 Frame is not encrypted. 1 Frame is encrypted.

unsynchronised

protected boolean unsynchronised

This flag indicates whether or not unsynchronisation was applied to this frame. See section 6 for details on unsynchronisation. If this flag is set all data from the end of this header to the end of this frame has been unsynchronised. Although desirable, the presence of a 'Data Length Indicator' is not made mandatory by unsynchronisation. 0 Frame has not been unsynchronised. 1 Frame has been unsyrchronised.

dataLengthIndicator

protected boolean dataLengthIndicator

This flag indicates that a data length indicator has been added to the frame. The data length indicator is the value one would write as the 'Frame length' if all of the frame format flags were zeroed, represented as a 32 bit synchsafe integer. 0 There is no Data Length Indicator. 1 A data length Indicator has been added to the frame.

Constructor Detail

Frame

protected Frame()

Method Detail

isDiscardedOnTagAlteration

public boolean isDiscardedOnTagAlteration()

isDiscardedOnFileAlteration

public boolean isDiscardedOnFileAlteration()

isReadOnly

public boolean isReadOnly()

isPartOfGroup

public boolean isPartOfGroup()

isCompressed

public boolean isCompressed()

isEncrypted

public boolean isEncrypted()

isUnsynchronized

public boolean isUnsynchronized()

hasDataLengthIndicator

public boolean hasDataLengthIndicator()

write

public void write(java.io.OutputStream out)
           throws java.io.IOException

Writes out this frame to the outputstream. It is up to subclasses to implement writeContent so that they properly write out their data to the stream

java.io.IOException

writeContent

public abstract void writeContent(java.io.OutputStream out)
                           throws java.io.IOException

This is called as the last step of write(OutputStream). Subclasses must implement in order to properly write out their data to the stream

java.io.IOException

getSize

public int getSize()

Returns the data length of this frame. This is the length of the content of this tag (everything but the ten byte header) before compression, encryption, and unsyrchronisation. Subclasses should override this to make it more iffecient

getTotalSize

public int getTotalSize()
                 throws java.io.IOException

Returns the total size of this frame (the header plus the content)

java.io.IOException

read

public static Frame read(java.io.PushbackInputStream in)
                  throws java.io.IOException,
                         Id3v2Exception

Reads in single frame from the passed in stream. There are several 'exceptional' cases that can occur:

1. The input stream doesn't contain a frame at all. In this case the stream is restored to its original condition
2. The input stream contains a frame unknown to the present version of this library. In this case the stream pointer is moved to the end of the frame, effectively ignoring the frame
3. The input stream contains a frame with an unsupported feature. In this case the stream pointer is moved to the end of the frame, effectively ignoring the frame

java.io.IOException

Id3v2Exception

readContent

public abstract void readContent(java.io.PushbackInputStream in,
                                 int length)
                          throws java.io.IOException,
                                 Id3v2Exception

Subclasses must implement this method so that they can restore the contents of their fields from the stream

java.io.IOException

Id3v2Exception

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object