CMSampleBuffer Reference

Derived from
Framework
CoreMedia.framework
Declared in
CMSampleBuffer.h

Overview

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 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.

Functions

CMAudioSampleBufferCreateWithPacketDescriptions

Creates a CMSampleBuffer containing the audio for a given packetDescription instead of the sizing and timing information.

OSStatus CMAudioSampleBufferCreateWithPacketDescriptions (
   CFAllocatorRef allocator,
   CMBlockBufferRef dataBuffer,
   Boolean dataReady,
   CMSampleBufferMakeDataReadyCallback makeDataReadyCallback,
   void *makeDataReadyRefcon,
   CMFormatDescriptionRef formatDescription,
   CMItemCount numSamples,
   CMTime sbufPTS,
   const AudioStreamPacketDescription *packetDescriptions,
   CMSampleBufferRef *sBufOut
);
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.

makeDataReadyRefcon

The reference constant,CMSampleBufferMakeDataReady, that this function should pass to the callback.

formatDescription

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

numSamples

Number of samples in the CMSampleBuffer. Must not be 0.

sbufPTS

Timestamp of the first sample in the buffer. Must be a numeric CMTime.

packetDescriptions

Array of packetDescriptions, one for each of numSamples. May be NULL if the samples are known to have a constant number of frames per packet and a constant size.

sBufOut

On output, points to the newly created CMSampleBuffer.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCallForEachSample

Calls a function for every individual sample in a sample buffer.

OSStatus CMSampleBufferCallForEachSample (
   CMSampleBufferRef sbuf,
   OSStatus (*callback)(CMSampleBufferRef sampleBuffer, CMItemCount index, void *refcon),
   void *refcon
);
Parameters
sbuf

CMSampleBuffer that may contain multiple samples.

refcon

Function to be called for each individual sample.

refcon

Refcon to be passed to the callback function.

Return Value

A result code. See “Result Codes.”

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).

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCopySampleBufferForRange

Creates a CMSampleBuffer containing a range of samples from an existing CMSampleBuffer.

OSStatus CMSampleBufferCopySampleBufferForRange (
   CFAllocatorRef allocator,
   CMSampleBufferRef sbuf,
   CFRange sampleRange,
   CMSampleBufferRef *sBufOut
);
Parameters
allocator

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

sbuf

CMSampleBuffer containing the original samples.

sampleRange

The range of samples to copy from sbuf, where sample 0 is the first sample in the sbuf

sBufOut

On output, points to the newly created CMSampleBuffer.

Return Value

A result code. See “Result Codes”

Discussion

Samples containing non-interleaved audio are currently not supported.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCreate

Creates a CMSampleBuffer.

OSStatus CMSampleBufferCreate (
   CFAllocatorRef allocator,
   CMBlockBufferRef dataBuffer,
   Boolean dataReady,
   CMSampleBufferMakeDataReadyCallback makeDataReadyCallback,
   void *makeDataReadyRefcon,
   CMFormatDescriptionRef formatDescription,
   CMItemCount numSamples,
   CMItemCount numSampleTimingEntries,
   const CMSampleTimingInfo *sampleTimingArray,
   CMItemCount numSampleSizeEntries,
   const size_t *sampleSizeArray,
   CMSampleBufferRef *sBufOut
);
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

A result code. See “Result Codes.”

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.

Example of usage for in-display-order video frames:

  • dataBuffer: contains 7 Motion JPEG frames

  • dataFormatDescription: describes Motion JPEG video

  • dataFormatDescription: describes Motion JPEG video

  • numSamples: 7

  • numSampleTimingEntries: 1

  • sampleTimingArray: one entry = {duration = 1001/30000, presentationTimeStamp = 0/30000, decodeTimeStamp = invalid }

  • numSampleSizeEntries: 7

  • sampleSizeArray: {105840, 104456, 103464, 116460, 100412, 94808, 120400}

Example of usage for video frames in out-of-display-order :

  • dataBuffer: contains 6 H.264 frames in decode order (P2,B0,B1,I5,B3,B4)

  • dataFormatDescription: describes H.264 video

  • numSamples: 6

  • numSampleTimingEntries: 6

  • sampleTimingArray: 6 entries = {

    • {duration = 1001/30000, presentationTimeStamp = 12012/30000, decodeTimeStamp = 10010/30000},

    • {duration = 1001/30000, presentationTimeStamp = 10010/30000, decodeTimeStamp = 11011/30000},

    • {duration = 1001/30000, presentationTimeStamp = 11011/30000, decodeTimeStamp = 12012/30000},

    • {duration = 1001/30000, presentationTimeStamp = 15015/30000, decodeTimeStamp = 13013/30000},

    • {duration = 1001/30000, presentationTimeStamp = 13013/30000, decodeTimeStamp = 14014/30000},

    • {duration = 1001/30000, presentationTimeStamp = 13013/30000, decodeTimeStamp = 14014/30000}}

  • numSampleSizeEntries: 6

  • sampleSizeArray: {10580, 1234, 1364, 75660, 1012, 988}

