# CMSampleBuffer An object that contains zero or more media samples of a uniform media type. ## Discussion Sample buffers are Core Foundation objects that the system uses to move media sample data through the media pipeline. An instance of `CMSampleBuffer` contains zero or more compressed (or uncompressed) samples of a particular media type and contains one of the following: - A [`CMBlockBuffer`](/documentation/CoreMedia/CMBlockBuffer) of one or more media samples - A , 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. Each individual sample in a buffer may provide attachments that include information such as timestamps and video frame dependencies. You read and write sample-level attachments using the [`CMSampleBufferGetSampleAttachmentsArray(_:createIfNecessary:)`](/documentation/CoreMedia/CMSampleBufferGetSampleAttachmentsArray(_:createIfNecessary:)) function. Buffer-level attachments provide information about the buffer as a whole, such as playback speed and actions to perform upon consuming the buffer. You can read and write buffer-level attachments using the APIs described in [CMAttachment](/documentation/CoreMedia/cmattachment-api) and the keys listed under [Sample Attachment Keys](/documentation/CoreMedia/sample-attachment-keys). It’s possible for a sample buffer to describe samples it doesn’t yet contain. For example, some media services may have access to sample size, timing, and format information before they read the data. Such services may create sample buffers with that information and insert them into queues early, and attach (or fill) the buffer of media data later, when it becomes ready. Sample buffers have the concept of data-readiness, which means you can test, set, and force them to become ready “now.” It’s also possible for a sample buffer 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`”). ## Topics ### Creating Sample Buffers [`CMSampleBufferCreateReady(allocator:dataBuffer:formatDescription:sampleCount:sampleTimingEntryCount:sampleTimingArray:sampleSizeEntryCount:sampleSizeArray:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreateReady(allocator:dataBuffer:formatDescription:sampleCount:sampleTimingEntryCount:sampleTimingArray:sampleSizeEntryCount:sampleSizeArray:sampleBufferOut:)) Creates a sample buffer with media data. [`CMSampleBufferCreateReadyWithImageBuffer(allocator:imageBuffer:formatDescription:sampleTiming:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreateReadyWithImageBuffer(allocator:imageBuffer:formatDescription:sampleTiming:sampleBufferOut:)) Creates a sample buffer with image data. [`CMAudioSampleBufferCreateReadyWithPacketDescriptions(allocator:dataBuffer:formatDescription:sampleCount:presentationTimeStamp:packetDescriptions:sampleBufferOut:)`](/documentation/CoreMedia/CMAudioSampleBufferCreateReadyWithPacketDescriptions(allocator:dataBuffer:formatDescription:sampleCount:presentationTimeStamp:packetDescriptions:sampleBufferOut:)) Creates a sample buffer with packet descriptions. [`CMSampleBufferCreateWithMakeDataReadyHandler(_:_:_:_:_:_:_:_:_:_:_:)`](/documentation/CoreMedia/CMSampleBufferCreateWithMakeDataReadyHandler(_:_:_:_:_:_:_:_:_:_:_:)) Creates a sample buffer with a handler to make the data ready for use. [`CMSampleBufferCreateForImageBufferWithMakeDataReadyHandler(_:_:_:_:_:_:_:)`](/documentation/CoreMedia/CMSampleBufferCreateForImageBufferWithMakeDataReadyHandler(_:_:_:_:_:_:_:)) Creates a sample buffer with an image buffer and a handler to make the data ready for use. [`CMSampleBufferCreateForTaggedBufferGroup`](/documentation/CoreMedia/CMSampleBufferCreateForTaggedBufferGroup) Creates a new sample buffer from a tagged buffer group. [`CMAudioSampleBufferCreateWithPacketDescriptionsAndMakeDataReadyHandler(_:_:_:_:_:_:_:_:_:)`](/documentation/CoreMedia/CMAudioSampleBufferCreateWithPacketDescriptionsAndMakeDataReadyHandler(_:_:_:_:_:_:_:_:_:)) Creates a sample buffer with packet descriptions and a handler to make the data ready for use. [`CMSampleBufferCreate(allocator:dataBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleCount:sampleTimingEntryCount:sampleTimingArray:sampleSizeEntryCount:sampleSizeArray:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreate(allocator:dataBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleCount:sampleTimingEntryCount:sampleTimingArray:sampleSizeEntryCount:sampleSizeArray:sampleBufferOut:)) Creates a sample buffer with a callback to make the data ready for use. [`CMSampleBufferCreateForImageBuffer(allocator:imageBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleTiming:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreateForImageBuffer(allocator:imageBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleTiming:sampleBufferOut:)) Creates a sample buffer with an image buffer and a callback to make the data ready for use. [`CMAudioSampleBufferCreateWithPacketDescriptions(allocator:dataBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleCount:presentationTimeStamp:packetDescriptions:sampleBufferOut:)`](/documentation/CoreMedia/CMAudioSampleBufferCreateWithPacketDescriptions(allocator:dataBuffer:dataReady:makeDataReadyCallback:refcon:formatDescription:sampleCount:presentationTimeStamp:packetDescriptions:sampleBufferOut:)) Creates a sample buffer with packet descriptions and a callback to make the data ready for use. ### Copying Sample Buffers [`CMSampleBufferCreateCopy(allocator:sampleBuffer:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreateCopy(allocator:sampleBuffer:sampleBufferOut:)) Creates a copy of a sample buffer. [`CMSampleBufferCreateCopyWithNewTiming(allocator:sampleBuffer:sampleTimingEntryCount:sampleTimingArray:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCreateCopyWithNewTiming(allocator:sampleBuffer:sampleTimingEntryCount:sampleTimingArray:sampleBufferOut:)) Creates a copy of a sample buffer with new timing information. [`CMSampleBufferCopySampleBufferForRange(allocator:sampleBuffer:sampleRange:sampleBufferOut:)`](/documentation/CoreMedia/CMSampleBufferCopySampleBufferForRange(allocator:sampleBuffer:sampleRange:sampleBufferOut:)) Creates a sample buffer that contains a range of samples from an existing sample buffer. ### Determining Readiness [`CMSampleBufferDataIsReady(_:)`](/documentation/CoreMedia/CMSampleBufferDataIsReady(_:)) Returns a Boolean value that indicates whether the sample buffer’s data is ready for use. [`CMSampleBufferSetDataReady(_:)`](/documentation/CoreMedia/CMSampleBufferSetDataReady(_:)) Marks a sample buffer’s data as ready for use. [`CMSampleBufferSetDataFailed(_:status:)`](/documentation/CoreMedia/CMSampleBufferSetDataFailed(_:status:)) Marks the sample buffer’s data as failed to indicate that it won’t become ready. [`CMSampleBufferHasDataFailed(_:statusOut:)`](/documentation/CoreMedia/CMSampleBufferHasDataFailed(_:statusOut:)) Returns a Boolean value that indicates whether the sample buffer’s data loading request failed. [`CMSampleBufferMakeDataReady(_:)`](/documentation/CoreMedia/CMSampleBufferMakeDataReady(_:)) Makes the sample buffer’s data ready for use by invoking its callback to load the data. [`CMSampleBufferTrackDataReadiness(_:sampleBufferToTrack:)`](/documentation/CoreMedia/CMSampleBufferTrackDataReadiness(_:sampleBufferToTrack:)) Associates a sample buffer’s data readiness with that of another sample buffer. ### Invalidating Sample Buffers [`CMSampleBufferSetInvalidateHandler(_:invalidateHandler:)`](/documentation/CoreMedia/CMSampleBufferSetInvalidateHandler(_:invalidateHandler:)) Sets the sample buffer’s invalidation handler. [`CMSampleBufferInvalidate(_:)`](/documentation/CoreMedia/CMSampleBufferInvalidate(_:)) Invalidates a sample buffer by calling its invalidation callback. [`CMSampleBufferIsValid(_:)`](/documentation/CoreMedia/CMSampleBufferIsValid(_:)) Returns a Boolean value that indicates whether a sample buffer is valid. [`CMSampleBufferSetInvalidateCallback(_:callback:refcon:)`](/documentation/CoreMedia/CMSampleBufferSetInvalidateCallback(_:callback:refcon:)) Sets the sample buffer’s invalidation callback. ### Inspecting Size Information [`CMSampleBufferGetNumSamples(_:)`](/documentation/CoreMedia/CMSampleBufferGetNumSamples(_:)) Returns the number of media samples in a sample buffer. [`CMSampleBufferGetTotalSampleSize(_:)`](/documentation/CoreMedia/CMSampleBufferGetTotalSampleSize(_:)) Returns the total size in bytes of sample data in a sample buffer. [`CMSampleBufferGetSampleSize(_:at:)`](/documentation/CoreMedia/CMSampleBufferGetSampleSize(_:at:)) Returns the size in bytes of a specified sample in a sample buffer. [`CMSampleBufferGetSampleSizeArray(_:entryCount:arrayToFill:entriesNeededOut:)`](/documentation/CoreMedia/CMSampleBufferGetSampleSizeArray(_:entryCount:arrayToFill:entriesNeededOut:)) Retrieves an array of sample sizes that represents each sample in a sample buffer. ### Inspecting Duration and Timing [`CMSampleBufferGetDuration(_:)`](/documentation/CoreMedia/CMSampleBufferGetDuration(_:)) Returns the total duration of a sample buffer. [`CMSampleBufferGetDecodeTimeStamp(_:)`](/documentation/CoreMedia/CMSampleBufferGetDecodeTimeStamp(_:)) Returns the decode timestamp that’s the earliest numerically of all the samples in a sample buffer. [`CMSampleBufferGetPresentationTimeStamp(_:)`](/documentation/CoreMedia/CMSampleBufferGetPresentationTimeStamp(_:)) Returns the presentation timestamp that’s the earliest numerically of all the samples in a sample buffer. [`CMSampleBufferGetOutputDuration(_:)`](/documentation/CoreMedia/CMSampleBufferGetOutputDuration(_:)) Returns the output duration of a sample buffer. [`CMSampleBufferGetOutputDecodeTimeStamp(_:)`](/documentation/CoreMedia/CMSampleBufferGetOutputDecodeTimeStamp(_:)) Returns the output decode timestamp of a sample buffer. [`CMSampleBufferGetOutputPresentationTimeStamp(_:)`](/documentation/CoreMedia/CMSampleBufferGetOutputPresentationTimeStamp(_:)) Returns the output presentation timestamp of a sample buffer. [`CMSampleBufferSetOutputPresentationTimeStamp(_:newValue:)`](/documentation/CoreMedia/CMSampleBufferSetOutputPresentationTimeStamp(_:newValue:)) Sets an output presentation timestamp to use in place of a calculated value. [`CMSampleBufferGetSampleTimingInfo(_:at:timingInfoOut:)`](/documentation/CoreMedia/CMSampleBufferGetSampleTimingInfo(_:at:timingInfoOut:)) Retrieves a timing information structure that describes a specified sample in a sample buffer. [`CMSampleBufferGetSampleTimingInfoArray(_:entryCount:arrayToFill:entriesNeededOut:)`](/documentation/CoreMedia/CMSampleBufferGetSampleTimingInfoArray(_:entryCount:arrayToFill:entriesNeededOut:)) Retrieves an array of sample timing information structures that represents each sample in a sample buffer. [`CMSampleBufferGetOutputSampleTimingInfoArray(_:entryCount:arrayToFill:entriesNeededOut:)`](/documentation/CoreMedia/CMSampleBufferGetOutputSampleTimingInfoArray(_:entryCount:arrayToFill:entriesNeededOut:)) Retrieves an array of output timing information structures that represents each sample in a sample buffer. ### Accessing the Format Description [`CMSampleBufferGetFormatDescription(_:)`](/documentation/CoreMedia/CMSampleBufferGetFormatDescription(_:)) Returns the format description of the samples in a sample buffer. ### Accessing Tag Information [`CMSampleBufferGetTaggedBufferGroup`](/documentation/CoreMedia/CMSampleBufferGetTaggedBufferGroup) Gets the tagged buffer group of a sample buffer. ### Modifying Sample Buffers [`CMSampleBufferGetDataBuffer(_:)`](/documentation/CoreMedia/CMSampleBufferGetDataBuffer(_:)) Returns a block buffer that contains the media data. [`CMSampleBufferSetDataBuffer(_:newValue:)`](/documentation/CoreMedia/CMSampleBufferSetDataBuffer(_:newValue:)) Sets a block buffer of media data on a sample buffer. [`CMSampleBufferGetImageBuffer(_:)`](/documentation/CoreMedia/CMSampleBufferGetImageBuffer(_:)) Returns an image buffer that contains the media data. [`CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(_:bufferListSizeNeededOut:bufferListOut:bufferListSize:blockBufferAllocator:blockBufferMemoryAllocator:flags:blockBufferOut:)`](/documentation/CoreMedia/CMSampleBufferGetAudioBufferListWithRetainedBlockBuffer(_:bufferListSizeNeededOut:bufferListOut:bufferListSize:blockBufferAllocator:blockBufferMemoryAllocator:flags:blockBufferOut:)) Returns an audio buffer list that contains the media data. [`CMSampleBufferSetDataBufferFromAudioBufferList(_:blockBufferAllocator:blockBufferMemoryAllocator:flags:bufferList:)`](/documentation/CoreMedia/CMSampleBufferSetDataBufferFromAudioBufferList(_:blockBufferAllocator:blockBufferMemoryAllocator:flags:bufferList:)) Creates a block buffer that contains a copy of the data from an audio buffer list. [`CMSampleBufferCopyPCMDataIntoAudioBufferList(_:at:frameCount:into:)`](/documentation/CoreMedia/CMSampleBufferCopyPCMDataIntoAudioBufferList(_:at:frameCount:into:)) Copies PCM audio data from a sample buffer into an audio buffer list. [`CMSampleBufferGetAudioStreamPacketDescriptions(_:allocatedSize:packetDescriptionsOut:packetDescriptionsSizeNeededOut:)`](/documentation/CoreMedia/CMSampleBufferGetAudioStreamPacketDescriptions(_:allocatedSize:packetDescriptionsOut:packetDescriptionsSizeNeededOut:)) Creates an array of audio stream packet descriptions. [`CMSampleBufferGetAudioStreamPacketDescriptionsPtr(_:packetDescriptionsPointerOut:sizeOut:)`](/documentation/CoreMedia/CMSampleBufferGetAudioStreamPacketDescriptionsPtr(_:packetDescriptionsPointerOut:sizeOut:)) Returns a pointer to a constant array of audio stream packet descriptions. ### Managing Attachments [`CMSampleBufferGetSampleAttachmentsArray(_:createIfNecessary:)`](/documentation/CoreMedia/CMSampleBufferGetSampleAttachmentsArray(_:createIfNecessary:)) Retrieves an array of sample attachment dictionaries that represents each sample in a sample buffer. [Sample Attachment Keys](/documentation/CoreMedia/sample-attachment-keys) Keys that specify attachments to individual samples in a buffer. ### Processing Samples [`CMSampleBufferCallBlockForEachSample(_:_:)`](/documentation/CoreMedia/CMSampleBufferCallBlockForEachSample(_:_:)) Calls a block for every individual sample in a sample buffer. [`CMSampleBufferCallForEachSample(_:callback:refcon:)`](/documentation/CoreMedia/CMSampleBufferCallForEachSample(_:callback:refcon:)) Calls a function for every individual sample in a sample buffer. ### Accessing the Type Identifier [`CMSampleBufferGetTypeID()`](/documentation/CoreMedia/CMSampleBufferGetTypeID()) Returns the type identifier of sample buffer objects. ### Data Types [`CMSampleBuffer`](/documentation/CoreMedia/CMSampleBuffer) A reference to a buffer of media data. [Sample Buffer Flags](/documentation/CoreMedia/sample-buffer-flags) Flags that customize the behavior of framework operations. [`CMSampleTimingInfo`](/documentation/CoreMedia/CMSampleTimingInfo) A collection of timing information for a sample in a sample buffer. [`CMBuffer`](/documentation/CoreMedia/CMBuffer) A reference to a buffer object. [`CMBufferGetSizeCallback`](/documentation/CoreMedia/CMBufferGetSizeCallback) A client callback that returns a size. [`CMItemIndex`](/documentation/CoreMedia/CMItemIndex) A datatype that represents an item index. [`CMItemCount`](/documentation/CoreMedia/CMItemCount) A datatype that represents an item count. [`CMPersistentTrackID`](/documentation/CoreMedia/CMPersistentTrackID) A datatype that represents a persistent track identifier. [`CMMuxedStreamType`](/documentation/CoreMedia/CMMuxedStreamType) A datatype that represents a muxed stream of data. ### Notifications [Sample Buffer Notifications](/documentation/CoreMedia/sample-buffer-notifications) Notifications the system posts when processing sample buffer objects. ### Errors [Sample Buffer Error Codes](/documentation/CoreMedia/sample-buffer-errors) Errors that occur when processing sample buffer objects. [`kCMPersistentTrackID_Invalid`](/documentation/CoreMedia/kCMPersistentTrackID_Invalid) Indicates an invalid track ID. ### Functions [`CMTimeFoldIntoRange(_:foldRange:)`](/documentation/CoreMedia/CMTimeFoldIntoRange(_:foldRange:)) Folds a time into a time range. [`CMVideoFormatDescriptionGetHEVCParameterSetAtIndex(_:parameterSetIndex:parameterSetPointerOut:parameterSetSizeOut:parameterSetCountOut:nalUnitHeaderLengthOut:)`](/documentation/CoreMedia/CMVideoFormatDescriptionGetHEVCParameterSetAtIndex(_:parameterSetIndex:parameterSetPointerOut:parameterSetSizeOut:parameterSetCountOut:nalUnitHeaderLengthOut:)) Returns a parameter set contained in an HEVC (H.265) format description. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)