CMSampleBuffer Reference

This document describes the API you use to create and manipulate the CMSampleBuffer opaque type.

CMSampleBuffers are Core Foundation objects containing zero or more compressed (or uncompressed) samples of a particular media type (audio, video, muxed, etc), that are used to move media sample data through the media system. A CMSampleBuffer can contain:

A CMBlockBuffer of one or more media samples, or

A CVImageBuffer, a reference to the format description for the stream of CMSampleBuffers, size and timing information for each of the contained media samples, and both buffer-level and sample-level attachments.

A sample buffer can contain both sample-level and buffer-level attachments. Sample-level attachments are associated with each individual sample (frame) in a buffer and include information such as timestamps and video frame dependencies. You can read and write sample-level attachments using the CMSampleBufferGetSampleAttachmentsArray function. Buffer-level attachments provide information about the buffer as a whole, such as playback speed and actions to be performed upon consuming the buffer. You can read and write buffer-level attachments using the APIs described in CMAttachment Reference and the keys listed under Sample Buffer Attachment Keys.

It is possible for a CMSampleBuffer to describe samples it does not yet contain. For example, some media services may have access to sample size, timing and format information before the data is read. Such services may create CMSampleBuffers with that information and insert them into queues early, and attach (or fill) the CMBlockBuffers of media data later, when the data becomes ready. To this end, CMSampleBuffers have the concept of data-readiness, which can be tested, set, forced to become ready “now" and so on. It is also possible for a CMSampleBuffer to contain nothing but a special buffer-level attachment that describes a media stream event (for example, "discontinuity: drain and reset decoder before processing the next CMSampleBuffer”). Such a special attachment can also be attached to regular CMSampleBuffers (i.e. that contain media sample data), and if so, the event it describes is defined to occur after the samples in that CMSampleBuffer.

Parameters

allocator

The allocator to use for allocating the CMSampleBuffer object.
Pass kCFAllocatorDefault to use the default allocator.

dataBuffer

CMBlockBuffer for the media data. This can be NULL, a CMBlockBuffer with no backing memory, a CMBlockBuffer with backing memory but no data yet, or a CMBlockBuffer that already contains the media data. If CMBlockBuffer contains the media data, dataReady should be true.

dataReady

Indicates whether or not the BlockBuffer already contains the media data.

makeDataReadyCallback

Callback that CMSampleBufferMakeDataReady should call to make the
data ready. Can be NULL.

Return Value

Discussion

Provides an optimization over CMSampleBufferCreate() when the caller already has packetDescriptions for
the audio data. This routine will use the packetDescriptions to create the sizing and timing arrays required
to make the sample buffer if necessary.

Return Value

Discussion

The system will create temporary sample buffers for individual samples. Each sample buffer will refer to the sample data and containing its timing, size and attachments.
The callback function may retain these sample buffers if desired. If the callback function returns an error, iteration will stop immediately and function returns the the error received from the callback. The function will return kCMSampleBufferError_CannotSubdivide error if there are no sample sizes in the provided sample buffer. This will happen, for example, if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where the channel values for a single sample are scattered through the buffer).

Parameters

allocator

The allocator to use for allocating the CMSampleBuffer object.
Pass kCFAllocatorDefault to use the default allocator.

dataBuffer

CMBlockBuffer for the media data. This can be NULL, a CMBlockBuffer with
no backing memory, a CMBlockBuffer with backing memory but no data yet,
or a CMBlockBuffer that already contains the media data. If CMBlockBuffer contains the media data, dataReady should be true. The Boolean dataReady should also be true if the dataBuffer is Null and numSamples is 0.

dataReady

Indicates whether or not the BlockBuffer already contains the media data

makeDataReadyCallback

Callback that CMSampleBufferMakeDataReady should call to make the
data ready. Can be NULL.

makeDataReadyRefcon

Refcon CMSampleBufferMakeDataReady should pass to the callback.

formatDescription

A description of the media data's format. Can be NULL.

numSamples