Example of usage for compressed audio:

  • dataBuffer: contains 24 compressed AAC packets

  • dataFormatDescription: describes 44.1kHz AAC audio

  • numSamples: 24

  • numSampleTimingEntries: 1

  • sampleTimingArray: one entry = {{duration = 1024/44100, presentationTimeStamp = 0/44100, decodeTimeStamp = invalid }}

  • numSampleSizeEntries: 24

  • sampleSizeArray: <up> {191, 183, 208, 213, 202, 206, 209, 206, 204, 192, 202, 277, <li> 282, 240, 209, 194, 193, 197, 196, 198, 168, 199, 171, 194}

Example of usage for uncompressed interleaved audio:

  • dataBuffer: contains 24000 uncompressed interleaved stereo frames, each containing 2 Float32s =

    • {{L,R},

    • {L,R},

    • {L,R}, ...}

  • dataFormatDescription: describes 48kHz Float32 interleaved audio

  • numSamples: 24000

  • numSampleTimingEntries: 1

  • sampleTimingArray: one entry = { {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }}

  • numSampleSizeEntries: 1

  • sampleSizeArray: {8}

Example of usage for uncompressed non-interleaved audio:

  • dataBuffer: contains 24000 uncompressed non-interleaved stereo frames, each containing 2 (non-contiguous) Float32s =

    • {{L,L,L,L,L,...},

    • {R,R,R,R,R,...}}

  • dataFormatDescription: describes 48kHz Float32 non-interleaved audio

  • numSamples: 24000

  • numSampleTimingEntries: 1

  • sampleTimingArray: one entry = {duration = 1/48000, presentationTimeStamp = 0/48000, decodeTimeStamp = invalid }

  • numSampleSizeEntries: 0

  • sampleSizeArray: NULL (because the samples are not contiguous)

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCreateCopy

Creates a copy of a CMSampleBuffer

OSStatus CMSampleBufferCreateCopy (
   CFAllocatorRef allocator,
   CMSampleBufferRef sbuf,
   CMSampleBufferRef *sbufCopyOut
);
Parameters
allocator

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

sbuf

CMSampleBuffer being copied.

sbufCopyOut

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

Return Value

A result code. See “Result Codes”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCreateCopyWithNewTiming

Creates a copy of CMSampleBuffer with new timing information.

OSStatus CMSampleBufferCreateCopyWithNewTiming (
   CFAllocatorRef allocator,
   CMSampleBufferRef originalSBuf,
   CMItemCount numSampleTimingEntries,
   const CMSampleTimingInfo *sampleTimingArray,
   CMSampleBufferRef *sBufCopyOut
);
Parameters
allocator

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

A result code. See “Result Codes”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferCreateForImageBuffer

Creates a CMSampleBuffer that contains a CVImageBuffer instead of a CMBlockBuffer.

OSStatus CMSampleBufferCreateForImageBuffer (
   CFAllocatorRef allocator,
   CVImageBufferRef imageBuffer,
   Boolean dataReady,
   CMSampleBufferMakeDataReadyCallback makeDataReadyCallback,
   void *makeDataReadyRefcon,
   CMVideoFormatDescriptionRef formatDescription,
   const CMSampleTimingInfo *sampleTiming,
   CMSampleBufferRef *sBufOut
);
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.

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. 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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferDataIsReady

Returns whether or not a CMSampleBuffer's data is ready.

Boolean CMSampleBufferDataIsReady (
   CMSampleBufferRef sbuf
);
Parameters
scuff

CMSampleBuffer being interrogated.

Return Value

A Boolean indicating whether or not the CMSampleBuffer's data is ready. True is returned for special marker buffers, eventhough they have no data. False is returned if there is an error.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer

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.

OSStatus CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer (
   CMSampleBufferRef sbuf,
   size_t *bufferListSizeNeededOut,
   AudioBufferList *bufferListOut,
   size_t bufferListSize,
   CFAllocatorRef bbufStructAllocator,
   CFAllocatorRef bbufMemoryAllocator,
   uint32_t flags,
   CMBlockBufferRef *blockBufferOut
);
Parameters
sbuf

