---

QuickTime Metadata Enhancements and API

QuickTime 7 introduces a new extensible metadata storage format that allows more flexible and efficient storage of metadata, including encapsulated storage of metadata in native format (without translating to and from a defined QuickTime format). For developers, this means that you can now write cleaner, more generic code that enables you to look at, for example, all the metadata in a QuickTime or iTunes music track using just a single function call.

Metadata, of course, is information about a file, track, or media, such as the white balance used to create a photographic image or the artist, album, and title of an MP3 track. Traditionally, metadata information is stored in QuickTime user data items or in ancilliary tracks in a movie. For example, copyright information is normally stored in a ’@cpy’ user data item, while cover art for an AAC audio track is normally stored in a track that is not displayed by all applications.

The new metadata enhancements in QuickTime 7 allow you to access both old (QuickTime) and new (iTunes) formats. The new metadata storage format is intended as a replacement for QuickTime user data, which was limited in features and robustness. Specifically, the metadata enhancements introduced in QuickTime 7 provide the following capabilities:

• The ability to assign data types to any metadata that you place into the new storage format.

• The ability to assign locale information––for example, a particular language or country––to the format.

• The ability to use a more descriptive key in the storage format––for example, a reverse DNS format, such as com.apple.quicktime.mov.

The new metadata format allows storage of data that is not possible in user data items, without extending the list of item types exhaustively, and allows labeling of metadata unambiguously, rather than as data in an undisplayed media track. It also permits inclusion of metadata that is always stored external to the movie, even when the movie is flattened (saved as self-contained).

In this section:

How It Works
Advantages of the New Metadata Format

How It Works

Metadata is encapsulated in an opaque container and accessed using a QTMetDataRef. A QTMetaDataRef represents a metadata repository consisting of one or more native metadata containers. The QuickTime metadata API supports unified access to and management of these containers.

Each container consists of some number of metadata items. Metadata items correspond to individually labeled values with characteristics such as keys, data types, locale information, and so on. Note that what QuickTime calls items are sometimes referred to as attributes or properties in other metadata systems.

You address each container by its storage format (kQTMetaDataStorageFormat). Initially, there is support for classic QuickTime user data items, iTunes metadata, and a richer QuickTime metadata container format. A QTMetaDataRef may have one or all of these. No direct access to the native storage containers is provided.

QTMetaDataRefs may be associated with a movie, track or media. This parallels user data atoms usage but provides access to other kinds of metadata storage at those levels.

A metadata item is assigned a runtime identifier (QTMetaDataItem) that along with the QTMetaDataRef identifies the particular item (and value) across all native containers managed by the QTMetaDataRef.

Each item is addressed by a key, or label. The key is not necessarily unique within its container, as it is possible to have multiple items with the same key (for example, multiple author items). Functions exist to enumerate all items or only items with a particular key.

Because a QTMetaDataRef may provide access to different native metadata containers with differing key structures—a four-char-code for one, a string for another, and so on—the key structure is also specified. A QTMetaDataKeyFormat indicates the key structure to functions that take keys. This also supports container formats that allow multiple key structures or multiple versions of key structures.

To allow unified access across disparate containers, you can specify a wildcard storage format. This can be used for operations such as searches across container formats. A special key format called kQTMetaDataKeyFormatCommon indicates one of a set of common keys that can be handled by multiple native containers (for example, copyright).

Both modes of operation are illustrated in Figure 2-37.

Advantages of the New Metadata Format

The QuickTime metadata format is inherently extensible. Instead of a set of structures and enumerated parameters, the metadata API uses a set of properties that can be enumerated, and whose characteristics can be discovered, dynamically at runtime. This is analogous to the QuickTime component property function in that you first get the property info, such as its size and format, and then you allocate the appropriate container or structure to get or set the actual property.

The new QuickTime metadata format and API consist of the following structures, enumerations, and functions, grouped in sections followed by the specific functions:

• “Metadata Format Constants”

• “Metadata Property IDs”

• “Metadata Key Constants”

• “Metadata Error Codes”

• QTCopyMovieMetaData

• QTCopyTrackMetaData

• QTCopyMediaMetaData

• QTMetaDataAddItem

• QTMetaDataGetItemCount

• QTMetaDataGetItemProperty

• QTMetaDataGetItemPropertyInfo

• QTMetaDataGetItemValue

• QTMetaDataGetNextItem

• QTMetaDataGetProperty

• QTMetaDataGetPropertyInfo

• QTMetaDataRetain

• QTMetaDataRelease

• QTMetaDataRemoveItem

• QTMetaDataRemoveItemsWithKey

• QTMetaDataSetItem

• QTMetaDataSetItemProperty

• QTMetaDataSetProperty

---