ID3v2_4Frame (jid3lib 0.5.4)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.farng.mp3.id3
Class ID3v2_4Frame

java.lang.Object
  org.farng.mp3.AbstractMP3FileItem
      org.farng.mp3.AbstractMP3Fragment
          org.farng.mp3.id3.AbstractID3v2Frame
              org.farng.mp3.id3.ID3v2_2Frame
                  org.farng.mp3.id3.ID3v2_3Frame
                      org.farng.mp3.id3.ID3v2_4Frame

public class ID3v2_4Frame
extends ID3v2_3Frame

   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 <text string>, or <full text string> 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 <text string according to encoding>, or <full text string
   according to encoding> 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 timestamp fields are based on a subset of ISO 8601. When being as
   precise as possible the format of a time string is
   yyyy-MM-ddTHH:mm:ss (year, "-", month, "-", day, "T", hour (out of
   24), ":", minutes, ":", seconds), but the precision may be reduced by
   removing as many time indicators as wanted. Hence valid timestamps
   are
   yyyy, yyyy-MM, yyyy-MM-dd, yyyy-MM-ddTHH, yyyy-MM-ddTHH:mm and
   yyyy-MM-ddTHH:mm:ss. All time stamps are UTC. For durations, use
   the slash character as described in 8601, and for multiple non-
   contiguous dates, use multiple strings, if allowed by the frame
   definition.

   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.

4.1. Frame header flags

   In the frame header the size descriptor is followed by two flag
   bytes. All unused flags MUST be cleared. The first byte is for
   'status messages' and the second byte is a format description. If an
   unknown flag is set in the first byte the frame MUST NOT be changed
   without that bit cleared. If an unknown flag is set in the second
   byte the frame is likely to not be readable. Some flags in the second
   byte indicates that extra information is added to the header. These
   fields of extra information is ordered as the flags that indicates
   them. The flags field is defined as follows (l and o left out because
   ther resemblence to one and zero):

%0abc0000 %0h00kmnp

   Some frame format flags indicate that additional information fields
   are added to the frame. This information is added after the frame
   header and before the frame data in the same order as the flags that
   indicates them. I.e. the four bytes of decompressed size will precede
   the encryption method byte. These additions affects the 'frame size'
   field, but are not subject to encryption or compression.

   The default status flags setting for a frame is, unless stated
   otherwise, 'preserved if tag is altered' and 'preserved if file is
   altered', i.e. %00000000.

4.1.1. Frame status flags

a - Tag alter preservation

     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.

0 Frame should be preserved.
1 Frame should be discarded.

b - File alter preservation

     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.

0 Frame should be preserved.
1 Frame should be discarded.

c - Read only

      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.

4.1.2. Frame format flags

h - Grouping identity

      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.

0 Frame does not contain group information
1 Frame contains group information

k - Compression

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.

m - Encryption

      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.

n - Unsynchronisation

      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.

p - Data length indicator

      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.

Version:: $Revision: 1.6 $
Author:: Eric Farng

Field Summary
`protected boolean`	`dataLengthIndicator`
`protected boolean`	`unsynchronization`

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

compression, encryption, fileAlterPreservation, groupingIdentity, readOnly, tagAlterPreservation

Constructor Summary
`ID3v2_4Frame()` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(AbstractID3v2Frame frame)` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(AbstractID3v2FrameBody body)` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(boolean readOnly, boolean groupingIdentity, boolean compression, boolean encryption, boolean unsynchronization, boolean dataLengthIndicator, AbstractID3v2FrameBody body)` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(ID3v2_4Frame copyObject)` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(Lyrics3v2Field field)` Creates a new ID3v2_4Frame object.
`ID3v2_4Frame(java.io.RandomAccessFile file)` Creates a new ID3v2_4Frame object.

Method Summary
`boolean`	`equals(java.lang.Object obj)` Returns true if this object and its body equals the argument and its body.
`int`	`getSize()`
`void`	`read(java.io.RandomAccessFile file)` import java.io.IOException; import java.io.RandomAccessFile; read from current file pointer position.
`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.ID3v2_3Frame

setAlterPreservation

Methods inherited from class org.farng.mp3.id3.AbstractID3v2Frame

getIdentifier, isValidID3v2FrameIdentifier, readBody, toString

Methods inherited from class org.farng.mp3.AbstractMP3Fragment

getBody, isSubsetOf, setBody

Methods inherited from class java.lang.Object

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

Field Detail

dataLengthIndicator

protected boolean dataLengthIndicator

unsynchronization

protected boolean unsynchronization

Constructor Detail