CMFormatDescription Reference

This document describes the API for creating and manipulating CMFormatDescription objects.

CMFormatDescriptions are immutable Core Foundation objects that describe media data of various types, including audio, video, and muxed media data. There are two types of API: media-type-agnostic APIs (supported by all CMFormatDescriptions) and media-type-specific APIs. The media-type-agnostic APIs are prefixed with CMFormatDescription, and the media-type-specific APIs are prefixed with CMAudioFormatDescription, CMVideoFormatDescription, and so on.

Parameters

desc

CMFormatDescription being interrogated.

extensionKey

Key of extension to be returned. Cannot be NULL.

Return Value

The specified extension of the CMFormatDescription. May be NULL.

Discussion

If the named extension does not exist, NULL is returned. The extension is always a valid
property list object. This means that it will be either a CFNumber, CFString, CFBoolean,
CFArray, CFDictionary, CFDate, or CFData. If it is a CFDictionary, the keys will all be
CFStrings. The returned extension is not retained by this call, so it is only valid as
long as the CMFormatDescription is valid. Clients are required to retain it if they
need to keep it longer.

Declaration

Parameters

desc

CMFormatDescription being interrogated

Return Value

An immutable dictionary containing all the extensions of the CMFormatDescription. May be NULL.

Discussion

If there are no extensions, NULL is returned. Extensions dictionaries are valid property list objects. This means that dictionary keys are all CFStrings, and the values are all either
CFNumber, CFString, CFBoolean, CFArray, CFDictionary, CFDate, or CFData. The returned dictionary is not retained by this call, so clients are required to retain it if they need to keep it longer.

Declaration

Parameters

desc

CMFormatDescription being interrogated

Return Value

Four-character code identifying the media subtype of the CMFormatDescription.

Discussion

The media subtype is defined in a media-specific way. For audio streams, the media subtype is the asbd.mFormatID. For video streams, the media subtype is the video codec type. For muxed streams, it is the format of the muxed stream.

For example, 'aac ' is returned for a description of an AAC audio stream, 'avc1' is returned for a description of an H.264 video stream, and 'mp2t' is returned for a description of an MPEG-2 transport (muxed) stream. If a particular type of media stream does not have subtypes, this API may return 0.

Return Value

A result code. See “Result Codes”

Discussion

The ASBD is required, the channel layout is optional, and the magic cookie is required
for some compression formats (and must be NULL for all others). The caller owns the
returned CMFormatDescription, and must release it when done with it. The ASBD,
magic cookie, channel layout, and extensions are all copied (the extensions are
deep-copied). The caller can deallocate them or re-use them after making this call.

Parameters

Pointer to variable that will be written with the results that represent the parts that are equal. Can be NULL.

Return Value

The result of the comparison. True if all parts in which the caller is interested are equal.
False if any of the parts in which the caller is interested are not equal.

Discussion

Bits in equalityMask specify the caller's interest in the equality of various parts of the descriptions.
Bits set and returned in equalityMaskOut represent the subset of those parts that are equal.
If there is any sort of error that prevents the comparison from occurring, false will be returned, and
all bits in equalityMaskOut will be cleared. If you pass kCMAudioFormatDescriptionMask_All in equalityMask,
and NULL for equalityMaskOut, this API is equivalent to CFEqual(desc1, desc2).

Parameters

Pointer to variable that will be written with the size of the layout. Can be NULL.

Return Value

A read-only pointer to the AudioChannelLayout inside the audio format description.

Discussion

See CoreAudioTypes.h for the definition of AudioChannelLayout.
AudioChannelLayouts are optional; this API will return NULL if
one does not exist. This API is specific to audio format
descriptions, and will return NULL if called with a non-audio format description.

Parameters

Pointer to variable that will be written with the size of the formatList.

Return Value

A read-only pointer to the array of AudioFormatListItem structs inside the audio format description.

Discussion

This property is analogous to kAudioFormatProperty_FormatList (See AudioFormat.h) and follows
its conventions. Namely, formats are returned in order from the most to least “rich”, with
channel count taking the highest precedence followed by sample rate.
This API is specific to audio format descriptions, and will return NULL if called with a non-audio
format description.

Parameters

Pointer to variable that will be written with the size of the cookie. Can be NULL.

Return Value

A read-only pointer to the magic cookie inside the audio format description.

Discussion

The magic cookie is a completely opaque piece of data, written and read only by
the codec itself. A magic cookie is only present for codecs that require it;
this API will return NULL if one does not exist. This API is specific to audio
format descriptions, and will return NULL if called with a non-audio format
description.

Parameters

desc

CMFormatDescription being interrogated.

Return Value

A read-only pointer to the appropriate AudioFormatListItem inside the audio format description.

Discussion

This property returns a pointer to the most compatible AudioFormatListItem in the kAudioFormatProperty_FormatList
(see AudioFormat.h). This API is specific to audio format descriptions, and will return NULL if called
with a non-audio format description.