Number of samples in the CMSampleBuffer. Can be zero.

numSampleTimingEntries

Number of entries in sampleTimingArray. Must be 0, 1, or numSamples.

sampleTimingArray

Array of CMSampleTimingInfo structs, one struct per sample.
If all samples have the same duration and are in presentation order, you can pass a single
CMSampleTimingInfo struct with duration set to the duration of one sample, presentationTimeStamp
set to the presentation time of the numerically earliest sample, and decodeTimeStamp set to
kCMTimeInvalid. Behavior is undefined if samples in a CMSampleBuffer (or even in multiple
buffers in the same stream) have the same presentationTimeStamp. Can be NULL.

numSampleSizeEntries

Number of entries in sampleSizeArray. Must be 0, 1, or numSamples.

sampleSizeArray

Array of size entries, one entry per sample. If all samples have the
same size, you can pass a single size entry containing the size of one sample. Can be NULL. Must be
NULL if the samples are non-contiguous in the buffer (eg. non-interleaved audio, where the channel
values for a single sample are scattered through the buffer).

sBufOut

On output, points to the newly created CMSampleBuffer.

Return Value

Discussion

Array parameters (sampleSizeArray, sampleTimingArray) should have only one element if that same element applies to all samples. All parameters are copied. On return, the caller can release them, free them or reuse them. On return, the caller owns the returned CMSampleBuffer, and must release it when done with it.

Return Value

Discussion

The copy is shallow: scalar properties (sizes and timing) are copied directly,
the data buffer and format description are retained, and the attachments that can be propagated are retained by the copy's dictionary.
If sbuf's data is not ready, the copy will be set to track its readiness.

Parameters

The allocator to use for allocating the CMSampleBuffer object.
Pass kCFAllocatorDefault to use the default allocator.

originalSBuf

CMSampleBuffer containing the original samples.

numSampleTimingEntries

Number of entries in sampleTimingArray. Must be 0, 1, or numSamples in original sampleBuffer.

sampleTimingArray

Array of CMSampleTimingInfo structs, one struct per sample.
If all samples have the same duration and are in presentation order, you can pass a single
CMSampleTimingInfo struct with duration set to the duration of one sample, presentationTimeStamp
set to the presentation time of the numerically earliest sample, and decodeTimeStamp set to
kCMTimeInvalid. Behavior is undefined if samples in a CMSampleBuffer (or even in multiple
buffers in the same stream) have the same presentationTimeStamp. Can be NULL.

sBufCopyOut

On output, points to the newly created copy of CMSampleBuffer.

Return Value

Discussion

This emulates CMSampleBufferCreateCopy, but changes the timing.
Array parameters (sampleTimingArray) should have only one element if that same
element applies to all samples. All parameters are copied; on return, the caller can release them,
free them or reuse them. Any outputPresentationTimestamp that has been set on the original Buffer
will not be copied because it is no longer relevant. On return, the caller owns the returned
CMSampleBuffer, and must release it when done with it.

Parameters

allocator

The allocator to use for allocating the CMSampleBuffer object.
Pass kCFAllocatorDefault to use the default allocator.

imageBuffer

CVImageBuffer for the media data. This can be a CVImageBuffer whose content
has not yet been rendered, or a CVImageBuffer that already contains the media data
(in which case dataReady should be true). May not be NULL.

dataReady

Indicates whether or not the CVImageBuffer already contains the media data.

A description of the media data's format. See discussion above for constraints.
May not be NULL.

sampleTiming

A CMSampleTimingInfo struct that provides the timing information for the media
represented by the CVImageBuffer.

sBufOut

On output, points to the newly created CMSampleBuffer that contains a CVImageBuffer.

Return Value

A result code. See Sample Buffer Result Codes

Discussion

