[Helix-client-dev] Statement of Design: Transfer of Cover Art and UITS properties through Helix DNA

SOD-CoverArt-UITS-Properties-1.0
Statement of Design: Transfer of Cover Art and UITS properties through Helix DNA

Revision History
-----------------+-------------+------------------------------------+---------
Name             | Date        | Reason For Changes                 | Version
-----------------+-------------+------------------------------------+---------
Petar Basic      | Oct-21-2009 | Initial Version                    | 1.0
-----------------+-------------+------------------------------------+---------


1. Purpose and introduction
=============================
GMP MetaEditor project requires that the following functionality be implemented in Helix DNA components:

--Reading and writing of Cover Art meta-data for MP4-based media files.
  Both 3GPP and iTunes flavors of meta-data must be supported.

--Reading and writing of UITS meta-data section for MP4-based media files.

This document proposes the design to be employed for transferring the above data through Helix DNA framework.


2. Reading and writing of Cover Art meta-data for MP4-based media files
=========================================================================
Helix DNA will carry Cover Art in its file header in a Buffer-property named "APICData".  To simplify extraction and insertion, the structure of the APIC data should be exactly as defined by ID3v2 spec (including the ID3 frame header).  The layout of ID3v2 APIC frame is as follows:

<Header for 'Attached picture', ID: "APIC">
  Text encoding  $xx
  MIME type      <text string> $00
  Picture type   $xx
  Description    <text string according to encoding> $00 (00)
  Picture data   <binary data>

To provide for easy parsing and generation of the APIC frame, a C++ utility class (e.g. class APICFrameWrapper) will be provided.  For example, to be able to look into the APIC fields, the code will only have to pass the contents of the "APICData" Buffer-property to the APICFrameWrapper constructor and call its methods.  Conversely, to construct the "APICData" Buffer-property, the code will pass relevant arguments (i.e. image BLOB, MIME-type) to the APICFrameWrapper constructor and retrieve the generated Buffer-property.  APICFrameWrapper can be also be designed as an implementation of an interface (e.g. IHXAPICFrame).

Supporting multiple attached pictures in Helix DNA can be done in the same manner as for keywords.  This translates to the following property definitions:
PropertyType: ULONG32, PropertyName: APICDataCount
PropertyType: Buffer,  PropertyName: APICData0
PropertyType: Buffer,  PropertyName: APICData1
etc.

"APICDataCount" contains the number of "APICData" prefixed Buffer-properties.  If "APICDataCount" property is missing, the code must assume there are no "APICData" Buffer-properties.  Otherwise, there are  exactly APICDataCount Buffer-properties named: "APICData" + APIC index.  APIC indices are 0 based and are not in any way related to the "Picture type" field of the contained APIC frame.

2.1. 3GPP meta-data flavor
----------------------------
Cover Art must be stored inside APIC frames of ID3v2 tag carried by the ID32 atom.  Per ID3 spec, multiple APIC frames can be stored inside ID3v2 tag.  APIC frame carries MIME-type field along with binary data, so any graphics format is supported.  Possible locations of ID32 atom inside the MP4 file are [file.meta.ID32], [file.moov.meta.ID32], [file.moov.trak.meta.ID32].

MP4 file-writer should write-out APIC frames stored within the Helix DNA file-header to the [file.moov.meta.ID32] location and those APIC frames stored within Helix DNA stream-headers should be written to corresponding [file.moov.trak.meta.ID32] locations.  Outputted ID3v2 tag must be constructed on the fly.  All APIC frames contained by "APICData" header properties must be injected into the constructed ID3v2 tag.

MP4 file-format should read APIC frames found under [file.moov.trak.meta.ID32] locations into the corresponding Helix DNA stream-headers, while APIC frames found under [file.moov.meta.ID32] location should be read into the Helix DNA file-header.  If [file.moov.meta.ID32] location is not present in the file, MP4 file-format can settle for APIC frames found under [file.meta.ID32] location and read those into the Helix DNA file-header.  Loaded ID3v2 tag must be parsed for all APIC frames.  Retrieved APIC frames must be extracted as "APICData" header properties.

2.2. iTunes meta-data flavor
------------------------------
Cover Art must be stored inside the [file.moov.udta.meta.ilst.covr.data] atom.  Storing multiple graphics objects is possible by putting multiple 'data' atoms under the 'covr' atom.  Per iTMF spec, graphics formats supported are: JPEG, PNG, GIF and BMP.

MP4 file-writer should write-out "Picture data" field of the APIC frame as iTunes' [file.moov.udta.meta.ilst.covr.data] atom contents and set the atom's payload-type flags according to "MIME type" field of the APIC frame.  "APICData" properties which contain unsupported MIME-types should be ignored.  Each APIC frame contained by "APICData" Helix DNA file-header properties must be injected into a separate 'data' atom.

MP4 file-format should read iTunes' [file.moov.udta.meta.ilst.covr.data] atoms and construct "APICData" Buffer-properties according to APIC frame layout.  "APICData" Buffer-properties must be inserted into the Helix DNA file-header.


3. Reading and writing of UITS meta-data section for MP4-based media files
============================================================================
UITS section is organized as a standalone XML document, which means UTF16 encoding should be supported.  Therefore, Helix DNA will carry UITS payload in a Buffer-property named "UITSData".  "UITSData" will contain a string formatted per UITS spec.

The exact location of UITS section inside the media-file depends on the container file format.  In case of MP4 media-file, UITS section should be embedded as a PRIV frame inside the ID3v2 tag carried by the [file.meta.ID32] or [file.moov.meta.ID32] atom.  The code will prefer [file.moov.meta.ID32] location.  The layout of the PRIV frame is as follows:

<Header for 'Private frame', ID: "PRIV">
  Owner identifier  <text string> $00
  The private data  <binary data>

What to use as the value of "Owner identifier" is to be determined.  From UITS spec: The 'Owner identifier' is a null-terminated string with a URL containing an email address, or a link to a location where an email address can be found, that belongs to the organisation responsible for the frame.

MP4 file-writer must write-out "UITSData" property found in the Helix DNA file-header as a PRIV frame inside the ID3v2 tag.  ID3v2 tag will be generated on the fly and placed into the [file.moov.meta.ID32] atom.

MP4 file-format must read [file.moov.meta.ID32] atom.  Loaded ID3v2 tag must be parsed for PRIV frame with "Owner identifier" which identifies the UITS section.  Matching frame's data must be extracted as "UITSData" property into the Helix DNA file-header.  If [file.moov.meta.ID32] location is not present in the file or does not contain required PRIV frame, the file-format can settle for matching PRIV frame found under [file.meta.ID32] location.


4. ID3v2 tag processing
==========================
With current requirements in mind, very limited ID3v2 parsing and generation capability is needed for now.  It would be best to create utility class that will support above but can be extended to support more in the future.  The other option is reusing existing ID3Lib project from our repository.