CMSampleBuffer being accessed.

bufferListSizeNeededOut

Receives the size of the AudioBufferList required to accommodate the data. May be NULL.

bufferListOut

Allocated by the caller, sized as specified by bufferListSizeNeededOut. It is filled in with pointers into the retained blockBufferOut. May be NULL.

bufferListSize

Size of the bufferListOut allocated by the client. If bufferListOut is not NULL and bufferListSize is insufficient, kFigSampleBufferError_ArrayTooSmall is returned.

bbufStructAllocator

Allocator to use when creating the CMBlockBuffer structure.

bbufMemoryAllocator

Allocator to use for memory block held by the CMBlockBuffer.

flags

Flags controlling operation.

blockBufferOut

The retained CMBlockBuffer.

Return Value

A result code. See “Result Codes.”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetAudioStreamPacketDescriptions

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.

OSStatus CMSampleBufferGetAudioStreamPacketDescriptions (
   CMSampleBufferRef sbuf,
   size_t packetDescriptionsSize,
   AudioStreamPacketDescription *packetDescriptionsOut,
   size_t *packetDescriptionsSizeNeededOut
);
Parameters
sbuf

CMSampleBuffer being accessed.

packetDescriptionsSize

Size of packetDescriptionsOut as allocated by the caller.

packetDescriptionsOut

Allocated by the caller, receives the packet descriptions for the samples in the CMSampleBuffer. If non-NULL and packetDescriptionsSize is too small, kFigSampleBufferError_ArrayTooSmall is returned.

packetDescriptionsSizeNeededOut

Used to query for the correct size required for packetDescriptionsOut. May be NULL.

Return Value

A result code. See “Result Codes.”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetAudioStreamPacketDescriptionsPtr

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.

OSStatus CMSampleBufferGetAudioStreamPacketDescriptionsPtr (
   CMSampleBufferRef sbuf,
   const AudioStreamPacketDescription **packetDescriptionsPtrOut,
   size_t *packetDescriptionsSizeOut
);
Parameters
sbuf

CMSampleBuffer being modified.

packetDescriptionsPtrOut

On output, contains pointer to a constant array of AudioStreamPacketDescriptions. May be NULL.

packetDescriptionsSizeOut

Size in bytes of constant array of AudioStreamPacketDescriptions. May be NULL.

Return Value

A result code. See “Result Codes”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetDataBuffer

Returns a CMSampleBuffer's CMBlockBuffer of media data.