Unlike a CMBlockBuffer which can reference many samples, a CVImageBuffer is defined to
reference only one sample; therefore this routine has fewer parameters than
CMSampleBufferCreate.
Sample timing information, which is a vector for CMSampleBufferCreate,
consists of only one value for this routine.
The concept of sample size does not apply to CVImageBuffers. As such, CMSampleBufferGetSampleSizeArray
will return kCMSampleBufferError_BufferHasNoSampleSizes, and CMSampleBufferGetSampleSize
will return 0. Because CVImageBuffers hold visual data, the format description provided is a CMVideoFormatDescription. The format description must be consistent with the attributes and 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 byCMVideoFormatDescriptionGetExtensionKeysCommonWithImageBuffers. if absent in either they must be absent in both.

Import Statement

Availability

Creates an AudioBufferList containing the data from the CMSampleBuffer,
and a CMBlockBuffer which references (and manages the lifetime of) the
data in that AudioBufferList. The data may or may not be copied,
depending on the contiguity and 16-byte alignment of the CMSampleBuffer's
data. The buffers placed in the AudioBufferList are guaranteed to be contiguous.
The buffers in the AudioBufferList will be 16-byte-aligned if
kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment is passed in.

Import Statement

Availability

Creates an array of AudioStreamPacketDescriptions for the
variable bytes per packet or variable frames per packet
audio data in the provided CMSampleBuffer. Constant bit rate,
constant frames-per-packet audio yields a return value of noErr
and no packet descriptions. This API is specific to audio format
sample buffers, and will return kCMSampleBufferError_InvalidMediaTypeForOperation
if called with a non-audio sample buffer.

Import Statement

Availability

Retrieves a pointer to (and size of) a constant array of
AudioStreamPacketDescriptions for the variable bytes per packet or variable frames per packet audio data in the provided CMSampleBuffer. The pointer will remain valid as long as the sbuf continues to be retained.
Constant bit rate, constant frames-per-packet audio yields a return value of noErr and no packet descriptions. This API is specific to audio format sample buffers, and will return
kCMSampleBufferError_InvalidMediaTypeForOperation if called
with a non-audio sample buffer.

Declaration

Parameters

sbuf

CMSampleBuffer being interrogated .

Return Value

The duration of the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

Discussion

If the buffer contains out-of-presentation-order samples, any gaps in the presentation timeline are not represented in the returned duration.
The returned duration is simply the sum of all the individual sample durations.

Declaration

Parameters

sbuf

CMSampleBuffer being interrogated.

Return Value

The output presentation timestamp of the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

Discussion

