Mac Developer Library

Developer

CoreMedia Framework Reference CMSampleBuffer Reference

Options
Deployment Target:

On This Page
Language:

CMSampleBuffer Reference

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreMedia

Objective-C

@import CoreMedia;

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.

Functions

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

    Declaration

    Swift

    func CMAudioSampleBufferCreateWithPacketDescriptions(_ allocator: CFAllocator!, _ dataBuffer: CMBlockBuffer!, _ dataReady: Boolean, _ makeDataReadyCallback: CMSampleBufferMakeDataReadyCallback, _ makeDataReadyRefcon: UnsafeMutablePointer<Void>, _ formatDescription: CMFormatDescription!, _ numSamples: CMItemCount, _ sbufPTS: CMTime, _ packetDescriptions: UnsafePointer<AudioStreamPacketDescription>, _ sBufOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferCallForEachSample(_ sbuf: CMSampleBuffer!, _ refcon: CFunctionPointer<((CMSampleBuffer!, CMItemCount, UnsafeMutablePointer<Void>) -> OSStatus)>, _ refcon: UnsafeMutablePointer<Void>) -> OSStatus

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferCopySampleBufferForRange(_ allocator: CFAllocator!, _ sbuf: CMSampleBuffer!, _ sampleRange: CFRange, _ sBufOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Creates a CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferCreate(_ allocator: CFAllocator!, _ dataBuffer: CMBlockBuffer!, _ dataReady: Boolean, _ makeDataReadyCallback: CMSampleBufferMakeDataReadyCallback, _ makeDataReadyRefcon: UnsafeMutablePointer<Void>, _ formatDescription: CMFormatDescription!, _ numSamples: CMItemCount, _ numSampleTimingEntries: CMItemCount, _ sampleTimingArray: UnsafePointer<CMSampleTimingInfo>, _ numSampleSizeEntries: CMItemCount, _ sampleSizeArray: UnsafePointer<Int>, _ sBufOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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)

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Creates a copy of a CMSampleBuffer

    Declaration

    Swift

    func CMSampleBufferCreateCopy(_ allocator: CFAllocator!, _ sbuf: CMSampleBuffer!, _ sbufCopyOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Creates a copy of CMSampleBuffer with new timing information.

    Declaration

    Swift

    func CMSampleBufferCreateCopyWithNewTiming(_ allocator: CFAllocator!, _ originalSBuf: CMSampleBuffer!, _ numSampleTimingEntries: CMItemCount, _ sampleTimingArray: UnsafePointer<CMSampleTimingInfo>, _ sBufCopyOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferCreateForImageBuffer(_ allocator: CFAllocator!, _ imageBuffer: CVImageBuffer!, _ dataReady: Boolean, _ makeDataReadyCallback: CMSampleBufferMakeDataReadyCallback, _ makeDataReadyRefcon: UnsafeMutablePointer<Void>, _ formatDescription: CMVideoFormatDescription!, _ sampleTiming: UnsafePointer<CMSampleTimingInfo>, _ sBufOut: UnsafeMutablePointer<Unmanaged<CMSampleBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferDataIsReady(_ scuff: CMSampleBuffer!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(_ sbuf: CMSampleBuffer!, _ bufferListSizeNeededOut: UnsafeMutablePointer<Int>, _ bufferListOut: UnsafeMutablePointer<AudioBufferList>, _ bufferListSize: Int, _ bbufStructAllocator: CFAllocator!, _ bbufMemoryAllocator: CFAllocator!, _ flags: UInt32, _ blockBufferOut: UnsafeMutablePointer<Unmanaged<CMBlockBuffer>?>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetAudioStreamPacketDescriptions(_ sbuf: CMSampleBuffer!, _ packetDescriptionsSize: Int, _ packetDescriptionsOut: UnsafeMutablePointer<AudioStreamPacketDescription>, _ packetDescriptionsSizeNeededOut: UnsafeMutablePointer<Int>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • 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

    Swift

    func CMSampleBufferGetAudioStreamPacketDescriptionsPtr(_ sbuf: CMSampleBuffer!, _ packetDescriptionsPtrOut: UnsafeMutablePointer<UnsafePointer<AudioStreamPacketDescription>>, _ packetDescriptionsSizeOut: UnsafeMutablePointer<Int>) -> OSStatus

    Objective-C

    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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns a CMSampleBuffer's CMBlockBuffer of media data.

    Declaration

    Swift

    func CMSampleBufferGetDataBuffer(_ sbuf: CMSampleBuffer!) -> CMBlockBuffer!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetDecodeTimeStamp(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the total duration of a CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetDuration(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the format description of the samples in a CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetFormatDescription(_ sbuf: CMSampleBuffer!) -> CMFormatDescription!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns a CMSampleBuffer's CVImageBuffer of media data.

    Declaration

    Swift

    func CMSampleBufferGetImageBuffer(_ sbuf: CMSampleBuffer!) -> CVImageBuffer!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the number of media samples in a CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetNumSamples(_ sbuf: CMSampleBuffer!) -> CMItemCount

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the output decode timestamp of the CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetOutputDecodeTimeStamp(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the output duration of a CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetOutputDuration(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the output presentation timestamp of the CMSampleBuffer.

    Declaration

    Swift

    func CMSampleBufferGetOutputPresentationTimeStamp(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetOutputSampleTimingInfoArray(_ sbuf: CMSampleBuffer!, _ timingArrayEntries: CMItemCount, _ timingArrayOut: UnsafeMutablePointer<CMSampleTimingInfo>, _ timingArrayEntriesNeededOut: UnsafeMutablePointer<CMItemCount>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetPresentationTimeStamp(_ sbuf: CMSampleBuffer!) -> CMTime

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetSampleAttachmentsArray(_ sbuf: CMSampleBuffer!, _ createIfNecessary: Boolean) -> CFArray!

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetSampleSize(_ sbuf: CMSampleBuffer!, _ sampleIndex: CMItemIndex) -> Int

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetSampleSizeArray(_ sbuf: CMSampleBuffer!, _ sizeArrayEntries: CMItemCount, _ sizeArrayOut: UnsafeMutablePointer<Int>, _ sizeArrayEntriesNeededOut: UnsafeMutablePointer<CMItemCount>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetSampleTimingInfo(_ sbuf: CMSampleBuffer!, _ sampleIndex: CMItemIndex, _ timingInfoOut: UnsafeMutablePointer<CMSampleTimingInfo>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetSampleTimingInfoArray(_ sbuf: CMSampleBuffer!, _ timingArrayEntries: CMItemCount, _ timingArrayOut: UnsafeMutablePointer<CMSampleTimingInfo>, _ timingArrayEntriesNeededOut: UnsafeMutablePointer<CMItemCount>) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferGetTotalSampleSize(_ sbuf: CMSampleBuffer!) -> Int

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Returns the CFTypeID of CMSampleBuffer objects.

    Declaration

    Swift

    func CMSampleBufferGetTypeID() -> CFTypeID

    Objective-C

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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferInvalidate(_ sbuf: CMSampleBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Queries whether a sample buffer is still valid.

    Declaration

    Swift

    func CMSampleBufferIsValid(_ sbuf: CMSampleBuffer!) -> Boolean

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferMakeDataReady(_ sbuf: CMSampleBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Associates a CMSampleBuffer with its CMBlockBuffer of media data.

    Declaration

    Swift

    func CMSampleBufferSetDataBuffer(_ sbuf: CMSampleBuffer!, _ dataBuffer: CMBlockBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferSetDataBufferFromAudioBufferList(_ sbuf: CMSampleBuffer!, _ bbufStructAllocator: CFAllocator!, _ bbufMemoryAllocator: CFAllocator!, _ flags: UInt32, _ bufferList: UnsafePointer<AudioBufferList>) -> OSStatus

    Objective-C

    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

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

  • Marks a CMSampleBuffer's data as "ready".

    Declaration

    Swift

    func CMSampleBufferSetDataReady(_ sbuf: CMSampleBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferSetInvalidateCallback(_ sbuf: CMSampleBuffer!, _ invalidateCallback: CMSampleBufferInvalidateCallback, _ invalidateRefCon: UInt64) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferSetOutputPresentationTimeStamp(_ sbuf: CMSampleBuffer!, _ outputPresentationTimeStamp: CMTime) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

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

    Declaration

    Swift

    func CMSampleBufferTrackDataReadiness(_ sbuf: CMSampleBuffer!, _ sbufToTrack: CMSampleBuffer!) -> OSStatus

    Objective-C

    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.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in OS X v10.7 and later.

Data Types

Miscellaneous

  • A reference to an immutable CMSampleBufferRef object.

    Declaration

    Swift

    typealias CMSampleBufferRef = CMSampleBuffer

    Objective-C

    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 OS X v10.7 and later.

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

    Declaration

    Swift

    struct CMSampleTimingInfo { var duration: CMTime var presentationTimeStamp: CMTime var decodeTimeStamp: CMTime init() init(duration duration: CMTime, presentationTimeStamp presentationTimeStamp: CMTime, decodeTimeStamp decodeTimeStamp: CMTime) }

    Objective-C

    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 OS X v10.7 and later.

Constants

  • Notifications posted by sample buffer objects.

    Declaration

    Swift

    let kCMSampleBufferNotification_DataBecameReady: CFString! let kCMSampleBufferConduitNotification_InhibitOutputUntil: CFString! let kCMSampleBufferConduitNotification_ResetOutput: CFString! let kCMSampleBufferConduitNotification_UpcomingOutputPTSRangeChanged: CFString! let kCMSampleBufferConsumerNotification_BufferConsumed: CFString!

    Objective-C

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

    Constants

    • kCMSampleBufferNotification_DataBecameReady

      kCMSampleBufferNotification_DataBecameReady

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

      Available in OS X v10.7 and later.

    • kCMSampleBufferConduitNotification_InhibitOutputUntil

      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 OS X v10.7 and later.

    • kCMSampleBufferConduitNotification_ResetOutput

      kCMSampleBufferConduitNotification_ResetOutput

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

      Available in OS X v10.7 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).

      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 OS X v10.7 and later.

    • kCMSampleBufferConsumerNotification_BufferConsumed

      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 OS X v10.7 and later.

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

    Declaration

    Swift

    let kCMSampleBufferConduitNotificationParameter_ResumeTag: CFString! let kCMSampleBufferConduitNotificationParameter_UpcomingOutputPTSRangeMayOverlapQueuedOutputPTSRange: CFString! let kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS: CFString! let kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS: CFString!

    Objective-C

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

    Constants

    • kCMSampleBufferConduitNotificationParameter_ResumeTag

      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 OS X v10.7 and later.

    • kCMSampleBufferConduitNotificationParameter_UpcomingOutputPTSRangeMayOverlapQueuedOutputPTSRange

      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 OS X v10.7 and later.

    • kCMSampleBufferConduitNotificationParameter_MinUpcomingOutputPTS

      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 OS X v10.7 and later.

    • kCMSampleBufferConduitNotificationParameter_MaxUpcomingOutputPTS

      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 OS X v10.8 and later.

  • Attachments associated with individual samples in a buffer.

    Declaration

    Swift

    let kCMSampleAttachmentKey_NotSync: CFString! let kCMSampleAttachmentKey_PartialSync: CFString! let kCMSampleAttachmentKey_HasRedundantCoding: CFString! let kCMSampleAttachmentKey_IsDependedOnByOthers: CFString! let kCMSampleAttachmentKey_DependsOnOthers: CFString! let kCMSampleAttachmentKey_EarlierDisplayTimesAllowed: CFString! let kCMSampleAttachmentKey_DisplayImmediately: CFString! let kCMSampleAttachmentKey_DoNotDisplay: CFString!

    Objective-C

    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

      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 OS X v10.7 and later.

    • kCMSampleAttachmentKey_PartialSync

      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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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.

      Available in OS X v10.7 and later.

    • kCMSampleAttachmentKey_DisplayImmediately

      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 OS X v10.7 and later.

    • kCMSampleAttachmentKey_DoNotDisplay

      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 OS X v10.7 and later.

    Discussion

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

  • Buffer-level attachments associated with a sample buffer.

    Declaration

    Swift

    let kCMSampleBufferAttachmentKey_ResetDecoderBeforeDecoding: CFString! let kCMSampleBufferAttachmentKey_DrainAfterDecoding: CFString! let kCMSampleBufferAttachmentKey_PostNotificationWhenConsumed: CFString! let kCMSampleBufferAttachmentKey_ResumeOutput: CFString! let kCMSampleBufferAttachmentKey_TransitionID: CFString! let kCMSampleBufferAttachmentKey_TrimDurationAtStart: CFString! let kCMSampleBufferAttachmentKey_TrimDurationAtEnd: CFString! let kCMSampleBufferAttachmentKey_SpeedMultiplier: CFString! let kCMSampleBufferAttachmentKey_Reverse: CFString! let kCMSampleBufferAttachmentKey_FillDiscontinuitiesWithSilence: CFString! let kCMSampleBufferAttachmentKey_EmptyMedia: CFString! let kCMSampleBufferAttachmentKey_PermanentEmptyMedia: CFString! let kCMSampleBufferAttachmentKey_DisplayEmptyMediaImmediately: CFString! let kCMSampleBufferAttachmentKey_EndsPreviousSampleDuration: CFString! let kCMSampleBufferAttachmentKey_SampleReferenceURL: CFString! let kCMSampleBufferAttachmentKey_SampleReferenceByteOffset: CFString! let kCMSampleBufferAttachmentKey_GradualDecoderRefresh: CFString!

    Objective-C

    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;

    Constants

    • kCMSampleBufferAttachmentKey_ResetDecoderBeforeDecoding

      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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_DrainAfterDecoding

      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 OS X v10.7 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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_ResumeOutput

      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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_TransitionID

      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 OS X v10.7 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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_TrimDurationAtEnd

      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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_SpeedMultiplier

      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 OS X v10.7 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.

      Available in OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_FillDiscontinuitiesWithSilence

      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 OS X v10.7 and later.

    • kCMSampleBufferAttachmentKey_EmptyMedia

      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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 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 OS X v10.7 and later.

    Discussion

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

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.