CMBlockBufferRef CMSampleBufferGetDataBuffer (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

The CMSampleBuffer being interrogated.

Return Value

CMBlockBuffer of media data. The result will be NULL if the CMSampleBuffer does not contain a CMBlockBuffer, if the CMSampleBuffer contains a CVImageBuffer, or if there is some other error.

Discussion

The caller does not own the returned dataBuffer, and must retain it explicitly if the caller needs to maintain a reference to it.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetDecodeTimeStamp

Returns the numerically earliest decode timestamp of all the samples in a CMSampleBuffer.

CMTime CMSampleBufferGetDecodeTimeStamp (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

The CMSampleBuffer being interrogated.

Return Value

The numerically earliest sample decode timestamp in the CMSampleBuffer. kCMTimeInvalid is returned if there is an error.

Discussion

The returned decode timestamp is always the decode timestamp of the first sample in the buffer, since even out-of-presentation-order samples are expected to be in decode order in the buffer.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetDuration

Returns the total duration of a CMSampleBuffer.

CMTime CMSampleBufferGetDuration (
   CMSampleBufferRef sbuf
);
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetFormatDescription

Returns the format description of the samples in a CMSampleBuffer.

CMFormatDescriptionRef CMSampleBufferGetFormatDescription (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

The format description of the samples in the CMSampleBuffer. NULL is returned if there is an error.

Discussion

On return, the caller does not own the returned formatDesc, and must retain it explicitly if the caller needs to maintain a reference to it.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetImageBuffer

Returns a CMSampleBuffer's CVImageBuffer of media data.

CVImageBufferRef CMSampleBufferGetImageBuffer (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

CVImageBuffer of media data. The result will be NULL if the CMSampleBuffer does not contain a CVImageBuffer, if the CMSampleBuffer contains a CMBlockBuffer, or if there is some other error.

Discussion

The caller does not own the returned dataBuffer, and must retain it explicitly if the caller needs to maintain a reference to it.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetNumSamples

Returns the number of media samples in a CMSampleBuffer.

CMItemCount CMSampleBufferGetNumSamples (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

The number of media samples in the CMSampleBuffer. 0 is returned if there is an error.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetOutputDecodeTimeStamp

Returns the output decode timestamp of the CMSampleBuffer.

CMTime CMSampleBufferGetOutputDecodeTimeStamp (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

The output decode timestamp of the CMSampleBuffer. CMInvalidTime is returned if there is an error.

Discussion

For consistency with CMSampleBufferGetOutputPresentationTimeStamp, this is calculated as: OutputPresentationTimeStamp + ((DecodeTimeStamp - PresentationTimeStamp) / SpeedMultiplier).

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetOutputDuration

Returns the output duration of a CMSampleBuffer.

CMTime CMSampleBufferGetOutputDuration (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

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

Discussion

The OutputDuration is the duration minus any trimmed duration, all divided by the SpeedMultiplier: (Duration - TrimDurationAtStart - TrimDurationAtEnd) / SpeedMultiplier.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetOutputPresentationTimeStamp

Returns the output presentation timestamp of the CMSampleBuffer.

CMTime CMSampleBufferGetOutputPresentationTimeStamp (
   CMSampleBufferRef sbuf
);
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetOutputSampleTimingInfoArray

Retrieves an array of output CMSampleTimingInfo structs, one for each sample in a CMSampleBuffer.

OSStatus CMSampleBufferGetOutputSampleTimingInfoArray (
   CMSampleBufferRef sbuf,
   CMItemCount timingArrayEntries,
   CMSampleTimingInfo *timingArrayOut,
   CMItemCount *timingArrayEntriesNeededOut
);
Parameters
sbuf

CMSampleBuffer being interrogated.

timingArrayEntries

Number of entries in timing array.

timingArrayOut

On output, points to an array of CMSampleTimingInfo structs to receive the timing info.

timingArrayEntriesNeededOut

Number of entries needed for the result.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetPresentationTimeStamp

Returns the numerically earliest presentation timestamp of all the samples in a CMSampleBuffer.

CMTime CMSampleBufferGetPresentationTimeStamp (
   CMSampleBufferRef sbuf
);
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.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
CMSampleBuffer.h

CMSampleBufferGetSampleAttachmentsArray

Returns a reference to a CMSampleBuffer's immutable array of mutable sample attachments dictionaries (one dictionary per sample in the CMSampleBuffer).

CFArrayRef CMSampleBufferGetSampleAttachmentsArray (
   CMSampleBufferRef sbuf,
   Boolean createIfNecessary
);
Parameters
sbuf

CMSampleBuffer being interrogated.

createIfNecessary

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetSampleSize

Returns the size in bytes of a specified sample in a CMSampleBuffer.

size_t CMSampleBufferGetSampleSize (
   CMSampleBufferRef sbuf,
   CMItemIndex sampleIndex
);
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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetSampleSizeArray

Retrieves an array of sample sizes, one for each sample in a CMSampleBuffer.

OSStatus CMSampleBufferGetSampleSizeArray (
   CMSampleBufferRef sbuf,
   CMItemCount sizeArrayEntries,
   size_t *sizeArrayOut,
   CMItemCount *sizeArrayEntriesNeededOut
);
Parameters
sbuf

CMSampleBuffer being interrogated.

sizeArrayEntries

Number of entries in sizeArray.

sizeArrayOut

Reference to an array of size_t values to receive the sample sizes.

sizeArrayEntriesNeededOut

Number of entries needed for the result.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetSampleTimingInfo

Retrieves a CMSampleTimingInfo struct describing a specified sample in a CMSampleBuffer.

OSStatus CMSampleBufferGetSampleTimingInfo (
   CMSampleBufferRef sbuf,
   CMItemIndex sampleIndex,
   CMSampleTimingInfo *timingInfoOut
);
Parameters
sbuf

CMSampleBuffer being interrogated .

sampleIndex

Sample index (0 is the first sample in sbuf).

timingInfoOut

On output, points to a single CMSampleTimingInfo struct to receive the timing info.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetSampleTimingInfoArray

Retrieves an array of CMSampleTimingInfo structs, one for each sample in a CMSampleBuffer.

OSStatus CMSampleBufferGetSampleTimingInfoArray (
   CMSampleBufferRef sbuf,
   CMItemCount timingArrayEntries,
   CMSampleTimingInfo *timingArrayOut,
   CMItemCount *timingArrayEntriesNeededOut
);
Parameters
sbuf

CMSampleBuffer being interrogated.

timingArrayEntries

Number of entries in timingArray

timingArrayOut

On output, points to an array of CMSampleTimingInfo structs to receive the timing info

timingArrayEntriesNeededOut

Number of entries needed for the result.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetTotalSampleSize

Returns the total size in bytes of sample data in a CMSampleBuffer.

size_t CMSampleBufferGetTotalSampleSize (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being interrogated.

Return Value

Total size in bytes of sample data in the CMSampleBuffer. If there are no sample sizes in this CMSampleBuffer, a size of 0 will be returned.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferGetTypeID

Returns the CFTypeID of CMSampleBuffer objects.

CFTypeID CMSampleBufferGetTypeID (
   void
);
Return Value

CFTypeID of CMSampleBuffer objects.

Discussion

You can check if a CFTypeRef object is actually a CMSampleBuffer by comparing CFGetTypeID(object) with CMSampleBufferGetTypeID().

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferInvalidate

Makes the sample buffer invalid, calling any installed invalidation callback.

OSStatus CMSampleBufferInvalidate (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being modified.

Return Value

A result code. See “Result Codes”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferIsValid

Queries whether a sample buffer is still valid.

Boolean CMSampleBufferIsValid (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

The CMSampleBuffer being interrogated.

Return Value

A Boolean indicating whether the sample buffer is still valid.

Discussion

Returns false if sbuf is NULL or CMSampleBufferInvalidate(sbuf) was called, true otherwise. Does not perform any kind of exhaustive validation of the sample buffer.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferMakeDataReady

Makes a CMSampleBuffer data ready, by calling the client's CMSampleBufferMakeDataReadyCallback.

OSStatus CMSampleBufferMakeDataReady (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being modified.

Return Value

A result code. See “Result Codes”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferSetDataBuffer

Associates a CMSampleBuffer with its CMBlockBuffer of media data.

OSStatus CMSampleBufferSetDataBuffer (
   CMSampleBufferRef sbuf,
   CMBlockBufferRef dataBuffer
);
Parameters
sbuf

CMSampleBuffer being modified.

dataBuffer

CMBlockBuffer of data being associated with.

Return Value

A result code. See “Result Codes”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferSetDataBufferFromAudioBufferList

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.

OSStatus CMSampleBufferSetDataBufferFromAudioBufferList (
   CMSampleBufferRef sbuf,
   CFAllocatorRef bbufStructAllocator,
   CFAllocatorRef bbufMemoryAllocator,
   uint32_t flags,
   const AudioBufferList *bufferList
);
Parameters
sbuf

CMSampleBuffer being modified.

bbufStructAllocator

Allocator to use when creating the CMBlockBuffer structure.

bbufMemoryAllocator

Allocator to use for memory block held by the CMBlockBuffer.

flags

Flags controlling operation.

bufferList

Buffer list whose data will be copied into the new CMBlockBuffer.

Return Value

A result code. See “Result Codes”

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferSetDataReady

Marks a CMSampleBuffer's data as "ready".

OSStatus CMSampleBufferSetDataReady (
   CMSampleBufferRef sbuf
);
Parameters
sbuf

CMSampleBuffer being modified.

Return Value

A result code. See “Result Codes”

Discussion

There is no way to undo this operation. The only way to get an "unready"CMSampleBuffer is to call CMSampleBufferCreate with the dataReady parameter set to false.

Example of usage: in a read completion routine.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferSetInvalidateCallback

Sets the CMSampleBuffer’s invalidation callback, which is called during CMSampleBufferInvalidate.

OSStatus CMSampleBufferSetInvalidateCallback (
   CMSampleBufferRef sbuf,
   CMSampleBufferInvalidateCallback invalidateCallback,
   uint64_t invalidateRefCon
);
Parameters
sbuf

The CMSampleBuffer being modified.

invalidateCallback

Reference to a function to be called during CMSampleBufferInvalidate.

invalidateRefCon

Reference constant to be passed to invalidateCallback.

Return Value

A result code. See “Result Codes.”

Discussion

A sample buffer can only have one invalidation callback. The invalidation callback is NOT called during ordinary sample buffer finalization.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferSetOutputPresentationTimeStamp

Sets an output presentation timestamp to be used in place of a calculated value.

OSStatus CMSampleBufferSetOutputPresentationTimeStamp (
   CMSampleBufferRef sbuf,
   CMTime outputPresentationTimeStamp
);
Parameters
sbuf

CMSampleBuffer being interrogated

outputPresentationTimeStamp

New value for OutputPresentationTimeStamp. Pass kCMTimeInvalid to go back to the default calculation.

Return Value

A result code. See “Result Codes.”

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:

((PresentationTimeStamp + TrimDurationAtStart - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.

For general reversed playback OutputPresentationTimeStamp should be set to:

((PresentationTimeStamp + Duration - TrimDurationAtEnd - EditStartMediaTime) / EditSpeedMultiplier) + EditStartTrackTime.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleBufferTrackDataReadiness

Associates a CMSampleBuffer's data readiness with another CMSampleBuffer's data readiness.

OSStatus CMSampleBufferTrackDataReadiness (
   CMSampleBufferRef sbuf,
   CMSampleBufferRef sbufToTrack
);
Parameters
sbuf

CMSampleBuffer being modified.

sbufToTrack

CMSampleBuffer being tracked.

Return Value

A result code. See “Result Codes.”

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.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

Data Types

CMSampleBufferRef

A reference to an immutable CMSampleBufferRef object.

typedef struct opaqueCMSampleBuffer *CMSampleBufferRef;
Discussion

A CMSampleBuffer is a Core Foundation object containing zero or more compressed (or uncompressed) samples of a particular media type (audio, video, muxed, and so on).

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

CMSampleTimingInfo

A collection of timing information for a sample in a CMSampleBuffer.

typedef struct {
   CMTime duration;
   CMTime presentationTimeStamp;
   CMTime decodeTimeStamp;
} CMSampleTimingInfo;
Fields
duration

The duration of the sample.

If a single struct applies to each of the samples, they all have this duration.

presentationTimeStamp

The time at which the sample will be presented.

If a single struct applies to each of the samples, they all have this duration.

decodeTimeStamp

The time at which the sample will be decoded.

If the samples are in presentation order, this must be set to kCMInvalidTime.

Discussion

A single CMSampleTimingInfo struct can describe every individual sample in a CMSampleBuffer, if the samples all have the same duration and are in presentation order with no gaps.

Availability
  • Available in iOS 4.0 and later.
Declared In
CMSampleBuffer.h

Constants

Sample Buffer Notifications

Notifications posted by sample buffer objects.

const CFStringRef kCMSampleBufferNotification_DataBecameReady;
const CFStringRef kCMSampleBufferConduitNotification_InhibitOutputUntil;
const CFStringRef kCMSampleBufferConduitNotification_ResetOutput;
const CFStringRef kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged;
const CFStringRef kCMSampleBufferConsumerNotification_BufferConsumed;
Constants
kCMSampleBufferNotification_DataBecameReady

Posted on a sample buffer by the CMSampleBufferSetDataReady function when the buffer becomes ready.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferConduitNotification_InhibitOutputUntil

Posted on a conduit of sample buffers to announce a coming discontinuity.

A conduit of sample buffers (for example, a buffer queue; see CMBufferQueue Reference) posts this notification when a discontinuity in decoding occurs. The userInfo dictionary for this notification contains the kCMSampleBufferConduitNotificationParameter_ResumeTag key, whose value specifies a tag that indicates when output should resume.

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.

Declared in CMSampleBuffer.h.

kCMSampleBufferConduitNotification_ResetOutput

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

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).

The userInfo dictionary for this notification contains the kCMSampleBufferConduitNotificationParameter_UpcomingOutputPTSRangeMayOverlapQueuedOutputPTSRange key. If the value for that key is kCFBooleanTrue, the dictionary also contains one or both of the kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS or kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS keys providing information about the range of overlapping presentation timestamps.

Available in iOS 4.3 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferConsumerNotification_BufferConsumed

Optionally posted when a sample buffer is consumed.

If a sample buffer has a value for the kCMSampleBufferAttachmentKey_PostNotificationWhenConsumed attachment, an object that consumes the sample buffer should post this notification with itself as the notifying object and the attachment value as the userInfo dictionary.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

Sample Buffer Notification Parameters

Keys used in the userInfo dictionaries of notifications posted by sample buffer objects.

const CFStringRef kCMSampleBufferConduitNotificationParameter_ResumeTag;
const CFStringRef kCMSampleBufferConduitNotificationParameter_UpcomingOutputPTSRangeMayOverlapQueuedOutputPTSRange;
const CFStringRef kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS;
const CFStringRef kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS;
Constants
kCMSampleBufferConduitNotificationParameter_ResumeTag

Specifies a tag to be attached to the first sample buffer following a discontinuity (type CFNumber).

A conduit of sample buffers posts the kCMSampleBufferConduitNotification_InhibitOutputUntil notification when a discontinuity in decoding occurs. The value for this key will be attached to the first sample buffer following the discontinuity using the kCMSampleBufferAttachmentKey_ResumeOutput attachment, indicating that clients should resume output.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferConduitNotificationParameter_UpcomingOutputPTSRangeMayOverlapQueuedOutputPTSRange

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.

Available in iOS 4.3 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS

Specifies the minimum presentation timestamp of upcoming output samples (type CFDictionary).

This key may be present in the userInfo dictionary for for the kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged notification in cases where upcoming frames may have earlier timestamps than those previously provided. Its value is the CFDictionary representation of a CMTime object (see CMTimeMakeFromDictionary).

Either this key or kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS may be omitted to leave the range open-ended.

Available in iOS 4.3 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS

Specifies the maximum presentation timestamp of upcoming output samples (type CFDictionary).

This key may be present in the userInfo dictionary for for the kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged notification in cases where upcoming frames may have earlier timestamps than those previously provided. Its value is the CFDictionary representation of a CMTime object (see CMTimeMakeFromDictionary).

Either this key or kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS may be omitted to leave the range open-ended.

Available in iOS 5.0 and later.

Declared in CMSampleBuffer.h.

Sample Attachment Keys

Attachments associated with individual samples in a buffer.

const CFStringRef kCMSampleAttachmentKey_NotSync;
const CFStringRef kCMSampleAttachmentKey_PartialSync;
const CFStringRef kCMSampleAttachmentKey_HasRedundantCoding;
const CFStringRef kCMSampleAttachmentKey_IsDependedOnByOthers;
const CFStringRef kCMSampleAttachmentKey_DependsOnOthers;
const CFStringRef kCMSampleAttachmentKey_EarlierDisplayTimesAllowed;
const CFStringRef kCMSampleAttachmentKey_DisplayImmediately;
const CFStringRef kCMSampleAttachmentKey_DoNotDisplay;
Constants
kCMSampleAttachmentKey_NotSync

Indicates whether the sample is a sync sample (type CFBoolean, default false).

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.

This attachment is read from and written to media files.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleAttachmentKey_PartialSync

Indicates whether the sample is a partial sync sample (type CFBoolean, default false).

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleAttachmentKey_DisplayImmediately

Indicates whether the sample should be displayed immediately (type CFBoolean, default false).

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.

Declared in CMSampleBuffer.h.

kCMSampleAttachmentKey_DoNotDisplay

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

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.

Declared in CMSampleBuffer.h.

Discussion

You can get and set sample-level attachments in a sample buffer using the CMSampleBufferGetSampleAttachmentsArray function.

Sample Buffer Attachment Keys

Buffer-level attachments associated with a sample buffer.

const CFStringRef kCMSampleBufferAttachmentKey_ResetDecoderBeforeDecoding;
const CFStringRef kCMSampleBufferAttachmentKey_DrainAfterDecoding;
const CFStringRef kCMSampleBufferAttachmentKey_PostNotificationWhenConsumed;
const CFStringRef kCMSampleBufferAttachmentKey_ResumeOutput;
const CFStringRef kCMSampleBufferAttachmentKey_TransitionID;
const CFStringRef kCMSampleBufferAttachmentKey_TrimDurationAtStart;
const CFStringRef kCMSampleBufferAttachmentKey_TrimDurationAtEnd;
const CFStringRef kCMSampleBufferAttachmentKey_SpeedMultiplier;
const CFStringRef kCMSampleBufferAttachmentKey_Reverse;
const CFStringRef kCMSampleBufferAttachmentKey_FillDiscontinuitiesWithSilence;
const CFStringRef kCMSampleBufferAttachmentKey_EmptyMedia;
const CFStringRef kCMSampleBufferAttachmentKey_PermanentEmptyMedia;
const CFStringRef kCMSampleBufferAttachmentKey_DisplayEmptyMediaImmediately;
const CFStringRef kCMSampleBufferAttachmentKey_EndsPreviousSampleDuration;
const CFStringRef kCMSampleBufferAttachmentKey_SampleReferenceURL;
const CFStringRef kCMSampleBufferAttachmentKey_SampleReferenceByteOffset;
const CFStringRef kCMSampleBufferAttachmentKey_GradualDecoderRefresh;
const CFStringRef kCMSampleBufferAttachmentKey_DroppedFrameReason;
const CFStringRef kCMSampleBufferAttachmentKey_DroppedFrameReasonInfo;
Constants
kCMSampleBufferAttachmentKey_ResetDecoderBeforeDecoding

Indicates whether the sample buffer should be reset before decoding (type CFBoolean, default false).

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

This attachment is not written to media files.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_DrainAfterDecoding

Indicates whether the sample buffer should be drained after decoding 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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_ResumeOutput

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

This attachment is used at run time to request that a decode pipeline resume producing output after a discontinuity announced using the kCMSampleBufferConduitNotification_InhibitOutputUntil notification.

This attachment is not written to media files.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_TransitionID

Marks a transition from one source of buffers to another.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_TrimDurationAtEnd

The duration that should be removed at the end 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.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_SpeedMultiplier

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.

Declared in CMSampleBuffer.h.

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.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_FillDiscontinuitiesWithSilence

Fill the difference between discontiguous sample buffers with silence (type CFBoolean, default false).

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.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_EmptyMedia

Marks an intentionally empty interval in the sequence of samples (type CFBoolean, default false).

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.”

Available in iOS 6.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferAttachmentKey_DroppedFrameReasonInfo

Indicates additional information regarding the dropped video frame (type CFString).

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.

Declared in CMSampleBuffer.h.

Discussion

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

Sample Buffer Dropped Frame Reasons

Values providing the reason for a dropped frame.

const CFStringRef kCMSampleBufferDroppedFrameReason_FrameWasLate;
const CFStringRef kCMSampleBufferDroppedFrameReason_OutOfBuffers;
const CFStringRef kCMSampleBufferDroppedFrameReason_Discontinuity;
Constants
kCMSampleBufferDroppedFrameReason_FrameWasLate

The frame was dropped because it was late.

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.

Declared in CMSampleBuffer.h.

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.

Declared in CMSampleBuffer.h.

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.

Available in iOS 6.0 and later.

Declared in CMSampleBuffer.h.

Discussion

These values can be associated with a sample buffer under the kCMSampleBufferAttachmentKey_DroppedFrameReason key.

Sample Buffer Dropped Frame Reason Information

Values providing additional information about the reason for a dropped frame.

const CFStringRef kCMSampleBufferDroppedFrameReasonInfo_CameraModeSwitch;
Constants
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.

Available in iOS 7.0 and later.

Declared in CMSampleBuffer.h.

Discussion

These values can be associated with a sample buffer under the kCMSampleBufferAttachmentKey_DroppedFrameReasonInfo key.

Result Codes

This table lists the result codes defined for CMSampleBuffer APIs.

Result Code

Value

Description

noErr

0

No error.

kCMSampleBufferError_AllocationFailed

-12730

Indicates that an allocation failed.

kCMSampleBufferError_RequiredParameterMissing

-12731

Indicates that NULL or 0 was passed for a required parameter.

kCMSampleBufferError_AlreadyHasDataBuffer

-12732

Indicates that an attempt was made to set a data buffer on a CMSampleBuffer that already has one.

kCMSampleBufferError_BufferNotReady

-12733

Indicates that the buffer could not be made ready.

kCMSampleBufferError_SampleIndexOutOfRange

-12734

Indicates that the sample index was not between 0 and numSamples-1, inclusive.

kCMSampleBufferError_BufferHasNoSampleSizes

-12735

Indicates that there was an attempt to get sample size information when there was none.

kCMSampleBufferError_BufferHasNoSampleTimingInfo

-12736

Indicates that there was an attempt to get sample timing information when there was none.

kCMSampleBufferError_ArrayTooSmall

-12737

Indicates that the output array was not large enough for the array being requested.

kCMSampleBufferError_InvalidEntryCount

-12738

Indicates that the timing info or size array entry count was not 0, 1, or numSamples.

kCMSampleBufferError_CannotSubdivide

-12739

Indicates that the sample buffer does not contain sample sizes.

This can happen when the samples in the buffer are non-contiguous (for example, in non-interleaved audio, where the channel values for a single sample are scattered through the buffer).

kCMSampleBufferError_SampleTimingInfoInvalid

-12740

Indicates that the buffer unexpectedly contains a non-numeric sample timing info.

kCMSampleBufferError_InvalidMediaTypeForOperation

-12741

Indicates that the media type specified by a format description is not valid for the given operation.

kCMSampleBufferError_InvalidSampleData

-12742

Indicates that Buffer contains bad data.

This value is only returned by CMSampleBuffer functions that inspect its sample data.

kCMSampleBufferError_InvalidMediaFormat

-12743

Indicates that the format of the given media does not match the given format description.

For example, a format description paired with a CVImageBuffer that fails CMVideoFormatDescriptionMatchesImageBuffer.

kCMSampleBufferError_Invalidated

-12744

Indicates that the sample buffer was invalidated.