The output presentation timestamp is the time at which the decoded, trimmed, stretched
and possibly reversed samples should commence being presented.
If CMSampleBufferGetOutputPresentationTimeStamp has been called to explicitly set the output PTS,
CMSampleBufferGetOutputPresentationTimeStamp returns it.
If not, CMSampleBufferGetOutputPresentationTimeStamp calculates its result as
(PresentationTimeStamp + TrimDurationAtStart)
unless kCMSampleBufferAttachmentKey_Reverse is kCFBooleanTrue, in which case it calculates the result as
(PresentationTimeStamp + Duration - TrimDurationAtEnd).
These are generally correct for un-stretched, un-shifted playback.
For general forward playback in a scaled edit, the OutputPresentationTimeStamp should be set to:
((PresentationTimeStamp + TrimDurationAtStart - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.
For general reversed playback:
((PresentationTimeStamp + Duration - TrimDurationAtEnd - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.

Return Value

Discussion

If only one CMSampleTimingInfo struct is returned, it applies to all samples in the buffer.
See documentation of CMSampleTimingInfo for details of how a single CMSampleTimingInfo struct can apply to multiple samples.
The timingArrayOut must be allocated by the caller, and the number of entries allocated must be passed in timingArrayEntries.
If timingArrayOut is NULL, timingArrayEntriesNeededOut will return the required number of entries. Similarly,
if *timingArrayEntriesNeededOut is too small, kCMSampleBufferError_ArrayTooSmallwill be returned, and timingArrayEntriesNeededOut will return the required number of entries. In either case, the caller can then make an appropriately-sized timingArrayOut and call again.
For example, the caller might pass the address of a CMSampleTimingInfo struct on the stack (as timingArrayOut), and 1 as
timingArrayEntries. If all samples are describable with a single CMSampleTimingInfo struct (or there is only one sample in the CMSampleBuffer), this call will succeed. If not, it will fail, and will return the number of entries required in timingArrayEntriesNeededOut. Only in this case will the caller actually need to allocate an array.
If there is no timingInfo in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned, and *timingArrayEntriesNeededOut will be set to 0.

Declaration

Parameters

sbuf

CMSampleBuffer being interrogated.

Return Value

Numerically earliest sample presentation timestamp in the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

Discussion

For in-presentation-order samples, this is the presentation timestamp of the first sample.
For out-of-presentation-order samples, this is the presentation timestamp of the sample that will be presented first, which is not necessarily the first sample in the buffer.

Parameters

Specifies whether an empty array should be created (if there are no sample attachments yet).

Return Value

A reference to the CMSampleBuffer's immutable array of mutable sample attachments dictionaries (one dictionary per sample in the CMSampleBuffer). NULL is returned if there is an error

Discussion

Attachments can then be added/removed directly by the caller, using Core Foundation APIs. On return, the caller does not
own the returned array of attachments dictionaries, and must retain it if the caller needs to maintain a
reference to it. If there are no sample attachments yet, and createIfNecessary is true, a new CFArray containing N empty
CFMutableDictionaries is returned (where N is the number of samples in the CMSampleBuffer), so that
attachments can be added directly by the caller. If there are no sample attachments yet, and createIfNecessary is
false, NULL is returned. Once the CFArray has been created, subsequent calls will return it, even if there are still
no sample attachments in the array.

Declaration

Parameters

sbuf

CMSampleBuffer being interrogated

sampleIndex

Sample index (0 is first sample in sbuf)

Return Value

Size in bytes of the specified sample in the CMSampleBuffer.
If the sample index is not in the range 0 .. numSamples-1,
a size of 0 will be returned. If there are no sample sizes
in this CMSampleBuffer, a size of 0 will be returned. This will be true, for example,
if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where
the channel values for a single sample are scattered through the buffer),
or if this CMSampleBuffer contains a CVImageBuffer.

Return Value

Discussion

If only one size entry is returned, all samples in the buffer are of this size.
The sizeArrayOut must be allocated by the caller, and the number of entries allocated must be passed in sizeArrayEntries.
If sizeArrayOut is NULL, sizeArrayEntriesNeededOut will return the required number of entries. Similarly, if sizeArrayEntries
is too small, kCMSampleBufferError_ArrayTooSmall will be returned, and sizeArrayEntriesNeededOut will return the required number of entries.
The caller can then make an appropriately-sized sizeArrayOut and call again. For example, the caller might pass the address
of a size_t variable on the stack (as sizeArrayOut), and 1 as sizeArrayEntries. If all samples are the same size (or there
is only one sample in the CMSampleBuffer), this call would succeed. If not, it will fail, and will return the number of
entries required in sizeArrayEntriesNeededOut. Only in this case (multiple samples of different sizes) will the caller
need to allocate an array. 0 entries will be returned if the samples in the buffer are non-contiguous (eg. non-interleaved
audio, where the channel values for a single sample are scattered through the buffer).
If there are no sample sizes in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleSizes will be returned,
and *sizeArrayEntriesNeededOut will be set to 0. This will be true, for example,
if the samples in the buffer are non-contiguous (eg. non-interleaved audio, where
the channel values for a single sample are scattered through the buffer), or if
this CMSampleBuffer contains a CVImageBuffer.

Return Value

Discussion

A sample-specific CMSampleTimingInfo struct will be returned (i.e. with a sample-specific
presentationTimeStamp and decodeTimeStamp), even if a single CMSampleTimingInfo struct was used
during creation to describe all the samples in the buffer. The timingInfo struct must be
allocated by the caller. If the sample index is not in the range 0 .. numSamples-1,
kCMSampleBufferError_SampleIndexOutOfRangewill be returned. If there is no timingInfo
in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned.

Return Value

Discussion

If only one CMSampleTimingInfo struct is returned, it applies to all samples in the buffer.
See documentation of CMSampleTimingInfo for details of how a single CMSampleTimingInfo struct can apply to multiple samples.
The timingArrayOut must be allocated by the caller, and the number of entries allocated must be passed in timingArrayEntries.
If timingArrayOut is NULL, timingArrayEntriesNeededOut will return the required number of entries. Similarly,
if *timingArrayEntriesNeededOut is too small, kCMSampleBufferError_ArrayTooSmallwill be returned, and timingArrayEntriesNeededOut
will return the required number of entries. In either case, the caller can then make an appropriately-sized timingArrayOut and call again.
For example, the caller might pass the address of a CMSampleTimingInfo struct on the stack (as timingArrayOut), and 1 as timingArrayEntries. If all samples are describable with a single CMSampleTimingInfo struct (or there is only one sample
in the CMSampleBuffer), this call will succeed. If not, it will fail, and will return the number of entries required in
timingArrayEntriesNeededOut. Only in this case will the caller actually need to allocate an array.
If there is no timingInfo in this CMSampleBuffer, kCMSampleBufferError_BufferHasNoSampleTimingInfo will be returned, and timingArrayEntriesNeededOut will be set to 0.

Parameters

Return Value

Discussion

An invalid sample buffer cannot be used -- all accessors will return kCMSampleBufferError_Invalidated
It is not a good idea to do this to a sample buffer that another module may be accessing concurrently.
Example of use: the invalidation callback could cancel pending I/O.

Parameters

Return Value

Discussion

The CMSampleBufferMakeDataReadyCallback is passed in by the client during creation. It must return 0 if successful, and in that case, CMSampleBufferMakeDataReady will set the data readiness of the CMSampleBuffer to true.

Example of usage: when it is time to actually use the data.

Example of callback routine: a routine to force a scheduled read to complete.

If the CMSampleBuffer is not ready, and there is no CMSampleBufferMakeDataReadyCallback to call, kCMSampleBufferError_BufferNotReady will be returned. Similarly, if the CMSampleBuffer is not ready, and the CMSampleBufferMakeDataReadyCallback fails and returns an error, kCMSampleBufferError_BufferNotReady will be returned.

Parameters

Return Value

Discussion

If successful, this operation retains the dataBuffer. This allows the caller to release the dataBuffer after calling this API, if it has no further need to reference it. This is a write-once operation; it will fail if the CMSampleBuffer already has a dataBuffer. This API allows a CMSampleBuffer to exist, with timing and format information, before the associated data shows up.

Example of usage: Some media services may have access to sample size, timing, and format information before the data is read. Such services may create CMSampleBuffers with that information and insert them into queues early, and use this API to attach the CMBlockBuffers later, when the data becomes ready.

Import Statement

import CoreMedia

Availability

Creates a CMBlockBuffer containing a copy of the data from the AudioBufferList. Sets that copy as the CMSampleBuffer's data buffer. The resulting buffer(s) in the
sample buffer will be 16-byte-aligned if
kCMSampleBufferFlag_AudioBufferList_Assure16ByteAlignment is passed in.

Return Value

Discussion

The output presentation timestamp is the time at which the decoded, trimmed, stretched and possibly reversed samples should commence being presented.
By default, this is calculated by calling CMSampleBufferGetOutputPresentationTimeStamp.
Call CMSampleBufferSetOutputPresentationTimeStamp to explicitly set the value for CMSampleBufferGetOutputPresentationTimeStamp to return.

For general forward playback in a scaled edit, the OutputPresentationTimeStamp should be set to:

Parameters

Return Value

Discussion

After calling this API, if CMSampleBufferDataIsReady(sbuf) is called, it will return sbufToTrack's data readiness. If CMSampleBufferMakeDataReady(sbuf) is called, it will make sbufToTrack data ready.

Example of use: This allows bursting a multi-sample CMSampleBuffer into single-sample CMSampleBuffers before the data is ready. The single-sample CMSampleBuffers will all track the multi-sample CMSampleBuffer's data readiness.

The first sample buffer following the discontinuity should have a kCMSampleBufferAttachmentKey_ResumeOutput attachment whose value is the same number as the resume tag announced in this notification. The consumer should discard output data until it receives this sample buffer. If multiple notifications of this type are received, the last one indicates the resume tag.

Available in iOS 4.0 and later.

kCMSampleBufferConduitNotification_ResetOutput

kCMSampleBufferConduitNotification_ResetOutput

Posted on a conduit of sample buffers to request invalidation of pending output data.

Available in iOS 4.0 and later.

kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged

kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged

Posted on a conduit of video sample buffers to report information about the range of upcoming output presentation timestamps.

This information can be important for frame-reordered video and for certain types of decoding where samples are transmitted in a different order from the order they will be displayed. If you need to process frames in presentation order, you can use this information to ensure that you do not process a frame too early (that is, when there are upcoming frames that will have earlier presentation timestamps than a frame to be processed).

Indicates that the presentation timestamps of upcoming output samples may overlap those of samples queued for output (type CFBoolean).

This key is always present in the userInfo dictionary for the kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged notification. If its value is kCFBooleanTrue, there is a possibility that upcoming frames may have earlier presentation timestamps than the frames previously provided to the conduit, and the dictionary also contains one or both of the kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS or kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS keys providing further information. If its value is kCFBooleanFalse, there is no such possibility.

Constants

A sync sample, also known as a key frame or IDR (Instantaneous Decoding Refresh), can be decoded without requiring any previous samples to have been decoded. Samples following a sync sample also do not require samples prior to the sync sample to have been decoded. Samples are assumed to be sync samples by default — set the value for this key to kCFBooleanTrue for samples which should not be treated as sync samples.

A partial sync sample can be decoded without requiring any previous samples to have been decoded. Samples following two consecutive partial sync samples also do not require samples prior to the pair to have been decoded. To treat a sample as a partial sync sample, set a value of kCFBooleanTrue for both this key and the kCMSampleAttachmentKey_NotSync key.

This attachment is read from and written to media files.

Available in iOS 4.0 and later.

kCMSampleAttachmentKey_HasRedundantCoding

kCMSampleAttachmentKey_HasRedundantCoding

Indicates whether the sample has redundant coding (type CFBoolean).

This key has no default value. If this key is not present, redundant coding information for the sample is unknown.

Available in iOS 4.0 and later.

kCMSampleAttachmentKey_IsDependedOnByOthers

kCMSampleAttachmentKey_IsDependedOnByOthers

Indicates whether other samples depend on this sample for decoding (type CFBoolean).

This key has no default value. If this key is not present, dependency information for the sample is unknown. If this key is present and its value is kCFBooleanFalse, the frame is considered droppable.

This attachment is read from and written to media files.

Available in iOS 4.0 and later.

kCMSampleAttachmentKey_DependsOnOthers

kCMSampleAttachmentKey_DependsOnOthers

Indicates whether the sample depends on other samples for decoding (type CFBoolean).

This key has no default value. If this key is not present, dependency information for the sample is unknown. A value of kCFBooleanFalse indicates that the sample does not depend on other samples (for example, an I frame). A value of kCFBooleanTrue indicates that the sample does depend on other samples (for example, a P or B frame).

This attachment is read from and written to media files.

Available in iOS 4.0 and later.

kCMSampleAttachmentKey_EarlierDisplayTimesAllowed

kCMSampleAttachmentKey_EarlierDisplayTimesAllowed

Indicates whether later samples may have earlier display times (type CFBoolean).

This key has no default value. If this key is not present, this information for the sample is unknown.

If this key is present, the sample should be displayed as soon as possible rather than according to its presentation timestamp. Use this attachment at run time to request this behavior from a display pipeline such as the AVSampleBufferDisplayLayer class.

This attachment is not written to media files.

Available in iOS 4.0 and later.

kCMSampleAttachmentKey_DoNotDisplay

kCMSampleAttachmentKey_DoNotDisplay

Indicates whether the sample should be decoded but not displayed (type CFBoolean, default false).

This attachment is used at run time to indicate that a sample precedes a break in decode sequence and that it is appropriate to drain the decoder after decoding this sample.

This attachment is not written to media files.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_PostNotificationWhenConsumed

kCMSampleBufferAttachmentKey_PostNotificationWhenConsumed

If present, indicates that decode pipelines should post a notification when consuming the sample buffer(type CFDictionary).

This attachment is used at run time to request that a decode pipeline post a kCMSampleBufferConsumerNotification_BufferConsumed notification when this sample buffer is consumed. The value for this key is used as the userInfo dictionary in the notification.

This attachment is not written to media files.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_ResumeOutput

kCMSampleBufferAttachmentKey_ResumeOutput

If present, indicates that output should be resumed following a discontinuity CFBoolean, default false).

For example, during gapless playback of a list of songs, this attachment marks the first buffer from the next song.
If this attachment is on a buffer containing no samples, the first following buffer that contains samples is the
buffer that contains the first samples from the next song. The value of this attachment is a CFTypeRef. This
transition identifier should be unique within a playlist, so each transition in a playlist is uniquely
identifiable. A CFNumberRef counter that increments with each transition is a simple example.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_TrimDurationAtStart

kCMSampleBufferAttachmentKey_TrimDurationAtStart

The duration that should be removed at the beginning of the sample buffer, after decoding.

If this attachment is not present, the trim duration is zero (nothing removed).
This is a CMTime in Core Foundation dictionary format as made by CMTimeCopyAsDictionary;
use CMTimeMakeFromDictionary to convert to CMTime.
In cases where all the output after decoding the sample buffer is to be discarded
(for example, the samples are only being decoded to prime the decoder) the usual convention
is to set kCMSampleBufferAttachmentKey_TrimDurationAtStart to the whole duration
and not to set a kCMSampleBufferAttachmentKey_TrimDurationAtEnd attachment.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_TrimDurationAtEnd

kCMSampleBufferAttachmentKey_TrimDurationAtEnd

The duration that should be removed at the end of the sample buffer, after decoding.

The factor by which the sample buffer's presentation should be accelerated (type CFNumber, default 1.0).

For normal playback the speed multiplier would be 1.0 (which is used if this attachment is not present);
for double-speed playback the speed multiplier would be 2.0, which would halve the output duration.
Speed-multiplication factors take effect after trimming; see CMSampleBufferGetOutputDuration.
Note that this attachment principally provides information about the duration-stretching effect:
by default, it should be implemented by rate conversion, but other attachments may specify richer
stretching operations—for example, scaling without pitch shift, or pitch shift without changing duration.
Sequences of speed-multiplied sample buffers should have explicit time stamps
to clarify when each should be output (see CMSampleBufferSetOutputPresentationTimeStamp).

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_Reverse

kCMSampleBufferAttachmentKey_Reverse

Indicates that the decoded contents of the sample buffer should be reversed (type CFBoolean, default false).

If this attachment is not present, the sample buffer should be played forwards as usual.
Reversal occurs after trimming and speed multipliers.

If a sample buffer enters a buffer queue and the presentation time stamp between the
previous buffer and the buffer with this attachment are discontiguous, handle the
discontinuity by generating silence for the time difference.

The sample buffer's output presentation timestamp indicates when the empty interval begins.
Marker sample buffers with this attachment are used to announce the arrival of empty edits.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_PermanentEmptyMedia

kCMSampleBufferAttachmentKey_PermanentEmptyMedia

Marks the end of the sequence of samples (type CFBoolean, default false).

Marker sample buffers with this attachment in addition to kCMSampleBufferAttachmentKey_EmptyMedia
are used to indicate that no further samples are expected.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_DisplayEmptyMediaImmediately

kCMSampleBufferAttachmentKey_DisplayEmptyMediaImmediately

Tells that the empty marker should be dequeued immediately regardless of its timestamp (type CFBoolean, default false).

Marker sample buffers with this attachment in addition to kCMSampleBufferAttachmentKey_EmptyMedia
are used to tell that the empty sample buffer should be dequeued immediately regardless of its timestamp.
This attachment should only be used with sample buffers with the kCMSampleBufferAttachmentKey_EmptyMedia
attachment.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_EndsPreviousSampleDuration

kCMSampleBufferAttachmentKey_EndsPreviousSampleDuration

Indicates that sample buffer's decode timestamp may be used to define the previous sample buffer's duration (type CFBoolean, default false).

Marker sample buffers with this attachment may be used in situations where sample buffers are transmitted
before their duration is known. In such situations, normally the recipient may use each sample buffer's timestamp
to calculate the duration of the previous sample buffer. The marker sample buffer with this attachment is sent
to provide the timestamp for calculating the final sample buffer's duration.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_SampleReferenceURL

kCMSampleBufferAttachmentKey_SampleReferenceURL

Indicates the URL where the sample data is (type CFURL).

This key is only used for sample buffers representing sample references.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_SampleReferenceByteOffset

kCMSampleBufferAttachmentKey_SampleReferenceByteOffset

Indicates the byte offset at which the sample data begins (type CFNumber).

This key is only used for sample buffers representing sample references. Its value is the byte offset from the beginning of data at the referenced URL to the contiguous sample data.

Available in iOS 4.0 and later.

kCMSampleBufferAttachmentKey_GradualDecoderRefresh

kCMSampleBufferAttachmentKey_GradualDecoderRefresh

Indicates the decoder refresh count (type CFNumber).

Sample buffers with this attachment may be used to identify the audio decoder refresh count.

Available in iOS 4.3 and later.

kCMSampleBufferAttachmentKey_DroppedFrameReason

kCMSampleBufferAttachmentKey_DroppedFrameReason

Indicates the reason the current video frame was dropped (type CFString).

Sample buffers with this attachment contain no image or data buffer. They mark a dropped video
frame. This attachment identifies the reason the frame was dropped. The value for this key is one of the string constants in Sample Buffer Dropped Frame Reasons.

Sample buffers with this attachment contain no image or data buffer. They mark a dropped video
frame. If present, this attachment provides additional information about the reason described by the kCMSampleBufferAttachmentKey_DroppedFrameReason key. The value for this key is one of the string constants in Sample Buffer Dropped Frame Reason Information.

Available in iOS 7.0 and later.

Discussion

To get and set a sample buffer’s buffer-level attachments, use the functions described in CMAttachment Reference.

Constants

A video capture client has indicated
that late video frames should be dropped and the current frame is late. This condition is typically
caused by the client's processing taking too long.

Available in iOS 6.0 and later.

kCMSampleBufferDroppedFrameReason_OutOfBuffers

kCMSampleBufferDroppedFrameReason_OutOfBuffers

The frame was dropped because the module providing frames is out of buffers.

The module providing sample buffers
has run out of source buffers. This condition is typically caused by the client holding onto
buffers for too long and can be alleviated by returning buffers to the provider.

Available in iOS 6.0 and later.

kCMSampleBufferDroppedFrameReason_Discontinuity

kCMSampleBufferDroppedFrameReason_Discontinuity

An unknown number of frames were dropped.

The module providing sample buffers
has experienced a discontinuity, and an unknown number of frames have been lost. This condition is
typically caused by the system being too busy.

Declaration

Constants

kCMSampleBufferDroppedFrameReasonInfo_CameraModeSwitch

kCMSampleBufferDroppedFrameReasonInfo_CameraModeSwitch

A discontinuity was caused by a camera mode switch.

The module providing sample buffers
has experienced a discontinuity due to a camera mode switch. Short discontinuities of this type can occur when the
session is configured for still image capture on some devices.