Parameters

desc

CMFormatDescription being interrogated.

Return Value

A read-only pointer to the appropriate AudioFormatListItem inside the audio format description.

Discussion

This property performs validation on the formats represented by the audio in the description. It
finds the first AudioFormatListItem for which the current system has a valid decoder.
This API is specific to audio format descriptions, and will return NULL if called with a non-audio
format description. It may also return NULL if there is no suitable decoder available on the
current system for this audio format.

Return Value

A result code. Returns noErr if successful.

Discussion

The caller owns the returned CMFormatDescription, and must release it when done with it. All input parameters
are copied (the extensions are deep-copied). The caller can deallocate them or re-use them after making this call.

where extensions is a CFDictionary of attachments to image buffer with keys specified by
CMVideoFormatDescriptionGetExtensionKeysCommonWithImageBuffers, and also kCMFormatDescriptionExtension_BytesPerRow if applicable.

Parameters

videoDesc

CMVideoFormatDescription being interrogated.

originIsAtTopLeft

Pass true if the CGRect will be used in an environment
where (0,0) is at the top-left corner of an enclosing rectangle
and y coordinates increase as you go down.
Pass false if the CGRect will be used in an environment
where (0,0) is at the bottom-left corner of an enclosing rectangle
and y coordinates increase as you go up.

Discussion

The clean aperture is a rectangle that defines the portion of the encoded pixel dimensions
that represents image data valid for display.

Declaration

Discussion

When specifying a CMFormatDescription for a CMSampleBuffer, the format description must
be consistent with formatting information attached to the CVImageBuffer. The width, height,
and codecType must match (for CVPixelBuffers the codec type is given by
CVPixelBufferGetPixelFormatType(pixelBuffer); for other CVImageBuffers, the codecType must be 0).
The format description extensions must match the image buffer attachments for all the keys in the
list returned by this function (if absent in either they must be absent in both).
Currently, the list is:

Parameters

Return Value

Discussion

This function uses the keys returned by CMVideoFormatDescriptionGetExtensionKeysCommonWithImageBuffers
to compare the extensions of the given format description to the attachments of the
given image buffer (if an attachment is absent in either it must be absent in both).
It also checks kCMFormatDescriptionExtension_BytesPerRow against CVPixelBufferGetBytesPerRow, if applicable.

Parameters

allocator

CFAllocator to be used. Pass NULL or kCFAllocatorDefault to use the default allocator.

muxType

Type of the muxed stream (e.g. kCMMuxedStreamType_MPEG2Transport for MPEG-2 transport stream). This is the media subtype, and will be returned if you subsequently call CMFormatDescriptionGetMediaSubType
(or CMMuxedFormatDescriptionGetStreamType).

Return Value

A result code. Returns noErr if successful.

Discussion

A muxed format description does not know the formats of the sub-streams within the muxed stream.
That information will only be discoverable by the demuxer software (or other software which understands
the details of the muxed bitstream) which will need to produce separate format descriptions for each of
its output streams. The caller owns the returned CMFormatDescription, and must release it when done
with it. All input parameters are copied (the extensions are deep-copied). The caller can deallocate
them or re-use them after making this call.

Parameters

Local Id identifying the key associated with the metadata description.

Return Value

A new dictionary containing the key specified by the localKeyID, or NULL if there is no key corresponding to the localKeyID.

Discussion

When writing a metadata track to a QuickTime movie, you can store many different kinds of metadata in one track. The format description for the track describes all of the kinds of metadata that might be present in that track. And each kind of metadata has an id assigned to it which is unique from the others in the group. So when individual samples of metadata are written (or read back later), they don't contain their full description, instead they just contain the unique id (called the local id) that was assigned to them. For instance, GPS might be local id 1, and face data might be local id 2. When someone pulls such a sample from a movie and wants to do a reverse lookup, they can call CMMetadataFormatDescriptionGetKeyWithLocalID, using the local id they've got, to get the Key associated with this metadata.

Parameters

desc

FormatDescription being interrogated.

originIsAtTopLeft

Pass true if the CGRect will be used in an environment
where (0,0) is at the top-left corner of an enclosing rectangle
and y coordinates increase as you go down.
Pass false if the CGRect will be used in an environment
where (0,0) is at the bottom-left corner of an enclosing rectangle
and y coordinates increase as you go up.

heightOfTextTrack

If originIsAtTopLeft is false, pass the height of the enclosing text track or destination.
This value will be used to properly compute the default text box for the given origin. Ignored if originIsAtTopLeft is true.

outDefaultTextBox

On output, receives the default text box.

Return Value

A result code. Returns noErr if successful.

Discussion

Within a text track, text is rendered within a text box. There is a default text box set, which can be over-ridden by a sample.

Return Value

A result code. Returns noErr if successful.

Discussion

The caller owns the returned CMFormatDescription, and must release it when done with it. All input parameters
are copied (the extensions are deep-copied). The caller can deallocate them or re-use them after making this call.