CMSampleBuffer Reference

Overview

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

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.

The buffer-level attachments of a CMSampleBuffer are distinct from the attachments of its contained CMBlockBuffer. An example of a sample-level attachment is an annotation about video frame dependencies (such as “droppable,” “other frames depend on me,” or “I depend on other frames”). Each sample (video frame) in the CMSampleBuffer would need its own attachment in this case. Another sample-level attachment example is SMPTE timecode acquired during capture. To get and set a CMSampleBuffer's buffer-level attachments, use the APIs in CMAttachmentBearerRef.

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

OSStatus CMAudioSampleBufferCreateWithPacketDescriptions (
   CFAllocatorRef allocator,
   CMBlockBufferRef dataBuffer,
   Boolean dataReady,
   CMSampleBufferMakeDataReadyCallback makeDataReadyCallback,
   void *makeDataReadyRefcon,
   CMFormatDescriptionRef formatDescription,
   CMItemCount numSamples,
   CMTime sbufPTS,
   const AudioStreamPacketDescription *packetDescriptions,
   CMSampleBufferRef *sBufOut
);

CMSampleBufferCallForEachSample

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

CMSampleBufferCopySampleBufferForRange

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

CMSampleBufferCreate

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

CMSampleBufferCreateCopy

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

CMSampleBufferCreateCopyWithNewTiming

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

CMSampleBufferCreateForImageBuffer

OSStatus CMSampleBufferCreateForImageBuffer (
   CFAllocatorRef allocator,
   CVImageBufferRef imageBuffer,
   Boolean dataReady,
   CMSampleBufferMakeDataReadyCallback makeDataReadyCallback,
   void *makeDataReadyRefcon,
   CMVideoFormatDescriptionRef formatDescription,
   const CMSampleTimingInfo *sampleTiming,
   CMSampleBufferRef *sBufOut
);

CMSampleBufferDataIsReady

Boolean CMSampleBufferDataIsReady (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer

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

CMSampleBufferGetAudioStreamPacketDescriptions

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

CMSampleBufferGetAudioStreamPacketDescriptionsPtr

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

CMSampleBufferGetDataBuffer

CMBlockBufferRef CMSampleBufferGetDataBuffer (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetDecodeTimeStamp

CMTime CMSampleBufferGetDecodeTimeStamp (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetDuration

CMTime CMSampleBufferGetDuration (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetFormatDescription

CMFormatDescriptionRef CMSampleBufferGetFormatDescription (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetImageBuffer

CVImageBufferRef CMSampleBufferGetImageBuffer (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetNumSamples

CMItemCount CMSampleBufferGetNumSamples (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetOutputDecodeTimeStamp

CMTime CMSampleBufferGetOutputDecodeTimeStamp (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetOutputDuration

CMTime CMSampleBufferGetOutputDuration (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetOutputPresentationTimeStamp

CMTime CMSampleBufferGetOutputPresentationTimeStamp (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetOutputSampleTimingInfoArray

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

CMSampleBufferGetPresentationTimeStamp

CMTime CMSampleBufferGetPresentationTimeStamp (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetSampleAttachmentsArray

CFArrayRef CMSampleBufferGetSampleAttachmentsArray (
   CMSampleBufferRef sbuf,
   Boolean createIfNecessary
);

CMSampleBufferGetSampleSize

size_t CMSampleBufferGetSampleSize (
   CMSampleBufferRef sbuf,
   CMItemIndex sampleIndex
);

CMSampleBufferGetSampleSizeArray

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

CMSampleBufferGetSampleTimingInfo

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

CMSampleBufferGetSampleTimingInfoArray

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

CMSampleBufferGetTotalSampleSize

size_t CMSampleBufferGetTotalSampleSize (
   CMSampleBufferRef sbuf
);

CMSampleBufferGetTypeID

CFTypeID CMSampleBufferGetTypeID (
   void
);

CMSampleBufferInvalidate

OSStatus CMSampleBufferInvalidate (
   CMSampleBufferRef sbuf
);

CMSampleBufferIsValid

Boolean CMSampleBufferIsValid (
   CMSampleBufferRef sbuf
);

CMSampleBufferMakeDataReady

OSStatus CMSampleBufferMakeDataReady (
   CMSampleBufferRef sbuf
);

CMSampleBufferSetDataBuffer

OSStatus CMSampleBufferSetDataBuffer (
   CMSampleBufferRef sbuf,
   CMBlockBufferRef dataBuffer
);

CMSampleBufferSetDataBufferFromAudioBufferList

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

CMSampleBufferSetDataReady

OSStatus CMSampleBufferSetDataReady (
   CMSampleBufferRef sbuf
);

CMSampleBufferSetInvalidateCallback

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

CMSampleBufferSetOutputPresentationTimeStamp

OSStatus CMSampleBufferSetOutputPresentationTimeStamp (
   CMSampleBufferRef sbuf,
   CMTime outputPresentationTimeStamp
);

CMSampleBufferTrackDataReadiness

OSStatus CMSampleBufferTrackDataReadiness (
   CMSampleBufferRef sbuf,
   CMSampleBufferRef sbufToTrack
);

Data Types

CMSampleBufferRef

A reference to an immutable CMSampleBufferRef object.

typedef struct opaqueCMSampleBuffer *CMSampleBufferRef;

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.

Constants

Error Codes

Error codes returned from the CMSampleBuffer functions.

enum {
   kCMSampleBufferError_AllocationFailed                = -12730,
   kCMSampleBufferError_RequiredParameterMissing        = -12731,
   kCMSampleBufferError_AlreadyHasDataBuffer            = -12732,
   kCMSampleBufferError_BufferNotReady                  = -12733,
   kCMSampleBufferError_SampleIndexOutOfRange           = -12734,
   kCMSampleBufferError_BufferHasNoSampleSizes          = -12735,
   kCMSampleBufferError_BufferHasNoSampleTimingInfo     = -12736,
   kCMSampleBufferError_ArrayTooSmall                   = -12737,
   kCMSampleBufferError_InvalidEntryCount               = -12738,
   kCMSampleBufferError_CannotSubdivide                 = -12739,
   kCMSampleBufferError_SampleTimingInfoInvalid         = -12740,
   kCMSampleBufferError_InvalidMediaTypeForOperation    = -12741,
   kCMSampleBufferError_InvalidSampleData               = -12742,
   kCMSampleBufferError_InvalidMediaFormat              = -12743,
   kCMSampleBufferError_Invalidated                     = -12744,
};

Constants

kCMSampleBufferError_AllocationFailed

Indicates that an allocation failed.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_RequiredParameterMissing

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_AlreadyHasDataBuffer

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_BufferNotReady

Indicates that the buffer could not be made ready.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_SampleIndexOutOfRange

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_BufferHasNoSampleSizes

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_BufferHasNoSampleTimingInfo

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_ArrayTooSmall

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_InvalidEntryCount

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_CannotSubdivide

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_SampleTimingInfoInvalid

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_InvalidMediaTypeForOperation

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

For example, a CMSampleBuffer with a non-audio format description was passed to CMSampleBufferGetAudioStreamPacketDescriptionsPtr.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_InvalidSampleData

Indicates that Buffer contains bad data.

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

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_InvalidMediaFormat

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.

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.

kCMSampleBufferError_Invalidated

Indicates that the sample buffer was invalidated..

Available in iOS 4.0 and later.

Declared in CMSampleBuffer.h.