MediaExtension macOS xcode15.0 b1
Alex Soto edited this page Jun 5, 2023
·
1 revision
#MediaExtension.framework
diff -ruN /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEError.h /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEError.h
--- /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEError.h 1969-12-31 19:00:00
+++ /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEError.h 2023-05-31 09:13:10
@@ -0,0 +1,69 @@
+/*
+ File: MEError.h
+
+ Framework: MediaExtension
+
+ Copyright © 2023 Apple Inc. All rights reserved.
+
+ To report bugs, go to: http://developer.apple.com/bugreporter/
+
+*/
+
+#ifndef MEError_h
+#define MEError_h
+
+#import <Foundation/Foundation.h>
+#import <CoreMedia/CMBase.h>
+
+#pragma mark - MEFormatReader Error codes
+
+ME_EXPORT NSErrorDomain const MediaExtensionErrorDomain API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos);
+
+/*!
+ @enum MEError
+ @abstract MediaExtension framework error codes.
+ @discussion These error codes are returned in the NSError object in the event a method fails.
+ @constant MEErrorUnsupportedFeature
+ Returned if the extension does not support an aspect of the media.
+ @constant MEErrorAllocationFailure
+ Returned if the extension cannot allocate memory.
+ @constant MEErrorInvalidParameter
+ Returned if the extension received an invalid parameter.
+ @constant MEErrorParsingFailure
+ Returned if any type of error occurred while parsing the media.
+ @constant MEErrorInternalFailure
+ Returned if the extension encountered an internal operation failure (e.g. code loading).
+ @constant MEErrorPropertyNotSupported
+ Returned if the extension encountered a property it does not support reading/writing to.
+ @constant MEErrorNoSuchEdit
+ Returned if the plugin track reader is requested to return an edit that is out of range.
+ @constant MEErrorNoSamples
+ Returned if the plugin sample cursor cannot be created because there are no samples in the track, or if a loadSampleBufferContainingSamplesToEndCursor request is made that cannot be satisfied.
+ @constant MEErrorLocationNotAvailable
+ Returned to indicate a specific sample is not contiguous, spans more than one file, or is for some other reason unsuitable for reading directly from a file. For such samples, clients must call loadSampleBufferContainingSamplesToEndCursor.
+ @constant MEErrorEndOfStream
+ Returned if the end of the source file has been reached.
+ @constant MEErrorPermissionDenied
+ Returned if an invalid operation is requested by the client on a byte source.
+ @constant MEErrorReferenceMissing
+ Returned if a decoder is asked to decode a sample without decoding the required reference frame dependencies first.
+*/
+typedef NS_ERROR_ENUM(MediaExtensionErrorDomain, MEError) {
+ MEErrorUnsupportedFeature = -19320,
+ MEErrorAllocationFailure = -19321,
+ MEErrorInvalidParameter = -19322,
+ MEErrorParsingFailure = -19323,
+ MEErrorInternalFailure = -19324,
+ MEErrorPropertyNotSupported = -19325,
+
+ MEErrorNoSuchEdit = -19326,
+ MEErrorNoSamples = -19327,
+ MEErrorLocationNotAvailable = -19328,
+
+ MEErrorEndOfStream = -19329,
+ MEErrorPermissionDenied = -19330,
+
+ MEErrorReferenceMissing = -19331,
+};
+
+#endif /* MEError_h */
diff -ruN /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEExtensionPlugin.h /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEExtensionPlugin.h
--- /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEExtensionPlugin.h 1969-12-31 19:00:00
+++ /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEExtensionPlugin.h 2023-05-31 09:13:09
@@ -0,0 +1,56 @@
+/*
+ File: MEExtensionPlugin.h
+
+ Framework: MediaExtension
+
+ Copyright © 2023 Apple Inc. All rights reserved.
+
+ To report bugs, go to: http://developer.apple.com/bugreporter/
+
+*/
+
+#ifndef MEExtensionPlugin_h
+#define MEExtensionPlugin_h
+
+/*!
+ @abstract Extension point names identify a bundle as a particular type of extension.
+ @constant kMEFormatReaderExtensionPointName
+ The extension point name for MediaExtension MediaToolbox format readers.
+ @constant kMEVideoDecoderExtensionPointName
+ The extension point name for MediaExtension VideoToolbox decoders.
+*/
+#define kMEFormatReaderExtensionPointName @"com.apple.mediaextension.formatreader"
+#define kMEVideoDecoderExtensionPointName @"com.apple.mediaextension.videodecoder"
+
+
+/*!
+ @abstract Extension attribute field keys for MediaExtension format reader plugin bundles.
+ @constant kMEFormatReaderClassImplementationID
+ The identifier for the format reader. This should be of the form "com.apple.mediatoolbox.formatreader.xxx".
+ @constant kMEFormatReaderUTTypeArrayKey
+ The array of UTType identifiers supported by the format reader plugin.
+ @constant kMEFormatReaderFileNameExtensionArrayKey
+ The array of file extensions supported by the format reader plugin. This should include file extensions for any type of related files.
+ @constant kMEFormatReaderObjectNameKey
+ The user readable name for the format reader.
+*/
+#define kMEFormatReaderClassImplementationIDKey @"ClassImplementationID"
+#define kMEFormatReaderUTTypeArrayKey @"MTUTTypeArray"
+#define kMEFormatReaderFileNameExtensionArrayKey @"MTFileNameExtensionArray"
+#define kMEFormatReaderObjectNameKey @"ObjectName"
+
+/*!
+ @abstract Extension attribute field keys for MediaExtension video decoder plugin bundles.
+ @constant kMEVideoDecoderClassImplementationIDKey
+ The identifier for the decoder. This should be of the form "com.apple.videotoolbox.videodecoder.xxx".
+ @constant kMEVideoDecoderCodecTypeKey
+ The four character code for the codec type, as a string.
+ @constant kMEVideoDecoderObjectNameKey
+ The user readable name for the decoder.
+*/
+#define kMEVideoDecoderClassImplementationIDKey @"ClassImplementationID"
+#define kMEVideoDecoderCodecTypeKey @"CodecType"
+#define kMEVideoDecoderObjectNameKey @"ObjectName"
+
+
+#endif /* MEExtensionPlugin_h */
diff -ruN /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEFormatReader.h /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEFormatReader.h
--- /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEFormatReader.h 1969-12-31 19:00:00
+++ /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEFormatReader.h 2023-05-31 09:13:10
@@ -0,0 +1,1151 @@
+/*
+ File: MEFormatReader.h
+
+ Framework: MediaExtension
+
+ Copyright © 2023 Apple Inc. All rights reserved.
+
+
+ Overview
+
+ This file contains the interface/protocol for MediaExtension format readers. Developers who wish to build MediaExtension
+ format readers using this API should contact Apple Worldwide Developer Relations to request access to the managed
+ entitlement "com.apple.developer.mediaextension.formatreader", specifying the list of concrete type identifiers and file
+ name extensions they want to support. Once approved, developers will be able to download a provisioning profile authorizing
+ their format readers to run. For more information about managed entitlements see:
+ https://developer.apple.com/help/account/reference/provisioning-with-managed-capabilities/
+
+
+ MediaExtension Format Reader Info.plist File Information
+
+ MediaExtension format readers will need to include two specialized dictionaries in their Info.plist files. One dictionary
+ is required and describes ExtensionKit information, while the other is optional and registers the format reader media format
+ with the system.
+
+ EXAppExtensionAttributes Dictionary
+
+ The EXAppExtensionAttributes dictionary is required by ExtensionKit. The following keys will be needed for MediaExtension
+ format readers:
+
+ - ClassImplementationID
+ This should be a string similar to the bundle identifier of the format reader. It should start with the reverse
+ domain identifier of the developer to prevent collisions with other developers, and for clarity contain
+ ".formatreader." and the name of the media format. If the developer envisions multiple variants of the same media
+ format, the name should include strings to make each format reader unique. An example might be something like
+ "com.mycompany.formatreader.mymediaformat.formatvariant".
+ - EXExtensionPointIdentifier
+ The string "com.apple.mediaextension.formatreader" (kMEFormatReaderExtensionPointName).
+ - EXExtensionPrincipalClass
+ The name of the format reader factory class, conforming to the MEFormatReaderExtension protocol.
+ - MTFileNameExtensionArray
+ An array of strings describing the file name extension strings (without the .) of all file types supported
+ by the format reader. There should be at least one entry for each type of media file supported.
+ - MTUTTypeArray
+ An array of strings describing the UTType identifier associated with the media the format reader supports. There
+ should be at least one entry for the media type that is supported.
+ - ObjectName
+ A user-readable string describing the format reader. This string is used for uniquely identifying format readers
+ and possibly for debug logging but is typically not visible to users.
+
+ UTExportedTypeDeclarations Dictionary
+
+ The UTExportedTypeDeclarations dictionary is optional and allows the format reader to register its supported format
+ from the MTUTTypeArray above with the system so that media files can be recognized and opened by other applications.
+ For general information on how to make a UTExportedTypeDeclarations dictionary, see documentation here:
+ https://developer.apple.com/documentation/bundleresources/information_property_list/utexportedtypedeclarations
+
+ - UTTypeDescription
+ A user-readable string describing the media "kind". This name will be displayed in Finder. This string can be
+ localized by making localized variants of the Info.plist file.
+ - UTTypeConformsTo
+ This is an array of UTType identifiers. The first entry should be set to the abstract type for MediaExtension
+ format readers, "com.apple.mediaextension-content". This type also conforms to higher level abstract types such as
+ "public.movie" and "public.audiovisual-content". Additional types can also be included as well if desired.
+ - UTTypeIdentifier
+ This should match the value in MTUTTypeArray in the EXAppExtensionAttributes dictionary.
+ - UTTypeTagSpecification
+ Inside the UTTypeTagSpecification dictionary, the public.filename-extension key should have a value matching the
+ MTFileNameExtensionArray in the EXAppExtensionAttributes dictionary.
+ - public.mime-type
+ This key is optional but should be a MIME type that corresponds to the format.
+
+
+ To report bugs, go to: http://developer.apple.com/bugreporter/
+
+*/
+
+#ifndef MEFormatReader_h
+#define MEFormatReader_h
+
+#import <Foundation/Foundation.h>
+#import <AVFoundation/AVFoundation.h>
+#import <CoreMedia/CMSampleBuffer.h>
+#import <CoreMedia/CMFormatDescription.h>
+#import <CoreMedia/CMTimeRange.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+// forward declarations
+@class MEFileInfo;
+@class METrackInfo;
+@class MEHEVCDependencyInfo;
+@class MESampleCursorChunk;
+@class MESampleLocation;
+@class MEEstimatedSampleLocation;
+@class MEByteSource;
+@protocol METrackReader;
+@protocol MESampleCursor;
+@protocol MEFormatReader;
+
+#pragma mark - MEFormatReader Defines
+
+/*!
+ @enum MEFileInfoFragmentsStatus
+ @discussion Describes whether a file supports or contains fragments. For QuickTime movie and ISO files, it indicates the presence of an 'mvex' box, which is necessary in order to signal the possible presence of later 'moof' boxes.
+ @constant MEFileInfoCouldNotContainFragments
+ The file is not capable of being extended by fragments.
+ @constant MEFileInfoContainsFragments
+ The file is capable of being extended by fragments *and* contains at least one fragment.
+ @constant MEFileInfoCouldContainButDoesNotContainFragments
+ The file is capable of being extended by fragments, but does not contain any fragments.
+*/
+typedef NS_ENUM(NSInteger, MEFileInfoFragmentsStatus) {
+ MEFileInfoCouldNotContainFragments = 0,
+ MEFileInfoContainsFragments = 1,
+ MEFileInfoCouldContainButDoesNotContainFragments = 2
+} NS_SWIFT_NAME(MEFileInfo.FragmentsStatus);
+
+
+/*!
+ @enum MEFormatReaderParseAdditionalFragmentsStatus
+ @abstract Informational status flags returned by parseAdditionalFragmentsWithCompletionHandler.
+ @discussion A combination of these values may be returned in the statusOut field from parseAdditionalFragmentsWithCompletionHandler.
+ @constant MEFormatReaderParseAdditionalFragmentsStatusSizeIncreased
+ Set if the size of the file increased.
+ @constant MEFormatReaderParseAdditionalFragmentsStatusFragmentAdded
+ Set if one or more fragments were added.
+ @constant MEFormatReaderParseAdditionalFragmentsStatusFragmentsComplete
+ Set if no more fragments can be added. Further calls to parseAdditionalFragmentsWithCompletionHandler will return an error.
+*/
+typedef NS_OPTIONS(NSUInteger, MEFormatReaderParseAdditionalFragmentsStatus) {
+ MEFormatReaderParseAdditionalFragmentsStatusSizeIncreased = 1 << 0,
+ MEFormatReaderParseAdditionalFragmentsStatusFragmentAdded = 1 << 1,
+ MEFormatReaderParseAdditionalFragmentsStatusFragmentsComplete = 1 << 2,
+};
+
+#pragma mark - MEFormatReaderInstantiationOptions
+
+/*!
+ @class MEFormatReaderInstantiationOptions
+ @abstract A class that encapsulates options to be passed to MEFormatReaderExtension
+ @discussion The class MEFormatReaderInstantiationOptions is mutable, with options set through instance properties.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEFormatReaderInstantiationOptions : NSObject <NSCopying>
+
+/*!
+ @property allowIncrementalFragmentParsing
+ @abstract Enables support for parsing additional fragments
+ @discussion If YES, requests that the MEFormatReader be configured to support calls to parseAdditionalFragments. By default the MEFormatReader does not support calls to parseAdditionalFragments.
+*/
+@property (nonatomic, readonly) BOOL allowIncrementalFragmentParsing;
+
+@end
+
+
+#pragma mark - MEFormatReaderExtension
+
+/*!
+ @protocol MEFormatReaderExtension
+ @abstract Provides a factory method for creating MEFormatReader objects.
+ @discussion The MEFormatReaderExtension protocol provides a factory method to create a new MEFormatReader when provided with an MEByteSource object. MEFormatReaderExtension is always instantiated by the Media Toolbox, and the MEByteSource object is also created by Media Toolbox based on the specified media asset. All async methods in MEFormatReader/METrackReader/MESampleCursor are allowed to call the completion handlers on any thread or queue.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol MEFormatReaderExtension <NSObject>
+
+- (instancetype)init;
+
+/*!
+ @method formatReaderWithByteSource
+ @abstract The factory method to create a new MEFormatReader.
+ @discussion Creates a new MEFormatReader given an MEByteSource, with optional MEFileReaderInstantiationOptions.
+ @param primaryByteSource
+ The primary MEByteSource instance for the format reader. The MEFormatReader should retain this object for use when responding to later requests for information, and release it in the object finalize method.
+ @param options
+ An optional instance of MEFormatReaderInstantiationOptions
+ @param error
+ On return, if initialization of the MEFormatReader fails, points to an NSError describing the nature of the failure.
+ @result A newly created instance of MEFormatReader.
+*/
+- (id<MEFormatReader> _Nullable)formatReaderWithByteSource:(MEByteSource *)primaryByteSource options:(MEFormatReaderInstantiationOptions * _Nullable)options error:(NSError *__autoreleasing _Nullable * _Nullable)error;
+
+@end
+
+
+#pragma mark - MEFormatReader
+
+/*!
+ @protocol MEFormatReader
+ @abstract The primary object for a MediaExtension format reader, representing a single media asset.
+ @discussion The MEFormatReader protocol provides an interface for the MediaToolbox to interact with MediaExtension format readers, which provide information about media assets. MEFormatReader objects are always instantiated by the MediaToolbox. To create an MEFormatReader object, MediaToolbox first creates a primary MEByteSource object around a source media asset. It then creates an MEFormatReaderExtension object and calls its formatReaderWithByteSource method. MEFormatReaders should expect to run in a sandboxed process with restricted access to the filesystem, network and other kernel resources.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol MEFormatReader <NSObject>
+
+/*!
+ @method loadFileInfoWithCompletionHandler
+ @abstract Asynchronously loads the MEFileInfo object with properties of the media asset.
+ @discussion This method should provide either a valid MEFileInfo object or nil in case of failure. If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'fileInfo'
+ The returned MEFileInfo object.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadFileInfoWithCompletionHandler:(void (^)(MEFileInfo* _Nullable fileInfo, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:fileInfo());
+
+/*!
+ @method loadMetadataWithCompletionHandler
+ @abstract Asynchronously loads the array of AVMetadataItems representing metadata from the media asset.
+ @discussion This method should provide either a valid NSArray or nil. If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'metadata'
+ The returned NSArray of AVMetadataItem objects.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadMetadataWithCompletionHandler:(void (^)(NSArray< AVMetadataItem * > * _Nullable metadata, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:metadata());
+
+/*!
+ @method loadTrackReadersWithCompletionHandler
+ @abstract Asynchronously loads the array of METrackReader objects representing the tracks in the media asset.
+ @discussion This method should provide either a valid NSArray object or nil. If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'trackReaders'
+ The returned NSArray of METrackReader objects.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadTrackReadersWithCompletionHandler:(void (^)(NSArray< id<METrackReader> > * _Nullable trackReaders, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:trackReaders());
+
+@optional
+
+/*!
+ @method parseAdditionalFragmentsWithCompletionHandler
+ @abstract Asynchronously incorporates additional fragments that have been appended since the file was last parsed.
+ @discussion Parses additional fragments of the media asset if they exist. Media asset formats that do not support incremental fragments do not need implement this method. The MEFormatReader must have been instantiated with the MEFormatReaderInstantiationOptions property allowIncrementalFragmentParsing set to YES. Does nothing if the MEFileInfo property couldContainFragments is NO. Once this function returns an error, later calls should also always fail.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'fragmentStatus'
+ The returned MEFormatReaderParseAdditionalFragmentsStatus flags with status information.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil. Returns an error of MEFormatReaderErrorUnsupportedFeature if the MEFormatReaderInstantiationOptions property allowIncrementalFragmentParsing was not set to YES at creation time. Returns an error of MEFormatReaderErrorParsingFailure if there was a parsing failure.
+*/
+- (void)parseAdditionalFragmentsWithCompletionHandler:(void (^)(MEFormatReaderParseAdditionalFragmentsStatus fragmentStatus, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(parseAdditionalFragments());
+
+@end
+
+
+#pragma mark - MEFileInfo
+
+/*!
+ @interface MEFileInfo
+ @abstract A class incorporating file properties parsed from the media asset.
+ @discussion The MEFileInfo properties are parsed asynchronously through the loadFileInfoWithCompletionHandler method of MEFormatReader.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEFileInfo : NSObject <NSCopying>
+
+/*!
+ @property duration
+ @abstract The duration of the media asset if known, otherwise kCMTimeInvalid.
+*/
+@property (nonatomic) CMTime duration;
+
+/*!
+ @property fragmentsStatus
+ @abstract Indicates if the media asset is capable of being extended by fragments or contains fragments
+ @discussion See the MEFileInfoFragmentsStatus values for details of the return value. The value will default to MEFileInfoCouldNotContainFragments.
+*/
+@property (nonatomic) MEFileInfoFragmentsStatus fragmentsStatus;
+
+@end
+
+
+#pragma mark - METrackReader
+
+/*!
+ @protocol METrackReader
+ @abstract Provides information about a track within a media asset.
+ @discussion The MEFormatReader creates METrackReader objects for each track in the media asset. MEFormatReader plugin authors should provide code to implement the METrackReader protocol methods. Since not every method or property applies to every track type, those that don't make sense should return default values.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol METrackReader <NSObject>
+
+/*!
+ @method loadTrackInfoWithCompletionHandler
+ @abstract Asynchronously loads the METrackInfo object with properties of the media asset track.
+ @discussion This method should provide either a valid METrackInfo object or nil. If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'trackInfo'
+ The returned METrackInfo object if the method succeeds, otherwise nil.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+ */
+- (void)loadTrackInfoWithCompletionHandler:(void (^)(METrackInfo* _Nullable trackInfo, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:trackInfo());
+
+/*!
+ @method generateSampleCursorAtPresentationTimeStamp
+ @abstract Provides a new MESampleCursor object pointing to the sample at or near the specified presentation timestamp.
+ @discussion The new MESampleCursor will point to the last sample with a PTS less than or equal to presentationTimeStamp, or if there are no such samples, the first sample in PTS order.
+ @param presentationTimeStamp
+ The desired PTS.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'sampleCursor'
+ The returned MESampleCursor if the method succeeds, otherwise nil.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)generateSampleCursorAtPresentationTimeStamp:(CMTime)presentationTimeStamp completionHandler:(void (^)(id<MESampleCursor> _Nullable sampleCursor, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(sampleCursor(atPresentationTimeStamp:));
+
+/*!
+ @method generateSampleCursorAtFirstSampleInDecodeOrderWithCompletionHandler
+ @abstract Provides a new MESampleCursor object pointing to the first sample in decode order.
+ @discussion The new MESampleCursor will point to the first sample in decode order regardless of the presentation time.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'sampleCursor'
+ The returned MESampleCursor if the method succeeds, otherwise nil.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)generateSampleCursorAtFirstSampleInDecodeOrderWithCompletionHandler:(void (^)(id<MESampleCursor> _Nullable sampleCursor, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:sampleCursorAtFirstSampleInDecodeOrder());
+
+/*!
+ @method generateSampleCursorAtLastSampleInDecodeOrderWithCompletionHandler
+ @abstract Provides a new MESampleCursor object pointing to the last sample in decode order.
+ @discussion The new MESampleCursor will point to the last sample in decode order regardless of the presentation time.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'sampleCursor'
+ The returned MESampleCursor if the method succeeds, otherwise nil.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)generateSampleCursorAtLastSampleInDecodeOrderWithCompletionHandler:(void (^)(id<MESampleCursor> _Nullable sampleCursor, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:sampleCursorAtLastSampleInDecodeOrder());
+
+@optional
+
+/*!
+ @method loadUneditedDurationWithCompletionHandler
+ @abstract Returns the duration of the track as a CMTime disregarding any edits.
+ @discussion This information may be used by the MediaToolbox to validate edit information or to check if the media is suitable for gapless playback.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'uneditedDuration'
+ A valid duration if the method succeeds, otherwise kCMTimeInvalid.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadUneditedDurationWithCompletionHandler:(void (^)(CMTime uneditedDuration, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:uneditedDuration());
+
+/*!
+ @method loadTotalSampleDataLengthWithCompletionHandler
+ @abstract Loads the total size in bytes of all the samples in the track.
+ @discussion If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'totalSampleDataLength'
+ A valid data length if the method succeeds, otherwise 0.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadTotalSampleDataLengthWithCompletionHandler:(void (^)(int64_t totalSampleDataLength, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:totalSampleDataLength());
+
+/*!
+ @method loadEstimatedDataRateWithCompletionHandler
+ @abstract Loads the approximate data rate of the track in bytes per second as a floating point number.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'estimatedDataRate'
+ A valid data rate if the method succeeds, otherwise 0.0.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadEstimatedDataRateWithCompletionHandler:(void (^)(Float32 estimatedDataRate, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:estimatedDataRate());
+
+/*!
+ @method loadMetadataWithCompletionHandler
+ @abstract Asynchronously loads an NSArray object with metadata from the media asset track.
+ @discussion This method should provide either a valid NSArray object or nil. If the method fails, the NSError will contain error information.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'metadata'
+ An NSArray of AVMetadataItem objects if the method succeeds, otherwise nil.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadMetadataWithCompletionHandler:(void (^)(NSArray< AVMetadataItem * > * _Nullable metadata, NSError * _Nullable error))completionHandler NS_SWIFT_ASYNC_NAME(getter:metadata());
+
+@end
+
+
+#pragma mark - METrackInfo
+
+/*!
+ @interface METrackInfo
+ @abstract A class incorporating track properties parsed from the media asset.
+ @discussion The METrackInfo properties are parsed asynchronously through the loadTrackInfoWithCompletionHandler method of METrackReader.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface METrackInfo : NSObject <NSCopying>
+
++ (instancetype)new NS_UNAVAILABLE;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/*!
+ @method initWithMediaType
+ @abstract Initializes a new METrackInfo instance.
+ @discussion The main initializer for the METrackInfo class. After creating the class, the METrackReader should fill in all the relevant properties with the values read in from the media track.
+ @param mediaType
+ The media type of the track.
+ @param trackID
+ An integer identifying the track within the media asset.
+ @param formatDescriptions
+ The format descriptions for the track, as an NSArray.
+ @result A new instance of METrackInfo.
+*/
+- (instancetype)initWithMediaType:(CMMediaType)mediaType trackID:(CMPersistentTrackID)trackID formatDescriptions:(NSArray*)formatDescriptions NS_DESIGNATED_INITIALIZER NS_REFINED_FOR_SWIFT;
+
+/*!
+ @property mediaType
+ @abstract The media type of the track.
+ @discussion This value is set through the class initializer.
+*/
+@property (nonatomic, readonly) CMMediaType mediaType;
+
+/*!
+ @property trackID
+ @abstract An integer identifying the track within the media asset.
+ @discussion The track ID is used to uniquely identify the track within the MEFormatReader. Track IDs must be unique within a media asset but do not need to be unique across assets. If a media format does not have a native concept of track IDs, track IDs may be assigned starting from 1. The track ID value of 0 is reserved to indicate an invalid track ID. This value is set through the class initializer.
+*/
+@property (nonatomic, readonly) CMPersistentTrackID trackID;
+
+/*!
+ @property enabled
+ @abstract A BOOL value indicating whether the track is enabled by default.
+*/
+@property (nonatomic, getter=isEnabled) BOOL enabled;
+
+/*!
+ @property formatDescriptions
+ @abstract The format descriptions for the track, as an NSArray.
+ @discussion This value is set through the class initializer.
+*/
+@property (nonatomic, copy, readonly) NSArray* formatDescriptions NS_REFINED_FOR_SWIFT;
+
+@end
+
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface METrackInfo (OptionalProperties)
+
+/*!
+ @property naturalTimescale
+ @abstract The natural timescale of the track, as a CMTimeScale value.
+*/
+@property (nonatomic) CMTimeScale naturalTimescale;
+
+/*!
+ @property trackEdits
+ @abstract Returns the array of edit segments for the given track.
+ @discussion Each NSValue in the array contains a CMTimeMapping object describing the track edit. The CMTimeMapping.target time ranges for successive edits must partition the time range from 0 to the track's duration. In other words, for edit index = 0 the CMTimeMapping.target.start must be kCMTimeZero, while for edit index > 0, the CMTimeMapping.target.start must match the CMTimeRangeGetEnd(CMTimeMapping.target) for edit (index - 1). It is valid for a track to have an empty trackEdits array; this means that there is nothing at all in the track and the track duration is zero. If this property is implemented for media asset formats that do not support edit segments, it can return nil.
+*/
+@property (nonatomic, copy, nullable) NSArray< NSValue * >* trackEdits NS_REFINED_FOR_SWIFT;
+
+
+@end
+
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface METrackInfo (LanguageTagOptionalProperties)
+
+/*!
+ @property extendedLanguageTag
+ @abstract Indicates the language tag associated with the track, as an IETF BCP 47 (RFC 4646) language identifier.
+ @discussion This property may be used by the MediaToolbox to group similar language tracks together or to match audio and caption tracks. If no language tag is indicated, this property should be set to nil.
+*/
+@property (nonatomic, copy, nullable) NSString* extendedLanguageTag;
+
+@end
+
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface METrackInfo (VideoSpecificOptionalProperties)
+
+/*!
+ @property naturalSize
+ @abstract Indicates the natural dimensions of the media data referenced by the track as a CGSize.
+ @discussion This property is only valid for tracks with visual media types and should return CGSizeZero if implemented for other track types.
+*/
+@property (nonatomic) CGSize naturalSize;
+
+/*!
+ @property preferredTransform
+ @abstract Indicates the preferred affine display transform of the track media for visual display.
+ @discussion Returns an CGAffineTransform representing the preferred affine transform of the track for visual display. This property is only valid for tracks with visual media types and should return CGAffineTransformIdentity if implemented for other track types.
+*/
+@property (nonatomic) CGAffineTransform preferredTransform;
+
+/*!
+ @property nominalFrameRate
+ @abstract The frame rate of the track, in frames per second, as a 32-bit floating point number.
+ @discussion For field-based video tracks that carry one field per media sample, the value of this property is the field rate, not the frame rate. This information from this property may be used by the MediaToolbox to calculate the maximum playback speed.
+*/
+@property (nonatomic) Float32 nominalFrameRate;
+
+/*!
+ @property requiresFrameReordering
+ @abstract Indicates whether frame reordering occurs in the track.
+ @discussion The value is YES if frame reordering occurs, NO otherwise. This property is only valid for tracks with video media type and should return NO for if implemented for other track types.
+*/
+@property (nonatomic) BOOL requiresFrameReordering;
+
+@end
+
+
+#pragma mark - MESampleCursor
+
+/*!
+ @protocol MESampleCursor
+ @abstract Provides information about samples within a track of a media asset.
+ @discussion The Media Toolbox creates an MESampleCursor object by calling one of the METrackReader sample cursor creation methods. It then makes method calls using the MESampleCursor protocol. MESampleCursors can deliver sample data either by providing sample location and sample chunk information, or by directly generating a sample buffer.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol MESampleCursor <NSObject, NSCopying>
+
+/*!
+ @property presentationTimeStamp
+ @abstract The presentation timestamp (PTS) of the sample at the current position of the cursor.
+*/
+@property (nonatomic, readonly) CMTime presentationTimeStamp;
+
+/*!
+ @property decodeTimeStamp
+ @abstract The decode timestamp (DTS) of the sample at the current position of the cursor.
+*/
+@property (nonatomic, readonly) CMTime decodeTimeStamp;
+
+/*!
+ @property currentSampleDuration
+ @abstract Indicates the decode duration of the sample at the receiver's current position.
+ @discussion If the receiver must be advanced past its current position in order to determine the decode duration of the current sample, the value of currentSampleDuration is equal to kCMTimeIndefinite. This can occur with streaming formats such as MPEG-2 transport streams.
+*/
+@property (nonatomic, readonly) CMTime currentSampleDuration;
+
+/*!
+ @property currentSampleFormatDescription
+ @abstract The format description for the sample at the current position of the cursor.
+*/
+@property (nonatomic, readonly, nullable) __attribute__((NSObject)) CMFormatDescriptionRef currentSampleFormatDescription;
+
+/*!
+ @method stepInDecodeOrderByCount
+ @abstract Moves the cursor a given number of samples in decode order.
+ @discussion If the request would advance the cursor past the last sample or before the first sample, the cursor should be set to point to that limiting sample and actualStepCount will report the number of samples the cursor was able to move.
+ @param stepCount
+ The number of samples to move. If positive, step forward this many samples. If negative, step backward (-stepCount) samples.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'actualStepCount'
+ The final count of steps taken.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)stepInDecodeOrderByCount:(int64_t)stepCount completionHandler:(void (^)(int64_t actualStepCount, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(stepInDecodeOrder(by:completionHandler:));
+
+/*!@
+ @method stepInPresentationOrderByCount
+ @abstract Moves the cursor a given number of samples in presentation order.
+ @discussion If the request would advance the cursor past the last sample or before the first sample, the cursor should be set to point to that limiting sample and actualStepCount will report the number of samples the cursor was able to move. If decode order and presentation order are the same (ie, the samples are not reordered), this method should have the same effect as stepInDecodeOrderByCount.
+ @param stepCount
+ The number of samples to move. If positive, step forward this many samples. If negative, step backward (-stepCount) samples.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'actualStepCount'
+ The final count of steps taken.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)stepInPresentationOrderByCount:(int64_t)stepCount completionHandler:(void (^)(int64_t actualStepCount, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(stepInPresentationOrder(by:completionHandler:));
+
+/*!
+ @method stepByDecodeTime
+ @abstract Moves the cursor by a given deltaDecodeTime on the decode timeline.
+ @discussion If the request would advance the cursor past the end of the last sample or before the first sample, the cursor should be set to point to that limiting sample, and positionWasPinned will be set to YES. Otherwise, positionWasPinned will be set to NO.
+ @param deltaDecodeTime
+ The cursor is moved to the sample at decode time (current sample decode time + deltaDecodeTime).
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'actualDecodeTime'
+ The final cursor decode time. Because sample cursors snap to sample boundaries when stepped, this value may not be equal to (current sample decode time + deltaDecodeTime) even if the cursor was not pinned.
+ 'positionWasPinned'
+ YES if the request attempted to advance the cursor beyond the track limits, otherwise NO.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)stepByDecodeTime:(CMTime)deltaDecodeTime completionHandler:(void (^)(CMTime actualDecodeTime, BOOL positionWasPinned, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(stepByDecodeTime(_:completionHandler:));
+
+/*!
+ @method stepByPresentationTime
+ @abstract Moves the cursor by a given deltaPresentationTime on the presentation timeline.
+ @discussion If the request would advance the cursor past the end of the last sample or before the first sample, the cursor should be set to point to that limiting sample, and positionWasPinned will be set to YES. Otherwise, positionWasPinned will be set to NO.
+ @param deltaPresentationTime
+ The cursor is moved to the sample at presentation time (current sample presentation time + deltaPresentationTime).
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'actualPresentationTime'
+ The final cursor presentation time. Because sample cursors snap to sample boundaries when stepped, this value may not be equal to (current sample presentation time + deltaPresentationTime) even if the cursor was not pinned.
+ 'positionWasPinned'
+ YES if the request attempted to advance the cursor beyond the track limits, otherwise NO.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)stepByPresentationTime:(CMTime)deltaPresentationTime completionHandler:(void (^)(CMTime actualPresentationTime, BOOL positionWasPinned, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(stepByPresentationTime(_:completionHandler:));
+
+@optional
+
+/*!
+ @property syncInfo
+ @abstract Retrieves decoder synchronization information about the sample pointed to by the cursor.
+ @discussion The returned value will be an AVSampleCursorSyncInfo structure with any valid flags set. If this kind of synchronization information does not make sense for the sequence of samples, this property should not be implemented.
+*/
+@property (nonatomic, readonly) AVSampleCursorSyncInfo syncInfo;
+
+/*!
+ @property sampleDependencyInfo
+ @abstract Retrieves generic dependency information about the sample pointed to by the cursor.
+ @discussion The returned value will be an AVSampleCursorDependencyInfo structure with any valid flags set. If this kind of dependency information does not make sense for the sequence of samples, this property should not be implemented.
+*/
+@property (nonatomic, readonly) AVSampleCursorDependencyInfo dependencyInfo;
+
+/*!
+ @property hevcDependencyInfo
+ @abstract Retrieves additional information necessary to recover complete sample dependency information.
+ @discussion hevcDependencyInfo is an optional property that communicates additional sample dependency information not contained in syncInfo or dependencyInfo. Examples of this are the NAL unit type of an HEVC sync sample or the number of samples necessary to refresh the decoder after a USAC Independent Frame. For formats where this information does not make sense, this property should be set to nil.
+*/
+@property (nonatomic, readonly, copy) MEHEVCDependencyInfo* hevcDependencyInfo;
+
+/*!
+ @property decodeTimeOfLastSampleReachableByForwardSteppingThatIsAlreadyLoadedByByteSource
+ @abstract Retrieves the duration of the content playable from the cursor as a CMTime.
+ @discussion Indicates the time difference between the current cursor DTS and last reachable sample DTS. This is necessary to play assets with e.g. HTTP URLs as it indicates what samples have already been loaded by the byte source.
+*/
+@property (nonatomic, readonly) CMTime decodeTimeOfLastSampleReachableByForwardSteppingThatIsAlreadyLoadedByByteSource;
+
+/*!
+ @method samplesWithEarlierDTSsMayHaveLaterPTSsThanCursor
+ @abstract Tests for an earlier boundary in sample reordering.
+ @discussion This method tests for a boundary in the reordering from decode order to presentation order, determining when it could be possible for any sample earlier in decode order than the receiver current sample to have a presentation time later than the current sample of the specified cursor. This test can be used to limit backward scans, e.g. to start forward playback. For example, with the argument cursor fixed, step the receiver backwards until it is impossible for any earlier-in-decode-order receiver samples to be later-in-presentation-order than the argument cursor sample. If sample reordering does not make sense for the track content, this method should not be implemented. If this method is not implemented, clients should assume the samples are not reordered.
+ @param cursor
+ An instance of id<MESampleCursor> with which to test the sample reordering boundary.
+ @result YES if it is possible earlier samples in decode order than that of the receiver can have a presentation timestamp later than that of the specified sample cursor, otherwise NO. If the receiver and argument cursors reference different sequences of samples, for example if they were created by different instances of MTTrackReader, the results are undefined.
+*/
+-(BOOL)samplesWithEarlierDTSsMayHaveLaterPTSsThanCursor:(id<MESampleCursor>)cursor NS_SWIFT_NAME(samplesWithEarlierDTSsMayHaveLaterPTSs(than:));
+
+/*!
+ @method samplesWithLaterDTSsMayHaveEarlierPTSsThanCursor
+ @abstract Tests for a later boundary in sample reordering.
+ @discussion This method tests for a boundary in the reordering from decode order to presentation order, determining when it could be possible for any sample later in decode order than the receiver current sample to have a presentation time earlier than the current sample of the specified cursor. This test can be used to limit forward scans, e.g. to start reverse playback. For example, with the argument cursor fixed, step the receiver forwards until it is impossible for any later-in-decode-order receiver samples to be earlier-in-presentation-order than the argument cursor sample. If sample reordering does not make sense for the track content, this method should not be implemented. If this method is not implemented, clients should assume the samples are not reordered.
+ @param cursor
+ An instance of id<MESampleCursor> with which to test the sample reordering boundary.
+ @result YES if it is possible later samples in decode order than that of the receiver can have a presentation timestamp earlier than that of the specified sample cursor, otherwise NO. If the receiver and argument cursors reference different sequences of samples, for example if they were created by different instances of MTTrackReader, the results are undefined.
+*/
+-(BOOL)samplesWithLaterDTSsMayHaveEarlierPTSsThanCursor:(id<MESampleCursor>)cursor NS_SWIFT_NAME(samplesWithLaterDTSsMayHaveEarlierPTSs(than:));
+
+/*!
+ Overview of MESampleCursor Sample Delivery
+
+ An MESampleCursor can return sample data to CoreMedia in one of two ways. Either it can return just information about the sample data location in the media and let CoreMedia do the actual reading of the data, or it can read the data iself and return sample buffers directly.
+
+ The MESampleCursor allows CoreMedia to read the data
+ ----------------------------------------------------
+
+ This is the preferred method to deliver sample data. It allows CoreMedia to optimize data I/O read operations, potentially combining multiple smaller reads into a single larger read for better performance. There are four methods available to deliver the required sample location information.
+
+ - sampleLocationReturningError:error
+ This is the main method to return sample location information. In order to allow CoreMedia to optimize I/O, the MESampleCursor must provide either this method or the two methods estimatedSampleLocationReturningError: and refineSampleLocation:. For formats where samples are stored in contiguous groups or blocks, this method will be used together with chunkDetailsReturningError:. For formats where samples are stored individually (e.g. video), implementation of chunkDetailsReturningError: is optional.
+
+ - chunkDetailsReturningError:error
+ For formats where samples are stored in contiguous groups, blocks, or chunks (e.g. audio), this method is used to indicate details about how many samples are stored in each grouping and the sample offset within the group. After determining the chunk information, CoreMedia will then call either sampleLocationReturningError: or estimatedSampleLocationReturningError: followed by refineSampleLocation: to locate individual samples within the chunk.
+
+ - estimatedSampleLocationReturningError:error
+ In some cases it is not possible to directly determine the sample location and return it through sampleLocationReturningError:. Instead, the sample location must be determined in two steps: a coarse estimatation followed by a refinement operation to find the exact location. This method returns the coarse estimation of the location, and the second step is refineSampleLocation:refinementData: to return the exact location. Both methods must be implemented to support this functionality.
+
+ - refineSampleLocation:refinementData:refinementDataLength:refinedLocation:error
+ This method returns the exact sample location information as a second step after the coarse estimate from estimatedSampleLocationReturningError:. This method must be implemented together with estimatedSampleLocationReturningError: in order to support the two-step location functionality.
+
+ The MESampleCursor reads sample buffers directly
+ ------------------------------------------------
+
+ In cases where it is not possible to let CoreMedia read the sample data using location information, the MESampleCursor will need to read the sample data itself using the MEByteSource and deliver sample data buffers to CoreMedia. This is less efficient for data I/O because it does not allow CoreMedia to optimize read operations.
+
+ - loadSampleBufferContainingSamplesToEndCursor:completionHandler:
+ This method delivers sample buffers directly, so it allows the MESampleCursor full flexibility in reading and unpacking the samples from the media. The MESampleCursor must use the MEByteSource directly to seek and read the sample data. This method can deliver sample buffers either with one sample (e.g. for video tracks) or with blocks of samples (e.g. for audio). It is also suitable for cases where samples must be synthesized using metadata from the media (e.g. for timecode tracks).
+
+ Practical Examples
+ ------------------
+
+ (1) Samples are stored in groups interleaved among other samples
+ The MESampleCursor should implement sampleLocationReturningError: and chunkDetailsReturningError: to allow CoreMedia to locate the chunks and find samples inside the chunks.
+
+ (2) Samples are stored in blocks interleaved among other samples, but some samples are non-contiguous
+ The MESampleCursor should implement sampleLocationReturningError:, chunkDetailsReturningError:, and loadSampleBufferContainingSamplesToEndCursor:. For contiguous samples, sampleLocationReturningError: should return with no error and the samples will be read this way. For non-contiguous samples, sampleLocationReturningError: and chunkDetailsReturningError: should return MEErrorLocationNotAvailable and CoreMedia will then attempt to read the samples using loadSampleBufferContainingSamplesToEndCursor:.
+
+ (3) Sample location cannot be directly determined in one step
+ If the sample location cannot be determined as a one-step process but is possible using a two-step, "coarse estimate followed by refinement" process, then the MESampleCursor should implement estimatedSampleLocationReturningError: and refineSampleLocation: instead of sampleLocationReturningError:. If determining the sample location does not fit into either the one-step or two-step model, then the MESampleCursor should implement loadSampleBufferContainingSamplesToEndCursor:.
+
+ (4) Sample data must be unpacked or prepared in some way before delivering to CoreMedia
+ If the sample data cannot be read directly by CoreMedia, then the MESampleCursor should implement loadSampleBufferContainingSamplesToEndCursor: to read the data itself, unpack or prepare it as appropriate, and deliver it in sample buffers.
+
+*/
+
+/*!
+ @method chunkDetailsReturningError
+ @abstract Returns information about the chunk holding the sample indicated by the cursor.
+ @discussion If the sample resides in a contiguous chunk of the file among similar samples, chunkDetails returns information about that chunk. Note: For some media asset formats it is not practical to implement chunkDetails. In this case chunkDetails should return MEErrorLocationNotAvailable and loadSampleBufferContainingSamplesToEndCursor must be used to load the sample data.
+ @param error
+ If provided, returns error information in the event that the method fails.
+ @result Returns an instance of MESampleCursorChunk with details about the chunk if successful, returns NULL and fails with MEErrorLocationNotAvailable if sampleCursor does not support chunkDetails, or returns NULL if the method otherwise fails with error.
+*/
+- (MESampleCursorChunk * _Nullable) chunkDetailsReturningError:(NSError *__autoreleasing _Nullable * _Nullable) error NS_SWIFT_NAME(chunkDetails());
+
+/*!
+ @method sampleLocationReturningError
+ @abstract Returns the location and byte source of the sample indicated by the cursor.
+ @discussion This method is used to allow the system to handle reading the sample data. Sample data is expected to be contiguous. For some media asset formats, most samples are contiguous but there are exceptions; such MESampleCursors should support both sampleLocation and loadSampleBufferContainingSamplesToEndCursor. For samples that are not contiguous, sampleLocation should return MEErrorLocationNotAvailable. For other media asset formats, it is not practical to implement sampleLocation; such MESampleCursors must implement loadSampleBufferContainingSamplesToEndCursor instead.
+ @param error
+ If provided, returns error information in the event that the method fails.
+ @result Returns an instance of MESampleLocation with information about the sample location if successful, returns NULL and fails with MEErrorLocationNotAvailable if the sample is not contiguous or this method is not supported, in which case loadSampleBufferContainingSamplesToEndCursor must be called instead in order to load the sample data, or returns NULL if the method otherwise fails with error.
+*/
+- (MESampleLocation * _Nullable) sampleLocationReturningError:(NSError *__autoreleasing _Nullable * _Nullable) error NS_SWIFT_NAME(sampleLocation());
+
+/*!
+ @method estimatedSampleLocationReturningError
+ @abstract Returns an estimate of the sample location indicated by the cursor that can later be refined using refineSampleLocation.
+ @discussion Optional addition to sampleLocationReturningError. For formats that need to read some data on a per-sample basis to produce the exact sample location, it may be more efficient to read a slightly larger chunk of data containing both the data necessary to produce the exact sample location and the actual sample data. The exact sample location will then be requested in a subsequent call to refineSampleLocation. It is possible to indicate that no refinement is necessary by returning a value for refinementDataLocation that has a zero length. If a non-zero length refinement location is returned, the range for the estimated sample location returned must fully cover the refined range returned by refineSampleLocation and the refinement data location. Note: Implementing estimatedSampleLocationReturningError also requires implementing refineSampleLocation. If the sample indicated by the cursor is not contiguous, this method will return MEErrorLocationNotAvailable. In this case the loadSampleBufferContainingSamplesToEndCursor must be used to load the sample data.
+ @param error
+ If provided, returns error information in the event that the method fails.
+ @result Returns an instance of MEEstimatedSampleLocation with information about the estimated sample location if successful, returns NULL and fails with MEErrorLocationNotAvailable if the sample is not contiguous or this method is not supported, in which case loadSampleBufferContainingSamplesToEndCursor must be called instead in order to load the sample data, or returns NULL if the method otherwise fails with error.
+ */
+- (MEEstimatedSampleLocation * _Nullable) estimatedSampleLocationReturningError:(NSError *__autoreleasing _Nullable * _Nullable)error NS_SWIFT_NAME(estimatedSampleLocation());
+
+/*!
+ @method refineSampleLocation
+ @abstract Produces an exact sample location based on data returned from a call to estimatedSampleLocationReturningError.
+ @discussion See the discussion in estimatedSampleLocationReturningError for details.
+ @param estimatedSampleLocation
+ The value that was previously returned in the MEEstimatedSampleLocation object from estimatedSampleLocationReturningError
+ @param refinementData
+ The refinement data returned from estimateSampleLocation in MEEstimatedSampleLocation.
+ @param refinementDataLength
+ The length of refinementData in bytes.
+ @param refinedLocationOut
+ Returns the exact starting file offset and size of the sample in bytes.
+ @param error
+ If provided, returns error information in the event that the method fails.
+ @result YES if the method succeeds, NO if it fails. If the method fails, error will contain error information.
+*/
+- (BOOL)refineSampleLocation:(AVSampleCursorStorageRange)estimatedSampleLocation
+ refinementData:(const uint8_t *)refinementData
+ refinementDataLength:(size_t)refinementDataLength
+ refinedLocation:(AVSampleCursorStorageRange * _Nonnull)refinedLocationOut
+ error:(NSError *__autoreleasing _Nullable * _Nullable)error
+NS_SWIFT_NAME(refineSampleLocation(_:refinementData:refinementDataLength:refinedLocation:));
+
+/*!
+ @method loadSampleBufferContainingSamplesToEndCursor
+ @abstract Builds a sample buffer containing the sample(s) at the cursor.
+ @discussion This method is to be implemented by those plugin format readers that always load sample data in order to answer cursor queries. If a plugin format reader does not implement sampleLocation, implementing loadSampleBufferContainingSamplesToEndCursor is required. If the MESampleCursor does implement sampleLocation, implementing loadSampleBufferContainingSamplesToEndCursor is optional. Important note: If there is a change of format description between the receiver and endSampleCursor, the returned sample buffer must contain only the contiguous samples with the same format description as the first sample. If there is no sample data between cursor and endSampleCursor, this method should return an empty sample buffer. This method should only provide a NULL sample buffer when there is an error.
+ @param endSampleCursor
+ If not nil, indicates the last sample that the new sample buffer should contain. If endSampleCursor refers to a sample earlier than the receiver, this method should fail and return MEErrorNoSamples as error code. If endSampleCursor is nil or refers to the same sample as the receiver, only a single sample should be returned in the new sample buffer.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'newSampleBuffer'
+ A CMSampleBufferRef with the newly created sample buffer. If the sample cursor is implemented in Objective-C, it is the responsibility of the sample cursor implementation to balance the creation of this sample buffer by calling CFRelease.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil.
+*/
+- (void)loadSampleBufferContainingSamplesToEndCursor:(nullable id<MESampleCursor>)endSampleCursor completionHandler:(void (^)(CMSampleBufferRef _Nullable newSampleBuffer, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(loadSampleBufferContainingSamples(to:completionHandler:));
+
+@end
+
+
+#pragma mark - MESampleCursorChunk
+
+/*!
+ @interface MESampleCursorChunk
+ @abstract Provides information about the chunk of media where a sample is located.
+ @discussion An instance of this class is returned by calls to the MESampleCursor method chunkDetails.
+*/
+NS_SWIFT_SENDABLE
+@interface MESampleCursorChunk : NSObject <NSCopying>
+
++ (instancetype)new NS_UNAVAILABLE;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/*!
+ @property initWithByteSource
+ @abstract The initializer for the MESampleCursorChunk class.
+ @param byteSource
+ The MEByteSource to be used to read the data for the sample.
+ @param chunkStorageRange
+ The offset location and length of the sample's chunk within the MEByteSource.
+ @param chunkInfo
+ A completed AVSampleCursorChunkInfo with details about the chunk in the media.
+ @param sampleIndexWithinChunk
+ The offset of the sample within the chunk, in samples.
+*/
+- (instancetype)initWithByteSource:(MEByteSource *)byteSource chunkStorageRange:(AVSampleCursorStorageRange)chunkStorageRange chunkInfo:(AVSampleCursorChunkInfo)chunkInfo sampleIndexWithinChunk:(CFIndex)sampleIndexWithinChunk NS_DESIGNATED_INITIALIZER;
+
+/*!
+ @property byteSource
+ @abstract The MEByteSource to be used to read the data for the sample.
+*/
+@property (nonatomic, readonly, retain) MEByteSource* byteSource;
+
+/*!
+ @property chunkStorageRange
+ @abstract The offset location and length of the sample's chunk, in bytes, within the MEByteSource.
+ @discussion The length should be set to 0 if there is no chunk associated with the sample.
+*/
+@property (nonatomic, readonly) AVSampleCursorStorageRange chunkStorageRange;
+
+/*!
+ @property chunkInfo
+ @abstract Provides information about the chunk of media samples.
+*/
+@property (nonatomic, readonly) AVSampleCursorChunkInfo chunkInfo;
+
+/*!
+ @property sampleIndexWithinChunk
+ @abstract The offset of the sample within the chunk, in samples.
+ @discussion Index value 0 corresponds to the start of the chunk. You would step back this many samples to position the cursor at the start of the chunk. Subtract from the chunkInfo.chunkSampleCount field to obtain the number of samples to the end of the chunk.
+*/
+@property (nonatomic, readonly) CFIndex sampleIndexWithinChunk;
+
+@end
+
+
+#pragma mark - MESampleLocation
+
+/*!
+ @interface MESampleLocation
+ @abstract Provides information about the sample location with the media.
+ @discussion An instance of this class is returned by calls to the MESampleCursor method sampleLocation.
+*/
+NS_SWIFT_SENDABLE
+@interface MESampleLocation : NSObject <NSCopying>
+
++ (instancetype)new NS_UNAVAILABLE;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/*!
+ @property initWithByteSource
+ @abstract The initializer for the MESampleLocation class.
+ @param byteSource
+ The MEByteSource to be used to read the data for the sample.
+ @param sampleLocation
+ The starting file offset and size in bytes of the sample.
+*/
+- (instancetype)initWithByteSource:(MEByteSource *)byteSource sampleLocation:(AVSampleCursorStorageRange)sampleLocation NS_DESIGNATED_INITIALIZER;
+
+/*!
+ @property sampleLocation
+ @abstract The starting file offset and size in bytes of the sample.
+*/
+@property (nonatomic, readonly) AVSampleCursorStorageRange sampleLocation;
+
+/*!
+ @property byteSource
+ @abstract The MEByteSource to be used to read the data for the sample.
+*/
+@property (nonatomic, retain, readonly) MEByteSource* byteSource;
+
+@end
+
+
+#pragma mark - MEEstimatedSampleLocation
+
+/*!
+ @interface MEEstimatedSampleLocation
+ @abstract Provides information about the estimated sample location with the media.
+ @discussion An instance of this class is returned by calls to the MESampleCursor method estimatedSampleLocationReturningError.
+*/
+NS_SWIFT_SENDABLE
+@interface MEEstimatedSampleLocation : NSObject <NSCopying>
+
++ (instancetype)new NS_UNAVAILABLE;
+
+- (instancetype)init NS_UNAVAILABLE;
+
+/*!
+ @property initWithByteSource
+ @abstract The initializer for the MEEstimatedSampleLocation class.
+ @param byteSource
+ The MEByteSource to be used to read the data for the sample.
+ @param estimatedSampleLocation
+ The estimated starting file offset and size in bytes of the sample.
+ @param refinementDataLocation
+ The starting file offset and size in bytes of the the data necessary to provide an accurate sample location.
+*/
+- (instancetype)initWithByteSource:(MEByteSource *)byteSource estimatedSampleLocation:(AVSampleCursorStorageRange)estimatedSampleLocation refinementDataLocation:(AVSampleCursorStorageRange)refinementDataLocation NS_DESIGNATED_INITIALIZER;
+
+/*!
+ @property estimatedSampleLocation
+ @abstract The estimated starting file offset and size in bytes of the sample.
+*/
+@property (nonatomic, readonly) AVSampleCursorStorageRange estimatedSampleLocation;
+
+/*!
+ @property refinementDataLocation
+ @abstract The starting file offset and size in bytes of the the data necessary to provide an accurate sample location.
+ @discussion The refinement data can be provided to the MESampleCursor method refineSampleLocation to determine the exact sample location.
+*/
+@property (nonatomic, readonly) AVSampleCursorStorageRange refinementDataLocation;
+
+/*!
+ @property byteSource
+ @abstract The MEByteSource to be used to read the data for the sample.
+*/
+@property (nonatomic, retain, readonly) MEByteSource* byteSource;
+
+@end
+
+
+#pragma mark - MEHEVCDependencyInfo
+
+/*!
+ @interface MEHEVCDependencyInfo
+ @abstract Provides information about the HEVC dependency attributes of a sample.
+ @discussion An instance of this class is returned by MESampleCursor property hevcDependencyInfo.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEHEVCDependencyInfo : NSObject <NSCopying>
+
+/*!
+ @property temporalSubLayerAccess
+ @abstract YES if the sample is an HEVC 'TSA' picture, NO otherwise.
+ @discussion Maps to the kCMSampleAttachmentKey_HEVCTemporalSubLayerAccess sample buffer attachment.
+*/
+@property (nonatomic, getter=hasTemporalSubLayerAccess) BOOL temporalSubLayerAccess;
+
+/*!
+ @property stepwiseTemporalSubLayerAccess
+ @abstract YES if the sample is an HEVC 'STSA' picture, NO otherwise.
+ @discussion Maps to the kCMSampleAttachmentKey_HEVCStepwiseTemporalSubLayerAccess sample buffer attachment.
+*/
+@property (nonatomic, getter=hasStepwiseTemporalSubLayerAccess) BOOL stepwiseTemporalSubLayerAccess;
+
+/*!
+ @property syncSampleNALUnitType
+ @abstract The NAL unit type for HEVC 'sync' sample groups, or -1 if this information is not available.
+ @discussion Maps to the kCMSampleAttachmentKey_HEVCSyncSampleNALUnitType sample buffer attachment.
+*/
+@property (nonatomic) int16_t syncSampleNALUnitType;
+
+@end
+
+
+#pragma mark - MEHEVCDependencyInfo (HEVCTemporalLevelInfo)
+
+/*!
+ @category MEHEVCDependencyInfo HEVCTemporalLevelInfo
+ @abstract Indicates a video frame's level within a hierarchical frame dependency structure.
+ @discussion The properties here map to the kCMSampleAttachmentKey_HEVCTemporalLevelInfo sample buffer attachment dictionary.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEHEVCDependencyInfo (HEVCTemporalLevelInfo)
+
+/*!
+ @property temporalLevel
+ @abstract The HEVC temporal level, or -1 if this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_TemporalLevel sample buffer attachment.
+*/
+@property (nonatomic) int16_t temporalLevel;
+
+/*!
+ @property profileSpace
+ @abstract The HEVC profile space, or -1 if this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_ProfileSpace sample buffer attachment.
+*/
+@property (nonatomic) int16_t profileSpace;
+
+/*!
+ @property tierFlag
+ @abstract The HEVC tier level flag, or -1 if this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_TierFlag sample buffer attachment.
+*/
+@property (nonatomic) int16_t tierFlag;
+
+/*!
+ @property profileIndex
+ @abstract The HEVC profile index, or -1 if this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_ProfileIndex sample buffer attachment.
+*/
+@property (nonatomic) int16_t profileIndex;
+
+/*!
+ @property profileCompatibilityFlags
+ @abstract The HEVC profile compatibility flags (4 bytes), or nil of this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_ProfileCompatibilityFlags sample buffer attachment.
+*/
+@property (nonatomic, copy, nullable) NSData* profileCompatibilityFlags;
+
+/*!
+ @property constraintIndicatorFlags
+ @abstract The HEVC constraint indicator flags (6 bytes), or nil of this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_ConstraintIndicatorFlags sample buffer attachment.
+*/
+@property (nonatomic, copy, nullable) NSData* constraintIndicatorFlags;
+
+/*!
+ @property levelIndex
+ @abstract The HEVC level index, or -1 if this information is not available.
+ @discussion Maps to the kCMHEVCTemporalLevelInfoKey_LevelIndex sample buffer attachment.
+*/
+@property (nonatomic) int16_t levelIndex;
+
+@end
+
+
+#pragma mark - MEByteSource
+
+/*!
+ @interface MEByteSource
+ @abstract Provides read access to the data in a media asset file.
+ @discussion The Media Toolbox passes an MEByteSource instance for the media asset's primary file when initializing an MEFormatReader object. The MEFormatReader may request additional MEByteSources be created for related files in the same directory as the primary file by calling the byteSourceForRelatedFileName method.
+*/
+NS_SWIFT_SENDABLE API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEByteSource : NSObject
+
++ (instancetype) new NS_UNAVAILABLE;
+
+- (instancetype) init NS_UNAVAILABLE;
+
+/*!
+ @property fileName
+ @abstract The name of a MEByteSource's file.
+ @discussion The name of the source file for the MEByteSource.
+*/
+@property (nonatomic, readonly) NSString* fileName;
+
+/*!
+ @property contentType
+ @abstract A UTType indicating the format of the MEByteSource's file.
+ @discussion A UTType indicating the format of the source file for the MEByteSource.
+*/
+@property (nonatomic, readonly, nullable) UTType* contentType;
+
+/*!
+ @property fileLength
+ @abstract The length of the MEByteSource's file.
+ @discussion The length in bytes of the source file for the MEByteSource, or 0 if that information is not available.
+*/
+@property (nonatomic, readonly) int64_t fileLength;
+
+/*!
+ @property relatedFileNamesInSameDirectory
+ @abstract The array of related file names in the MEByteSource's parent directory.
+ @discussion The array of related files within the MEByteSource's parent directory that are accessible to the MEByteSource. Only the relative file names are returned, not the paths. If no related files are available, returns an empty array.
+*/
+@property (nonatomic, readonly) NSArray<NSString *> * relatedFileNamesInSameDirectory;
+
+/*!
+ @method readDataOfLength:fromOffset:toDestination:completionHandler:
+ @abstract Reads bytes from an MEByteSource asynchronously into a buffer.
+ @discussion Asynchronously reads out the specified number of bytes starting at the indicated offset. Returns the actual number of bytes read out in bytesRead. Read attempts that extend beyond the end of the MEByteSource will succeed if they include at least one valid byte before the end of the MEByteSource.
+ @param length
+ The number of bytes to read.
+ @param offset
+ The relative offset in bytes from the beginning of the file from which to start reading.
+ @param dest
+ The block of memory to hold the data to be read. Must be at least num bytes in length.
+ @param completionHandler
+ The handler that will be invoked when the method completes.
+ 'bytesRead'
+ The actual number of bytes read.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil. Returns MEErrorEndOfStream if no more bytes can be read.
+*/
+- (void) readDataOfLength:(size_t)length fromOffset:(int64_t)offset toDestination:(void *)dest completionHandler:(void (^)(size_t bytesRead, NSError * _Nullable error))completionHandler NS_SWIFT_UNAVAILABLE("Use 'read(length:from:completionHandler:)' instead");
+
+/*!
+ @method readDataOfLength:fromOffset:completionHandler:
+ @abstract Reads bytes from an MEByteSource asynchronously into an NSData object.
+ @discussion Asynchronously reads out the specified number of bytes starting at the indicated offset. Returns the actual number of bytes read out in bytesRead. Read attempts that extend beyond the end of the MEByteSource will succeed if they include at least one valid byte before the end of the MEByteSource.
+ @param length
+ The number of bytes to read.
+ @param offset
+ The relative offset in bytes from the beginning of the file from which to start reading.
+ @param completionHandler
+ Completion block called when the method completes.
+ 'data'
+ The NSData object holding the data that have been read. The NSData length property will indicate the actual number of bytes read.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil. Returns MEErrorEndOfStream if no more bytes can be read.
+*/
+- (void) readDataOfLength:(size_t)length fromOffset:(int64_t)offset completionHandler:(void (^)(NSData * _Nullable data, NSError * _Nullable error))completionHandler NS_SWIFT_NAME(read(length:from:completionHandler:));
+
+/*!
+ @method readDataOfLength:fromOffset:toDestination:bytesRead:error
+ @abstract Reads bytes from an MEByteSource synchronously into a buffer.
+ @discussion Synchronously reads out the specified number of bytes starting at the indicated offset. Returns the actual number of bytes read out in bytesReadOut. Read attempts that extend beyond the end of the MEByteSource will succeed if they include at least one valid byte before the end of the MEByteSource.
+ @param length
+ The number of bytes to read.
+ @param offset
+ The relative offset in bytes from the beginning of the file from which to start reading.
+ @param dest
+ The block of memory to hold the data to be read. Must be at least num bytes in length.
+ @param bytesReadOut
+ The actual number of bytes read.
+ @param error
+ Reports any errors. Returns MEErrorEndOfStream if no more bytes can be read.
+ @result Returns YES if successful, NO if an error occured.
+*/
+- (BOOL) readDataOfLength:(size_t)length fromOffset:(int64_t)offset toDestination:(void *)dest bytesRead:(size_t *)bytesReadOut error:(NSError * __autoreleasing _Nullable * _Nullable)error NS_SWIFT_UNAVAILABLE("Use 'read(length:from:completionHandler:)' instead");
+
+/*!
+ @method availableLengthAtOffset:
+ @abstract Returns the number of available bytes from the offset within the MEByteSource.
+ @discussion Returns the number of available bytes at the time of the query. This value could change over time. Attempting to read past this value may cause slow I/O.
+ @param offset
+ The offset in bytes from the beginning of the MEByteSource.
+ @result Returns the number of available bytes from the offset, or 0 if that information is not available.
+*/
+- (int64_t) availableLengthAtOffset:(int64_t)offset NS_SWIFT_NAME(availableLength(at:));
+
+/*!
+ @method byteSourceForRelatedFileName:error:
+ @abstract Requests creation of a new MEByteSource for a related file.
+ @discussion Requests creation of a new MEByteSource for a file related to the receiving MEByteSource. The scope of fileName that may be opened is restricted. Only files in the same directory as the receiver MEByteSource may be accessed, and the file extension must match one of the extensions listed in the format reader bundle plist.
+ @param fileName
+ The relative file name in the receiver MEByteSource's parent directory.
+ @param errorOut
+ Reports any errors. Returns MEErrorPermissionDenied if the file cannot be accessed or is prohibited.
+ @result Returns nil if fileName refers to a file that cannot be accessed or is prohibited, or if an error occured. The returned MEByteSource is autoreleased.
+*/
+- (MEByteSource * _Nullable) byteSourceForRelatedFileName:(NSString *)fileName error:(NSError * _Nullable * _Nullable)errorOut NS_SWIFT_NAME(byteSourceForRelatedFileName(_:));
+
+@end
+
+
+NS_ASSUME_NONNULL_END
+
+#endif /* MEFormatReader_h */
+
diff -ruN /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEVideoDecoder.h /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEVideoDecoder.h
--- /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEVideoDecoder.h 1969-12-31 19:00:00
+++ /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MEVideoDecoder.h 2023-05-31 09:13:09
@@ -0,0 +1,328 @@
+/*
+ File: MEVideoDecoder.h
+
+ Framework: MediaExtension
+
+ Copyright © 2023 Apple Inc. All rights reserved.
+
+ Overview
+
+ This file contains the interface/protocol for MediaExtension video decoders. Developers who wish to build MediaExtension
+ video decoders using this API should contact Apple Worldwide Developer Relations to request access to the managed
+ entitlement "com.apple.developer.mediaextension.videodecoder", specifying the list of codec-type four-character-codes to be
+ decoded. Once approved, developers will be able to download a provisioning profile authorizing their video decoders to run.
+ For more information about managed entitlements see:
+ https://developer.apple.com/help/account/reference/provisioning-with-managed-capabilities/
+
+
+ MediaExtension Video Decoder Info.plist File Information
+
+ MediaExtension video decoders will need to include a specialized EXAppExtensionAttributes dictionary in their Info.plist
+ files describing ExtensionKit information.
+
+ EXAppExtensionAttributes Dictionary
+
+ The EXAppExtensionAttributes dictionary is required by ExtensionKit. The following keys will be needed for ExtensionKit
+ video decoders:
+
+ - ClassImplementationID
+ This should be a string similar to the bundle identifier of the video decoder. It should start with the reverse domain
+ identifier of the developer to prevent collisions with other developers, and for clarity contain ".videodecoder." and
+ the name of the codec. If the developer envisions multiple variants of the same decoder, the name should include strings
+ to make each format reader unique. An example might be something like "com.mycompany.videodecoder.mycodec.codecvariant".
+ - EXExtensionPointIdentifier
+ The string "com.apple.mediaextension.videodecoder" (kMEVideoDecoderExtensionPointName).
+ - EXExtensionPrincipalClass
+ The name of the video decoder factory class, conforming to the MEVideoDecoderExtension protocol.
+ - CodecType
+ An array of one or more strings describing the four-character codes of the codecs that the decoder supports. Each string
+ should be exactly four characters long and use ASCII character set encoding.
+ - ObjectName
+ A user-readable string describing the decoder. This string is used for uniquely identifying video decoders and possibly
+ for debug logging but is typically not visible to users.
+
+
+ To report bugs, go to: http://developer.apple.com/bugreporter/
+
+*/
+
+#ifndef MEVIDEODECODER_H
+#define MEVIDEODECODER_H
+
+
+/*!
+ MediaExtension Video Decoder Call Flow and Life Cycle Overview
+
+ MediaExtension video decoder operation and life cycle are closely tied to VTDecompressionSession.
+ See <VideoToolbox/VTDecompressionSession.h> for more details on this interface.
+
+ Creation:
+ An instance of an MEVideoDecoderExtension factory object is created the first time a given decoder is opened
+ by the VideoToolbox in a process. The videoDecoderWithCodecType: method on the MEVideoDecoderExtension
+ object will be called once for each decoder instance needed. The decoder can evaluate the provided codecType
+ and CMVideoFormatDescription at this point and confirm whether it is able to decode the specified format. If the
+ decoder cannot decode the format, the factory routine should return MEErrorUnsupportedFeature. This sequence of
+ calls will happen inside of VTDecompressionSessionCreate.
+
+ Pixel Buffer Requirement Configuration:
+ At any point after instantiation, the decoder can call back into the provided MEVideoDecoderPixelBufferManager object
+ to notify the VideoToolbox of its output pixelBuffer requirements. The decoder extension may make multiple calls if
+ output requirements change in response to properties being set or due to observed bitstream characteristics.
+
+ Property calls
+ Properties can be queried or set on the decoder at any time, before, during or after frame decode, unless otherwise
+ noted. These calls generally correspond to calls to VTSessionSetProperty and VTSessionCopyProperty being made
+ on the VTDecompressionSession which opened the decoder. There may be cases where the VideoToolbox directly sets or
+ queries properties as well.
+
+ Frame Decoding:
+ Calls to decodeFrameFromSampleBuffer: will be serialized. A new frame will not be sent to the decoder until the last
+ decodeFrameFromSampleBuffer: has returned, but may be submitted before the decodeFrameFromSampleBuffer: completion
+ handler is called if the decode is happening asynchronously. These calls correspond to VTDecompressionSessionDecodeFrame
+ calls on the parent VTDecompressionSession.
+
+ Video decoders must write their output frames into CVPixelBuffers allocated through the MEVideoDecoderPixelBufferManager
+ createPixelBufferAndReturnError: interface. Returning CVPixelBuffers from any other source may result in degraded performance
+ or other issues.
+
+ If the decoder's internal decoding queue is full, and it cannot decode more frames, it should return
+ NO when the isReadyForMoreMediaData property is queried. This property should return YES again when the decoder
+ is able to accept new frames -- generally after an earlier asynchronous frame decode is completed.
+
+ Format Description Changes:
+ If there is a change in the format description on incoming CMSampleBuffers, the VideoToolbox will confirm whether the
+ decoder is able to transition to the new format description by calling the canAcceptFormatDescription: method. If this
+ method returns "NO", the decoder will usually be closed and a new instance will be created for the new format description.
+ This call may either be triggered by a call to VTDecompressionSessionCanAcceptFormatDescription, or be initiated directly by
+ the VideoToolbox if a format description change is seen on incoming CMSampleBuffers.
+*/
+
+#import <Foundation/Foundation.h>
+#import <CoreMedia/CMSampleBuffer.h>
+#import <CoreMedia/CMFormatDescription.h>
+#import <CoreFoundation/CoreFoundation.h>
+#import <VideoToolbox/VideoToolbox.h>
+#import <CoreVideo/CVPixelBuffer.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol MEVideoDecoder;
+@class MEVideoDecoderPixelBufferManager;
+
+/*!
+ @protocol MEVideoDecoderExtension
+ @abstract Provides a stateless factory interface for creating new MEVideoDecoder instances.
+ @discussion The MEVideoDecoderExtension protocol provides a factory method to create a new MEVideoDecoder instance for a codecType implemented by the extension. A single MEVideoDecoderExtension is instantiated by the Video Toolbox, and will be called to create individual MEVideoDecoder instances as needed. If the codecType or FormatDescription passed to videoDecoderWithCodecType is not compatible with the MEVideoDecoder implementation, the factory call should fail and return MEErrorUnsupportedFeature.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol MEVideoDecoderExtension <NSObject>
+
+- (instancetype)init;
+
+/*!
+ @method videoDecoderWithCodecType
+ @abstract The factory method to create a new MEVideoDecoder.
+ @discussion Creates a new MEVideoDecoder matching the given CMVideoCodecType and CMVideoFormatDescriptionRef. If these parameters are not compatible with the MEVideoDecoder, the call should fail, returnig MEErrorUnsupportedFeature.
+ @param codecType
+ The codec type for the requested decoder
+ @param videoFormatDescription
+ A CMVideoFormatDescription describing the video data.
+ @param videoDecoderSpecifications
+ A dictionary of videoDecoderSpecification values (See kVTVideoDecoderSpecification keys in VideoToolbox/VTDecompressionProperties.h). This may be empty.
+ @param extensionDecoderPixelBufferManager
+ An MEVideoDecoderPixelBufferManager instance that should be retained by the new MEVideoDecoder instance and used for output pixelBuffer configuration and allocation.
+ @param error
+ On return, if initialization of the MEVideoDecoder fails, points to an NSError describing the nature of the failure.
+ @result A newly created instance conforming to MEVideoDecoder.
+*/
+- (id<MEVideoDecoder> _Nullable)videoDecoderWithCodecType:(CMVideoCodecType)codecType
+ videoFormatDescription: (CMVideoFormatDescriptionRef) videoFormatDescription
+ videoDecoderSpecifications: (NSDictionary<NSString *, id> * )videoDecoderSpecifications
+ extensionDecoderPixelBufferManager: (MEVideoDecoderPixelBufferManager *)extensionDecoderPixelBufferManager
+ error:(NSError *__autoreleasing _Nullable * _Nullable)error NS_SWIFT_NAME(makeVideoDecoder(codecType:videoFormatDescription:videoDecoderSpecifications:pixelBufferManager:));
+
+@end
+
+/*!
+ @interface MEVideoDecoderPixelBufferManager
+ @abstract Describes pixel buffer requirements and creates new pixel buffers.
+ @discussion Contains the interfaces that the App Extension video decoder uses for two tasks. First, to declare its set of requirements for output CVPixelBuffers in the form of a pixelBufferAttributes dictionary. Second, to create pixelBuffers which match decoder output requirements but also satisfy VideoToolbox and client requirements.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEVideoDecoderPixelBufferManager : NSObject
+
+/*!
+ @property pixelBufferAttributes
+ @abstract VideoToolbox will use these attributes when creating a PixelBuffer for the decoder.
+ @discussion This can be updated by the decoder before requesting a new pixelBuffer.
+*/
+@property(nonatomic, copy,readwrite) NSDictionary<NSString*, id> * pixelBufferAttributes;
+
+
+/*!
+ @method createPixelBufferAndReturnError:
+ @abstract Generates a pixel buffer using the session's pixel buffer pool.
+ @discussion If implemented in Objective-C, the caller is responsible for releasing the returned CVPixelBuffer.
+ @param error
+ If provided, returns error information in the event that the method fails.
+ @result
+ A pixel buffer compatible with the extension's most recently set pixelBufferAttributes
+*/
+- (CVPixelBufferRef _Nullable) createPixelBufferAndReturnError: (NSError **)error CF_RETURNS_RETAINED NS_SWIFT_NAME(makePixelBuffer());
+
+@end
+
+
+/*!
+ @interface MEDecodeFrameOptions
+ @abstract Conveys directives or options from the VideoToolbox to guide decoder operation on a per-frame basis.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@interface MEDecodeFrameOptions : NSObject
+
+/*!
+ @property doNotOutputFrame
+ @abstract A hint to the video decoder that a CVImageBuffer should not be emitted for this frame. NULL will be returned instead.
+*/
+@property(readwrite) BOOL doNotOutputFrame;
+
+
+/*!
+ @property realTimePlayback
+ @abstract A hint to the video decoder that it would be OK to use a low-power mode that can not decode faster than 1x realtime.
+ @discussion Note that this hint only takes the current decode session into account. For example, if multiple instances of a decoder are operating at once, it may not actually be OK to use such a low-power mode if real-time playback might not be sustained across all the streams. This hint will be set to false during all uses other than 1x forward real-time playback, including seeking, playback at other rates, and export.
+*/
+@property(readwrite) BOOL realTimePlayback;
+
+@end
+
+
+// This notification is used to notify the VideoToolbox that the value of the readyForMoreMediaData property has changed
+ME_EXPORT NSNotificationName const MEVideoDecoderReadyForMoreMediaDataDidChangeNotification API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos);
+
+
+
+/*!
+ @enum MEDecodeFrameStatus
+ @abstract These values are used to convey non-error status related to a frame decode operation.
+ @constant MEDecodeFrameNoStatus
+ Set by the decoder to indicate that no non-error status information is available.
+ @constant MEDecodeFrameFrameDropped
+ Set by the decoder to report that output of this frame was dropped for non-error reasons, for example, if doNotOutputFrame was specified.
+*/
+typedef NS_OPTIONS(NSUInteger, MEDecodeFrameStatus) {
+ MEDecodeFrameNoStatus = 0UL,
+ MEDecodeFrameFrameDropped = 1UL << 0,
+} API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos);
+
+
+/*!
+ @protocol MEVideoDecoder
+ @abstract The primary object for a MediaExtension video decoder, providing an interface for VideoToolbox to talk to the decoder.
+ @discussion The MEVideoDecoder protocol provides an interface for the VideoToolbox to interact with MediaExtension video decoders. MEVideoDecoder objects are always instantiated by the VideoToolbox. To create an MEVideoDecoder, the VideoToolbox first creates an MEVideoDecoderExtension object and calls its videoDecoderWithCodecType: method. MEVideoDecoders should expect to run in a sandboxed process without access to the file system, network, or other kernel resources.
+*/
+API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos)
+@protocol MEVideoDecoder <NSObject>
+
+
+@optional
+
+/*!
+ @property contentHasInterframeDependencies
+ @abstract The extension should return whether the content being decoded has interframe dependencies, if the decoder knows.
+ @discussion This optional property is queried on the extension when a VideoToolbox client queries the kVTDecompressionPropertyKey_ContentHasInterframeDependencies property on the hosting VTDecompressionSession.
+*/
+@property (readonly) BOOL contentHasInterframeDependencies;
+
+
+/*!
+ @property recommendedThreadCount
+ @abstract Sets the recommended number of threads to be used by the decoder.
+ @discussion This optional property is set when a VideoToolbox client sets the kVTDecompressionPropertyKey_ThreadCount property on the hosting VTDecompressionSession.
+*/
+@property (readwrite) NSInteger recommendedThreadCount;
+
+
+/*!
+ @property actualThreadCount
+ @abstract Returns the actual number of threads used by decoder.
+ @discussion This optional property is queried when a VideoToolbox client queries the kVTDecompressionPropertyKey_ThreadCount property on the hosting VTDecompressionSession.
+*/
+@property (readonly) NSInteger actualThreadCount;
+
+
+/*!
+ @property supportedPixelFormatsOrderedByQuality
+ @abstract Provides hints about quality tradeoffs between pixel formats.
+ @discussion This optional property value is an array of NSNumbers with CMPixelFormatTypes values, ordered by quality from best to worse. This property is queried when a VideoToolbox client queries the kVTDecompressionPropertyKey_SupportedPixelFormatsOrderedByQuality property on the hosting VTDecompressionSession.
+*/
+@property (readonly) NSArray<NSNumber *> * supportedPixelFormatsOrderedByQuality;
+
+
+/*!
+ @property reducedResolution
+ @abstract Requests decoding at a smaller resolution than full-size.
+ @discussion This optional property conveys a request for reduced resolution for decoding. Decoders that only support a fixed set of resolutions should pick the smallest resolution greater than or equal to the requested { width, height }. If the output CVPixelBuffer is not in a format where reduced resolution decoding is supported, this setting should be disregarded. This property is set on the extension when a VideoToolbox client sets the kVTDecompressionPropertyKey_ReducedResolutionDecode property on the hosting VTDecompressionSession.
+*/
+@property (readwrite) CGSize reducedResolution;
+
+/*!
+ @property pixelFormatsWithReducedResolutionDecodeSupport
+ @abstract Provides a list of output pixel formats where the decoder supports reduced resolution decoding
+ @discussion This optional property should return an array of NSNumbers holding CMPixelFormatType values. This property is queried when a VideoToolbox client queries the kVTDecompressionPropertyKey_PixelFormatsWithReducedResolutionSupport property on the hosting VTDecompressionSession.
+*/
+@property (readonly) NSArray<NSNumber *> * pixelFormatsWithReducedResolutionDecodeSupport;
+
+
+@required
+
+/*!
+ @property readyForMoreMediaData
+ @abstract Indicates the readiness of the decoder to accept more sample buffers.
+ @discussion Video decoders which operate asynchronously often have a fixed capacity for buffers in flight in the decoder. This property allows the decoder to signal to the VideoToolbox that its internal buffers are full and it cannot accept more samples at this time. The decoder must use MEVideoDecoderReadyForMoreMediaDataDidChangeNotification to notify the VideoToolbox when this property changes.
+*/
+@property (nonatomic, readonly, getter=isReadyForMoreMediaData) BOOL readyForMoreMediaData;
+
+/*!
+ @method decodeFrameFromSampleBuffer:options:completionHandler:
+ @abstract Requests that the extension decode a video frame.
+ @discussion The completionHandler block must be called for every decodeFrameFromSampleBuffer call when decode is complete. The completion handler block should return either a decoded pixelBuffer, an error, or a decodeStatus indicating the frame was dropped.
+ @param sampleBuffer
+ A CMSampleBuffer containing one video frame.
+ @param options
+ A MEDecodeFrameOptions containing specific requests for this frame.
+ @param completionHandler
+ The handler that will be invoked when a frame is decoded and ready to be sent back to
+ caller. This block will not necessarily be called in display order.
+ 'imageBuffer'
+ Contains the decompressed frame if decompression was successful, otherwise NULL. The imageBuffer must be allocated using MEVideoDecoderPixelBufferManager.
+ 'decodeStatus'
+ Reports the status of decoding the sampleBuffer.
+ 'error'
+ An NSError object that will contain error information if the method fails, otherwise nil. Errors outside of MediaExtensionErrorDomain will be reported as kVTVideoDecoderUnknownErr to the VTDecompressionSession client.
+*/
+- (void) decodeFrameFromSampleBuffer: (CMSampleBufferRef)sampleBuffer
+ options: (MEDecodeFrameOptions *)options
+ completionHandler: (void (^)(CVImageBufferRef _Nullable imageBuffer,
+ MEDecodeFrameStatus decodeStatus,
+ NSError * _Nullable error))completionHandler;
+
+@optional
+/*!
+ @method canAcceptFormatDescription:
+ @abstract Asks the extension whether the decoder can decode frames with the given format description.
+ @discussion Some video decoders are able to accommodate minor changes in format without needing to be completely reset in a new session. This function can be used to test whether a format change is allowed.
+ @param formatDescription
+ The new format description that need to be evaluated.
+ @result YES if the decoder can continue decoding samples without being reset, NO if this is not possible. If this method returns NO, typically the VideoToolbox will release the current decoder instance and instantiate a new one using the new format description.
+*/
+- (BOOL) canAcceptFormatDescription: (CMFormatDescriptionRef) formatDescription;
+
+
+@end
+
+
+NS_ASSUME_NONNULL_END
+
+
+#endif /* MEVIDEODECODER_H */
diff -ruN /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MediaExtension.h /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MediaExtension.h
--- /Applications/Xcode_14.3.1.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MediaExtension.h 1969-12-31 19:00:00
+++ /Applications/Xcode_15.0.0-beta.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/MediaExtension.framework/Headers/MediaExtension.h 2023-05-31 09:13:09
@@ -0,0 +1,21 @@
+/*
+ File: MediaExtension.h
+
+ Framework: MediaExtension
+
+ Copyright 2023 Apple Inc. All rights reserved.
+
+ To report bugs, go to: http://developer.apple.com/bugreporter/
+
+*/
+
+#ifndef MEDIAEXTENSION_H
+#define MEDIAEXTENSION_H
+
+#include <CoreMedia/CMBase.h>
+#include <MediaExtension/MEError.h>
+#include <MediaExtension/MEExtensionPlugin.h>
+#include <MediaExtension/MEFormatReader.h>
+#include <MediaExtension/MEVideoDecoder.h>
+
+#endif // MEDIAEXTENSION_H
- README
- xcode13.0 Binding Status
- xcode13.1 Binding Status
- xcode13.2 Binding Status
- xcode13.3 Binding Status
- xcode13.4 Binding Status
- xcode14.0 Binding Status
- xcode14.1 Binding Status
- xcode14.2 Binding Status
- xcode14.3 Binding Status
- xcode15.0 Binding Status
- xcode15.1 Binding Status
- xcode15.3 Binding Status