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