Focus on non standard fields

What are non-standard fields ?

A given field is considered "non standard" when :

• The metadata container specification has a finite set of standard fields (e.g. ID3v2) and the field you're trying to write is not among them
• The metadata container specification has rules for field names (e.g. MP4 where field codes shouldn't be longer than 4 characters) and the field you're trying to write doesn't follow these rules

How does ATL handle them at read time ?

• If they are mapped to a standard ATL field, they appear as such (e.g. MP4 where ----:com.apple.iTunes:CONDUCTOR which is mapped as IMetaData.Conductor;
• If not, they appear as a key-value pair inside IMetaData.AdditionalFields.

Specifics

ID3v2 / TXXX

Non-standard fields persisted using the TXXX ("User-defined information frame") field code appear inside AdditionalFields with their actual field name.

Using specifications vocabulary, AdditionalFields's key contains the Description and AdditionalFields's value contains the Value.

ID3v2 / GEOB (v4.12+)

Non-standard fields persisted using the GEOB ("Encapsulated object") field code appear inside AdditionalFields with a key comprised of their content description prepended with GEOB..

Using specifications vocabulary, AdditionalFields's key contains the Content description and AdditionalFields's value contains the Encapsulated object.

NB : The Encapsulated object is serialized as a string encoded with ISO-8859-1.

MP4, M4A, M4B

Any non-standard field persisted using the ---- field code and the com.apple.iTunes namespace will appear inside IMetaData.AdditionalFields with its bare name (e.g. if the file contains ----:com.apple.iTunes:MY_CUSTOM_FIELD, the corresponding AdditionalFields key will read "MY_CUSTOM_FIELD")

Any non-standard field persisted using the ---- field code and any other namespace will appear inside IMetaData.AdditionalFields with its complete name (e.g. if the file contains ----:my.namespace:MY_CUSTOM_FIELD, the corresponding AdditionalFields key will read "----:my.namespace:MY_CUSTOM_FIELD")

How does ATL handle them at write time ?

General rule

When the field is mapped to a standard ATL field, it is handled by the library. No extra processing is required.

When the metadata container has a "wildcard" field type that can host custom fields (e.g. TXXX for ID3v2.4), ATL uses it to write non-standard fields.

If not, the field is ignored and a warning message will be logged to the ATL logger.

Specifics

For any given input field with <name> and <value> stored into AdditionalFields for writing :

ID3v2 / TXXX

Any field that is outside predefined standards is converted into a TXXX field, using the following convention :

• ID : TXXX
• Value : <name> \0 <value> (where, according to specs, <name> is the Description and <value> is the Value)

ID3v2 / GEOB (v4.12+)

Any field that is provided with a key in the form of GEOB.<something> is converted into a GEOB field, using the following convention :

• ID : GEOB
• Text encoding : ISO-8859-1 (hardcoded for now)
• MIME type : application/octet-stream (hardcoded for now)
• Filename : empty (no value; hardcoded for now)
• Content description : <something> (NB : <name> has the form GEOB.<something>)
• Encapsulated object: <value>

MP4, M4A, M4B

• If <name> starts with WM/, the field is part of the specific Microsoft Xtra atom and is written there;
• If <name> is 4 characters or shorter, the field will be persisted as a standard atom;
• If <name> is longer than 4 characters
  • If you provide just a bare name (e.g. "MY_CUSTOM_FIELD"), it will be persisted as a ---- custom atom, using the com.apple.iTunes namespace
  • If you provide a namespace using the : separator (e.g. "my.namespace:MY_CUSTOM_FIELD" or "----:my.namespace:MY_CUSTOM_FIELD"), it will be persisted as a ---- custom atom, using the namespace you provided

AIFF

Any field with a <name> longer than 4 characters is ignored.

TwinVQ

Any field with a <name> longer than 4 characters is ignored.