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 deserialized as a string encoded with ISO-8859-1.

ID3v2 / PRIV (v5.20+)

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

Using specifications vocabulary, AdditionalFields's key contains the Owner identifier and AdditionalFields's value contains the Private data.

NB : The Encapsulated object is deserialized 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 appears inside IMetaData.AdditionalFields with its bare name (e.g. if the file contains ----:com.apple.iTunes:MY_CUSTOM_FIELD, the corresponding AdditionalFields key reads "MY_CUSTOM_FIELD")

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

MP4, M4A, M4B / UUID (v5.21+)

Any field persisted using an uuid node appears inside IMetaData.AdditionalFields with the uuid. prefix followed by its UUID in hexadecimal format (e.g. uuid.BE7ACFCB97A942E89C71999491E3AFAC).

NB : The value of the field is deserialized as a string encoded with UTF-8.

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>, encoded as a string using ISO-8859-1

ID3v2 / PRIV (v5.20+)

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

• ID : PRIV
• Owner identifier : <something> (NB : <name> has the form PRIV.<something>)
• Private data : <value>, encoded as a string using ISO-8859-1

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 is 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 is 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 is persisted as a ---- custom atom, using the namespace you provided

MP4, M4A, M4B / UUID (v5.21+)

Any field that is provided with a key in the form of uuid.<UUID> is converted into an uuid atom, using the following convention :

• UUID : <UUID> (NB : <name> has the form uuid.<UUID> where <UUID> is the hexadecimal representation of a 16-bytes UUID)
• Data : <value>, encoded as a string using UTF-8

AIFF

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

TwinVQ

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