-
Notifications
You must be signed in to change notification settings - Fork 570
AVFoundation tvOS xcode27.0 b2
Alex Soto edited this page Jun 23, 2026
·
1 revision
#AVFoundation.framework
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetExportSession.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetExportSession.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetExportSession.h 2026-05-27 01:19:11
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetExportSession.h 2026-06-12 02:20:54
@@ -108,26 +108,17 @@
AVAssetExportSessionStatusCancelled = 5
};
-/*!
- @typedef AVAssetTrackGroupOutputHandling
- @abstract A bitfield type that specifies output handling policies for alternate tracks in a track group.
-
- @constant AVAssetTrackGroupOutputHandlingNone
- @abstract No specific processing directives are applied to alternate tracks. The output is produced without regard to alternate track group assignments in the original asset.
- @constant AVAssetTrackGroupOutputHandlingPreserveAlternateTracks
- @abstract Preserve alternate tracks via pass-through.
- */
+/// A bitfield type that specifies output handling policies for alternate tracks in a track group.
typedef NS_OPTIONS(NSUInteger, AVAssetTrackGroupOutputHandling) {
+ /// No specific processing directives are applied to alternate tracks. The output is produced without regard to alternate track group assignments in the original asset.
AVAssetTrackGroupOutputHandlingNone = 0UL,
+ /// Preserve alternate tracks via pass-through.
AVAssetTrackGroupOutputHandlingPreserveAlternateTracks = (1UL << 0),
AVAssetTrackGroupOutputHandlingDefaultPolicy = AVAssetTrackGroupOutputHandlingNone
} API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @typedef AVAssetExportSessionResumptionFailureReason
- @abstract An enum that identifies various reasons why resumable export configuration has failed.
- */
+/// An enum that identifies various reasons why resumable export configuration has failed.
typedef NSString * AVAssetExportSessionResumptionFailureReason NS_SWIFT_NAME(AVAssetExportSession.ResumptionFailureReason) NS_EXTENSIBLE_STRING_ENUM API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos);
AVF_EXPORT AVAssetExportSessionResumptionFailureReason const AVAssetExportSessionResumptionFailureReasonIncompatiblePreset API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos);
@@ -136,75 +127,56 @@
AVF_EXPORT AVAssetExportSessionResumptionFailureReason const AVAssetExportSessionResumptionFailureReasonIncompatibleSessionSettings API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos);
AVF_EXPORT AVAssetExportSessionResumptionFailureReason const AVAssetExportSessionResumptionFailureReasonIncompatibleTemporaryDirectoryContents API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos);
-/*!
- @class AVAssetExportSessionResumptionState
-
- @abstract AVAssetExportSessionResumptionState details the current resumption state
- of the export session.
- A resumable export session is configured via configureForResumableExportWithCompletionHandler:.
- */
+/// AVAssetExportSessionResumptionState details the current resumption state of the export session. A resumable export session is configured via configureForResumableExportWithCompletionHandler:.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
NS_REFINED_FOR_SWIFT
@interface AVAssetExportSessionResumptionState : NSObject
-/*!
- @property resumptionConfigured
- @abstract Reports whether or not the export session has been successfully configure as resumable.
- @discussion If YES, the export session in configured as resumable. If NO, the export session will remain
- as non-resumable (default). exportAsynchronouslyWithCompletionHandler may still be called
- if this returns as NO.
- */
+/// Reports whether or not the export session has been successfully configure as resumable.
+///
+/// If YES, the export session in configured as resumable. If NO, the export session will remain
+/// as non-resumable (default). exportAsynchronouslyWithCompletionHandler may still be called
+/// if this returns as NO.
@property (readonly, getter=isResumptionConfigured) BOOL resumptionConfigured;
-/*!
- @property resumingFromPreviousState
- @abstract Reports whether or not a resuming export is continuing from a previous state.
- @discussion This indicates whether or not the export is resuming (YES) or starting from the beginning (NO).
- Valid only if resumptionConfigured is YES.
- */
+/// Reports whether or not a resuming export is continuing from a previous state.
+///
+/// This indicates whether or not the export is resuming (YES) or starting from the beginning (NO).
+/// Valid only if resumptionConfigured is YES.
@property (readonly, getter=isResumingFromPreviousState) BOOL resumingFromPreviousState;
-/*!
- @property configurationFailureReason
- @abstract Provides details on why the session was not able to be configured as resumable.
- @discussion Reasons for failure include incompatible session settings and incompatible
- directoryForTemporaryFiles contents.
- Valid only if resumptionConfigured is NO.
- */
+/// Provides details on why the session was not able to be configured as resumable.
+///
+/// Reasons for failure include incompatible session settings and incompatible
+/// directoryForTemporaryFiles contents.
+/// Valid only if resumptionConfigured is NO.
@property (readonly, nullable) AVAssetExportSessionResumptionFailureReason configurationFailureReason;
@end // AVAssetExportSessionResumptionState
-/*!
- @class AVAssetExportSession
-
- @abstract An AVAssetExportSession creates a new timed media resource from the contents of an
- existing AVAsset in the form described by a specified export preset.
-
- @discussion
- Prior to initializing an instance of AVAssetExportSession, you can invoke
- +allExportPresets to obtain the complete list of presets available. Use
- +exportPresetsCompatibleWithAsset: to obtain a list of presets that are compatible
- with a specific AVAsset.
-
- To configure an export, initialize an AVAssetExportSession with an AVAsset that contains
- the source media, an AVAssetExportPreset, the output file type, (a UTI string from
- those defined in AVMediaFormat.h) and the output URL.
-
- After configuration is complete, invoke exportAsynchronouslyWithCompletionHandler:
- to start the export process. This method returns immediately; the export is performed
- asynchronously. Invoke the -progress method to check on the progress. Note that in
- some cases, depending on the capabilities of the device, when multiple exports are
- attempted at the same time some may be queued until others have been completed. When
- this happens, the status of a queued export will indicate that it's "waiting".
-
- Whether the export fails, completes, or is cancelled, the completion handler you
- supply to -exportAsynchronouslyWithCompletionHandler: will be called. Upon
- completion, the status property indicates whether the export has completed
- successfully. If it has failed, the value of the error property supplies additional
- information about the reason for the failure.
-
-*/
+/// An AVAssetExportSession creates a new timed media resource from the contents of an existing AVAsset in the form described by a specified export preset.
+///
+/// Prior to initializing an instance of AVAssetExportSession, you can invoke
+/// +allExportPresets to obtain the complete list of presets available. Use
+/// +exportPresetsCompatibleWithAsset: to obtain a list of presets that are compatible
+/// with a specific AVAsset.
+///
+/// To configure an export, initialize an AVAssetExportSession with an AVAsset that contains
+/// the source media, an AVAssetExportPreset, the output file type, (a UTI string from
+/// those defined in AVMediaFormat.h) and the output URL.
+///
+/// After configuration is complete, invoke exportAsynchronouslyWithCompletionHandler:
+/// to start the export process. This method returns immediately; the export is performed
+/// asynchronously. Invoke the -progress method to check on the progress. Note that in
+/// some cases, depending on the capabilities of the device, when multiple exports are
+/// attempted at the same time some may be queued until others have been completed. When
+/// this happens, the status of a queued export will indicate that it's "waiting".
+///
+/// Whether the export fails, completes, or is cancelled, the completion handler you
+/// supply to -exportAsynchronouslyWithCompletionHandler: will be called. Upon
+/// completion, the status property indicates whether the export has completed
+/// successfully. If it has failed, the value of the error property supplies additional
+/// information about the reason for the failure.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession : NSObject
@@ -214,110 +186,97 @@
}
AV_INIT_UNAVAILABLE
-/*!
- @method exportSessionWithAsset:presetName:
- @abstract Returns an instance of AVAssetExportSession for the specified source asset and preset.
- @param asset An AVAsset object that is intended to be exported.
- @param presetName An NSString specifying the name of the preset template for the export.
- @result An instance of AVAssetExportSession.
- @discussion If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.
-*/
+/// Returns an instance of AVAssetExportSession for the specified source asset and preset.
+///
+/// If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.
+///
+/// - Parameter asset: An AVAsset object that is intended to be exported.
+/// - Parameter presetName: An NSString specifying the name of the preset template for the export.
+///
+/// - Returns: An instance of AVAssetExportSession.
+ (nullable instancetype)exportSessionWithAsset:(AVAsset *)asset presetName:(NSString *)presetName API_AVAILABLE(macos(10.7), ios(4.1), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @method initWithAsset:presetName:
- @abstract Initialize an AVAssetExportSession with the specified preset and set the source to the contents of the asset.
- @param asset An AVAsset object that is intended to be exported.
- @param presetName An NSString specifying the name of the preset template for the export.
- @result Returns the initialized AVAssetExportSession.
- @discussion If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.
-*/
+/// Initialize an AVAssetExportSession with the specified preset and set the source to the contents of the asset.
+///
+/// If the specified asset belongs to a mutable subclass of AVAsset, AVMutableComposition or AVMutableMovie, the results of any export-related operation are undefined if you mutate the asset after the operation commences. These operations include but are not limited to: 1) testing the compatibility of export presets with the asset, 2) calculating the maximum duration or estimated length of the output file, and 3) the export operation itself.
+///
+/// - Parameter asset: An AVAsset object that is intended to be exported.
+/// - Parameter presetName: An NSString specifying the name of the preset template for the export.
+///
+/// - Returns: Returns the initialized AVAssetExportSession.
- (nullable instancetype)initWithAsset:(AVAsset *)asset presetName:(NSString *)presetName NS_DESIGNATED_INITIALIZER;
/* AVAssetExportSession properties are key-value observable unless documented otherwise */
/* Swift apps should use AVAssetExportSession.states to monitor the session */
-/* Indicates the name of the preset with which the AVExportSession was initialized */
+/// Indicates the name of the preset with which the AVExportSession was initialized.
@property (nonatomic, readonly) NSString *presetName;
-/* Indicates the instance of AVAsset with which the AVExportSession was initialized */
+/// Indicates the instance of AVAsset with which the AVExportSession was initialized.
@property (nonatomic, retain, readonly) AVAsset *asset API_AVAILABLE(macos(10.8), ios(5.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/* Indicates the type of file to be written by the session.
- The value of this property must be set before you invoke -exportAsynchronouslyWithCompletionHandler:; otherwise -exportAsynchronouslyWithCompletionHandler: will raise an NSInternalInconsistencyException.
- Setting the value of this property to a file type that's not among the session's supported file types will result in an NSInvalidArgumentException. See supportedFileTypes. */
+/// Indicates the type of file to be written by the session.
+///
+/// The value of this property must be set before you invoke -exportAsynchronouslyWithCompletionHandler:; otherwise -exportAsynchronouslyWithCompletionHandler: will raise an NSInternalInconsistencyException. Setting the value of this property to a file type that's not among the session's supported file types will result in an NSInvalidArgumentException. See supportedFileTypes.
@property (nonatomic, copy, nullable) AVFileType outputFileType
#if defined(__swift__)
API_DEPRECATED("Use export(to:as:) async throws instead", macos(10.7, 27.0), ios(4.0, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0)) API_UNAVAILABLE(watchos)
#endif
;
-/* Indicates the URL of the export session's output. You may use [[UTType typeWithIdentifier:outputFileType] preferredFilenameExtension] to obtain an appropriate path extension for the outputFileType you have specified. For more information, see <UniformTypeIdentifiers/UTType.h>. */
+/// Indicates the URL of the export session's output. You may use [[UTType typeWithIdentifier:outputFileType] preferredFilenameExtension] to obtain an appropriate path extension for the outputFileType you have specified. For more information, see <UniformTypeIdentifiers/UTType.h>.
@property (nonatomic, copy, nullable) NSURL *outputURL
#if defined(__swift__)
API_DEPRECATED("Use export(to:as:) async throws instead", macos(10.7, 27.0), ios(4.0, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0)) API_UNAVAILABLE(watchos)
#endif
;
-/* indicates that the output file should be optimized for network use, e.g. that a QuickTime movie file should support "fast start" */
+/// Indicates that the output file should be optimized for network use, e.g. that a QuickTime movie file should support "fast start".
@property (nonatomic) BOOL shouldOptimizeForNetworkUse;
-/*!
- @property allowsParallelizedExport
- @abstract Determines whether or not parallelization can be employed in the export.
- @discussion On select platforms, there may be opportunities to expedite the export by using additional resources in parallel.
- If set to YES, export parallelization will be enabled, only if parallelization requirements are met. There will
- be no error signaled if export parallelization is not achievable, and instead the export will proceed as normal
- (without parallelization).
- If set to NO, export parallelization will not be used.
-*/
+/// Determines whether or not parallelization can be employed in the export.
+///
+/// On select platforms, there may be opportunities to expedite the export by using additional resources in parallel.
+/// If set to YES, export parallelization will be enabled, only if parallelization requirements are met. There will
+/// be no error signaled if export parallelization is not achievable, and instead the export will proceed as normal
+/// (without parallelization).
+/// If set to NO, export parallelization will not be used.
@property (nonatomic) BOOL allowsParallelizedExport API_AVAILABLE(macos(14.0)) API_UNAVAILABLE(ios, tvos, watchos, visionos); // defaults to YES
-/* indicates the status of the export session */
+/// Indicates the status of the export session.
@property (nonatomic, readonly) AVAssetExportSessionStatus status
#if defined(__swift__)
API_DEPRECATED("Use states(updateInterval:) instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos)
#endif
;
-/* describes the error that occured if the export status is AVAssetExportSessionStatusFailed */
+/// Describes the error that occured if the export status is AVAssetExportSessionStatusFailed.
@property (nonatomic, readonly, nullable) NSError *error
#if defined(__swift__)
API_DEPRECATED("Use export(to:as:) async throws instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos)
#endif
;
-/*!
- @method exportAsynchronouslyWithCompletionHandler:
- @abstract Starts the asynchronous execution of an export session.
- @param handler
- If internal preparation for export fails, the handler will be invoked synchronously.
- The handler may also be called asynchronously after -exportAsynchronouslyWithCompletionHandler: returns,
- in the following cases:
- 1) if a failure occurs during the export, including failures of loading, re-encoding, or writing media data to the output,
- 2) if -cancelExport is invoked,
- 3) if export session succeeds, having completely written its output to the outputURL.
- In each case, AVAssetExportSession.status will signal the terminal state of the asset reader, and if a failure occurs, the NSError
- that describes the failure can be obtained from the error property.
- @discussion Initiates an asynchronous export operation and returns immediately.
-*/
+/// Starts the asynchronous execution of an export session.
+///
+/// Initiates an asynchronous export operation and returns immediately.
+///
+/// - Parameter handler: If internal preparation for export fails, the handler will be invoked synchronously. The handler may also be called asynchronously after -exportAsynchronouslyWithCompletionHandler: returns, in the following cases: 1) if a failure occurs during the export, including failures of loading, re-encoding, or writing media data to the output, 2) if -cancelExport is invoked, 3) if export session succeeds, having completely written its output to the outputURL. In each case, AVAssetExportSession.status will signal the terminal state of the asset reader, and if a failure occurs, the NSError that describes the failure can be obtained from the error property.
- (void)exportAsynchronouslyWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(void))handler
#if defined(__swift__)
API_DEPRECATED_WITH_REPLACEMENT("export(to:as:) async throws", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos)
#endif
;
-/* Specifies the progress of the export on a scale from 0 to 1.0. A value of 0 means the export has not yet begun, A value of 1.0 means the export is complete. This property is not key-value observable. */
+/// Specifies the progress of the export on a scale from 0 to 1.0. A value of 0 means the export has not yet begun, A value of 1.0 means the export is complete. This property is not key-value observable.
@property (nonatomic, readonly) float progress
#if defined(__swift__)
API_DEPRECATED("Use states(updateInterval:) instead", macos(10.7, 27.0), ios(4.0, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0)) API_UNAVAILABLE(watchos)
#endif
;
-/*!
- @method cancelExport
- @abstract Cancels the execution of an export session.
- @discussion Cancel can be invoked when the export is running.
-*/
+/// Cancels the execution of an export session.
+///
+/// Cancel can be invoked when the export is running.
- (void)cancelExport
#if defined(__swift__)
API_DEPRECATED("Use Task.cancel() instead", macos(10.7, 27.0), ios(4.0, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0)) API_UNAVAILABLE(watchos)
@@ -329,44 +288,41 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionPresets)
-/*!
- @method allExportPresets
- @abstract Returns all available export preset names.
- @discussion Returns an array of NSStrings with the names of all available presets. Note that not all presets are
- compatible with all AVAssets.
- @result An NSArray containing an NSString for each of the available preset names.
-*/
+/// Returns all available export preset names.
+///
+/// Returns an array of NSStrings with the names of all available presets. Note that not all presets are
+/// compatible with all AVAssets.
+///
+/// - Returns: An NSArray containing an NSString for each of the available preset names.
+ (NSArray<NSString *> *)allExportPresets;
-/*!
- @method exportPresetsCompatibleWithAsset:
- @abstract Returns only the identifiers compatible with the given AVAsset object.
- @discussion Not all export presets are compatible with all AVAssets. For example an video only asset is not compatible with an audio only preset.
- This method returns only the identifiers for presets that will be compatible with the given asset.
- A client should pass in an AVAsset that is ready to be exported.
- In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes
- (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation.
- This method will access the tracks property of the AVAsset to build the returned NSArray. To avoid blocking the calling thread,
- the tracks property should be loaded using the AVAsynchronousKeyValueLoading protocol before calling this method.
- @param asset An AVAsset object that is intended to be exported.
- @result An NSArray containing NSString values for the identifiers of compatible export types.
- The array is a complete list of the valid identifiers that can be used as arguments to
- initWithAsset:presetName: with the specified asset.
-*/
+/// Returns only the identifiers compatible with the given AVAsset object.
+///
+/// Not all export presets are compatible with all AVAssets. For example an video only asset is not compatible with an audio only preset.
+/// This method returns only the identifiers for presets that will be compatible with the given asset.
+/// A client should pass in an AVAsset that is ready to be exported.
+/// In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes
+/// (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation.
+/// This method will access the tracks property of the AVAsset to build the returned NSArray. To avoid blocking the calling thread,
+/// the tracks property should be loaded using the AVAsynchronousKeyValueLoading protocol before calling this method.
+///
+/// - Parameter asset: An AVAsset object that is intended to be exported.
+///
+/// - Returns: An NSArray containing NSString values for the identifiers of compatible export types.
+/// The array is a complete list of the valid identifiers that can be used as arguments to
+/// initWithAsset:presetName: with the specified asset.
+ (NSArray<NSString *> *)exportPresetsCompatibleWithAsset:(AVAsset *)asset API_DEPRECATED_WITH_REPLACEMENT("determineCompatibilityOfExportPreset:withAsset:outputFileType:completionHandler:", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0)) API_UNAVAILABLE(watchos, visionos);
-/*!
- @method determineCompatibilityOfExportPreset:withAsset:outputFileType:completionHandler:
- @abstract Performs an inspection on the compatibility of an export preset, AVAsset and output file type. Calls the completion handler with YES if
- the arguments are compatible; NO otherwise.
- @discussion Not all export presets are compatible with all AVAssets and file types. This method can be used to query compatibility.
- In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes
- (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation.
- @param presetName An NSString specifying the name of the preset template for the export.
- @param asset An AVAsset object that is intended to be exported.
- @param outputFileType An AVFileType indicating a file type to check; or nil, to query whether there are any compatible types.
- @param handler A block called with the compatibility result.
- */
+/// Performs an inspection on the compatibility of an export preset, AVAsset and output file type. Calls the completion handler with YES if the arguments are compatible; NO otherwise.
+///
+/// Not all export presets are compatible with all AVAssets and file types. This method can be used to query compatibility.
+/// In order to ensure that the setup and running of an export operation will succeed using a given preset no significant changes
+/// (such as adding or deleting tracks) should be made to the asset between retrieving compatible identifiers and performing the export operation.
+///
+/// - Parameter presetName: An NSString specifying the name of the preset template for the export.
+/// - Parameter asset: An AVAsset object that is intended to be exported.
+/// - Parameter outputFileType: An AVFileType indicating a file type to check; or nil, to query whether there are any compatible types.
+/// - Parameter handler: A block called with the compatibility result.
+ (void)determineCompatibilityOfExportPreset:(NSString *)presetName withAsset:(AVAsset *)asset outputFileType:(nullable AVFileType)outputFileType completionHandler:(void (^ NS_SWIFT_SENDABLE)(BOOL compatible))handler API_AVAILABLE(macos(10.9), ios(6.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos) NS_SWIFT_ASYNC_NAME(compatibility(ofExportPreset:with:outputFileType:));
@end // AVAssetExportSessionPresets
@@ -374,17 +330,16 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionFileTypes)
-/* Indicates the types of files the target can write, according to the preset the target was initialized with.
- Does not perform an inspection of the AVAsset to determine whether its contents are compatible with the supported file types. If you need to make that determination before initiating the export, use - (void)determineCompatibleFileTypesWithCompletionHandler:(void (^)(NSArray *compatibleFileTypes))handler:. */
+/// Indicates the types of files the target can write, according to the preset the target was initialized with.
+///
+/// Does not perform an inspection of the AVAsset to determine whether its contents are compatible with the supported file types. If you need to make that determination before initiating the export, use - (void)determineCompatibleFileTypesWithCompletionHandler:(void (^)(NSArray *compatibleFileTypes))handler:.
@property (nonatomic, readonly) NSArray<AVFileType> *supportedFileTypes;
-/*!
- @method determineCompatibleFileTypesWithCompletionHandler:
- @abstract Performs an inspection on the AVAsset and Preset the object was initialized with to determine a list of file types the ExportSession can write.
- @param handler
- Called when the inspection completes with an array of file types the ExportSession can write. Note that this may have a count of zero.
- @discussion This method is different than the supportedFileTypes property in that it performs an inspection of the AVAsset in order to determine its compatibility with each of the session's supported file types.
-*/
+/// Performs an inspection on the AVAsset and Preset the object was initialized with to determine a list of file types the ExportSession can write.
+///
+/// This method is different than the supportedFileTypes property in that it performs an inspection of the AVAsset in order to determine its compatibility with each of the session's supported file types.
+///
+/// - Parameter handler: Called when the inspection completes with an array of file types the ExportSession can write. Note that this may have a count of zero.
- (void)determineCompatibleFileTypesWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVFileType> *compatibleFileTypes))handler API_AVAILABLE(macos(10.9), ios(6.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos) NS_SWIFT_ASYNC_NAME(getter:compatibleFileTypes());
@end // AVAssetExportSessionFileTypes
@@ -392,34 +347,30 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionDurationAndLength)
-/* Specifies a time range to be exported from the source. The default timeRange of an export session is kCMTimeZero..kCMTimePositiveInfinity, meaning that the full duration of the asset will be exported. */
+/// Specifies a time range to be exported from the source. The default timeRange of an export session is kCMTimeZero..kCMTimePositiveInfinity, meaning that the full duration of the asset will be exported.
@property (nonatomic) CMTimeRange timeRange;
-/* Provides an estimate of the maximum duration of exported media that is possible given the source asset, the export preset, and the current value of fileLengthLimit. The export will not stop when it reaches this maximum duration; set the timeRange property to export only a certain time range. */
+/// Provides an estimate of the maximum duration of exported media that is possible given the source asset, the export preset, and the current value of fileLengthLimit. The export will not stop when it reaches this maximum duration; set the timeRange property to export only a certain time range.
@property (nonatomic, readonly) CMTime maxDuration API_DEPRECATED("Use estimateMaximumDurationWithCompletionHandler: instead", macos(10.14, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0)) API_UNAVAILABLE(watchos, visionos);
-/* Indicates the estimated byte size of exported file. Returns zero when export preset is AVAssetExportPresetPassthrough, AVAssetExportPresetAppleProRes422LPCM or AVAssetExportPresetAppleProRes4444LPCM. This property will also return zero if a numeric value (ie. not invalid, indefinite, or infinite) for the timeRange property has not been set. Note that the returned value does not take into account the source asset information. For a more accurate estimation, use estimateOutputFileLengthWithCompletionHandler. */
+/// Indicates the estimated byte size of exported file. Returns zero when export preset is AVAssetExportPresetPassthrough, AVAssetExportPresetAppleProRes422LPCM or AVAssetExportPresetAppleProRes4444LPCM. This property will also return zero if a numeric value (ie. not invalid, indefinite, or infinite) for the timeRange property has not been set. Note that the returned value does not take into account the source asset information. For a more accurate estimation, use estimateOutputFileLengthWithCompletionHandler.
@property (nonatomic, readonly) long long estimatedOutputFileLength API_DEPRECATED("Use estimateOutputFileLengthWithCompletionHandler: instead", macos(10.9, 15.0), ios(5.0, 18.0), tvos(5.0, 18.0)) API_UNAVAILABLE(watchos, visionos);
-/* Indicates the file length that the output of the session should not exceed. Depending on the content of the source asset, it is possible for the output to slightly exceed the file length limit. The length of the output file should be tested if you require that a strict limit be observed before making use of the output. See also maxDuration and timeRange. */
+/// Indicates the file length that the output of the session should not exceed. Depending on the content of the source asset, it is possible for the output to slightly exceed the file length limit. The length of the output file should be tested if you require that a strict limit be observed before making use of the output. See also maxDuration and timeRange.
@property (nonatomic) long long fileLengthLimit API_AVAILABLE(macos(10.14), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @method estimateMaximumDurationWithCompletionHandler:
- @abstract Starts the asynchronous execution of estimating the maximum duration of the export based on the asset, preset, and fileLengthLimit associated with the export session.
- @discussion If fileLengthLimit is not set on the export session, fileLengthLimit will be assumed to be the maximum file size specified by the preset (if any); else infinite.
- @param handler
- A block called with the estimated maximum duration, or kCMTimeInvalid if an error occurs. The error parameter will be non-nil if an error occurs.
-*/
+/// Starts the asynchronous execution of estimating the maximum duration of the export based on the asset, preset, and fileLengthLimit associated with the export session.
+///
+/// If fileLengthLimit is not set on the export session, fileLengthLimit will be assumed to be the maximum file size specified by the preset (if any); else infinite.
+///
+/// - Parameter handler: A block called with the estimated maximum duration, or kCMTimeInvalid if an error occurs. The error parameter will be non-nil if an error occurs.
- (void)estimateMaximumDurationWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(CMTime estimatedMaximumDuration, NSError * _Nullable error ))handler API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), visionos(1.0)) API_UNAVAILABLE(watchos) NS_SWIFT_ASYNC_NAME(getter:estimatedMaximumDuration());
-/*!
- @method estimateOutputFileLengthWithCompletionHandler:
- @abstract Starts the asynchronous execution of estimating the output file length of the export based on the asset, preset, and timeRange associated with the export session.
- @discussion If timeRange is not set on the export session, timeRange will be assumed to be the full time range of the asset.
- @param handler
- A block called with the estimated output file length in bytes, if it can be determined; 0 otherwise. The error parameter will be non-nil if an error occurs.
- */
+/// Starts the asynchronous execution of estimating the output file length of the export based on the asset, preset, and timeRange associated with the export session.
+///
+/// If timeRange is not set on the export session, timeRange will be assumed to be the full time range of the asset.
+///
+/// - Parameter handler: A block called with the estimated output file length in bytes, if it can be determined; 0 otherwise. The error parameter will be non-nil if an error occurs.
- (void)estimateOutputFileLengthWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(int64_t estimatedOutputFileLength, NSError * _Nullable error ))handler API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), visionos(1.0)) API_UNAVAILABLE(watchos) NS_SWIFT_ASYNC_NAME(getter:estimatedOutputFileLengthInBytes());
@end // AVAssetExportSessionDurationAndLength
@@ -427,14 +378,14 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionMetadata)
-/* Specifies an NSArray of AVMetadataItems that are to be written to the output file by the export session.
- If the value of this key is nil, any existing metadata in the exported asset will be translated as accurately as possible into
- the appropriate metadata keyspace for the output file and written to the output. */
+/// Specifies an NSArray of AVMetadataItems that are to be written to the output file by the export session.
+///
+/// If the value of this key is nil, any existing metadata in the exported asset will be translated as accurately as possible into the appropriate metadata keyspace for the output file and written to the output.
@property (nonatomic, copy, nullable) NSArray<AVMetadataItem *> *metadata;
-/* Specifies a filter object to be used during export to determine which metadata items should be transferred from the source asset.
- If the value of this key is nil, no filter will be applied. This is the default.
- The filter will not be applied to metadata set with via the metadata property. To apply the filter to metadata before it is set on the metadata property, see the methods in AVMetadataItem's AVMetadataItemArrayFiltering category. */
+/// Specifies a filter object to be used during export to determine which metadata items should be transferred from the source asset.
+///
+/// If the value of this key is nil, no filter will be applied. This is the default. The filter will not be applied to metadata set with via the metadata property. To apply the filter to metadata before it is set on the metadata property, see the methods in AVMetadataItem's AVMetadataItemArrayFiltering category.
@property (nonatomic, retain, nullable) AVMetadataItemFilter *metadataItemFilter API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end // AVAssetExportSessionMetadata
@@ -442,30 +393,26 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionMediaProcessing)
-/* Indicates the processing algorithm used to manage audio pitch for scaled audio edits.
- Constants for various time pitch algorithms, e.g. AVAudioTimePitchAlgorithmSpectral, are defined in AVAudioProcessingSettings.h. An NSInvalidArgumentException will be raised if this property is set to a value other than the constants defined in that file.
- The default value is AVAudioTimePitchAlgorithmSpectral. */
+/// Indicates the processing algorithm used to manage audio pitch for scaled audio edits.
+///
+/// Constants for various time pitch algorithms, e.g. AVAudioTimePitchAlgorithmSpectral, are defined in AVAudioProcessingSettings.h. An NSInvalidArgumentException will be raised if this property is set to a value other than the constants defined in that file. The default value is AVAudioTimePitchAlgorithmSpectral.
@property (nonatomic, copy) AVAudioTimePitchAlgorithm audioTimePitchAlgorithm API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/* Indicates whether non-default audio mixing is enabled for export and supplies the parameters for audio mixing. Ignored when export preset is AVAssetExportPresetPassthrough. */
+/// Indicates whether non-default audio mixing is enabled for export and supplies the parameters for audio mixing. Ignored when export preset is AVAssetExportPresetPassthrough.
@property (nonatomic, copy, nullable) AVAudioMix *audioMix;
-/* Indicates whether video composition is enabled for export and supplies the instructions for video composition. Ignored when export preset is AVAssetExportPresetPassthrough. */
+/// Indicates whether video composition is enabled for export and supplies the instructions for video composition. Ignored when export preset is AVAssetExportPresetPassthrough.
@property (nonatomic, copy, nullable) AVVideoComposition *videoComposition;
-/* Indicates the custom video compositor instance used, if any */
+/// Indicates the custom video compositor instance used, if any.
@property (nonatomic, readonly, nullable) id <AVVideoCompositing> customVideoCompositor API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property audioTrackGroupHandling
- @abstract Defines export policy for handling alternate audio tracks
-
- @discussion
- Specifies the handling of audio tracks that are members of the same alternate track group corresponding to an exported audio track in the source asset.
- If no audio track group is present, the value of this property has no effect.
- If necessary, use the trackGroups property of AVAsset to determine whether any audio track groups are present.
- The AVAudioMix property is not allowed to be used when also specifying alternate track output handling. An exception will be thrown if both are specified.
-*/
+/// Defines export policy for handling alternate audio tracks
+///
+/// Specifies the handling of audio tracks that are members of the same alternate track group corresponding to an exported audio track in the source asset.
+/// If no audio track group is present, the value of this property has no effect.
+/// If necessary, use the trackGroups property of AVAsset to determine whether any audio track groups are present.
+/// The AVAudioMix property is not allowed to be used when also specifying alternate track output handling. An exception will be thrown if both are specified.
@property (nonatomic) AVAssetTrackGroupOutputHandling audioTrackGroupHandling API_AVAILABLE(macos(13.0), ios(16.0), tvos(16.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end // AVAssetExportSessionMediaProcessing
@@ -473,76 +420,65 @@
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionMultipass)
-/*!
- @property canPerformMultiplePassesOverSourceMediaData
- @abstract
- Determines whether the export session can perform multiple passes over the source media to achieve better results.
-
- @discussion
- When the value for this property is YES, the export session can produce higher quality results at the expense of longer export times. Setting this property to YES may also require the export session to write temporary data to disk during the export. To control the location of temporary data, use the property directoryForTemporaryFiles.
-
- The default value is NO. Not all export session configurations can benefit from performing multiple passes over the source media. In these cases, setting this property to YES has no effect.
-
- This property cannot be set after the export has started.
-*/
+/// Determines whether the export session can perform multiple passes over the source media to achieve better results.
+///
+/// When the value for this property is YES, the export session can produce higher quality results at the expense of longer export times. Setting this property to YES may also require the export session to write temporary data to disk during the export. To control the location of temporary data, use the property directoryForTemporaryFiles.
+///
+/// The default value is NO. Not all export session configurations can benefit from performing multiple passes over the source media. In these cases, setting this property to YES has no effect.
+///
+/// This property cannot be set after the export has started.
@property (nonatomic) BOOL canPerformMultiplePassesOverSourceMediaData API_AVAILABLE(macos(10.10), ios(8.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property directoryForTemporaryFiles
- @abstract
- Specifies a directory that is suitable for containing temporary files generated during the export process
-
- @discussion
- AVAssetExportSession may need to write temporary files when configured in certain ways, such as when canPerformMultiplePassesOverSourceMediaData is set to YES. This property can be used to control where in the filesystem those temporary files are created. All temporary files will be deleted when the export is completed, is canceled, or fails.
-
- When the value of this property is nil, the export session will choose a suitable location when writing temporary files. The default value is nil.
-
- This property cannot be set after the export has started. The export will fail if the URL points to a location that is not a directory, does not exist, is not on the local file system, or if a file cannot be created in this directory (for example, due to insufficient permissions or sandboxing restrictions).
-*/
+/// Specifies a directory that is suitable for containing temporary files generated during the export process
+///
+/// AVAssetExportSession may need to write temporary files when configured in certain ways, such as when canPerformMultiplePassesOverSourceMediaData is set to YES. This property can be used to control where in the filesystem those temporary files are created. All temporary files will be deleted when the export is completed, is canceled, or fails.
+///
+/// When the value of this property is nil, the export session will choose a suitable location when writing temporary files. The default value is nil.
+///
+/// This property cannot be set after the export has started. The export will fail if the URL points to a location that is not a directory, does not exist, is not on the local file system, or if a file cannot be created in this directory (for example, due to insufficient permissions or sandboxing restrictions).
@property (nonatomic, copy, nullable) NSURL *directoryForTemporaryFiles API_AVAILABLE(macos(10.10), ios(8.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end // AVAssetExportSessionMultipass
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVAssetExportSession (AVAssetExportSessionResumable)
-/*!
- @method configureForResumableExportWithCompletionHandler:
- @abstract Attempt to configure the exportSession into resumption mode.
- @discussion For select encoders, an export can be performed in temporal segments, and then
- stitched together at the end.
- The client is responsible for configuring the export session identically for subsequent
- sessions, if the export is to be resumed from partial results from a previous run.
-
- IMPORTANT: directoryForTemporaryFiles MUST be specified for resumable exports.
- This directory holds the temporary files for resumable exports which allows the export to
- resume on a subsequent instantiation. The client is responsible for making the
- directoryForTemporaryFiles unique and deterministic across app launches or device reboots
- if the session is intended to be resumable after such events. The client must ensure that
- it does not re-use a temporary directory corresponding to a different resumable export
- session, or the contents between different exports may be erroneously combined.
-
- This method validates that the currently configured export properties allow resumption,
- and interrogates the contents of directoryForTemporaryFiles to determine if this is a resuming
- session or a new one. As such, this should be called after all settings are finalized for this
- export session, i.e. just prior to exportAsynchronouslyWithCompletionHandler.
-
- resumptionState details the currently configured resumption state of the export session.
- Even if resumptionState indicates not all conditions for resumption are met, a client may still
- call exportAsynchronouslyWithCompletionHandler using the current session, and the export
- will be performed in the default (non-resuming) manner.
-
- This method cannot be called after the export has started.
-
- cancelExport may be called if an in-flight export needs to be interrupted. The partial results
- will be maintained.
-
- The client is responsible for deleting the temporary directory if the export will never be
- resumed in the future.
-
- Since intermediate files are written to support the resume functionality, resumable exports
- will typically double the NAND accesses, since the samples need to be written to disk twice.
-*/
+/// Attempt to configure the exportSession into resumption mode.
+///
+/// For select encoders, an export can be performed in temporal segments, and then
+/// stitched together at the end.
+///
+/// The client is responsible for configuring the export session identically for subsequent
+/// sessions, if the export is to be resumed from partial results from a previous run.
+///
+/// IMPORTANT: directoryForTemporaryFiles MUST be specified for resumable exports.
+/// This directory holds the temporary files for resumable exports which allows the export to
+/// resume on a subsequent instantiation. The client is responsible for making the
+/// directoryForTemporaryFiles unique and deterministic across app launches or device reboots
+/// if the session is intended to be resumable after such events. The client must ensure that
+/// it does not re-use a temporary directory corresponding to a different resumable export
+/// session, or the contents between different exports may be erroneously combined.
+///
+/// This method validates that the currently configured export properties allow resumption,
+/// and interrogates the contents of directoryForTemporaryFiles to determine if this is a resuming
+/// session or a new one. As such, this should be called after all settings are finalized for this
+/// export session, i.e. just prior to exportAsynchronouslyWithCompletionHandler.
+///
+/// resumptionState details the currently configured resumption state of the export session.
+/// Even if resumptionState indicates not all conditions for resumption are met, a client may still
+/// call exportAsynchronouslyWithCompletionHandler using the current session, and the export
+/// will be performed in the default (non-resuming) manner.
+///
+/// This method cannot be called after the export has started.
+///
+/// cancelExport may be called if an in-flight export needs to be interrupted. The partial results
+/// will be maintained.
+///
+/// The client is responsible for deleting the temporary directory if the export will never be
+/// resumed in the future.
+///
+/// Since intermediate files are written to support the resume functionality, resumable exports
+/// will typically double the NAND accesses, since the samples need to be written to disk twice.
- (void)configureForResumableExportWithCompletionHandler:(void (^)(AVAssetExportSessionResumptionState * resumptionState))completionHandler NS_REFINED_FOR_SWIFT;
@end // AVAssetExportSessionResumable
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWriter.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWriter.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWriter.h 2026-05-27 00:09:45
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWriter.h 2026-06-17 00:58:26
@@ -23,44 +23,29 @@
NS_ASSUME_NONNULL_BEGIN
-/*!
- @enum AVAssetWriterStatus
- @abstract
- These constants are returned by the AVAssetWriter status property to indicate whether it can successfully write samples to its output file.
-
- @constant AVAssetWriterStatusUnknown
- Indicates that the status of the asset writer is not currently known.
- @constant AVAssetWriterStatusWriting
- Indicates that the asset writer is successfully writing samples to its output file.
- @constant AVAssetWriterStatusCompleted
- Indicates that the asset writer has successfully written all samples following a call to finishWriting.
- @constant AVAssetWriterStatusFailed
- Indicates that the asset writer can no longer write samples to its output file because of an error. The error is described by the value of the asset writer's error property.
- @constant AVAssetWriterStatusCancelled
- Indicates that the asset writer can no longer write samples because writing was canceled with the cancelWriting method.
- */
+/// These constants are returned by the AVAssetWriter status property to indicate whether it can successfully write samples to its output file.
typedef NS_ENUM(NSInteger, AVAssetWriterStatus) {
+ /// Indicates that the status of the asset writer is not currently known.
AVAssetWriterStatusUnknown = 0,
+ /// Indicates that the asset writer is successfully writing samples to its output file.
AVAssetWriterStatusWriting = 1,
+ /// Indicates that the asset writer has successfully written all samples following a call to finishWriting.
AVAssetWriterStatusCompleted = 2,
+ /// Indicates that the asset writer can no longer write samples to its output file because of an error. The error is described by the value of the asset writer's error property.
AVAssetWriterStatusFailed = 3,
+ /// Indicates that the asset writer can no longer write samples because writing was canceled with the cancelWriting method.
AVAssetWriterStatusCancelled = 4
};
@class AVAssetWriterInternal;
-/*!
- @class AVAssetWriter
- @abstract
- AVAssetWriter provides services for writing media data to a new file,
-
- @discussion
- Instances of AVAssetWriter can write media to new files in formats such as the QuickTime movie file format or the MPEG-4 file format. AVAssetWriter has support for automatic interleaving of media data for multiple concurrent tracks. Source media data can be obtained from instances of AVAssetReader for one or more assets or from other sources outside of AVFoundation.
-
- Instances of AVAssetWriter can re-encode media samples as they are written. Instances of AVAssetWriter can also optionally write metadata collections to the output file.
-
- A single instance of AVAssetWriter can be used once to write to a single file. Clients that wish to write to files multiple times must use a new instance of AVAssetWriter each time.
- */
+/// AVAssetWriter provides services for writing media data to a new file.
+///
+/// Instances of AVAssetWriter can write media to new files in formats such as the QuickTime movie file format or the MPEG-4 file format. AVAssetWriter has support for automatic interleaving of media data for multiple concurrent tracks. Source media data can be obtained from instances of AVAssetReader for one or more assets or from other sources outside of AVFoundation.
+///
+/// Instances of AVAssetWriter can re-encode media samples as they are written. Instances of AVAssetWriter can also optionally write metadata collections to the output file.
+///
+/// A single instance of AVAssetWriter can be used once to write to a single file. Clients that wish to write to files multiple times must use a new instance of AVAssetWriter each time.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(10.7), ios(4.1), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetWriter : NSObject
@@ -70,215 +55,132 @@
}
AV_INIT_UNAVAILABLE
-/*!
- @method assetWriterWithURL:fileType:error:
- @abstract
- Returns an instance of AVAssetWriter configured to write to a file in a specified container format.
-
- @param outputURL
- The location of the file to be written. The URL must be a file URL.
- @param outputFileType
- A UTI indicating the format of the file to be written.
- @param outError
- On return, if initialization of the AVAssetWriter fails, points to an NSError describing the nature of the failure.
- @result
- An instance of AVAssetWriter.
-
- @discussion
- Writing will fail if a file already exists at the specified URL.
-
- UTIs for container formats that can be written are declared in AVMediaFormat.h.
- */
+/// Returns an instance of AVAssetWriter configured to write to a file in a specified container format.
+///
+/// Writing will fail if a file already exists at the specified URL.
+///
+/// UTIs for container formats that can be written are declared in AVMediaFormat.h.
+///
+/// - Parameter outputURL: The location of the file to be written. The URL must be a file URL.
+/// - Parameter outputFileType: A UTI indicating the format of the file to be written.
+/// - Parameter outError: On return, if initialization of the AVAssetWriter fails, points to an NSError describing the nature of the failure.
+///
+/// - Returns: An instance of AVAssetWriter.
+ (nullable instancetype)assetWriterWithURL:(NSURL *)outputURL fileType:(AVFileType)outputFileType error:(NSError * _Nullable * _Nullable)outError;
-/*!
- @method initWithURL:fileType:error:
- @abstract
- Creates an instance of AVAssetWriter configured to write to a file in a specified container format.
-
- @param outputURL
- The location of the file to be written. The URL must be a file URL.
- @param outputFileType
- A UTI indicating the format of the file to be written.
- @param outError
- On return, if initialization of the AVAssetWriter fails, points to an NSError describing the nature of the failure.
- @result
- An instance of AVAssetWriter.
-
- @discussion
- Writing will fail if a file already exists at the specified URL.
-
- This method throws an exception if the output file type is not declared in AVMediaFormat.h.
- */
+/// Creates an instance of AVAssetWriter configured to write to a file in a specified container format.
+///
+/// Writing will fail if a file already exists at the specified URL.
+///
+/// This method throws an exception if the output file type is not declared in AVMediaFormat.h.
+///
+/// - Parameter outputURL: The location of the file to be written. The URL must be a file URL.
+/// - Parameter outputFileType: A UTI indicating the format of the file to be written.
+/// - Parameter outError: On return, if initialization of the AVAssetWriter fails, points to an NSError describing the nature of the failure.
+///
+/// - Returns: An instance of AVAssetWriter.
- (nullable instancetype)initWithURL:(NSURL *)outputURL fileType:(AVFileType)outputFileType error:(NSError * _Nullable * _Nullable)outError NS_DESIGNATED_INITIALIZER;
-/*!
- @method initWithContentType:
- @abstract
- Creates an instance of AVAssetWriter configured to output segment data in a specified container format.
-
- @param outputContentType
- A UTType indicating the format of the segment data to be output.
- @result
- An instance of AVAssetWriter.
-
- @discussion
- Clients that want to receive segment data through the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method should use this initializer instead of -initWithURL:fileType:error:.
-
- Clients may use +typeWithIdentifier: with a UTI to create an instance of UTType. See <UniformTypeIdentifiers/UTType.h>.
-
- This method throws an exception if the output content type UTI for container format is not declared in AVMediaFormat.h.
- */
+/// Creates an instance of AVAssetWriter configured to output segment data in a specified container format.
+///
+/// Clients that want to receive segment data through the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method should use this initializer instead of -initWithURL:fileType:error:.
+///
+/// Clients may use +typeWithIdentifier: with a UTI to create an instance of UTType. See <UniformTypeIdentifiers/UTType.h>.
+///
+/// This method throws an exception if the output content type UTI for container format is not declared in AVMediaFormat.h.
+///
+/// - Parameter outputContentType: A UTType indicating the format of the segment data to be output.
+///
+/// - Returns: An instance of AVAssetWriter.
- (instancetype)initWithContentType:(UTType *)outputContentType NS_DESIGNATED_INITIALIZER API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property outputURL
- @abstract
- The location of the file for which the instance of AVAssetWriter was initialized for writing.
- @discussion
- You may use [[UTType typeWithIdentifier:outputFileType] preferredFilenameExtension] to obtain an appropriate path extension for the outputFileType you have specified. For more information, see <UniformTypeIdentifiers/UTType.h>.
- */
+/// The location of the file for which the instance of AVAssetWriter was initialized for writing.
+///
+/// You may use [[UTType typeWithIdentifier:outputFileType] preferredFilenameExtension] to obtain an appropriate path extension for the outputFileType you have specified. For more information, see <UniformTypeIdentifiers/UTType.h>.
@property (nonatomic, copy, readonly) NSURL *outputURL;
-/*!
- @property outputFileType
- @abstract
- The UTI of the file format of the file for which the instance of AVAssetWriter was initialized for writing.
- */
+/// The UTI of the file format of the file for which the instance of AVAssetWriter was initialized for writing.
@property (nonatomic, copy, readonly) AVFileType outputFileType;
-/*!
- @property availableMediaTypes
- @abstract
- The media types for which inputs can be added to the receiver.
-
- @discussion
- Some media types may not be accepted within the file format with which an AVAssetWriter was initialized.
- */
+/// The media types for which inputs can be added to the receiver.
+///
+/// Some media types may not be accepted within the file format with which an AVAssetWriter was initialized.
@property (nonatomic, readonly) NSArray<AVMediaType> *availableMediaTypes;
-/*!
- @property status
- @abstract
- The status of writing samples to the receiver's output file.
-
- @discussion
- The value of this property is an AVAssetWriterStatus that indicates whether writing is in progress, has completed successfully, has been canceled, or has failed. Clients of AVAssetWriterInput objects should check the value of this property after appending samples fails to determine why no more samples could be written. This property is thread safe.
- */
+/// The status of writing samples to the receiver's output file.
+///
+/// The value of this property is an AVAssetWriterStatus that indicates whether writing is in progress, has completed successfully, has been canceled, or has failed. Clients of AVAssetWriterInput objects should check the value of this property after appending samples fails to determine why no more samples could be written. This property is thread safe.
@property (readonly) AVAssetWriterStatus status;
-/*!
- @property error
- @abstract
- If the receiver's status is AVAssetWriterStatusFailed, this describes the error that caused the failure.
-
- @discussion
- The value of this property is an NSError that describes what caused the receiver to no longer be able to write to its output file. If the receiver's status is not AVAssetWriterStatusFailed, the value of this property is nil. This property is thread safe.
- */
+/// If the receiver's status is AVAssetWriterStatusFailed, this describes the error that caused the failure.
+///
+/// The value of this property is an NSError that describes what caused the receiver to no longer be able to write to its output file. If the receiver's status is not AVAssetWriterStatusFailed, the value of this property is nil. This property is thread safe.
@property (readonly, nullable) NSError *error;
-/*!
- @property metadata
- @abstract
- A collection of metadata to be written to the receiver's output file.
-
- @discussion
- The value of this property is an array of AVMetadataItem objects representing the collection of top-level metadata to be written in the output file.
-
- This property cannot be set after writing has started.
- */
+/// A collection of metadata to be written to the receiver's output file.
+///
+/// The value of this property is an array of AVMetadataItem objects representing the collection of top-level metadata to be written in the output file.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic, copy) NSArray<AVMetadataItem *> *metadata;
-/*!
- @property shouldOptimizeForNetworkUse
- @abstract
- Specifies whether the output file should be written in way that makes it more suitable for playback over a network
-
- @discussion
- When the value of this property is YES, the output file will be written in such a way that playback can start after only a small amount of the file is downloaded.
-
- This property cannot be set after writing has started.
- */
+/// Specifies whether the output file should be written in way that makes it more suitable for playback over a network
+///
+/// When the value of this property is YES, the output file will be written in such a way that playback can start after only a small amount of the file is downloaded.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) BOOL shouldOptimizeForNetworkUse;
-/*!
- @property directoryForTemporaryFiles
- @abstract
- Specifies a directory that is suitable for containing temporary files generated during the process of writing an asset.
-
- @discussion
- AVAssetWriter may need to write temporary files when configured in certain ways, such as when performsMultiPassEncodingIfSupported is set to YES on one or more of its inputs. This property can be used to control where in the filesystem those temporary files are created. All temporary files will be deleted when asset writing is completed, is canceled, or fails.
-
- When the value of this property is nil, the asset writer will choose a suitable location when writing temporary files. The default value is nil.
-
- This property cannot be set after writing has started. The asset writer will fail if a file cannot be created in this directory (for example, due to insufficient permissions).
- */
+/// Specifies a directory that is suitable for containing temporary files generated during the process of writing an asset.
+///
+/// AVAssetWriter may need to write temporary files when configured in certain ways, such as when performsMultiPassEncodingIfSupported is set to YES on one or more of its inputs. This property can be used to control where in the filesystem those temporary files are created. All temporary files will be deleted when asset writing is completed, is canceled, or fails.
+///
+/// When the value of this property is nil, the asset writer will choose a suitable location when writing temporary files. The default value is nil.
+///
+/// This property cannot be set after writing has started. The asset writer will fail if a file cannot be created in this directory (for example, due to insufficient permissions).
@property (nonatomic, copy, nullable) NSURL *directoryForTemporaryFiles API_AVAILABLE(macos(10.10), ios(8.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property inputs
- @abstract
- The inputs from which the asset writer receives media data.
- @discussion
- The value of this property is an NSArray containing concrete instances of AVAssetWriterInput. Inputs can be added to the receiver using the addInput: method.
- */
+/// The inputs from which the asset writer receives media data.
+///
+/// The value of this property is an NSArray containing concrete instances of AVAssetWriterInput. Inputs can be added to the receiver using the addInput: method.
@property (nonatomic, readonly) NSArray<AVAssetWriterInput *> *inputs;
-/*!
- @method canApplyOutputSettings:forMediaType:
- @abstract
- Tests whether output settings for a specific media type are supported by the receiver's file format.
-
- @param outputSettings
- The output settings that are to be tested.
- @param mediaType
- The media type for which the output settings are to be tested. Media types are defined in AVMediaFormat.h.
- @result
- A BOOL indicating whether the given output settings can be used for the given media type.
-
- @discussion
- This method determines whether the output settings for the specified media type can be used with the receiver's file format. For example, video compression settings that specify H.264 compression are not compatible with file formats that cannot contain H.264-compressed video.
-
- Attempting to add an input with output settings and a media type for which this method returns NO will cause an exception to be thrown.
-*/
+/// Tests whether output settings for a specific media type are supported by the receiver's file format.
+///
+/// This method determines whether the output settings for the specified media type can be used with the receiver's file format. For example, video compression settings that specify H.264 compression are not compatible with file formats that cannot contain H.264-compressed video.
+///
+/// Attempting to add an input with output settings and a media type for which this method returns NO will cause an exception to be thrown.
+///
+/// - Parameter outputSettings: The output settings that are to be tested.
+/// - Parameter mediaType: The media type for which the output settings are to be tested. Media types are defined in AVMediaFormat.h.
+///
+/// - Returns: A BOOL indicating whether the given output settings can be used for the given media type.
- (BOOL)canApplyOutputSettings:(nullable NSDictionary<NSString *, id> *)outputSettings forMediaType:(AVMediaType)mediaType;
-/*!
- @method canAddInput:
- @abstract
- Tests whether an input can be added to the receiver.
-
- @param input
- The AVAssetWriterInput object to be tested.
- @result
- A BOOL indicating whether the input can be added to the receiver.
-
- @discussion
- An input that accepts media data of a type that is not compatible with the receiver, or with output settings that are not compatible with the receiver, cannot be added.
- */
+/// Tests whether an input can be added to the receiver.
+///
+/// An input that accepts media data of a type that is not compatible with the receiver, or with output settings that are not compatible with the receiver, cannot be added.
+///
+/// - Parameter input: The AVAssetWriterInput object to be tested.
+///
+/// - Returns: A BOOL indicating whether the input can be added to the receiver.
- (BOOL)canAddInput:(AVAssetWriterInput *)input;
-/*!
- @method addInput:
- @abstract
- Adds an input to the receiver.
-
- @param input
- The AVAssetWriterInput object to be added.
-
- @discussion
- Inputs are created with a media type and output settings. These both must be compatible with the receiver.
-
- Inputs cannot be added after writing has started.
-
- This method throws an exception if any of the following conditions are satisfied:
- - the input's media type is not allowed for this asset writer
- - writing uncompressed video in a specific format
- - passthrough* to files (other than AVFileTypeQuickTimeMovie) is missing a format hint in the AVAssetWriterInput initializer
- - passthrough* is not supported for this media/file type combination (for example, AVFileTypeWAVE only supports AVMediaTypeAudio)
-
- *Passthrough is indicated when the input's output settings are nil.
- */
+/// Adds an input to the receiver.
+///
+/// Inputs are created with a media type and output settings. These both must be compatible with the receiver.
+///
+/// Inputs cannot be added after writing has started.
+///
+/// This method throws an exception if any of the following conditions are satisfied:
+/// - the input's media type is not allowed for this asset writer
+/// - writing uncompressed video in a specific format
+/// - passthrough\* to files (other than AVFileTypeQuickTimeMovie) is missing a format hint in the AVAssetWriterInput initializer
+/// - passthrough\* is not supported for this media/file type combination (for example, AVFileTypeWAVE only supports AVMediaTypeAudio)
+///
+/// \*Passthrough is indicated when the input's output settings are nil.
+///
+/// - Parameter input: The AVAssetWriterInput object to be added.
- (void)addInput:(AVAssetWriterInput *)input
#if __swift__
API_DEPRECATED("Use the appropriate AVAssetWriter.inputReceiver(for:...) overload for your input and optional adaptor instead", macos(10.7, 27.0), ios(4.1, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0))
@@ -288,21 +190,15 @@
#endif
;
-/*!
- @method startWriting
- @abstract
- Prepares the receiver for accepting input and for writing its output to its output file.
-
- @result
- A BOOL indicating whether writing successfully started.
-
- @discussion
- This method must be called after all inputs have been added and other configuration properties have been set in order to tell the receiver to prepare for writing. After this method is called, clients can start writing sessions using startSessionAtSourceTime: and can write media samples using the methods provided by each of the receiver's inputs.
-
- If writing cannot be started, this method returns NO. Clients can check the values of the status and error properties for more information on why writing could not be started.
-
- On iOS, if the status of an AVAssetWriter is AVAssetWriterStatusWriting when the client app goes into the background, its status will change to AVAssetWriterStatusFailed and appending to any of its inputs will fail. You may want to use -[UIApplication beginBackgroundTaskWithExpirationHandler:] to avoid being interrupted in the middle of a writing session and to finish writing the data that has already been appended. For more information about executing code in the background, see the iOS Application Programming Guide.
- */
+/// Prepares the receiver for accepting input and for writing its output to its output file.
+///
+/// This method must be called after all inputs have been added and other configuration properties have been set in order to tell the receiver to prepare for writing. After this method is called, clients can start writing sessions using startSessionAtSourceTime: and can write media samples using the methods provided by each of the receiver's inputs.
+///
+/// If writing cannot be started, this method returns NO. Clients can check the values of the status and error properties for more information on why writing could not be started.
+///
+/// On iOS, if the status of an AVAssetWriter is AVAssetWriterStatusWriting when the client app goes into the background, its status will change to AVAssetWriterStatusFailed and appending to any of its inputs will fail. You may want to use -[UIApplication beginBackgroundTaskWithExpirationHandler:] to avoid being interrupted in the middle of a writing session and to finish writing the data that has already been appended. For more information about executing code in the background, see the iOS Application Programming Guide.
+///
+/// - Returns: A BOOL indicating whether writing successfully started.
- (BOOL)startWriting
#if __swift__
API_DEPRECATED("Use start() instead", macos(10.7, 27.0), ios(4.1, 27.0), tvos(9.0, 27.0), visionos(1.0, 27.0))
@@ -312,95 +208,67 @@
#endif
;
-/*!
- @method startSessionAtSourceTime:
- @abstract
- Initiates a sample-writing session for the receiver.
-
- @param startTime
- The starting asset time for the sample-writing session, in the timeline of the source samples.
-
- @discussion
- Sequences of sample data appended to the asset writer inputs are considered to fall within "sample-writing sessions", initiated with this method. Accordingly, this method must be called after writing has started (using -startWriting) but before any sample data is appended to the receiver's inputs.
-
- Each writing session has a start time which, where allowed by the file format being written, defines the mapping from the timeline of source samples to the timeline of the written file. In the case of the QuickTime movie file format, the first session begins at movie time 0, so a sample appended with timestamp T will be played at movie time (T-startTime). Samples with timestamps earlier than startTime will still be added to the output file but will be edited out (i.e. not presented during playback). If the earliest appended sample for an input has a timestamp later than than startTime, an empty edit will be inserted to preserve synchronization between tracks of the output asset.
-
- To end the session started by use of this method, use -endSessionAtSourceTime: or -finishWritingWithCompletionHandler:. It is an error to invoke -startSessionAtSourceTime: twice in a row without invoking -endSessionAtSourceTime: in between.
-
- NOTE: Multiple sample-writing sessions are currently not supported. It is an error to call -startSessionAtSourceTime: a second time after calling -endSessionAtSourceTime:.
- */
+/// Initiates a sample-writing session for the receiver.
+///
+/// Sequences of sample data appended to the asset writer inputs are considered to fall within "sample-writing sessions", initiated with this method. Accordingly, this method must be called after writing has started (using -startWriting) but before any sample data is appended to the receiver's inputs.
+///
+/// Each writing session has a start time which, where allowed by the file format being written, defines the mapping from the timeline of source samples to the timeline of the written file. In the case of the QuickTime movie file format, the first session begins at movie time 0, so a sample appended with timestamp T will be played at movie time (T-startTime). Samples with timestamps earlier than startTime will still be added to the output file but will be edited out (i.e. not presented during playback). If the earliest appended sample for an input has a timestamp later than than startTime, an empty edit will be inserted to preserve synchronization between tracks of the output asset.
+///
+/// To end the session started by use of this method, use -endSessionAtSourceTime: or -finishWritingWithCompletionHandler:. It is an error to invoke -startSessionAtSourceTime: twice in a row without invoking -endSessionAtSourceTime: in between.
+///
+/// NOTE: Multiple sample-writing sessions are currently not supported. It is an error to call -startSessionAtSourceTime: a second time after calling -endSessionAtSourceTime:.
+///
+/// - Parameter startTime: The starting asset time for the sample-writing session, in the timeline of the source samples.
- (void)startSessionAtSourceTime:(CMTime)startTime;
-/*!
- @method endSessionAtSourceTime:
- @abstract
- Concludes a sample-writing session.
-
- @param endTime
- The ending asset time for the sample-writing session, in the timeline of the source samples.
-
- @discussion
- Call this method to complete a session started with -startSessionAtSourceTime:.
-
- The endTime defines the moment on the timeline of source samples at which the session ends. In the case of the QuickTime movie file format, each sample-writing session's startTime...endTime pair corresponds to a period of movie time into which the session's samples are inserted. Samples with timestamps that are later than the session end time will still be added to the written file but will be edited out (i.e. not presented during playback). So if the first session has duration D1 = endTime - startTime, it will be inserted into the written file at time 0 through D1; the second session would be inserted into the written file at time D1 through D1+D2, etc. It is legal to have a session with no samples; this will cause creation of an empty edit of the prescribed duration.
-
- It is not mandatory to call -endSessionAtSourceTime:; if -finishWritingWithCompletionHandler: is called without first invoking -endSessionAtSourceTime:, the session's effective end time will be the latest end timestamp of the session's appended samples (i.e. no samples will be edited out at the end).
-
- It is an error to append samples outside of a sample-writing session. To append more samples after invoking -endSessionAtSourceTime:, you must first start a new session using -startSessionAtSourceTime:.
-
- NOTE: Multiple sample-writing sessions are currently not supported. It is an error to call -startSessionAtSourceTime: a second time after calling -endSessionAtSourceTime:.
-
- This method throws an exception if the session is ended without first starting it.
- */
+/// Concludes a sample-writing session.
+///
+/// Call this method to complete a session started with -startSessionAtSourceTime:.
+///
+/// The endTime defines the moment on the timeline of source samples at which the session ends. In the case of the QuickTime movie file format, each sample-writing session's startTime...endTime pair corresponds to a period of movie time into which the session's samples are inserted. Samples with timestamps that are later than the session end time will still be added to the written file but will be edited out (i.e. not presented during playback). So if the first session has duration D1 = endTime - startTime, it will be inserted into the written file at time 0 through D1; the second session would be inserted into the written file at time D1 through D1+D2, etc. It is legal to have a session with no samples; this will cause creation of an empty edit of the prescribed duration.
+///
+/// It is not mandatory to call -endSessionAtSourceTime:; if -finishWritingWithCompletionHandler: is called without first invoking -endSessionAtSourceTime:, the session's effective end time will be the latest end timestamp of the session's appended samples (i.e. no samples will be edited out at the end).
+///
+/// It is an error to append samples outside of a sample-writing session. To append more samples after invoking -endSessionAtSourceTime:, you must first start a new session using -startSessionAtSourceTime:.
+///
+/// NOTE: Multiple sample-writing sessions are currently not supported. It is an error to call -startSessionAtSourceTime: a second time after calling -endSessionAtSourceTime:.
+///
+/// This method throws an exception if the session is ended without first starting it.
+///
+/// - Parameter endTime: The ending asset time for the sample-writing session, in the timeline of the source samples.
- (void)endSessionAtSourceTime:(CMTime)endTime;
-/*!
- @method cancelWriting
- @abstract
- Cancels the creation of the output file.
-
- @discussion
- If the status of the receiver is "failed" or "completed," -cancelWriting is a no-op. Otherwise, this method will block until writing is canceled.
-
- If an output file was created by the receiver during the writing process, -cancelWriting will delete the file.
-
- This method should not be called concurrently with -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:].
-*/
+/// Cancels the creation of the output file.
+///
+/// If the status of the receiver is "failed" or "completed," -cancelWriting is a no-op. Otherwise, this method will block until writing is canceled.
+///
+/// If an output file was created by the receiver during the writing process, -cancelWriting will delete the file.
+///
+/// This method should not be called concurrently with -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:].
- (void)cancelWriting;
-/*!
- @method finishWriting
- @abstract
- Completes the writing of the output file.
-
- @result
- A BOOL indicating whether writing successfully finished.
-
- @discussion
- This method is deprecated. Use finishWritingWithCompletionHandler: instead.
-
- This method will block until writing is finished. When this method returns successfully, the file being written by the receiver is complete and ready to use.
-
- Because this method is blocking and can take a long time to execute (especially with shouldOptimizeForNetworkUse set to YES), it should not be called from the main thread. Doing so can cause the finishWriting operation to fail.
-
- If writing cannot be finished, this method returns NO. Clients can check the values of the status and error properties for more information on why writing could not be finished.
-
- This method should not be called concurrently with -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:].
-*/
+/// Completes the writing of the output file.
+///
+/// This method is deprecated. Use finishWritingWithCompletionHandler: instead.
+///
+/// This method will block until writing is finished. When this method returns successfully, the file being written by the receiver is complete and ready to use.
+///
+/// Because this method is blocking and can take a long time to execute (especially with shouldOptimizeForNetworkUse set to YES), it should not be called from the main thread. Doing so can cause the finishWriting operation to fail.
+///
+/// If writing cannot be finished, this method returns NO. Clients can check the values of the status and error properties for more information on why writing could not be finished.
+///
+/// This method should not be called concurrently with -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:].
+///
+/// - Returns: A BOOL indicating whether writing successfully finished.
- (BOOL)finishWriting API_DEPRECATED_WITH_REPLACEMENT("finishWritingWithCompletionHandler:", macos(10.7, 10.9), ios(4.1, 6.0), tvos(9.0, 9.0)) API_UNAVAILABLE(watchos, visionos);
-/*!
- @method finishWritingWithCompletionHandler:
- @abstract
- Marks all unfinished inputs as finished and completes the writing of the output file.
-
- @discussion
- This method returns immediately and causes its work to be performed asynchronously.
-
- When the writing of the output file is finished, or if a failure or a cancellation occurs in the meantime, the specified handler will be invoked to indicate completion of the operation. To determine whether the operation succeeded, your handler can check the value of AVAssetWriter.status. If the status is AVAssetWriterStatusFailed, AVAsset.error will contain an instance of NSError that describes the failure.
-
- To guarantee that all sample buffers are successfully written, ensure all calls to -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:] have returned before invoking this method.
-*/
+/// Marks all unfinished inputs as finished and completes the writing of the output file.
+///
+/// This method returns immediately and causes its work to be performed asynchronously.
+///
+/// When the writing of the output file is finished, or if a failure or a cancellation occurs in the meantime, the specified handler will be invoked to indicate completion of the operation. To determine whether the operation succeeded, your handler can check the value of AVAssetWriter.status. If the status is AVAssetWriterStatusFailed, AVAsset.error will contain an instance of NSError that describes the failure.
+///
+/// To guarantee that all sample buffers are successfully written, ensure all calls to -[AVAssetWriterInput appendSampleBuffer:] or -[AVAssetWriterInputPixelBufferAdaptor appendPixelBuffer:withPresentationTime:] have returned before invoking this method.
- (void)finishWritingWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(void))handler API_AVAILABLE(macos(10.9), ios(6.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@@ -408,86 +276,56 @@
API_AVAILABLE(macos(10.7), ios(4.1), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetWriter (AVAssetWriterFileTypeSpecificProperties)
-/*!
- @property movieFragmentInterval
- @abstract
- For file types that support movie fragments, specifies the frequency at which movie fragments should be written.
-
- @discussion
- When movie fragments are used, a partially written asset whose writing is unexpectedly interrupted can be successfully opened and played up to multiples of the specified time interval. The default value of this property is kCMTimeInvalid, which indicates that movie fragments should not be used.
-
- When using movie fragments, for best writing performance to external storage devices, set the movieFragmentInterval to 10 seconds or greater.
-
- This property cannot be set after writing has started.
- */
+/// For file types that support movie fragments, specifies the frequency at which movie fragments should be written.
+///
+/// When movie fragments are used, a partially written asset whose writing is unexpectedly interrupted can be successfully opened and played up to multiples of the specified time interval. The default value of this property is kCMTimeInvalid, which indicates that movie fragments should not be used.
+///
+/// When using movie fragments, for best writing performance to external storage devices, set the movieFragmentInterval to 10 seconds or greater.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTime movieFragmentInterval;
-/*!
- @property initialMovieFragmentInterval
- @abstract
- For file types that support movie fragments, specifies the interval at which initial movie fragment should be written.
-
- @discussion
- This property is irrelevant if the movieFragmentInterval property is not set. The default value is kCMTimeInvalid, which indicates that the interval for initial movie fragment is same as the one specified by movieFragmentInterval property.
-
- This property cannot be set after writing has started.
- */
+/// For file types that support movie fragments, specifies the interval at which initial movie fragment should be written.
+///
+/// This property is irrelevant if the movieFragmentInterval property is not set. The default value is kCMTimeInvalid, which indicates that the interval for initial movie fragment is same as the one specified by movieFragmentInterval property.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTime initialMovieFragmentInterval API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property initialMovieFragmentSequenceNumber
- @abstract
- For file types that support movie fragments, specifies the initial movie fragment sequence number.
-
- @discussion
- The value must be equal to or greater than 1.
-
- The default value is 1.
-
- Note that if you combine movie fragments produced by an instance of AVAssetWriter with additional movie fragments, produced either by a different instance of AVAssetWriter or by some other means, it is necessary to ensure that movie fragment sequence numbers increase monotonically across the entire combined collection, in temporal order.
-
- This property cannot be set after writing has started.
- */
+/// For file types that support movie fragments, specifies the initial movie fragment sequence number.
+///
+/// The value must be equal to or greater than 1.
+///
+/// The default value is 1.
+///
+/// Note that if you combine movie fragments produced by an instance of AVAssetWriter with additional movie fragments, produced either by a different instance of AVAssetWriter or by some other means, it is necessary to ensure that movie fragment sequence numbers increase monotonically across the entire combined collection, in temporal order.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) NSInteger initialMovieFragmentSequenceNumber API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property producesCombinableFragments
- @abstract
- For file types that support fragmented MPEG-4, specifies whether the movie fragments should be produced in way that makes them suitable for combining with movie fragments produced by one or more other instances of AVAssetWriter into a single fragment stream of uniform encoding.
-
- @discussion
- The default value is NO.
-
- When multiple instances of AVAssetWriter are used to produce distinct streams that complement each other, for example to create HLS encoding or bitrate variants, it’s not necessary to set this property to YES.
-
- This property cannot be set after writing has started.
- */
+/// For file types that support fragmented MPEG-4, specifies whether the movie fragments should be produced in way that makes them suitable for combining with movie fragments produced by one or more other instances of AVAssetWriter into a single fragment stream of uniform encoding.
+///
+/// The default value is NO.
+///
+/// When multiple instances of AVAssetWriter are used to produce distinct streams that complement each other, for example to create HLS encoding or bitrate variants, it’s not necessary to set this property to YES.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) BOOL producesCombinableFragments API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property overallDurationHint
- @abstract
- For file types that support movie fragments, provides a hint of the final duration of the file to be written
-
- @discussion
- The value of this property must be a nonnegative, numeric CMTime. Alternatively, if the value of this property is an invalid CMTime (e.g. kCMTimeInvalid), no overall duration hint will be written to the file. The default value is kCMTimeInvalid.
-
- This property is currently ignored if movie fragments are not being written. Use the movieFragmentInterval property to enable movie fragments.
-
- This property cannot be set after writing has started.
- */
+/// For file types that support movie fragments, provides a hint of the final duration of the file to be written
+///
+/// The value of this property must be a nonnegative, numeric CMTime. Alternatively, if the value of this property is an invalid CMTime (e.g. kCMTimeInvalid), no overall duration hint will be written to the file. The default value is kCMTimeInvalid.
+///
+/// This property is currently ignored if movie fragments are not being written. Use the movieFragmentInterval property to enable movie fragments.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTime overallDurationHint;
-/*!
- @property movieTimeScale
- @abstract
- For file types that contain a 'moov' atom, such as QuickTime Movie files, specifies the asset-level time scale to be used.
-
- @discussion
- The default value is 0, which indicates that the receiver should choose a convenient value, if applicable.
-
- This property cannot be set after writing has started.
- */
+/// For file types that contain a 'moov' atom, such as QuickTime Movie files, specifies the asset-level time scale to be used.
+///
+/// The default value is 0, which indicates that the receiver should choose a convenient value, if applicable.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTimeScale movieTimeScale API_AVAILABLE(macos(10.7), ios(4.3), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@@ -498,48 +336,32 @@
API_AVAILABLE(macos(10.7), ios(4.1), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetWriter (AVAssetWriterInputGroups)
-/*!
- @method canAddInputGroup:
- @abstract
- Tests whether an input group can be added to the receiver.
-
- @param inputGroup
- The AVAssetWriterInputGroup object to be tested.
- @result
- A BOOL indicating whether the input group can be added to the receiver.
-
- @discussion
- If outputFileType specifies a container format that does not support mutually exclusive relationships among tracks, or if the specified instance of AVAssetWriterInputGroup contains inputs with media types that cannot be related, the group cannot be added to the AVAssetWriter.
-
- This method throws an exception if any of the following conditions are satisfied:
- - this writer's output file type does not support mutually exclusive relationships among tracks (allowed types are AVFileTypeQuickTimeMovie, AVFileTypeAppleM4A, AVFileTypeAppleM4V, AVFileType3GPP, AVFileTypeMPEG4)
- - any AVAssetWriterInput in the input group is also present in an input group already added
- */
+/// Tests whether an input group can be added to the receiver.
+///
+/// If outputFileType specifies a container format that does not support mutually exclusive relationships among tracks, or if the specified instance of AVAssetWriterInputGroup contains inputs with media types that cannot be related, the group cannot be added to the AVAssetWriter.
+///
+/// This method throws an exception if any of the following conditions are satisfied:
+/// - this writer's output file type does not support mutually exclusive relationships among tracks (allowed types are AVFileTypeQuickTimeMovie, AVFileTypeAppleM4A, AVFileTypeAppleM4V, AVFileType3GPP, AVFileTypeMPEG4)
+/// - any AVAssetWriterInput in the input group is also present in an input group already added
+///
+/// - Parameter inputGroup: The AVAssetWriterInputGroup object to be tested.
+///
+/// - Returns: A BOOL indicating whether the input group can be added to the receiver.
- (BOOL)canAddInputGroup:(AVAssetWriterInputGroup *)inputGroup API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*
- @method addInputGroup:
- @abstract
- Adds an instance of AVAssetWriterInputGroup to the AVAssetWriter. The AVAssetWriter will mark the tracks associated with grouped inputs as mutually exclusive to each other for playback or other processing, if the output container format supports mutually exlusive relationships among tracks.
- @param inputGroup
- The collection of AVAssetWriterInputs to be grouped together.
-
- @discussion
- When an input group is added to an AVAssetWriter, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
-
- Input groups cannot be added after writing has started.
- */
+/// Adds an instance of AVAssetWriterInputGroup to the AVAssetWriter. The AVAssetWriter will mark the tracks associated with grouped inputs as mutually exclusive to each other for playback or other processing, if the output container format supports mutually exlusive relationships among tracks.
+///
+/// When an input group is added to an AVAssetWriter, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
+///
+/// Input groups cannot be added after writing has started.
+///
+/// - Parameter inputGroup: The collection of AVAssetWriterInputs to be grouped together.
- (void)addInputGroup:(AVAssetWriterInputGroup *)inputGroup API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property inputGroups
- @abstract
- The instances of AVAssetWriterInputGroup that have been added to the AVAssetWriter.
-
- @discussion
- The value of this property is an NSArray containing concrete instances of AVAssetWriterInputGroup. Input groups can be added to the receiver using the addInputGroup: method.
- */
+/// The instances of AVAssetWriterInputGroup that have been added to the AVAssetWriter.
+///
+/// The value of this property is an NSArray containing concrete instances of AVAssetWriterInputGroup. Input groups can be added to the receiver using the addInputGroup: method.
@property (nonatomic, readonly) NSArray<AVAssetWriterInputGroup *> *inputGroups API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@@ -547,16 +369,11 @@
@class AVAssetWriterInputGroupInternal;
-/*
- @class AVAssetWriterInputGroup
- @abstract Associates tracks corresponding to inputs with each other in a mutually exclusive relationship.
-
- @discussion
- This class is used to associate tracks corresponding to multiple AVAssetWriterInputs as mutually exclusive to each other for playback or other processing. For example, if you are creating an asset with multiple audio tracks using different spoken languages, only one of which should be played at a time, group the inputs corresponding to those tracks into a single instance of AVAssetWriterInputGroup and add the group to the AVAssetWriter via -[AVAssetWriter addInputGroup:]. If the output format supports mutually exlusive relationships among tracks, the AVAssetWriter will mark the tracks as mutually exclusive to each other.
-
- Note that because AVAssetWriterInputGroup is a subclass of AVMediaSelectionGroup, clients can examine the media selection options that will be available on the output asset before the asset is written. Best results for examining the options of the AVAssetWriterInputGroup will be obtained after associating the AVAssetWriterInputs of the AVAsset as appropriate via -[AVAssetWriterInput addTrackAssociationWithTrackOfInput:type:] and by initializing each AVAssetWriterInput with a source format hint, where appropriate.
- */
-
+/// Associates tracks corresponding to inputs with each other in a mutually exclusive relationship.
+///
+/// This class is used to associate tracks corresponding to multiple AVAssetWriterInputs as mutually exclusive to each other for playback or other processing. For example, if you are creating an asset with multiple audio tracks using different spoken languages, only one of which should be played at a time, group the inputs corresponding to those tracks into a single instance of AVAssetWriterInputGroup and add the group to the AVAssetWriter via -[AVAssetWriter addInputGroup:]. If the output format supports mutually exlusive relationships among tracks, the AVAssetWriter will mark the tracks as mutually exclusive to each other.
+///
+/// Note that because AVAssetWriterInputGroup is a subclass of AVMediaSelectionGroup, clients can examine the media selection options that will be available on the output asset before the asset is written. Best results for examining the options of the AVAssetWriterInputGroup will be obtained after associating the AVAssetWriterInputs of the AVAsset as appropriate via -[AVAssetWriterInput addTrackAssociationWithTrackOfInput:type:] and by initializing each AVAssetWriterInput with a source format hint, where appropriate.
API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetWriterInputGroup : AVMediaSelectionGroup
{
@@ -565,52 +382,30 @@
}
AV_INIT_UNAVAILABLE
-/*
- @method assetWriterInputGroupWithInputs:defaultInput:
- @abstract
- Creates an instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
-
- @param inputs
- The collection of AVAssetWriterInputs to be grouped together.
- @param defaultInput
- The instance of AVAssetWriterInput in the group to designate as the default. When the input group is added to an AVAssetWriter via -addInputGroup:, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
- @result
- An instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
- */
+/// Creates an instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
+///
+/// - Parameter inputs: The collection of AVAssetWriterInputs to be grouped together.
+/// - Parameter defaultInput: The instance of AVAssetWriterInput in the group to designate as the default. When the input group is added to an AVAssetWriter via -addInputGroup:, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
+///
+/// - Returns: An instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
+ (instancetype)assetWriterInputGroupWithInputs:(NSArray<AVAssetWriterInput *> *)inputs defaultInput:(nullable AVAssetWriterInput *)defaultInput;
-/*
- @method initWithInputs:defaultInput:
- @abstract
- Creates an instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
-
- @param inputs
- The collection of AVAssetWriterInputs to be grouped together.
- @param defaultInput
- The instance of AVAssetWriterInput in the group to designate as the default. When the input group is added to an AVAssetWriter via -addInputGroup:, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
- @result
- An instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
- */
+/// Creates an instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
+///
+/// - Parameter inputs: The collection of AVAssetWriterInputs to be grouped together.
+/// - Parameter defaultInput: The instance of AVAssetWriterInput in the group to designate as the default. When the input group is added to an AVAssetWriter via -addInputGroup:, the value of marksOutputTrackAsEnabled will automatically be set to YES for the default input and set to NO for all of the other inputs in the group.
+///
+/// - Returns: An instance of AVAssetWriterInputGroup, for use with -[AVAssetWriter addInputGroup:].
- (instancetype)initWithInputs:(NSArray<AVAssetWriterInput *> *)inputs defaultInput:(nullable AVAssetWriterInput *)defaultInput NS_DESIGNATED_INITIALIZER;
-/*!
- @property inputs
- @abstract
- The inputs grouped together by the receiver.
-
- @discussion
- The value of this property is an NSArray containing concrete instances of AVAssetWriterInput.
- */
+/// The inputs grouped together by the receiver.
+///
+/// The value of this property is an NSArray containing concrete instances of AVAssetWriterInput.
@property (nonatomic, readonly) NSArray<AVAssetWriterInput *> *inputs;
-/*!
- @property defaultInput
- @abstract
- The input designated at the defaultInput of the receiver.
-
- @discussion
- The value of this property is a concrete instance of AVAssetWriterInput.
- */
+/// The input designated at the defaultInput of the receiver.
+///
+/// The value of this property is a concrete instance of AVAssetWriterInput.
@property (nonatomic, readonly, nullable) AVAssetWriterInput *defaultInput;
@end
@@ -621,66 +416,40 @@
API_AVAILABLE(macos(10.7), ios(4.1), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVAssetWriter (AVAssetWriterSegmentation)
-/*!
- @property preferredOutputSegmentInterval
- @abstract
- Specifies preferred segment interval.
-
- @discussion
- The default value is kCMTimeInvalid, which means that the receiver will choose an appropriate default value. The value can be set to positive numeric or kCMTimeIndefinite.
- If the value is kCMTimeIndefinite, every time a client calls -flushSegment the receiver outputs a segment data.
-
- This property cannot be set after writing has started.
- */
+/// Specifies preferred segment interval.
+///
+/// The default value is kCMTimeInvalid, which means that the receiver will choose an appropriate default value. The value can be set to positive numeric or kCMTimeIndefinite.
+/// If the value is kCMTimeIndefinite, every time a client calls -flushSegment the receiver outputs a segment data.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTime preferredOutputSegmentInterval API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property initialSegmentStartTime
- @abstract
- Specifies start time of initial segment.
-
- @discussion
- A numeric time must be set if the value of preferredOutputSegmentInterval property is positive numeric. If not, this property is irrelevant.
-
- This property cannot be set after writing has started.
- */
+/// Specifies start time of initial segment.
+///
+/// A numeric time must be set if the value of preferredOutputSegmentInterval property is positive numeric. If not, this property is irrelevant.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic) CMTime initialSegmentStartTime API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property outputFileTypeProfile
- @abstract
- Specifies a file type profile for the specified file type.
-
- @discussion
- The default value is nil, which means that the receiver will choose an appropriate default profile based on the specified file type.
-
- Clients that want to receive segment data that is suitable for streaming through the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method should set AVFileTypeProfileMPEG4AppleHLS, or AVFileTypeProfileMPEG4CMAFCompliant to require output that is specifically compliant with CMAF format, with AVFileTypeMPEG4 file type.
-
- File type profiles are declared in AVMediaFormat.h.
-
- This property cannot be set after writing has started.
- */
-
+/// Specifies a file type profile for the specified file type.
+///
+/// The default value is nil, which means that the receiver will choose an appropriate default profile based on the specified file type.
+///
+/// Clients that want to receive segment data that is suitable for streaming through the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method should set AVFileTypeProfileMPEG4AppleHLS, or AVFileTypeProfileMPEG4CMAFCompliant to require output that is specifically compliant with CMAF format, with AVFileTypeMPEG4 file type.
+///
+/// File type profiles are declared in AVMediaFormat.h.
+///
+/// This property cannot be set after writing has started.
@property (nonatomic, copy, nullable) AVFileTypeProfile outputFileTypeProfile API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property delegate
- @abstract
- An object that implements one or more of the methods in the AVAssetWriterDelegate protocol.
-
- @discussion
- This property cannot be set after writing has started.
- */
+/// An object that implements one or more of the methods in the AVAssetWriterDelegate protocol.
+///
+/// This property cannot be set after writing has started.
@property (weak, nullable) id <AVAssetWriterDelegate> delegate API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @method flushSegment
- @abstract
- Closes the current segment and outputs it to the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method.
-
- @discussion
- This method throws an exception if the delegate method to output segment data is not implemented, or if the value of the preferredOutputSegmentInterval property is not kCMTimeIndefinite.
- */
+/// Closes the current segment and outputs it to the -assetWriter:didOutputSegmentData:segmentType:segmentReport: or -assetWriter:didOutputSegmentData:segmentType: delegate method.
+///
+/// This method throws an exception if the delegate method to output segment data is not implemented, or if the value of the preferredOutputSegmentInterval property is not kCMTimeIndefinite.
- (void)flushSegment API_AVAILABLE(macos(11.0), ios(14.0), tvos(14.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@@ -690,65 +459,48 @@
@protocol AVAssetWriterDelegate <NSObject>
@optional
-/*!
- @method assetWriter:didOutputSegmentData:segmentType:segmentReport:
- @abstract
- A method invoked when a segment data is output.
-
- @param writer
- An AVAssetWriter instance.
- @param segmentData
- An instance of NSData containing a segment data.
- @param segmentType
- A segment type of the segment data. Segment types are declared in AVAssetSegmentReport.h.
- @param segmentReport
- An AVAssetSegmentReport instance.
-
- @discussion
- If this method is implemented, normal file writing will be suppressed. The instance of AVAssetWriter must be initialized by -initWithContentType: initializer.
- Then, clients append media data to AVAssetWriterInputs added to the receiver, call -markAsFinished for each input to mark the input as finished and call -finishWritingWithCompletionHandler: to finish writing as is the case in normal file writing.
-
- Do not use the movieFragmentInterval or shouldOptimizeForNetworkUse properties, as these properties are ignored in this mode of operation.
-
- Clients that need to reference the NSData outside of the scope of this method must retain or copy it and then release it when they are finished with it.
-
- The segmentReport provides information on the segment data. If there is no information available to report, the segmentReport may be nil.
- Clients that do not need information on consecutive segment data should implement the -assetWriter:didOutputSegmentData:segmentType: method instead of this one for greater efficiency, as this will signal the receiver to skip the preparation of segment reports.
- See more detailed description of AVAssetSegmentReport in AVAssetSegmentReport.h.
-
- If the file type is AVFileTypeMPEG4 and the outputFileTypeProfile is AVFileTypeProfileMPEG4AppleHLS or AVFileTypeProfileMPEG4CMAFCompliant, when the segmentType is AVAssetSegmentTypeInitialization, the segment contains a 'moov' atom that does not contain any sample tables other than the sample descriptions, and is suitable for use as an initialization segment for the following segment data sequences.
- When the segmentType is AVAssetSegmentTypeSeparable, the segment contains a 'moof' atom that contains one 'moof' atom followed by one 'mdat' atom.
-
- 1. If the value of preferredOutputSegmentInterval property is positive numeric, when (a sample's output PTS - InitialSegmentStartTime) >= (interval * N) (N = 1, 2, 3...), the receiver waits for next sync sample and outputs a segment data that includes all samples appended since the previous interval to the delegate method when the sync sample appears, so that the next segment can start with the sync sample.
- In this configuration, passthrough (by passing nil to output settings for AVAssetWriterInputs) and compression are available. The media type of input can be AVMediaTypeVideo or AVMediaTypeAudio.
- Only one input of each media type can be added for compression and when (a sample's PTS - InitialSegmentStartTime) >= (interval * N) (N = 1, 2, 3...), the sample will be forced to be encoded as sync sample so that the current segment will be closed immediately.
- For passthrough, only one input can be added.
-
- 2. If the value of preferredOutputSegmentInterval property is kCMTimeIndefinite, every time a client calls -flushSegment the receiver outputs a segment data that includes all samples appended since the previous call to the delegate method.
- The delegate method may be called asynchronously, on a different thread from the one that calls -flushSegment.
- In this configuration, only passthrough is available. The media type of input can be AVMediaTypeVideo or AVMediaTypeAudio.
- Only one input of each media type can be added.
- The client should call -flushSegment prior to a sync sample so that the next segment can start with the sync sample. Otherwise, it is an error.
- */
+/// A method invoked when a segment data is output.
+///
+/// If this method is implemented, normal file writing will be suppressed. The instance of AVAssetWriter must be initialized by -initWithContentType: initializer.
+/// Then, clients append media data to AVAssetWriterInputs added to the receiver, call -markAsFinished for each input to mark the input as finished and call -finishWritingWithCompletionHandler: to finish writing as is the case in normal file writing.
+///
+/// Do not use the movieFragmentInterval or shouldOptimizeForNetworkUse properties, as these properties are ignored in this mode of operation.
+///
+/// Clients that need to reference the NSData outside of the scope of this method must retain or copy it and then release it when they are finished with it.
+///
+/// The segmentReport provides information on the segment data. If there is no information available to report, the segmentReport may be nil.
+/// Clients that do not need information on consecutive segment data should implement the -assetWriter:didOutputSegmentData:segmentType: method instead of this one for greater efficiency, as this will signal the receiver to skip the preparation of segment reports.
+/// See more detailed description of AVAssetSegmentReport in AVAssetSegmentReport.h.
+///
+/// If the file type is AVFileTypeMPEG4 and the outputFileTypeProfile is AVFileTypeProfileMPEG4AppleHLS or AVFileTypeProfileMPEG4CMAFCompliant, when the segmentType is AVAssetSegmentTypeInitialization, the segment contains a 'moov' atom that does not contain any sample tables other than the sample descriptions, and is suitable for use as an initialization segment for the following segment data sequences.
+/// When the segmentType is AVAssetSegmentTypeSeparable, the segment contains a 'moof' atom that contains one 'moof' atom followed by one 'mdat' atom.
+///
+/// 1. If the value of preferredOutputSegmentInterval property is positive numeric, when (a sample's output PTS - InitialSegmentStartTime) >= (interval * N) (N = 1, 2, 3...), the receiver waits for next sync sample and outputs a segment data that includes all samples appended since the previous interval to the delegate method when the sync sample appears, so that the next segment can start with the sync sample.
+/// In this configuration, passthrough (by passing nil to output settings for AVAssetWriterInputs) and compression are available. The media type of input can be AVMediaTypeVideo or AVMediaTypeAudio.
+/// Only one input of each media type can be added for compression and when (a sample's PTS - InitialSegmentStartTime) >= (interval * N) (N = 1, 2, 3...), the sample will be forced to be encoded as sync sample so that the current segment will be closed immediately.
+/// For passthrough, only one input can be added.
+///
+/// 2. If the value of preferredOutputSegmentInterval property is kCMTimeIndefinite, every time a client calls -flushSegment the receiver outputs a segment data that includes all samples appended since the previous call to the delegate method.
+/// The delegate method may be called asynchronously, on a different thread from the one that calls -flushSegment.
+/// In this configuration, only passthrough is available. The media type of input can be AVMediaTypeVideo or AVMediaTypeAudio.
+/// Only one input of each media type can be added.
+/// The client should call -flushSegment prior to a sync sample so that the next segment can start with the sync sample. Otherwise, it is an error.
+///
+/// - Parameter writer: An AVAssetWriter instance.
+/// - Parameter segmentData: An instance of NSData containing a segment data.
+/// - Parameter segmentType: A segment type of the segment data. Segment types are declared in AVAssetSegmentReport.h.
+/// - Parameter segmentReport: An AVAssetSegmentReport instance.
- (void)assetWriter:(AVAssetWriter *)writer didOutputSegmentData:(NSData *)segmentData segmentType:(AVAssetSegmentType)segmentType segmentReport:(nullable AVAssetSegmentReport *)segmentReport;
-/*!
- @method assetWriter:didOutputSegmentData:segmentType:
- @abstract
- A method invoked when a segment data is output.
-
- @param writer
- An AVAssetWriter instance.
- @param segmentData
- An instance of NSData containing a segment data.
- @param segmentType
- A segment type of the segment data. Segment types are declared in AVAssetSegmentReport.h.
-
- @discussion
- The usage of this method is same as -assetWriter:didOutputSegmentData:segmentType:segmentReport: except that this method does not deliver AVAssetSegmentReport.
-
- If clients implement the -assetWriter:didOutputSegmentData:segmentType:segmentReport: method, that method is called instead of this one.
- */
+/// A method invoked when a segment data is output.
+///
+/// The usage of this method is same as -assetWriter:didOutputSegmentData:segmentType:segmentReport: except that this method does not deliver AVAssetSegmentReport.
+///
+/// If clients implement the -assetWriter:didOutputSegmentData:segmentType:segmentReport: method, that method is called instead of this one.
+///
+/// - Parameter writer: An AVAssetWriter instance.
+/// - Parameter segmentData: An instance of NSData containing a segment data.
+/// - Parameter segmentType: A segment type of the segment data. Segment types are declared in AVAssetSegmentReport.h.
- (void)assetWriter:(AVAssetWriter *)writer didOutputSegmentData:(NSData *)segmentData segmentType:(AVAssetSegmentType)segmentType;
@end
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWritingPlanner.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWritingPlanner.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWritingPlanner.h 2026-05-27 00:09:43
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAssetWritingPlanner.h 2026-06-13 01:14:44
@@ -32,213 +32,146 @@
NS_ASSUME_NONNULL_BEGIN
-/*!
- @struct AVPlannedVideoSegmentBoundaryGuidelines
- @abstract
- AVPlannedVideoSegmentBoundaryGuidelines provides guidance on determining planned segment boundaries for a video track in an incremental writing session executed by the AVAssetWritingPlanner.
-
- @field minimumFrameCount
- The minimum number of frames in each incremental segment
- 0 means that incremental segmentation is not supported for this codecType.
- 1 means there is no frame count restriction for incremental encoding for this codecType.
- Using 1 for segment frame count is not recommended because of the performance overhead, so the client should choose a value that represents a reasonable amount of work.
- @field minimumDuration
- The minimum duration of each incremental segment
- kCMTimeZero means there is no minimum segment duration requirement.
- kCMTimePositiveInfinity means that incremental segmentation is not supported for this codecType.
-
- @discussion
- The properties provide guidance on determining segment boundaries for a video track in an incremental writing session. All conditions should be supported for best results. The client should choose frame count and minimum duration that meet the minimum requirement. However, the client should also consider the balance between overhead caused by completing and saving states for small segments, and the cost of having to redo a large segment if the incremental session stopped in the middle of a segment due to errors or crashes. For example, use 1 minute segments for 4K60fps video.
- */
+/// AVPlannedVideoSegmentBoundaryGuidelines provides guidance on determining planned segment boundaries for a video track in an incremental writing session executed by the AVAssetWritingPlanner.
+///
+/// The properties provide guidance on determining segment boundaries for a video track in an incremental writing session. All conditions should be supported for best results. The client should choose frame count and minimum duration that meet the minimum requirement. However, the client should also consider the balance between overhead caused by completing and saving states for small segments, and the cost of having to redo a large segment if the incremental session stopped in the middle of a segment due to errors or crashes. For example, use 1 minute segments for 4K60fps video.
typedef struct {
+ /// The minimum number of frames in each incremental segment. 0 means that incremental segmentation is not supported for this codecType. 1 means there is no frame count restriction for incremental encoding for this codecType. Using 1 for segment frame count is not recommended because of the performance overhead, so the client should choose a value that represents a reasonable amount of work.
NSInteger minimumFrameCount;
+ /// The minimum duration of each incremental segment. kCMTimeZero means there is no minimum segment duration requirement. kCMTimePositiveInfinity means that incremental segmentation is not supported for this codecType.
CMTime minimumDuration;
} AVPlannedVideoSegmentBoundaryGuidelines API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
NS_SWIFT_NAME(AVAssetWritingPlanner.SegmentBoundaryGuidelines);
@class AVAssetTrackPlan, AVPlannedVideoSegmentConfiguration, AVPlannedSegmentWritingRequest, AVAssetWritingPlannerProgress;
-/*!
- @class AVAssetWritingPlanner
- @abstract
- AVAssetWritingPlanner orchestrates incremental writing of media files.
-
- @discussion
- AVAssetWritingPlanner orchestrates an incremental and resumable asset file
- writing session. It keeps track of the progress of the incremental segments,
- and can resume the writing from the last checkpoint. This is NOT intended for
- any real time applications. Also, not all tracks can be written incrementally.
- The workflow is as follows:
- 1. The client creates the planner with a unique directoryForTemporaryFiles.
- 2. The client tells the planner which tracks are to be written incrementally
- by calling the "planTrack:withSegmentsGeneratedBy:" method, providing a
- callback block that writes one segment per block invocation.
- 3. The client kicks off the incremental writing session by calling the
- "executePlanWithCompletionHandler" method.
- 4. The planner will call the writingSegmentCallbackBlock to ask the client to
- write one incremental segment of one track at a time. The client code
- should write one incremental segment according to the
- "AVPlannedSegmentWritingRequest" object passed in to the callback block.
- Clients must call "finish" or "finishWithError" or "finishWithClientState"
- or "cancel" methods on the request object when it finishes the segment
- successfully, or encountered an error, or wants to cancel the writing of
- the segment.
- 5. At the end of the writing, after all incremental segments are finished,
- the planner calls the completionHandler. The client can use the
- "assemblyComposition" object passed in to the completionHandler to
- assemble the incremental segments into full tracks and export it to a
- final output file. The completionHandler will also be called when there
- is any irrecoverable error.
- 6. The client is responsible for cleaning all files in the
- directoryForTemporaryFiles after the incremental session is done and the
- final output file is written.
-
- AVAssetWritingPlanner is able to recognize when a plan-in-progress matching
- the plan was already saved at directoryForTemporaryFiles, presumably by a
- previous invocation of the client, and possibly aborted due to that client
- being terminated abruptly, and will assist by resuming the plan at the first
- step that wasn't previously completed.
-*/
+/// AVAssetWritingPlanner orchestrates incremental writing of media files.
+///
+/// AVAssetWritingPlanner orchestrates an incremental and resumable asset file
+/// writing session. It keeps track of the progress of the incremental segments,
+/// and can resume the writing from the last checkpoint. This is NOT intended for
+/// any real time applications. Also, not all tracks can be written incrementally.
+/// The workflow is as follows:
+/// 1. The client creates the planner with a unique directoryForTemporaryFiles.
+/// 2. The client tells the planner which tracks are to be written incrementally
+/// by calling the "planTrack:withSegmentsGeneratedBy:" method, providing a
+/// callback block that writes one segment per block invocation.
+/// 3. The client kicks off the incremental writing session by calling the
+/// "executePlanWithCompletionHandler" method.
+/// 4. The planner will call the writingSegmentCallbackBlock to ask the client to
+/// write one incremental segment of one track at a time. The client code
+/// should write one incremental segment according to the
+/// "AVPlannedSegmentWritingRequest" object passed in to the callback block.
+/// Clients must call "finish" or "finishWithError" or "finishWithClientState"
+/// or "cancel" methods on the request object when it finishes the segment
+/// successfully, or encountered an error, or wants to cancel the writing of
+/// the segment.
+/// 5. At the end of the writing, after all incremental segments are finished,
+/// the planner calls the completionHandler. The client can use the
+/// "assemblyComposition" object passed in to the completionHandler to
+/// assemble the incremental segments into full tracks and export it to a
+/// final output file. The completionHandler will also be called when there
+/// is any irrecoverable error.
+/// 6. The client is responsible for cleaning all files in the
+/// directoryForTemporaryFiles after the incremental session is done and the
+/// final output file is written.
+///
+/// AVAssetWritingPlanner is able to recognize when a plan-in-progress matching
+/// the plan was already saved at directoryForTemporaryFiles, presumably by a
+/// previous invocation of the client, and possibly aborted due to that client
+/// being terminated abruptly, and will assist by resuming the plan at the first
+/// step that wasn't previously completed.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
NS_SWIFT_NONSENDABLE
@interface AVAssetWritingPlanner : NSObject
-/*!
- @method initWithDirectoryForTemporaryFiles:
- @abstract
- Creates an instance of AVAssetWritingPlanner given a unique file directory to host all incremental segment files and other intermediate files.
-
- @param directoryForTemporaryFiles
- The file directory to host all incremental segment files and other intermediate files for the current AVAssetWritingPlanner operation.
-
- @result
- An instance of AVAssetWritingPlanner.
-
- @discussion
- The directoryForTemporaryFiles must differ between export operations, but remain identical when resuming the same export operation. The client is responsible for ensuring that this NSURL can be re-synthesized exactly across multiple launches of the app and device reboots (if desired). For example, if there are multiple source assets that need to be exported concurrently, these should result in unique NSURLs so that the planner can correctly identify each one.
- Another example is if the same source asset is being output with different compression configurations, they also should be uniquely identifiable so that they do not alias to the same output file.
- Source assets, compression configs, and video composition settings should all be taken into account when generating the unique URL.
- A resuming planner instance can only find the files from a previous planner instance if presented with the identical URL. All intermediate segment files and metadata files are stored in the specified directoryForTemporaryFiles.
- This initializer throws NSInvalidArgumentException if directoryForTemporaryFiles does not exist, or it is not writable, or it contains a corrupted AVAssetWritingPlanner incremental state file.
- */
+/// Creates an instance of AVAssetWritingPlanner given a unique file directory to host all incremental segment files and other intermediate files.
+///
+/// The directoryForTemporaryFiles must differ between export operations, but remain identical when resuming the same export operation. The client is responsible for ensuring that this NSURL can be re-synthesized exactly across multiple launches of the app and device reboots (if desired). For example, if there are multiple source assets that need to be exported concurrently, these should result in unique NSURLs so that the planner can correctly identify each one.
+/// Another example is if the same source asset is being output with different compression configurations, they also should be uniquely identifiable so that they do not alias to the same output file.
+/// Source assets, compression configs, and video composition settings should all be taken into account when generating the unique URL.
+/// A resuming planner instance can only find the files from a previous planner instance if presented with the identical URL. All intermediate segment files and metadata files are stored in the specified directoryForTemporaryFiles.
+/// This initializer throws NSInvalidArgumentException if directoryForTemporaryFiles does not exist, or it is not writable, or it contains a corrupted AVAssetWritingPlanner incremental state file.
+///
+/// - Parameter directoryForTemporaryFiles: The file directory to host all incremental segment files and other intermediate files for the current AVAssetWritingPlanner operation.
+///
+/// - Returns: An instance of AVAssetWritingPlanner.
- (instancetype)initWithDirectoryForTemporaryFiles:(NSURL *)directoryForTemporaryFiles NS_DESIGNATED_INITIALIZER NS_REFINED_FOR_SWIFT;
-/*!
- @property progress
- @abstract
- The current progress of the AVAssetWritingPlanner.
-
- @discussion
- Returns an AVAssetWritingPlannerProgress object that can be queried for per-track and overall progress information.
-*/
+/// The current progress of the AVAssetWritingPlanner.
+///
+/// Returns an AVAssetWritingPlannerProgress object that can be queried for per-track and overall progress information.
@property (readonly) AVAssetWritingPlannerProgress *progress;
-/*!
- @method segmentBoundaryGuidelinesForVideoCodecType:videoEncoderSpecification:
- @abstract
- Returns segment boundary guidelines that help clients determine how to segment compression video tracks with best results.
-
- @param videoCodecType
- The output videoCodecType for the video track.
- @param videoEncoderSpecification
- The video encoder specification includes options for choosing a specific video encoder. This is a dictionary containing kVTVideoEncoderSpecification_* keys specified in the VideoToolbox framework.
-
- @result
- An AVPlannedVideoSegmentBoundaryGuidelines.
-
- @discussion
- The videoEncoderSpecification parameter here is the same encoder specification the client uses to compress the video track.
-*/
+/// Returns segment boundary guidelines that help clients determine how to segment compression video tracks with best results.
+///
+/// The videoEncoderSpecification parameter here is the same encoder specification the client uses to compress the video track.
+///
+/// - Parameter videoCodecType: The output videoCodecType for the video track.
+/// - Parameter videoEncoderSpecification: The video encoder specification includes options for choosing a specific video encoder. This is a dictionary containing kVTVideoEncoderSpecification_* keys specified in the VideoToolbox framework.
+///
+/// - Returns: An AVPlannedVideoSegmentBoundaryGuidelines.
+ (AVPlannedVideoSegmentBoundaryGuidelines)segmentBoundaryGuidelinesForVideoCodecType:(AVVideoCodecType)videoCodecType videoEncoderSpecification:(NSDictionary *)videoEncoderSpecification
NS_REFINED_FOR_SWIFT;
-/*!
- @method segmentBoundaryRecommendationsForVideoAVAssetTrack:minimumSegmentDuration:minimumSegmentFrameCount:
- @abstract
- Returns segment boundary recommendations for a given source video asset track.
-
- @param videoAssetTrack
- The source video AVAssetTrack to be analyzed.
- @param minimumSegmentDuration
- The client selected minimum duration for the segments.
- @param minimumSegmentFrameCount
- The minimum number of source frames in a segment.
-
- @result
- Array of AVPlannedVideoSegmentConfigurations.
-
- @discussion
- This is a convenience method that can help clients to pick optimal segmentation boundaries for a given
- source video AVAssetTrack based on the structure of the track and the minimumSegmentDuration and
- minimumSegmentFrameCount values provided.
-
- The client needs to ensure that the minimumSegmentDuration is greater than or equal to the segment
- boundary guidelines for the codec type. The client should also ensure that minimumSegmentFrameCount
- also exceeds the segment boundary guidelines.
-
- The segments returned will satisfy both the minimumSegmentDuration and minimumSegmentFrameCount
- requirements. The only exception is the very last segment, which may be shorter.
-
- The returned array will ensure that segment boundaries occur on sample boundaries.
-
- Clients can use these results to fill in the AVPlannedVideoSegmentConfiguration for this asset track,
- if the output maintains the source timing. If the output timing differs from the source, then the
- returned AVPlannedVideoSegmentConfiguration array's results need to be modified accordingly by the client.
-
- This method throws NSInvalidArgumentException if minimumSegmentDuration is not numeric or is less than
- or equal to zero, or if minimumSegmentFrameCount is less than or equal to 0.
-*/
+/// Returns segment boundary recommendations for a given source video asset track.
+///
+/// This is a convenience method that can help clients to pick optimal segmentation boundaries for a given
+/// source video AVAssetTrack based on the structure of the track and the minimumSegmentDuration and
+/// minimumSegmentFrameCount values provided.
+///
+/// The client needs to ensure that the minimumSegmentDuration is greater than or equal to the segment
+/// boundary guidelines for the codec type. The client should also ensure that minimumSegmentFrameCount
+/// also exceeds the segment boundary guidelines.
+///
+/// The segments returned will satisfy both the minimumSegmentDuration and minimumSegmentFrameCount
+/// requirements. The only exception is the very last segment, which may be shorter.
+///
+/// The returned array will ensure that segment boundaries occur on sample boundaries.
+///
+/// Clients can use these results to fill in the AVPlannedVideoSegmentConfiguration for this asset track,
+/// if the output maintains the source timing. If the output timing differs from the source, then the
+/// returned AVPlannedVideoSegmentConfiguration array's results need to be modified accordingly by the client.
+///
+/// This method throws NSInvalidArgumentException if minimumSegmentDuration is not numeric or is less than
+/// or equal to zero, or if minimumSegmentFrameCount is less than or equal to 0.
+///
+/// - Parameter videoAssetTrack: The source video AVAssetTrack to be analyzed.
+/// - Parameter minimumSegmentDuration: The client selected minimum duration for the segments.
+/// - Parameter minimumSegmentFrameCount: The minimum number of source frames in a segment.
+///
+/// - Returns: Array of AVPlannedVideoSegmentConfigurations.
+ (NSArray <AVPlannedVideoSegmentConfiguration *> *)segmentBoundaryRecommendationsForVideoAVAssetTrack:(AVAssetTrack *)videoAssetTrack minimumSegmentDuration:(CMTime)minimumSegmentDuration minimumSegmentFrameCount:(NSInteger)minimumSegmentFrameCount
NS_SWIFT_NAME(segmentBoundaryRecommendations(forVideoTrack:minimumSegmentDuration:minimumSegmentFrameCount:));
-/*!
- @method planTrack:withSegmentsGeneratedBy:
- @abstract
- Adds an AVAssetTrackPlan to this AVAssetWritingPlanner, with a block to be called by the planner to generate each segment of the track.
-
- @param trackPlan
- The track plan contains information about the track and boundaries of all the segments.
- @param writingSegmentCallbackBlock
- A block to be called by the AVAssetWritingPlanner on each incremental segment for this track to write the segment to an intermediate file, according to the specifications in the "segmentWriteRequest" object passed to the block.
-
- @discussion
- This method throws NSInternalInconsistencyException if a trackPlan with the same assemblyTrackID already exists in the planner, or if called after executePlanWithCompletionHandler: has been invoked.
-*/
+/// Adds an AVAssetTrackPlan to this AVAssetWritingPlanner, with a block to be called by the planner to generate each segment of the track.
+///
+/// This method throws NSInternalInconsistencyException if a trackPlan with the same assemblyTrackID already exists in the planner, or if called after executePlanWithCompletionHandler: has been invoked.
+///
+/// - Parameter trackPlan: The track plan contains information about the track and boundaries of all the segments.
+/// - Parameter writingSegmentCallbackBlock: A block to be called by the AVAssetWritingPlanner on each incremental segment for this track to write the segment to an intermediate file, according to the specifications in the "segmentWriteRequest" object passed to the block.
- (void)planTrack:(AVAssetTrackPlan *)trackPlan withSegmentsGeneratedBy:(void (^ NS_SWIFT_SENDABLE)(AVPlannedSegmentWritingRequest * NS_SWIFT_SENDING segmentWriteRequest))writingSegmentCallbackBlock
NS_REFINED_FOR_SWIFT;
-/*!
- @method executePlanWithCompletionHandler:
- @abstract
- Starts the incremental segment writing.
- @param completionHandler
- Called when all the incremental segments on all tracks added to the planner have completed, or some error occurs.
-
- @discussion
- The planner calls the writingSegmentCallbackBlock sequentially, starting with the first segment work, or at the next unfinished segment if resuming a previously suspended session.
- The completionHandler is called upon failure or success. When called with success (error is nil), this means that all segments for all tracks have been completed. The assemblyComposition will be non-nil and can be used to put the incremental tracks back together. One way to accomplish this is by feeding the assemblyComposition through AVAssetExportSession with the pass-through preset.
- The client is responsible for combining any other tracks (those that were not eligible for incremental writing), as well as establishing any track references between the incrementally written tracks and the other tracks in the final asset.
-*/
+/// Starts the incremental segment writing.
+///
+/// The planner calls the writingSegmentCallbackBlock sequentially, starting with the first segment work, or at the next unfinished segment if resuming a previously suspended session.
+/// The completionHandler is called upon failure or success. When called with success (error is nil), this means that all segments for all tracks have been completed. The assemblyComposition will be non-nil and can be used to put the incremental tracks back together. One way to accomplish this is by feeding the assemblyComposition through AVAssetExportSession with the pass-through preset.
+/// The client is responsible for combining any other tracks (those that were not eligible for incremental writing), as well as establishing any track references between the incrementally written tracks and the other tracks in the final asset.
+///
+/// - Parameter completionHandler: Called when all the incremental segments on all tracks added to the planner have completed, or some error occurs.
-(void)executePlanWithCompletionHandler:
(void (^ NS_SWIFT_SENDABLE)(AVComposition * _Nullable NS_SWIFT_SENDING assemblyComposition, NSError * _Nullable error))completionHandler
NS_REFINED_FOR_SWIFT;
-/*!
- @method executePlanOnQueue:withCompletionHandler:
- @abstract
- Starts the incremental segment writing on a given dispatch queue
-
- @param executionQueue
- The dispatch queue on which the planner executes the plans. The segment writing callback blocks and the completion handler are called from this queue.
-
- @param completionHandler
- Called when all the incremental segments on all tracks added to the planner have completed, or some error occurs.
-
- @discussion
- The planner calls the writingSegmentCallbackBlock sequentially, starting with the first segment work, or at the next unfinished segment if resuming a previously suspended export.
- The completionHandler is called upon failure or success. When called with success (error is nil), this means that all segments for all tracks have been completed. The assemblyComposition will be non-nil and can be used to put the incremental tracks back together. One way to accomplish this is by feeding the assemblyComposition through AVAssetExportSession with the pass-through preset.
- The client is responsible for combining any other tracks (those that were not eligible for incremental writing), as well as establishing any track references between the incrementally written tracks and the other tracks in the final asset.
-*/
+/// Starts the incremental segment writing on a given dispatch queue
+///
+/// The planner calls the writingSegmentCallbackBlock sequentially, starting with the first segment work, or at the next unfinished segment if resuming a previously suspended export.
+/// The completionHandler is called upon failure or success. When called with success (error is nil), this means that all segments for all tracks have been completed. The assemblyComposition will be non-nil and can be used to put the incremental tracks back together. One way to accomplish this is by feeding the assemblyComposition through AVAssetExportSession with the pass-through preset.
+/// The client is responsible for combining any other tracks (those that were not eligible for incremental writing), as well as establishing any track references between the incrementally written tracks and the other tracks in the final asset.
+///
+/// - Parameter executionQueue: The dispatch queue on which the planner executes the plans. The segment writing callback blocks and the completion handler are called from this queue.
+/// - Parameter completionHandler: Called when all the incremental segments on all tracks added to the planner have completed, or some error occurs.
-(void)executePlanOnQueue:(dispatch_queue_t)executionQueue
withCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(AVComposition * _Nullable NS_SWIFT_SENDING assemblyComposition, NSError * _Nullable error))completionHandler
NS_SWIFT_UNAVAILABLE("Use executePlan(completionHandler:) instead");
@@ -247,425 +180,237 @@
@end // AVAssetWritingPlanner
-
-/*!
- @class AVAssetWritingPlannerProgress
- @abstract
- AVAssetWritingPlannerProgress tracks the progress of incremental writing for each track in an AVAssetWritingPlanner session.
-
- @discussion
- This class provides per-track progress information as a percentage of the total duration completed. Progress can be queried by assemblyTrackID.
-*/
+/// AVAssetWritingPlannerProgress tracks the progress of incremental writing for each track in an AVAssetWritingPlanner session.
+///
+/// This class provides per-track progress information as a percentage of the total duration completed. Progress can be queried by assemblyTrackID.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
NS_SWIFT_SENDABLE
@interface AVAssetWritingPlannerProgress : NSObject
-/*!
- @method progressForTrack:
- @abstract
- Returns the progress for a specific track identified by its assemblyTrackID.
-
- @param assemblyTrackID
- The track ID to query progress for.
-
- @result
- A float value between 0.0 and 1.0 representing the percentage of duration completed for the track. Returns 0.0 if the track ID is not found.
-
- @discussion
- The progress is calculated as the ratio of completed duration to total duration for the track.
-*/
+/// Returns the progress for a specific track identified by its assemblyTrackID.
+///
+/// The progress is calculated as the ratio of completed duration to total duration for the track.
+///
+/// - Parameter assemblyTrackID: The track ID to query progress for.
+///
+/// - Returns: A float value between 0.0 and 1.0 representing the percentage of duration completed for the track. Returns 0.0 if the track ID is not found.
- (float)progressForTrack:(CMPersistentTrackID)assemblyTrackID
NS_SWIFT_NAME(progress(forTrack:));
-/*!
- @property overallProgress
- @abstract
- The overall progress across all tracks.
-
- @discussion
- Returns a float value between 0.0 and 1.0 representing the overall progress. This is calculated as the average progress of all tracks weighted by their durations.
-*/
+/// The overall progress across all tracks.
+///
+/// Returns a float value between 0.0 and 1.0 representing the overall progress. This is calculated as the average progress of all tracks weighted by their durations.
@property (readonly) float overallProgress;
@end // AVAssetWritingPlannerProgress
-
-/*!
- @class AVPlannedSegmentConfiguration
- @abstract
- AVPlannedSegmentConfiguration describes the requirements for a planned segment in an incremental writing session executed by the AVAssetWritingPlanner. Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
-*/
+/// AVPlannedSegmentConfiguration describes the requirements for a planned segment in an incremental writing session executed by the AVAssetWritingPlanner. Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVPlannedSegmentConfiguration : NSObject
-/*!
- @method initWithDuration
- @abstract
- Creates an instance of AVPlannedSegmentConfiguration specifying the duration of the planned segment.
-
- @param duration
- The total duration of this planned segment. If an empty edit is included, this duration may be larger than the sum of the durations of the samples in this planned segment.
-
- @result
- An instance of AVPlannedSegmentConfiguration, or nil if initialization fails.
-
- @discussion
- The duration parameter must be numeric and greater than 0. Otherwise, the initializer throws NSInvalidArgumentException.
- */
+/// Creates an instance of AVPlannedSegmentConfiguration specifying the duration of the planned segment.
+///
+/// The duration parameter must be numeric and greater than 0. Otherwise, the initializer throws NSInvalidArgumentException.
+///
+/// - Parameter duration: The total duration of this planned segment. If an empty edit is included, this duration may be larger than the sum of the durations of the samples in this planned segment.
+///
+/// - Returns: An instance of AVPlannedSegmentConfiguration, or nil if initialization fails.
- (instancetype)initWithDuration:(CMTime)duration NS_DESIGNATED_INITIALIZER;
-/*!
- @property duration
- @abstract
- The duration of this planned segment.
- */
+/// The duration of this planned segment.
@property (readonly) CMTime duration;
AV_INIT_UNAVAILABLE
@end // AVPlannedSegmentConfiguration
-/*!
- @class AVPlannedVideoSegmentConfiguration
- @abstract
- AVPlannedVideoSegmentConfiguration describes the requirements for a planned video segment in an incremental writing session executed by the AVAssetWritingPlanner.
-
- @discussion
- Use this class instead of the base class AVPlannedSegmentConfiguration if you are setting up AVAssetWriterInput to do video compression. AVAssetWritingPlanner will provide required video compression properties in its AVPlannedSegmentWritingRequest that are needed to prevent visual artifacts on segment boundaries.
-*/
+/// AVPlannedVideoSegmentConfiguration describes the requirements for a planned video segment in an incremental writing session executed by the AVAssetWritingPlanner.
+///
+/// Use this class instead of the base class AVPlannedSegmentConfiguration if you are setting up AVAssetWriterInput to do video compression. AVAssetWritingPlanner will provide required video compression properties in its AVPlannedSegmentWritingRequest that are needed to prevent visual artifacts on segment boundaries.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVPlannedVideoSegmentConfiguration : AVPlannedSegmentConfiguration
-/*!
- @method initWithNumberOfFrames:duration:
- @abstract
- Creates an instance of AVPlannedVideoSegmentConfiguration specifying the number of frames in and total duration of the segment.
-
- @param frameCount
- The number of frames in this planned video segment.
- @param duration
- The duration of this planned video segment.
-
- @result
- An instance of AVPlannedVideoSegmentConfiguration.
-
- @discussion
- For best results, frameCount and duration should be greater or equal to the minimumFrameCount and minimumDuration of AVPlannedVideoSegmentBoundaryGuidelines respectively.
- This initializer throws NSInvalidArgumentException if frameCount is less than or equal to 0, or duration is not numeric, or duration is less than or equal to 0.
- */
+/// Creates an instance of AVPlannedVideoSegmentConfiguration specifying the number of frames in and total duration of the segment.
+///
+/// For best results, frameCount and duration should be greater or equal to the minimumFrameCount and minimumDuration of AVPlannedVideoSegmentBoundaryGuidelines respectively.
+/// This initializer throws NSInvalidArgumentException if frameCount is less than or equal to 0, or duration is not numeric, or duration is less than or equal to 0.
+///
+/// - Parameter frameCount: The number of frames in this planned video segment.
+/// - Parameter duration: The duration of this planned video segment.
+///
+/// - Returns: An instance of AVPlannedVideoSegmentConfiguration.
- (instancetype)initWithNumberOfFrames:(NSInteger)frameCount duration:(CMTime)duration NS_DESIGNATED_INITIALIZER;
-/*!
- @property frameCount
- @abstract
- The number of frames in this planned video segment.
- */
+/// The number of frames in this planned video segment.
@property (readonly) NSInteger frameCount;
AV_INIT_UNAVAILABLE
@end // AVPlannedVideoSegmentConfiguration
-/*!
- @class AVAssetTrackPlan
- @abstract
- AVAssetTrackPlan holds information about a track and how it should be segmented and executed in an incremental writing session.
-
- @discussion
- Call AVAssetWritingPlanner's "planTrack:withSegmentsGeneratedBy:" method to add an AVAssetTrackPlan to the planner to include it in the incremental writing session.
-*/
+/// AVAssetTrackPlan holds information about a track and how it should be segmented and executed in an incremental writing session.
+///
+/// Call AVAssetWritingPlanner's "planTrack:withSegmentsGeneratedBy:" method to add an AVAssetTrackPlan to the planner to include it in the incremental writing session.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVAssetTrackPlan : NSObject
-/*!
- @property assemblyTrackID
- @abstract
- This is the track ID of this track when it is included in the assemblyComposition the planner passes to the completion handler to assemble all planned segments of all tracks into a single AVComposition.
-
- @discussion
- The assemblyTrackID serves the purpose as a unique identifier of the track in the incremental writing session. This does not necessarily match the trackID of the source asset.
- The client is responsible for remembering the relationship between assemblyTrackID and the trackID in the source asset.
-*/
+/// This is the track ID of this track when it is included in the assemblyComposition the planner passes to the completion handler to assemble all planned segments of all tracks into a single AVComposition.
+///
+/// The assemblyTrackID serves the purpose as a unique identifier of the track in the incremental writing session. This does not necessarily match the trackID of the source asset.
+/// The client is responsible for remembering the relationship between assemblyTrackID and the trackID in the source asset.
@property (readonly) CMPersistentTrackID assemblyTrackID;
-/*!
- @property mediaType
- @abstract
- The media type of this track.
- */
+/// The media type of this track.
@property (readonly) AVMediaType mediaType;
-/*!
- @property segmentConfigurations
- @abstract
- An array of AVPlannedSegmentConfigurations, each element specifying the configuration of a planned segment, ordered in output PTS order.
- */
+/// An array of AVPlannedSegmentConfigurations, each element specifying the configuration of a planned segment, ordered in output PTS order.
@property (readonly, copy) NSArray<AVPlannedSegmentConfiguration *> *segmentConfigurations;
-/*!
- @method initWithMediaType:segmentConfigurations:assemblyTrackID:
- @abstract
- Returns an instance of AVAssetTrackPlan
-
- @param mediaType
- Media type of the track
- @param segmentConfigurations
- Segment configurations of the track
- @param trackID
- The trackID that identifies this track in the assemblyComposition the planner passes to the completion handler of the incremental writing session.
-
- @discussion
- This initializer throws NSInvalidArgumentException if trackID is kCMPersistentTrackID_Invalid.
- */
+/// Returns an instance of AVAssetTrackPlan
+///
+/// This initializer throws NSInvalidArgumentException if trackID is kCMPersistentTrackID_Invalid.
+///
+/// - Parameter mediaType: Media type of the track
+/// - Parameter segmentConfigurations: Segment configurations of the track
+/// - Parameter trackID: The trackID that identifies this track in the assemblyComposition the planner passes to the completion handler of the incremental writing session.
- (instancetype)initWithMediaType:(AVMediaType)mediaType segmentConfigurations:(NSArray<AVPlannedSegmentConfiguration *> *)segmentConfigurations assemblyTrackID:(CMPersistentTrackID)trackID NS_DESIGNATED_INITIALIZER;
AV_INIT_UNAVAILABLE
@end // AVAssetTrackPlan
-/*!
- @class AVAssetVideoTrackPlan
- @abstract
- AVAssetVideoTrackPlan holds information about a track and how it should be segmented and executed in an incremental writing session.
-
- @discussion
- Call AVAssetWritingPlanner's "planTrack:withSegmentsGeneratedBy:" method to add an AVAssetTrackPlan to the planner's plan to include it in the incremental writing session.
- Use this class instead of the base class AVAssetTrackPlan if you are setting up AVAssetWriter with video compression. This configuration hints to the planner that it
- must coordinate segment boundaries transitions between segments. This is abstracted from the client via using either the createResumableAVAssetWriterInputWithMediaType
- or createResumableCompressionSessionWithAllocator helper functions within the AVPlannedVideoSegmentWritingRequest.
-*/
+/// AVAssetVideoTrackPlan holds information about a track and how it should be segmented and executed in an incremental writing session.
+///
+/// Call AVAssetWritingPlanner's "planTrack:withSegmentsGeneratedBy:" method to add an AVAssetTrackPlan to the planner's plan to include it in the incremental writing session.
+/// Use this class instead of the base class AVAssetTrackPlan if you are setting up AVAssetWriter with video compression. This configuration hints to the planner that it
+/// must coordinate segment boundaries transitions between segments. This is abstracted from the client via using either the resumableAssetWriterInputWithMediaType
+/// or createResumableCompressionSessionWithAllocator helper functions within the AVPlannedVideoSegmentWritingRequest.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVAssetVideoTrackPlan : AVAssetTrackPlan
-/*!
- @property videoCodecType
- @abstract
- Video codec type of this track
- */
+/// Video codec type of this track
@property (readonly) AVVideoCodecType videoCodecType;
-/*!
- @method initWithVideoCodecType:mediaType:segmentConfigurations:assemblyTrackID:
- @abstract
- Returns an instance of AVAssetVideoTrackPlan
-
- @param videoCodecType
- Video codec type of the track
- @param encoderSpecification
- The encoder specification the client will use to write planned segments of this track
- @param mediaType
- Media type of the track. Only AVMediaTypeVideo and AVMediaTypeAuxiliaryPicture are supported.
- @param segmentConfigurations
- Segment configurations of the track
- @param trackID
- The trackID that identifies this track in the assemblyComposition the planner passes to the completion handler of the incremental writing session.
-
- @discussion
- This initializer throws NSInvalidArgumentException in the following cases.
- 1. mediaType is not supported. Supported media types are AVMediaTypeVideo and AVMediaTypeAuxiliaryPicture
- 2. The encoder specified by videoCodecType and encoderSpecification does not support video encoding in segments
- */
+/// Returns an instance of AVAssetVideoTrackPlan
+///
+/// This initializer throws NSInvalidArgumentException in the following cases.
+/// 1. mediaType is not supported. Supported media types are AVMediaTypeVideo and AVMediaTypeAuxiliaryPicture
+/// 2. The encoder specified by videoCodecType and encoderSpecification does not support video encoding in segments
+///
+/// - Parameter videoCodecType: Video codec type of the track
+/// - Parameter encoderSpecification: The encoder specification the client will use to write planned segments of this track
+/// - Parameter mediaType: Media type of the track. Only AVMediaTypeVideo and AVMediaTypeAuxiliaryPicture are supported.
+/// - Parameter segmentConfigurations: Segment configurations of the track
+/// - Parameter trackID: The trackID that identifies this track in the assemblyComposition the planner passes to the completion handler of the incremental writing session.
- (instancetype)initWithVideoCodecType:(AVVideoCodecType)videoCodecType encoderSpecification:(nullable NSDictionary *)encoderSpecification mediaType:(AVMediaType)mediaType segmentConfigurations:(NSArray<AVPlannedSegmentConfiguration *> *)segmentConfigurations assemblyTrackID:(CMPersistentTrackID)trackID NS_REFINED_FOR_SWIFT NS_DESIGNATED_INITIALIZER;
AV_INIT_UNAVAILABLE
@end // AVAssetVideoTrackPlan
-
-/*!
- @class AVPlannedSegmentWritingRequest
- @abstract
- AVPlannedSegmentWritingRequest encompasses a request from the AVAssetWritingPlanner to the client code to write one incremental track segment.
-
- @discussion
- The client should respond to this request by writing the specified time range of data to a movie file at the specified segmentFileOutputURL, with start PTS zero. The client's writing work may be completed asynchronously. If it completes successfully, clients must call the `-finish` or `-finishWithClientState` method on the request object. If writing the segment fails, clients must call the `-finishWithError:` method on the request object. If segment writing needs to be stopped before reaching the end of the segment, clients must call `-cancel`.
-*/
+/// AVPlannedSegmentWritingRequest encompasses a request from the AVAssetWritingPlanner to the client code to write one incremental track segment.
+///
+/// The client should respond to this request by writing the specified time range of data to a movie file at the specified segmentFileOutputURL, with start PTS zero. The client's writing work may be completed asynchronously. If it completes successfully, clients must call the `-finish` or `-finishWithClientState` method on the request object. If writing the segment fails, clients must call the `-finishWithError:` method on the request object. If segment writing needs to be stopped before reaching the end of the segment, clients must call `-cancel`.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVPlannedSegmentWritingRequest : NSObject
-/*!
- @property segmentFileOutputURL
- @abstract
- The URL of the file where this incremental segment should be written to.
-
- @discussion
- AVAssetWritingPlanner will request each incremental segment to be written to a different file. If the file already exists from a previous session, the client should delete it to allow the subsequent asset writer session to succeed.
- */
+/// The URL of the file where this incremental segment should be written to.
+///
+/// AVAssetWritingPlanner will request each incremental segment to be written to a different file. If the file already exists from a previous session, the client should delete it to allow the subsequent asset writer session to succeed.
@property (readonly) NSURL *segmentFileOutputURL;
-/*!
- @property timeRange
- @abstract
- The PTS range for this segment.
-
- @discussion
- The client is responsible for delivering the appropriate sample corresponding to timeRange.start if we are resuming a previous session that has already made incremental progress for this track.
- */
+/// The PTS range for this segment.
+///
+/// The client is responsible for delivering the appropriate sample corresponding to timeRange.start if we are resuming a previous session that has already made incremental progress for this track.
@property (readonly) CMTimeRange timeRange;
-/*!
- @property assemblyTrackID
- @abstract
- The trackID identifies which track should be written to this segment file. This is the same track ID in the AVAssetTrackPlan object. This is also the trackID the AVAssetWritingPlanner uses to build the assembled AVComposition before it calls the completion handler.
- */
+/// The trackID identifies which track should be written to this segment file. This is the same track ID in the AVAssetTrackPlan object. This is also the trackID the AVAssetWritingPlanner uses to build the assembled AVComposition before it calls the completion handler.
@property (readonly) CMPersistentTrackID assemblyTrackID;
-/*!
- @property clientStateToRestore
- @abstract
- The client state persisted from the previous segment, if any. Specifically, this is the NSData provided to the previous segment's finishWithClientState: method. The client is responsible to restore its client state before writing the current segment.
- For example, clients such as compositors with a temporal element may need some processing history of previous samples in order to generate an output sample at time N. This will be
- nil for algorithms that are stateless.
- */
+/// The client state persisted from the previous segment, if any. Specifically, this is the NSData provided to the previous segment's finishWithClientState: method. The client is responsible to restore its client state before writing the current segment. For example, clients such as compositors with a temporal element may need some processing history of previous samples in order to generate an output sample at time N. This will be nil for algorithms that are stateless.
@property (readonly, nullable) NSData *clientStateToRestore;
-/*!
- @property progress
- @abstract
- The current progress for the track identified by assemblyTrackID.
-
- @discussion
- Returns a float value between 0.0 and 1.0 representing the percentage of duration completed for this track. This value is updated as segments are completed.
-*/
+/// The current progress for the track identified by assemblyTrackID.
+///
+/// Returns a float value between 0.0 and 1.0 representing the percentage of duration completed for this track. This value is updated as segments are completed.
@property (readonly) float progress;
-/*!
- @method finish
- @abstract
- Clients must call this method after all writing activities for the intermediate segment file have successfully completed.
-
- @discussion
- This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- */
+/// Clients must call this method after all writing activities for the intermediate segment file have successfully completed.
+///
+/// This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- (void)finish NS_REFINED_FOR_SWIFT;
-/*!
- @method finishWithClientState:
- @abstract
- Clients must call this method after all writing activities for the intermediate segment file have successfully completed.
- If called with nil, this is equivalent to calling finish.
-
- @discussion
- This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- */
+/// Clients must call this method after all writing activities for the intermediate segment file have successfully completed. If called with nil, this is equivalent to calling finish.
+///
+/// This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- (void)finishWithClientState:(nullable NSData *)segmentEndingClientState NS_REFINED_FOR_SWIFT;
-/*!
- @method finishWithError:
- @abstract
- Clients must call this method if a non-recoverable error occurs while generating the segment file. The completionHandler of AVAssetWritingPlanner will be called with an error whose code
- is AVErrorAssetWritingPlannerClientWritingError, and the error provided here will be available in the NSUnderlyingErrorKey of the userInfo dictionary.
- If called with nil, this is equivalent to calling finish.
-
- @discussion
- This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- */
+/// Clients must call this method if a non-recoverable error occurs while generating the segment file. The completionHandler of AVAssetWritingPlanner will be called with an error whose code is AVErrorAssetWritingPlannerClientWritingError, and the error provided here will be available in the NSUnderlyingErrorKey of the userInfo dictionary. If called with nil, this is equivalent to calling finish.
+///
+/// This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- (void)finishWithError:(nullable NSError *)error NS_REFINED_FOR_SWIFT;
-/*!
- @method cancel
- @abstract
- Clients should call this if the current segment is to be cancelled, but the export is still expected to be resumed at a later time. For example, this could happen if the export is running in the background
- and the expiration handler is called due to changes in system conditions.
-
- @discussion
- This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- */
+/// Clients should call this if the current segment is to be cancelled, but the export is still expected to be resumed at a later time. For example, this could happen if the export is running in the background and the expiration handler is called due to changes in system conditions.
+///
+/// This method throws NSGenericException if finish, finishWithClientState:, finishWithError:, or cancel has already been called on this request.
- (void)cancel NS_REFINED_FOR_SWIFT;
AV_INIT_UNAVAILABLE
@end // AVPlannedSegmentWritingRequest
-
-/*!
- @class AVPlannedVideoSegmentWritingRequest
- @abstract
- AVPlannedVideoSegmentWritingRequest encompasses a request from the AVAssetWritingPlanner to the client code to write one incremental video track segment with compression.
-
- @discussion
- The client should respond to this request by writing the specified time range of data to a movie file at the specified segmentFileOutputURL, with start PTS zero. The client's writing work may be completed asynchronously. If it completes successfully, it must call the `-finish` method on the request object. If writing the segment fails, it must call the `-finishWithError:` method on the request object.
-*/
+/// AVPlannedVideoSegmentWritingRequest encompasses a request from the AVAssetWritingPlanner to the client code to write one incremental video track segment with compression.
+///
+/// The client should respond to this request by writing the specified time range of data to a movie file at the specified segmentFileOutputURL, with start PTS zero. The client's writing work may be completed asynchronously. If it completes successfully, it must call the `-finish` method on the request object. If writing the segment fails, it must call the `-finishWithError:` method on the request object.
API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), visionos(27.0)) API_UNAVAILABLE(watchos)
@interface AVPlannedVideoSegmentWritingRequest : AVPlannedSegmentWritingRequest
-/*!
- @property frameCount
- @abstract
- The number of frames in this planned video segment. This is provided for convenience, and is the same value that was configured for the segment in AVPlannedVideoSegmentConfiguration.
- */
+/// The number of frames in this planned video segment. This is provided for convenience, and is the same value that was configured for the segment in AVPlannedVideoSegmentConfiguration.
@property (readonly) NSInteger frameCount;
-/*!
- @method resumableAssetWriterInputWithMediaType:outputSettings:sourceFormatHint:returningError:
- @abstract
- Helper function that returns a minimally configured AVAssetWriterInput object for writing the current segment. The final video encoder state from the previous segment will be restored before writing starts.
-
- @param mediaType
- The type of media that an input accepts.
- @param outputSettings
- The settings to use for configuring the AVAssetWriterInput object to be returned. Create an output settings dictionary manually, or use AVOutputSettingsAssistant to create preset-based settings.
- @param sourceFormatHint
- A hint about the format of the media data to append. The input uses the source format hint to fill in missing output settings. If you specify a hint, you only need to specify AVFormatIDKey for the audio output settings, and AVVideoCodecKey is the only required key for video output settings.
- The system raises an error if the format description isn't valid for the indicated media type.
- @param errorOut
- A pointer where a NSError object may be returned.
- @return A new writer input. Nil if a writer input cannot be created.
-
-@discussion
- Clients using AVAssetWriterInput with video compression must use this method to create the writer input for writing the segment. The planner initializes the writer input in such a way that when writing starts, the video encoder's state is restored to the final state of the last segment.
- The client should perform additional configurations on the returned writer input as needed, but must apply the same configurations for each segment of the track.
-
- Client cannot call this method more than once on a writing request object.
- For the same segment writing request, this method and the "createResumableCompressionSessionWithAllocator" method are mutually exclusive. The client can call either one of the two, but not both.
- This method fails (returns nil) with error if the outputSettings or sourceFormatHint differs from the previous segment.
-
- The writing request retains the writer input but does not mutate it after this method is returned.
- */
+/// Helper function that returns a minimally configured AVAssetWriterInput object for writing the current segment. The final video encoder state from the previous segment will be restored before writing starts.
+///
+/// Clients using AVAssetWriterInput with video compression must use this method to create the writer input for writing the segment. The planner initializes the writer input in such a way that when writing starts, the video encoder's state is restored to the final state of the last segment.
+/// The client should perform additional configurations on the returned writer input as needed, but must apply the same configurations for each segment of the track.
+///
+/// Client cannot call this method more than once on a writing request object.
+/// For the same segment writing request, this method and the "createResumableCompressionSessionWithAllocator" method are mutually exclusive. The client can call either one of the two, but not both.
+/// This method fails (returns nil) with error if the outputSettings or sourceFormatHint differs from the previous segment.
+///
+/// The writing request retains the writer input but does not mutate it after this method is returned.
+///
+/// - Parameter mediaType: The type of media that an input accepts.
+/// - Parameter outputSettings: The settings to use for configuring the AVAssetWriterInput object to be returned. Create an output settings dictionary manually, or use AVOutputSettingsAssistant to create preset-based settings.
+/// - Parameter sourceFormatHint: A hint about the format of the media data to append. The input uses the source format hint to fill in missing output settings. If you specify a hint, you only need to specify AVFormatIDKey for the audio output settings, and AVVideoCodecKey is the only required key for video output settings. The system raises an error if the format description isn't valid for the indicated media type.
+/// - Parameter errorOut: A pointer where a NSError object may be returned.
+/// - Returns: A new writer input. Nil if a writer input cannot be created.
- (nullable AVAssetWriterInput *)resumableAssetWriterInputWithMediaType:(AVMediaType)mediaType outputSettings:(nullable NSDictionary<NSString *, id>*)outputSettings sourceFormatHint:(nullable CMFormatDescriptionRef)sourceFormatHint returningError:(NSError * _Nullable * _Nullable)errorOut
NS_REFINED_FOR_SWIFT;
#if AVF_VTCOMPRESSIONSESSION_AVAILABLE
-/*!
-@method createResumableCompressionSessionWithAllocator:width:height:codecType:encoderSpecification:sourceImageBufferAttributes:compressedDataAllocator:outputCallback:outputCallbackRefCon:returningError
-@abstract
- Helper function to create a VTCompressionSession that restores the video encoder state persisted at the end of the previous segment.
-@param allocator
- An allocator for the session. Pass NULL to use the default allocator.
-@param width
- The pixel width of video frames.
-@param height
- The pixel height of video frames.
-@param codecType
- The codec type.
-@param encoderSpecification
- A dictionary describing the characteristics of a video encoder to use. Pass NULL to let the system choose an encoder. If the client provides a specification, it should omit the following keys: kVTCompressionPropertyKey_SourceFrameCount, kVTCompressionPropertyKey_MoreFramesBeforeStart, and kVTCompressionPropertyKey_MoreFramesAfterEnd, since such keys will be overwritten by the underlying implementation.
-@param sourceImageBufferAttributes
- Required attributes for source pixel buffers, used when creating a pixel buffer pool for source frames. If you don't want the system to create one for you, pass NULL.
- Using pixel buffers not allocated by the system increases the chance that you'll have to copy image data.
-@param compressedDataAllocator
- An allocator for the compressed data. Pass NULL to use the default allocator.
- In macOS 10.12 and later, using a compressedDataAllocator may trigger an extra buffer copy.
-@param outputCallback
- The callback to invoke with compressed frames. The system may call this function asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrame.
- Pass NULL only if you'll be calling VTCompressionSessionEncodeFrameWithOutputHandler for encoding frames.
-@param outputCallbackRefCon
- Client-defined reference value for the output callback.
-@param errorOut
- A pointer where a NSError object may be returned.
-
-@discussion
- Clients using VTCompressionSession directly to produce encoded video samples for writing the segment must use this method to create the session.
- The client should perform additional configurations on the returned compression session, but must apply the same configurations for each segment of the track.
-
- Client cannot call this method more than once on a writing request object.
- For the same segment writing request, this method and the resumableAssetWriterInputWithMediaType:outputSettings:sourceFormatHint:returningError: method are mutually exclusive. The client can call either one of the two, but not both.
- This method fails (returns nil) with error if the parameters differ from the previous segment.
-
- The client should release the session after use.
- The writing request retains the compression session but does not mutate the session after this method is returned.
-*/
+/// Helper function to create a VTCompressionSession that restores the video encoder state persisted at the end of the previous segment.
+///
+/// Clients using VTCompressionSession directly to produce encoded video samples for writing the segment must use this method to create the session.
+/// The client should perform additional configurations on the returned compression session, but must apply the same configurations for each segment of the track.
+///
+/// Client cannot call this method more than once on a writing request object.
+/// For the same segment writing request, this method and the resumableAssetWriterInputWithMediaType:outputSettings:sourceFormatHint:returningError: method are mutually exclusive. The client can call either one of the two, but not both.
+/// This method fails (returns nil) with error if the parameters differ from the previous segment.
+///
+/// The client should release the session after use.
+/// The writing request retains the compression session but does not mutate the session after this method is returned.
+///
+/// - Parameter allocator: An allocator for the session. Pass NULL to use the default allocator.
+/// - Parameter width: The pixel width of video frames.
+/// - Parameter height: The pixel height of video frames.
+/// - Parameter codecType: The codec type.
+/// - Parameter encoderSpecification: A dictionary describing the characteristics of a video encoder to use. Pass NULL to let the system choose an encoder. If the client provides a specification, it should omit the following keys: kVTCompressionPropertyKey_SourceFrameCount, kVTCompressionPropertyKey_MoreFramesBeforeStart, and kVTCompressionPropertyKey_MoreFramesAfterEnd, since such keys will be overwritten by the underlying implementation.
+/// - Parameter sourceImageBufferAttributes: Required attributes for source pixel buffers, used when creating a pixel buffer pool for source frames. If you don't want the system to create one for you, pass NULL. Using pixel buffers not allocated by the system increases the chance that you'll have to copy image data.
+/// - Parameter compressedDataAllocator: An allocator for the compressed data. Pass NULL to use the default allocator. In macOS 10.12 and later, using a compressedDataAllocator may trigger an extra buffer copy.
+/// - Parameter outputCallback: The callback to invoke with compressed frames. The system may call this function asynchronously, on a different thread from the one that calls VTCompressionSessionEncodeFrame. Pass NULL only if you'll be calling VTCompressionSessionEncodeFrameWithOutputHandler for encoding frames.
+/// - Parameter outputCallbackRefCon: Client-defined reference value for the output callback.
+/// - Parameter errorOut: A pointer where a NSError object may be returned.
- (nullable VTCompressionSessionRef)createResumableCompressionSessionWithAllocator:(nullable CFAllocatorRef)allocator
width:(int32_t)width
height:(int32_t)height
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAudioMix.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAudioMix.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAudioMix.h 2026-05-29 23:09:27
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVAudioMix.h 2026-06-12 02:20:08
@@ -21,19 +21,13 @@
#import <MediaToolbox/MTAudioProcessingTap.h>
#endif
-/*!
-
- @class AVAudioMix
-
- @abstract Allows custom audio processing to be performed on audio tracks during playback or other operations.
-
-*/
@class AVAudioMixInternal;
@class AVAudioMixInputParameters;
NS_ASSUME_NONNULL_BEGIN
+/// Allows custom audio processing to be performed on audio tracks during playback or other operations.
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), watchos(1.0), visionos(1.0))
@interface AVAudioMix : NSObject <NSCopying, NSMutableCopying> {
@private
@@ -55,103 +49,69 @@
AVMutableAudioMixInternal *_mutableAudioMix __attribute__((unused));
}
-/*
- @method audioMix
- @abstract Returns a new instance of AVMutableAudioMix with a nil array of inputParameters.
-*/
+/// Returns a new instance of AVMutableAudioMix with a nil array of inputParameters.
+ (instancetype)audioMix;
-/*!
- @property inputParameters
- @abstract Indicates parameters for inputs to the mix; an NSArray of instances of AVAudioMixInputParameters.
- @discussion Note that an instance of AVAudioMixInputParameters is not required for each audio track that contributes to the mix; audio for those without associated AVAudioMixInputParameters will be included in the mix, processed according to default behavior.
-*/
+/// Indicates parameters for inputs to the mix; an NSArray of instances of AVAudioMixInputParameters.
+///
+/// Note that an instance of AVAudioMixInputParameters is not required for each audio track that contributes to the mix; audio for those without associated AVAudioMixInputParameters will be included in the mix, processed according to default behavior.
@property (nonatomic, copy) NSArray<AVAudioMixInputParameters *> *inputParameters;
@end
-
-/*!
- @enum AVAudioMixInputParametersTrackID
- @abstract
- Special value for the trackID property of AVAudioMixInputParameters.
- @constant AVAudioMixInputParametersTrackMixID
- Indicates that the specified input parameters should be applied to the mix of all audio tracks rather than to a single specific audio track. This is particularly useful for setting up volume ramps or an audio tap for streaming playback.
-*/
+/// Special value for the trackID property of AVAudioMixInputParameters.
typedef NS_ENUM (CMPersistentTrackID, AVAudioMixInputParametersTrackID) {
+ /// Indicates that the specified input parameters should be applied to the mix of all audio tracks rather than to a single specific audio track. This is particularly useful for setting up volume ramps or an audio tap for streaming playback.
AVAudioMixInputParametersTrackMixID = 0
} API_AVAILABLE(macos(27.0), ios(27.0), tvos(27.0), watchos(27.0), visionos(27.0));
-/*!
-
- @class AVAudioMixInputParameters
-
- @abstract Provides time-varying parameters to apply to an input of an audio mix. Audio volume is currently supported as a time-varying parameter.
-
- @discussion
- Use an instance of AVAudioMixInputParameters to apply audio volume ramps for an input to an audio mix.
- AVAudioMixInputParameters are associated with audio tracks via the trackID property.
-
- Notes on audio volume ramps:
-
- Before the first time at which a volume is set, a volume of 1.0 used; after the last time for which a volume has been set, the last volume is used.
- Within the timeRange of a volume ramp, the volume is interpolated between the startVolume and endVolume of the ramp.
- For example, setting the volume to 1.0 at time 0 and also setting a volume ramp from a volume of 0.5 to 0.2 with a timeRange of [4.0, 5.0]
- results in an audio volume parameters that hold the volume constant at 1.0 from 0.0 sec to 4.0 sec, then cause it to jump to 0.5 and
- descend to 0.2 from 4.0 sec to 9.0 sec, holding constant at 0.2 thereafter.
-*/
-
@class AVAudioMixInputParametersInternal;
+/// Provides time-varying parameters to apply to an input of an audio mix. Audio volume is currently supported as a time-varying parameter.
+///
+/// Use an instance of AVAudioMixInputParameters to apply audio volume ramps for an input to an audio mix.
+/// AVAudioMixInputParameters are associated with audio tracks via the trackID property.
+///
+/// Notes on audio volume ramps:
+///
+/// Before the first time at which a volume is set, a volume of 1.0 used; after the last time for which a volume has been set, the last volume is used.
+/// Within the timeRange of a volume ramp, the volume is interpolated between the startVolume and endVolume of the ramp.
+/// For example, setting the volume to 1.0 at time 0 and also setting a volume ramp from a volume of 0.5 to 0.2 with a timeRange of [4.0, 5.0]
+/// results in an audio volume parameters that hold the volume constant at 1.0 from 0.0 sec to 4.0 sec, then cause it to jump to 0.5 and
+/// descend to 0.2 from 4.0 sec to 9.0 sec, holding constant at 0.2 thereafter.
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), watchos(1.0), visionos(1.0))
@interface AVAudioMixInputParameters : NSObject <NSCopying, NSMutableCopying> {
@private
AVAudioMixInputParametersInternal *_inputParameters;
}
-/*!
- @property trackID
- @abstract Indicates the trackID of the audio track to which the parameters should be applied.
-*/
+/// Indicates the trackID of the audio track to which the parameters should be applied.
@property (nonatomic, readonly) CMPersistentTrackID trackID;
-/*!
- @property audioTimePitchAlgorithm
- @abstract Indicates the processing algorithm used to manage audio pitch at varying rates and for scaled audio edits.
- @discussion
- Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
- Can be nil, in which case the audioTimePitchAlgorithm set on the AVPlayerItem, AVAssetExportSession, or AVAssetReaderAudioMixOutput on which the AVAudioMix is set will be used for the associated track.
-*/
+/// Indicates the processing algorithm used to manage audio pitch at varying rates and for scaled audio edits.
+///
+/// Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
+/// Can be nil, in which case the audioTimePitchAlgorithm set on the AVPlayerItem, AVAssetExportSession, or AVAssetReaderAudioMixOutput on which the AVAudioMix is set will be used for the associated track.
@property (nonatomic, readonly, copy, nullable) AVAudioTimePitchAlgorithm audioTimePitchAlgorithm API_AVAILABLE(macos(10.10), ios(7.0), tvos(9.0), watchos(1.0), visionos(1.0));
#if AVF_AUDIO_PROCESSING_TAP_AVAILABLE
-/*!
- @property audioTapProcessor
- @abstract Indicates the audio processing tap that will be used for the audio track or tracks.
- @discussion
- If you wish to tap the mix of audio tracks (i.e. if trackID is equal to AVAudioMixInputParametersTrackMixID), use the function MTAudioProcessingTapCreateWithPreferredFormat to create the instance of MTAudioProcessingTap to set as the value of audioTapProcessor. Created otherwise, the processing format of a tap of a track mix is undefined (but may be observed via the use of your MTAudioProcessingTapPrepareCallback).
-*/
+/// Indicates the audio processing tap that will be used for the audio track or tracks.
+///
+/// If you wish to tap the mix of audio tracks (i.e. if trackID is equal to AVAudioMixInputParametersTrackMixID), use the function MTAudioProcessingTapCreateWithPreferredFormat to create the instance of MTAudioProcessingTap to set as the value of audioTapProcessor. Created otherwise, the processing format of a tap of a track mix is undefined (but may be observed via the use of your MTAudioProcessingTapPrepareCallback).
@property (nonatomic, readonly, retain, nullable) __attribute__((NSObject)) MTAudioProcessingTapRef audioTapProcessor API_AVAILABLE(macos(10.9), ios(6.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
#endif
-/*
- @method getVolumeRampForTime:startVolume:endVolume:timeRange:
- @abstract Obtains the volume ramp that includes the specified time.
- @param time
- If a ramp with a timeRange that contains the specified time has been set, information about the effective ramp for that time is supplied.
- Otherwise, information about the first ramp that starts after the specified time is supplied.
- @param startVolume
- A pointer to a float to receive the starting volume value for the volume ramp. May be NULL.
- @param endVolume
- A pointer to a float to receive the ending volume value for the volume ramp. May be NULL.
- @param timeRange
- A pointer to a CMTimeRange to receive the timeRange of the volume ramp. May be NULL.
- @result
- An indication of success. NO will be returned if the specified time is beyond the duration of the last volume ramp that has been set.
-*/
+/// Obtains the volume ramp that includes the specified time.
+///
+/// - Parameter time: If a ramp with a timeRange that contains the specified time has been set, information about the effective ramp for that time is supplied. Otherwise, information about the first ramp that starts after the specified time is supplied.
+/// - Parameter startVolume: A pointer to a float to receive the starting volume value for the volume ramp. May be NULL.
+/// - Parameter endVolume: A pointer to a float to receive the ending volume value for the volume ramp. May be NULL.
+/// - Parameter timeRange: A pointer to a CMTimeRange to receive the timeRange of the volume ramp. May be NULL.
+///
+/// - Returns: An indication of success. NO will be returned if the specified time is beyond the duration of the last volume ramp that has been set.
- (BOOL)getVolumeRampForTime:(CMTime)time startVolume:(nullable float *)startVolume endVolume:(nullable float *)endVolume timeRange:(nullable CMTimeRange *)timeRange;
@end
@@ -168,67 +128,47 @@
AVMutableAudioMixInputParametersInternal *_mutableInputParameters __attribute__((unused));
}
-/*
- @method audioMixInputParametersWithTrack:
- @abstract Returns a new instance of AVMutableAudioMixInputParameters with no volume ramps and a trackID set to the specified track's trackID.
- @param track
- A reference to an AVAssetTrack.
-*/
+/// Returns a new instance of AVMutableAudioMixInputParameters with no volume ramps and a trackID set to the specified track's trackID.
+///
+/// - Parameter track: A reference to an AVAssetTrack.
+ (instancetype)audioMixInputParametersWithTrack:(nullable AVAssetTrack *)track;
-/*
- @method audioMixInputParameters
- @abstract Returns a new instance of AVMutableAudioMixInputParameters with no volume ramps and a trackID initialized to AVAudioMixInputParametersTrackMixID.
-*/
+/// Returns a new instance of AVMutableAudioMixInputParameters with no volume ramps and a trackID initialized to AVAudioMixInputParametersTrackMixID.
+ (instancetype)audioMixInputParameters;
-/*!
- @property trackID
- @abstract Indicates the trackID of the audio track to which the parameters should be applied.
- @discussion
- To apply your input parameters to a mix of all audio tracks rather than to a single specific track, set trackID to AVAudioMixInputParametersTrackMixID.
-*/
+/// Indicates the trackID of the audio track to which the parameters should be applied.
+///
+/// To apply your input parameters to a mix of all audio tracks rather than to a single specific track, set trackID to AVAudioMixInputParametersTrackMixID.
@property (nonatomic) CMPersistentTrackID trackID;
-/*!
- @property audioTimePitchAlgorithm
- @abstract Indicates the processing algorithm used to manage audio pitch at varying rates and for scaled audio edits.
- @discussion
- Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
- Can be nil, in which case the audioTimePitchAlgorithm set on the AVPlayerItem, AVAssetExportSession, or AVAssetReaderAudioMixOutput on which the AVAudioMix is set will be used for the associated track.
-*/
+/// Indicates the processing algorithm used to manage audio pitch at varying rates and for scaled audio edits.
+///
+/// Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
+/// Can be nil, in which case the audioTimePitchAlgorithm set on the AVPlayerItem, AVAssetExportSession, or AVAssetReaderAudioMixOutput on which the AVAudioMix is set will be used for the associated track.
@property (nonatomic, copy, nullable) AVAudioTimePitchAlgorithm audioTimePitchAlgorithm API_AVAILABLE(macos(10.10), ios(7.0), tvos(9.0), watchos(1.0), visionos(1.0));
#if AVF_AUDIO_PROCESSING_TAP_AVAILABLE
-/*!
- @property audioTapProcessor
- @abstract Indicates the audio processing tap that will be used for the audio track or tracks.
- @discussion
- If you wish to tap the mix of audio tracks (i.e. if trackID is equal to AVAudioMixInputParametersTrackMixID), use the function MTAudioProcessingTapCreateWithPreferredFormat to create the instance of MTAudioProcessingTap to set as the value of audioTapProcessor. Created otherwise, the processing format of a tap of a track mix is undefined (but may be observed via the use of your MTAudioProcessingTapPrepareCallback).
-*/
+/// Indicates the audio processing tap that will be used for the audio track or tracks.
+///
+/// If you wish to tap the mix of audio tracks (i.e. if trackID is equal to AVAudioMixInputParametersTrackMixID), use the function MTAudioProcessingTapCreateWithPreferredFormat to create the instance of MTAudioProcessingTap to set as the value of audioTapProcessor. Created otherwise, the processing format of a tap of a track mix is undefined (but may be observed via the use of your MTAudioProcessingTapPrepareCallback).
@property (nonatomic, retain, nullable) __attribute__((NSObject)) MTAudioProcessingTapRef audioTapProcessor API_AVAILABLE(macos(10.9), ios(6.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
#endif
-/*
- @method setVolumeRampFromStartVolume:toEndVolume:timeRange:
- @abstract Sets a volume ramp to apply during the specified timeRange.
- @discussion This method throws an exception if the time range's start or duration is not numeric.
-*/
+/// Sets a volume ramp to apply during the specified timeRange.
+///
+/// This method throws an exception if the time range's start or duration is not numeric.
- (void)setVolumeRampFromStartVolume:(float)startVolume toEndVolume:(float)endVolume timeRange:(CMTimeRange)timeRange;
-/*
- @method setVolume:atTime:
- @abstract Sets the value of the audio volume at a specific time.
- @discussion This method throws an exception if the time is not numeric.
-*/
+/// Sets the value of the audio volume at a specific time.
+///
+/// This method throws an exception if the time is not numeric.
- (void)setVolume:(float)volume atTime:(CMTime)time;
@end
NS_ASSUME_NONNULL_END
-
#else
#import <AVFCore/AVAudioMix.h>
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptionRenderer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptionRenderer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptionRenderer.h 2026-05-29 23:09:27
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptionRenderer.h 2026-06-17 01:03:57
@@ -21,13 +21,9 @@
#pragma mark --- AVCaptionRenderer ---
-/*!
- @class AVCaptionRenderer
- @abstract
- An instance of AVCaptionRenderer represents a service that can render the captions for a particular time
- @discussion
- An instance of AVCaptionRenderer performs drawing of a caption "scene" from a population of captions given a time. If there are no captions or no captions at the specified time, "emptiness" will still be drawn (e.g., flood filling with zero alpha or a color).
- */
+/// An instance of AVCaptionRenderer represents a service that can render the captions for a particular time
+///
+/// An instance of AVCaptionRenderer performs drawing of a caption "scene" from a population of captions given a time. If there are no captions or no captions at the specified time, "emptiness" will still be drawn (e.g., flood filling with zero alpha or a color).
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(12.0), ios(18.0), tvos(26.4), visionos(26.4), macCatalyst(15.0)) API_UNAVAILABLE(watchos)
@interface AVCaptionRenderer : NSObject
@@ -38,45 +34,32 @@
- (instancetype)init API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos);
-/*!
- @property captions
- @abstract
- A NSArray holding captions to consider for rendering.
- @discussion
- This is the array of AVCaptions to consider when drawing. The array can contain no captions.
- */
+/// A NSArray holding captions to consider for rendering.
+///
+/// This is the array of AVCaptions to consider when drawing. The array can contain no captions.
@property (nonatomic, copy) NSArray<AVCaption *> * captions API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos);
-/*!
- @property bounds
- @abstract
- A CGRect holding bounds for the drawing of caption scene(s).
- @discussion
- This is a CGRect indicating where captions are drawn using renderInContext:atTime: Once established, this CGRect is used in each call to renderInContext:atTime: until it is changed to another value. This should be set up earlier than drawing.
- */
+/// A CGRect holding bounds for the drawing of caption scene(s).
+///
+/// This is a CGRect indicating where captions are drawn using renderInContext:atTime: Once established, this CGRect is used in each call to renderInContext:atTime: until it is changed to another value. This should be set up earlier than drawing.
@property (nonatomic) CGRect bounds API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos);
-/*!
- @method captionSceneChangesInRange:
- @abstract Determine render time ranges within an enclosing time range to account for visual changes among captions.
- @result An NSArray of AVCaptionRendererScenes; perhaps empty if there are no captions intersecting with the consideredTimeRange
- @discussion
- This is an optional service useful for optimizing drawing. A client can perform drawing without it.
-
- As captions may become active and inactive throughout the timeline, this method will return a NSArray holding scene objects with time ranges on whose edges there's a visual change. The client can use the ranges of time between these edges with -renderInContext:atTime: to ensure all visual changes are rendered. The returned time ranges consider activation/deactivation of captions, temporal overlapping, and intra-caption timing requirements (e.g., character reveal animations). Time ranges may be returned where no captions are active as this is also a change in the caption "scene".
-
- The returned NSArray contains AVCaptionRendererScenes, each holding the CMTimeRange of that scene but potentially other information that may be useful to the client during renderering.
-
- The consideredTimeRange parameter is a CMTimeRange expressing the limits for consideration. The extent of this range does not need to correspond to the timing of captions. It might be the range from 0 to some duration. For efficiency, the range can be limited to a window of time. It is also possible to use the range anchored at a time and extending in the direction of playback.
- */
+/// Determine render time ranges within an enclosing time range to account for visual changes among captions.
+///
+/// This is an optional service useful for optimizing drawing. A client can perform drawing without it.
+///
+/// As captions may become active and inactive throughout the timeline, this method will return a NSArray holding scene objects with time ranges on whose edges there's a visual change. The client can use the ranges of time between these edges with -renderInContext:atTime: to ensure all visual changes are rendered. The returned time ranges consider activation/deactivation of captions, temporal overlapping, and intra-caption timing requirements (e.g., character reveal animations). Time ranges may be returned where no captions are active as this is also a change in the caption "scene".
+///
+/// The returned NSArray contains AVCaptionRendererScenes, each holding the CMTimeRange of that scene but potentially other information that may be useful to the client during renderering.
+///
+/// The consideredTimeRange parameter is a CMTimeRange expressing the limits for consideration. The extent of this range does not need to correspond to the timing of captions. It might be the range from 0 to some duration. For efficiency, the range can be limited to a window of time. It is also possible to use the range anchored at a time and extending in the direction of playback.
+///
+/// - Returns: An NSArray of AVCaptionRendererScenes; perhaps empty if there are no captions intersecting with the consideredTimeRange
- (NSArray<AVCaptionRendererScene *> *)captionSceneChangesInRange:(CMTimeRange)consideredTimeRange API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos);
-
-/*!
- @method renderInContext:forTime:
- @abstract Draw the captions corresponding to a time established by the AVCaptions to a CGContext.
- @discussion Captions are drawn into the CGContextRef based upon their activation at the specified time. If there are no captions or no captions at the specified time, "emptiness" will still be drawn (e.g., flood filling with zero alpha or a color).
- */
+/// Draw the captions corresponding to a time established by the AVCaptions to a CGContext.
+///
+/// Captions are drawn into the CGContextRef based upon their activation at the specified time. If there are no captions or no captions at the specified time, "emptiness" will still be drawn (e.g., flood filling with zero alpha or a color).
- (void)renderInContext:(CGContextRef)ctx forTime:(CMTime)time API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos);
@end
@@ -86,19 +69,17 @@
API_AVAILABLE(macos(26.4), ios(26.4), tvos(26.4), visionos(26.4)) API_UNAVAILABLE(watchos)
@interface AVCaptionRenderer (AVCaptionRenderer_CaptionPreview)
-/*!
- @method captionPreviewForProfileID:extendedLanguageTag:renderSize:
- @abstract Generate a caption preview attributed string for the specified profile ID.
- @discussion Returns an attributed string containing a preview of captions rendered using the specified profile ID.
- @param profileID
- The identifier of the accessibility profile to use for caption appearance. Profile IDs can be obtained from MACaptionAppearanceCopyProfileIDs(). This determines font, color, background, and other visual characteristics.
- @param extendedLanguageTag
- The IETF BCP 47 (RFC 4646) language identifier that will be used to generate the localized caption preview text. If nil, the system language will be used.
- @param renderSize
- The size of the layer into which the captions will be rendered. This determines the layout and positioning of the caption text.
- @result An NSAttributedString containing the caption preview.
- @discussion It is strongly recommended that the caller take appropriate measures to prevent blocking essential services such as the user interface, for example, by avoiding calling this method in the main thread.
- */
+/// Generate a caption preview attributed string for the specified profile ID.
+///
+/// Returns an attributed string containing a preview of captions rendered using the specified profile ID.
+///
+/// - Important: It is strongly recommended that the caller take appropriate measures to prevent blocking essential services such as the user interface, for example, by avoiding calling this method in the main thread.
+///
+/// - Parameter profileID: The identifier of the accessibility profile to use for caption appearance. Profile IDs can be obtained from MACaptionAppearanceCopyProfileIDs(). This determines font, color, background, and other visual characteristics.
+/// - Parameter extendedLanguageTag: The IETF BCP 47 (RFC 4646) language identifier that will be used to generate the localized caption preview text. If nil, the system language will be used.
+/// - Parameter renderSize: The size of the layer into which the captions will be rendered. This determines the layout and positioning of the caption text.
+///
+/// - Returns: An NSAttributedString containing the caption preview.
+ (NSAttributedString *)captionPreviewForProfileID:(NSString *)profileID extendedLanguageTag:(nullable NSString *)extendedLanguageTag renderSize:(CGSize)renderSize;
@end
@@ -107,17 +88,13 @@
@class AVCaptionRendererSceneInternal;
-/*!
- @class AVCaptionRendererScene
- @abstract
- An instance of AVCaptionRendererScene holds a time range and associated state indicating when the AVCaptionRenderer will draw different output.
- @discussion
- In rendering the timeline established by the captions referenced by an AVCaptionRenderer, there are considerations such as temporal overlapping of captions, the existence of captions and other graphical elements like regions, and whether captions may be animated (e.g., scrolling in regions, character reveal in a caption). To communicate to the AVCaptionRenderer client the minimal set of time ranges where there are any visual differences, AVCaptionRendererScenes can be requested from -[AVCaptionRenderer captionSceneChangesInRange:]. A client wanting to optimize drawing performance may use this timing information to draw scenes only once per scene. Alternatively, clients can ignore scenes and repeatedly call renderInContext:atTime: but this may have additional performance impact.
-
- Other information about the rendering of a caption scene can be communicated through the AVCaptionRendererScene. For example, if captions are animated, an AVCaptionRendererScene with the time range and an indication of the animation occurring will be returned. There should be no inference from the number of scenes to the number of captions. Even a single caption with internal animations in part of its duration could result in multiple AVCaptionRendererScenes being produced.
-
- Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
- */
+/// An instance of AVCaptionRendererScene holds a time range and associated state indicating when the AVCaptionRenderer will draw different output.
+///
+/// In rendering the timeline established by the captions referenced by an AVCaptionRenderer, there are considerations such as temporal overlapping of captions, the existence of captions and other graphical elements like regions, and whether captions may be animated (e.g., scrolling in regions, character reveal in a caption). To communicate to the AVCaptionRenderer client the minimal set of time ranges where there are any visual differences, AVCaptionRendererScenes can be requested from -[AVCaptionRenderer captionSceneChangesInRange:]. A client wanting to optimize drawing performance may use this timing information to draw scenes only once per scene. Alternatively, clients can ignore scenes and repeatedly call renderInContext:atTime: but this may have additional performance impact.
+///
+/// Other information about the rendering of a caption scene can be communicated through the AVCaptionRendererScene. For example, if captions are animated, an AVCaptionRendererScene with the time range and an indication of the animation occurring will be returned. There should be no inference from the number of scenes to the number of captions. Even a single caption with internal animations in part of its duration could result in multiple AVCaptionRendererScenes being produced.
+///
+/// Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
NS_SWIFT_SENDABLE
API_AVAILABLE(macos(12.0), ios(18.0), macCatalyst(15.0)) API_UNAVAILABLE(tvos, watchos, visionos)
@interface AVCaptionRendererScene : NSObject <NSCopying>
@@ -127,29 +104,17 @@
}
AV_INIT_UNAVAILABLE
-/*!
- @property timeRange
- @abstract
- The time range during which new captions will not be introduced into or existing captions will be retired from the caption scene
- */
+/// The time range during which new captions will not be introduced into or existing captions will be retired from the caption scene
@property (nonatomic, readonly) CMTimeRange timeRange;
-/*!
- @property hasActiveCaptions
- @abstract
- The scene contains one or more active captions.
- @discussion
- Clients should not use this to restrict their drawing and should call renderInContext:atTime: to draw "emptiness". However, this information may be useful for purposes such as scrubbing to times where captions are present, skipping scenes in which no captions are present.
- */
+/// The scene contains one or more active captions.
+///
+/// Clients should not use this to restrict their drawing and should call renderInContext:atTime: to draw "emptiness". However, this information may be useful for purposes such as scrubbing to times where captions are present, skipping scenes in which no captions are present.
@property (nonatomic, readonly) BOOL hasActiveCaptions;
-/*!
- @property needsPeriodicRefresh
- @abstract
- The scene may have embedded animations or other state where periodic redrawing while playing through this scene is needed.
- @discussion
- This property indicates if refreshing should occur if the client is progressing through the content. If the client is not progressing (i.e., it is treating playback as though the rate is 0.0), a single render at the current render time suffices. This property does not prescribe a refresh rate. A client is free to choose a refresh rate corresponding to rates of associated video frames or other timing appropriate for the client.
- */
+/// The scene may have embedded animations or other state where periodic redrawing while playing through this scene is needed.
+///
+/// This property indicates if refreshing should occur if the client is progressing through the content. If the client is not progressing (i.e., it is treating playback as though the rate is 0.0), a single render at the current render time suffices. This property does not prescribe a refresh rate. A client is free to choose a refresh rate corresponding to rates of associated video frames or other timing appropriate for the client.
@property (nonatomic, readonly) BOOL needsPeriodicRefresh;
@end
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureDevice.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureDevice.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureDevice.h 2026-05-23 02:15:50
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureDevice.h 2026-06-18 01:34:24
@@ -52,6 +52,18 @@
+/// Constants indicating video orientation, for use with AVCaptureDeviceRotationCoordinator.
+typedef NS_ENUM(NSInteger, AVCaptureVideoOrientation) {
+ /// Indicates that video should be oriented vertically, port on the bottom.
+ AVCaptureVideoOrientationPortrait = 1,
+ /// Indicates that video should be oriented vertically, port on the top.
+ AVCaptureVideoOrientationPortraitUpsideDown = 2,
+ /// Indicates that video should be oriented horizontally, port on the right.
+ AVCaptureVideoOrientationLandscapeRight = 3,
+ /// Indicates that video should be oriented horizontally, port on the left.
+ AVCaptureVideoOrientationLandscapeLeft = 4,
+} API_AVAILABLE(ios(4.0)) API_DEPRECATED("Use AVCaptureDeviceRotationCoordinator instead", macos(10.7, 14.0), macCatalyst(14.0, 17.0)) API_UNAVAILABLE(tvos, visionos) API_UNAVAILABLE(watchos);
+
#pragma mark - AVCaptureDevice
@class AVCaptureDeviceFormat;
@@ -393,6 +405,11 @@
/// Use this property as the minimum allowable frame duration to pass to ``AVCaptureDeviceInput/follow:externalSyncDevice:videoFrameDuration:delegate:`` when you want to follow an external sync device. This property returns `kCMTimeInvalid` when the device's' current configuration does not support external sync device following.
@property(nonatomic, readonly) CMTime minSupportedExternalSyncFrameDuration API_AVAILABLE(macos(26.0), ios(26.0), macCatalyst(26.0), tvos(26.0)) API_UNAVAILABLE(visionos) API_UNAVAILABLE(watchos);
+/// Whether adjusting the signal compensation delay property of an external sync device is supported while the session is running.
+///
+/// This property returns `true` if the ``signalCompensationDelay`` of an ``AVExternalSyncDevice`` being followed by this device's ``AVCaptureDeviceInput`` can be adjusted while the ``AVCaptureSession`` is running.
+@property(nonatomic, readonly, getter=isAdjustingSignalCompensationDelayWhileRunningSupported) BOOL adjustingSignalCompensationDelayWhileRunningSupported API_AVAILABLE(macos(27.0), ios(27.0), macCatalyst(27.0), tvos(27.0)) API_UNAVAILABLE(visionos) API_UNAVAILABLE(watchos);
+
/// Indicates whether the receiver should enable auto video frame rate.
///
/// When you enable this property, the device automatically adjusts the active frame rate, depending on light level. Under low light conditions, it decreases the frame rate to properly expose the scene. For formats with a maximum frame rate of 30 fps, the device switches the frame rate between 30 - 24. For formats with a maximum frame rate of 60 fps, the device switches the frame rate between 60 - 30 - 24.
@@ -593,6 +610,7 @@
*/
AVF_EXPORT AVCaptureDeviceType const AVCaptureDeviceTypeDeskViewCamera API_AVAILABLE(macos(13.0)) API_UNAVAILABLE(ios, macCatalyst, tvos, visionos) API_UNAVAILABLE(watchos);
+
/*!
@constant AVCaptureDeviceTypeExternalUnknown
A deprecated synonym for AVCaptureDeviceTypeExternal. Please use AVCaptureDeviceTypeExternal instead.
@@ -2946,6 +2964,16 @@
The video rotation angle represents by how much the photos or movies captured from the camera should be rotated to be horizon-level relative to gravity. A video rotation angle of 0 degrees means that the output will be in the camera's unrotated, native sensor orientation. The video rotation angle for capture may differ between cameras. For example when an iOS device is held in portrait orientation, photos and movies captured from built-in cameras may need to be rotated by 90 degrees while the photos and movies from an external camera should not be rotated. External cameras return 0 degrees of rotation even if they physically rotate when their position in physical space is unknown. The video rotation angle returned from this property is distinct from the angle returned by -videoRotationAngleForHorizonLevelPreview because in certain combinations of device and interface orientations, the video rotation angle needed for horizon-level preview may not match the amount of rotation needed for horizon-level capture. This property is key-value observable and delivers updates on the main queue.
*/
@property(nonatomic, readonly) CGFloat videoRotationAngleForHorizonLevelCapture;
+
+
+/// Returns a video rotation angle in degrees from this camera relative to the provided orientation.
+///
+/// - Parameter orientation: Specify the device orientation, represented with the ``AVCaptureVideoOrientation`` enum.
+///
+/// The returned video rotation angle represents the amount by which photos or movies captured from the camera should be rotated to be upright relative to the provided orientation. A returned video rotation angle of 0 degrees means that the output will be in the camera's unrotated, native sensor orientation. The returned video rotation angle for an orientation may differ between cameras. For example, some cameras are upright when the device is held with the port on the bottom, while others are upright when holding the device with the port on the left or right. External cameras return 0 degrees for all given video orientations because the relationship between the device and the camera is unknown.
+///
+/// The angle returned from this property is distinct from the angles returned by -videoRotationAngleForHorizonLevelCapture and -videoRotationAngleForHorizonLevelPreview because those return angles relative to the horizon which change dynamically as the device is physically rotated, while this returns the static angle relative to the provided orientation regardless of how the device is physically oriented at the time this method is called.
+- (CGFloat)videoRotationAngleRelativeToDeviceOrientation:(AVCaptureVideoOrientation)deviceOrientation API_AVAILABLE(ios(27.0)) API_UNAVAILABLE(macos, macCatalyst, tvos, visionos, watchos);
@end
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureSession.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureSession.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureSession.h 2026-05-29 23:20:12
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureSession.h 2026-06-18 00:51:50
@@ -115,27 +115,6 @@
*/
AVF_EXPORT NSNotificationName const AVCaptureSessionInterruptionEndedNotification NS_SWIFT_NAME(AVCaptureSession.interruptionEndedNotification) API_AVAILABLE(macos(10.14), ios(4.0), macCatalyst(14.0), tvos(17.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @enum AVCaptureVideoOrientation
- @abstract
- Constants indicating video orientation, for use with AVCaptureVideoPreviewLayer (see AVCaptureVideoPreviewLayer.h) and AVCaptureConnection (see below).
-
- @constant AVCaptureVideoOrientationPortrait
- Indicates that video should be oriented vertically, home button on the bottom.
- @constant AVCaptureVideoOrientationPortraitUpsideDown
- Indicates that video should be oriented vertically, home button on the top.
- @constant AVCaptureVideoOrientationLandscapeRight
- Indicates that video should be oriented horizontally, home button on the right.
- @constant AVCaptureVideoOrientationLandscapeLeft
- Indicates that video should be oriented horizontally, home button on the left.
- */
-typedef NS_ENUM(NSInteger, AVCaptureVideoOrientation) {
- AVCaptureVideoOrientationPortrait = 1,
- AVCaptureVideoOrientationPortraitUpsideDown = 2,
- AVCaptureVideoOrientationLandscapeRight = 3,
- AVCaptureVideoOrientationLandscapeLeft = 4,
-} API_DEPRECATED("Use AVCaptureDeviceRotationCoordinator instead", macos(10.7, 14.0), ios(4.0, 17.0), macCatalyst(14.0, 17.0)) API_UNAVAILABLE(tvos, visionos) API_UNAVAILABLE(watchos);
-
#pragma mark - AVCaptureSession
@class AVCaptureInput;
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureVideoPreviewLayer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureVideoPreviewLayer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureVideoPreviewLayer.h 2026-05-29 23:16:13
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVCaptureVideoPreviewLayer.h 2026-06-18 00:52:56
@@ -225,7 +225,7 @@
Specifies the orientation of the preview layer.
@discussion
- AVCaptureVideoOrientation and its constants are defined in AVCaptureSession.h. The value of @"orientationSupported" must be YES in order to set @"orientation". An exception will be raised if this requirement is ignored. This property is deprecated. Use AVCaptureConnection's -videoOrientation instead.
+ AVCaptureVideoOrientation and its constants are defined in AVCaptureDevice.h. The value of @"orientationSupported" must be YES in order to set @"orientation". An exception will be raised if this requirement is ignored. This property is deprecated. Use AVCaptureConnection's -videoOrientation instead.
*/
@property(nonatomic) AVCaptureVideoOrientation orientation API_DEPRECATED("Use AVCaptureConnection's videoOrientation instead.", ios(4.0, 6.0)) API_UNAVAILABLE(macos, visionos) API_UNAVAILABLE(tvos);
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVExternalSyncDevice.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVExternalSyncDevice.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVExternalSyncDevice.h 2026-05-23 01:43:47
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVExternalSyncDevice.h 2026-06-18 01:37:32
@@ -46,9 +46,20 @@
/// This property returns `NULL` until the ``status`` reaches ``AVExternalSyncDeviceStatusActiveSync``.
@property(nonatomic, readonly, nullable) __attribute__((NSObject)) CMClockRef clock;
+/// Whether adjusting the signal compensation delay property is currently supported.
+///
+/// This property returns `true` if the ``signalCompensationDelay`` can be adjusted.
+///
+/// ``signalCompensationDelay`` can be adjusted while the ``AVCaptureSession`` is not running.
+///
+/// Once the session is running, this property's value depends on ``AVCaptureDevice/isAdjustingSignalCompensationDelayWhileRunningSupported`` of the ``AVCaptureDevice`` backing the ``AVCaptureDeviceInput`` that is following this external sync device. Inspect that property in advance to determine whether ``signalCompensationDelay`` will remain adjustable while running on a given device.
+@property(nonatomic, readonly, getter=isSignalCompensationDelaySupported) BOOL signalCompensationDelaySupported API_AVAILABLE(macos(27.0), ios(27.0), macCatalyst(27.0), tvos(27.0)) API_UNAVAILABLE(visionos) API_UNAVAILABLE(watchos);
+
/// Delay to wait before starting the frame capture.
///
/// An external sync is generally used to configure multiple devices in the real world. A display and a camera may receive a signal at the same time, but that does not mean the refresh of the display and camera are aligned in a way that does not cause tearing in the recording. The signal compensation delay can be used to offset the readout of a camera on an intra-frame scale.
+///
+/// Setting this property throws an NSInvalidArgumentException if called when ``AVExternalSyncDevice/isSignalCompensationDelaySupported`` returns NO.
///
/// - Important: You should always set this property to a value less than the frame duration at which the camera is operating.
@property(nonatomic) CMTime signalCompensationDelay;
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVMovie.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVMovie.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVMovie.h 2026-05-27 01:19:12
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVMovie.h 2026-06-17 00:58:25
@@ -16,36 +16,12 @@
NS_ASSUME_NONNULL_BEGIN
-/*!
- @class AVMovie
- @abstract AVMovie represents the audiovisual containers in a file that conforms to the QuickTime movie file format or to one of the related ISO base media file formats (such as MPEG-4).
-
- @discussion AVMovie supports operations involving the format-specific portions of the QuickTime Movie model that are not supported by AVAsset. For instance, you can retrieve the movie header from an existing QuickTime movie file. You can also use AVMovie to write a movie header into a new file, thereby creating a reference movie.
-
- A mutable subclass of AVMovie, AVMutableMovie, provides methods that support the familiar Movie editing model; for instance, you can use AVMutableMovie to copy media data from one track and paste that data into another track. You can also use AVMutableMovie to establish track references from one track to another (for example, to set one track as a chapter track of another track). If you want to perform editing operations on individual tracks, you can use the associated classes AVMovieTrack and AVMutableMovieTrack.
-
- You need to use AVMovie and AVMutableMovie only when operating on format-specific features of a QuickTime or ISO base media file. You generally do not need to use these classes just to open and play QuickTime movie files or ISO base media files. Instead, you can use the classes AVURLAsset and AVPlayerItem. If however you already have an AVMutableMovie and want to play it or inspect it, you can make an immutable snapshot of the AVMutableMovie like this:
-
- // myMutableMovie is of type AVMutableMovie; the client wants to inspect and play it in its current state
- AVMovie *immutableSnapshotOfMyMovie = [myMutableMovie copy];
- AVPlayerItem *playerItemForSnapshotOfMovie = [[AVPlayerItem alloc] initWithAsset:immutableSnapshotOfMyMovie];
-
- When performing media insertions, AVMutableMovie interleaves the media data from the tracks in the source asset in order to create movie files that are optimized for playback. It's possible, however, that performing a series of media insertions may result in a movie file that is not optimally interleaved. You can create a well-interleaved, self-contained, fast-start movie file from an instance of AVMutableMovie by passing that instance to an AVAssetExportSession using the export preset AVAssetExportPresetPassthrough and setting the setShouldOptimizeForNetworkUse property to YES.
-
- AVMovie conforms to NSMutableCopying, but creating a mutable copy of a movie can cause its properties to be loaded synchronously. This can cause the calling thread to block while synchronous I/O is performed. To avoid the worst side-effects of blocking, such as user interface hangs, avoid making a mutable copy from the main thread or from a thread owned by Swift's concurrency thread pool.
-
-*/
-
// Keys for options dictionary for use with various AVMovie initialization methods
-/*!
- @constant AVMovieReferenceRestrictionsKey
- @abstract
- Indicates the restrictions used by the movie when resolving references to external media data. The value of this key is an NSNumber wrapping an AVAssetReferenceRestrictions enum value or the logical combination of multiple such values. See AVAsset.h for the declaration of the AVAssetReferenceRestrictions enum.
- @discussion
- Some movies can contain references to media data stored outside the movie's container, for example in another file. This key can be used to specify a policy to use when these references are encountered. If a movie contains one or more references of a type that is forbidden by the reference restrictions, loading of movie properties will fail. In addition, such a movie cannot be used with other AVFoundation modules, such as AVPlayerItem or AVAssetExportSession.
-*/
+/// Indicates the restrictions used by the movie when resolving references to external media data. The value of this key is an NSNumber wrapping an AVAssetReferenceRestrictions enum value or the logical combination of multiple such values. See AVAsset.h for the declaration of the AVAssetReferenceRestrictions enum.
+///
+/// Some movies can contain references to media data stored outside the movie's container, for example in another file. This key can be used to specify a policy to use when these references are encountered. If a movie contains one or more references of a type that is forbidden by the reference restrictions, loading of movie properties will fail. In addition, such a movie cannot be used with other AVFoundation modules, such as AVPlayerItem or AVAssetExportSession.
AVF_EXPORT NSString *const AVMovieReferenceRestrictionsKey API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
@class AVMovieInternal;
@@ -53,6 +29,21 @@
@class AVMetadataItem;
#pragma mark --- AVMovie ---
+/// AVMovie represents the audiovisual containers in a file that conforms to the QuickTime movie file format or to one of the related ISO base media file formats (such as MPEG-4).
+///
+/// AVMovie supports operations involving the format-specific portions of the QuickTime Movie model that are not supported by AVAsset. For instance, you can retrieve the movie header from an existing QuickTime movie file. You can also use AVMovie to write a movie header into a new file, thereby creating a reference movie.
+///
+/// A mutable subclass of AVMovie, AVMutableMovie, provides methods that support the familiar Movie editing model; for instance, you can use AVMutableMovie to copy media data from one track and paste that data into another track. You can also use AVMutableMovie to establish track references from one track to another (for example, to set one track as a chapter track of another track). If you want to perform editing operations on individual tracks, you can use the associated classes AVMovieTrack and AVMutableMovieTrack.
+///
+/// You need to use AVMovie and AVMutableMovie only when operating on format-specific features of a QuickTime or ISO base media file. You generally do not need to use these classes just to open and play QuickTime movie files or ISO base media files. Instead, you can use the classes AVURLAsset and AVPlayerItem. If however you already have an AVMutableMovie and want to play it or inspect it, you can make an immutable snapshot of the AVMutableMovie like this:
+///
+/// // myMutableMovie is of type AVMutableMovie; the client wants to inspect and play it in its current state
+/// AVMovie *immutableSnapshotOfMyMovie = [myMutableMovie copy];
+/// AVPlayerItem *playerItemForSnapshotOfMovie = [[AVPlayerItem alloc] initWithAsset:immutableSnapshotOfMyMovie];
+///
+/// When performing media insertions, AVMutableMovie interleaves the media data from the tracks in the source asset in order to create movie files that are optimized for playback. It's possible, however, that performing a series of media insertions may result in a movie file that is not optimally interleaved. You can create a well-interleaved, self-contained, fast-start movie file from an instance of AVMutableMovie by passing that instance to an AVAssetExportSession using the export preset AVAssetExportPresetPassthrough and setting the setShouldOptimizeForNetworkUse property to YES.
+///
+/// AVMovie conforms to NSMutableCopying, but creating a mutable copy of a movie can cause its properties to be loaded synchronously. This can cause the calling thread to block while synchronous I/O is performed. To avoid the worst side-effects of blocking, such as user interface hangs, avoid making a mutable copy from the main thread or from a thread owned by Swift's concurrency thread pool.
API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMovie : AVAsset <NSCopying, NSMutableCopying>
{
@@ -60,174 +51,135 @@
AVMovieInternal *_movie;
}
-/*!
- @method movieTypes
- @abstract Provides the file types the AVMovie class understands.
- @result An NSArray of UTIs identifying the file types the AVMovie class understands.
-*/
+/// Provides the file types the AVMovie class understands.
+///
+/// - Returns: An NSArray of UTIs identifying the file types the AVMovie class understands.
+ (NSArray<AVFileType> *)movieTypes;
-/*!
- @method movieWithURL:options:
- @abstract Creates an AVMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
- @param URL
- An NSURL object that specifies a file containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
- @result An AVMovie object
- @discussion By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
- to indicate where the sample data should be written.
-*/
+/// Creates an AVMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
+/// to indicate where the sample data should be written.
+///
+/// - Parameter URL: An NSURL object that specifies a file containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
+///
+/// - Returns: An AVMovie object
+ (instancetype)movieWithURL:(NSURL *)URL options:(nullable NSDictionary<NSString *, id> *)options;
-/*!
- @method initWithURL:options:
- @abstract Creates an AVMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
- @param URL
- An NSURL object that specifies a file containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
- @result An AVMovie object
- @discussion By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
- to indicate where the sample data should be written.
-*/
+/// Creates an AVMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
+/// to indicate where the sample data should be written.
+///
+/// - Parameter URL: An NSURL object that specifies a file containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
+///
+/// - Returns: An AVMovie object
- (instancetype)initWithURL:(NSURL *)URL options:(nullable NSDictionary<NSString *, id> *)options NS_DESIGNATED_INITIALIZER;
-/*!
- @method movieWithData:options:
- @abstract Creates an AVMovie object from a movie header stored in an NSData object.
- @param data
- An NSData object containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
- @result An AVMovie object
- @discussion You can use this method to operate on movie headers that are not stored in files; this might include movie headers on the pasteboard (which do not contain media data). In general you should avoid loading an entire movie file with its media data into an instance of NSData! By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMovie object from a movie header stored in an NSData object.
+///
+/// You can use this method to operate on movie headers that are not stored in files; this might include movie headers on the pasteboard (which do not contain media data). In general you should avoid loading an entire movie file with its media data into an instance of NSData! By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter data: An NSData object containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
+///
+/// - Returns: An AVMovie object
+ (instancetype)movieWithData:(NSData *)data options:(nullable NSDictionary<NSString *, id> *)options API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @method initWithData:options:
- @abstract Creates an AVMovie object from a movie header stored in an NSData object.
- @param data
- An NSData object containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
- @result An AVMovie object
- @discussion You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
-
- By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMovie object from a movie header stored in an NSData object.
+///
+/// You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter data: An NSData object containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMovie object.
+///
+/// - Returns: An AVMovie object
- (instancetype)initWithData:(NSData *)data options:(nullable NSDictionary<NSString *, id> *)options NS_DESIGNATED_INITIALIZER API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
#pragma mark --- Keys for initialization options dictionary ---
-/*!
- @constant AVMovieShouldSupportAliasDataReferencesKey
- @abstract Indicates whether alias data references in the movie should be parsed and resolved.
- @discussion
- Default is NO. Although the majority of QuickTime movie files contain all of the media data they require, some contain references to media stored in other files. While AVFoundation and CoreMedia typically employ a URL reference for this purpose, older implementations such as QuickTime 7 have commonly employed a Macintosh alias instead, as documented in the QuickTime File Format specification. If your application must work with legacy QuickTime movie files containing alias-based references to media data stored in other files, the use of this AVMovie initialization option is appropriate. AVMovie and AVMutableMovie do not create movies using alias data references to external media files.
-
- If you provide a value for AVMovieReferenceRestrictionsKey, restrictions will be observed for resolved alias references just as they are for URL references.
-
- For more details about alias resolution, consult documentation of the bookmark-related interfaces of NSURL.
-*/
+
+/// Indicates whether alias data references in the movie should be parsed and resolved.
+///
+/// Default is NO. Although the majority of QuickTime movie files contain all of the media data they require, some contain references to media stored in other files. While AVFoundation and CoreMedia typically employ a URL reference for this purpose, older implementations such as QuickTime 7 have commonly employed a Macintosh alias instead, as documented in the QuickTime File Format specification. If your application must work with legacy QuickTime movie files containing alias-based references to media data stored in other files, the use of this AVMovie initialization option is appropriate. AVMovie and AVMutableMovie do not create movies using alias data references to external media files.
+///
+/// If you provide a value for AVMovieReferenceRestrictionsKey, restrictions will be observed for resolved alias references just as they are for URL references.
+///
+/// For more details about alias resolution, consult documentation of the bookmark-related interfaces of NSURL.
AVF_EXPORT NSString *const AVMovieShouldSupportAliasDataReferencesKey API_AVAILABLE(macos(10.12)) API_DEPRECATED("AVMovieShouldSupportAliasDataReferencesKey is not supported on this platform", ios(13.0, 27.0), watchos(6.0, 27.0), visionos(1.0, 27.0)) API_UNAVAILABLE(tvos);
-/*!
- @property URL
- @abstract The URL with which the instance of AVMovie was initialized; may be nil.
-*/
+/// The URL with which the instance of AVMovie was initialized; may be nil.
@property (nonatomic, readonly, nullable) NSURL *URL;
-/*!
- @property data
- @abstract The data block with which the instance of AVMovie was initialized; may be nil.
-*/
+/// The data block with which the instance of AVMovie was initialized; may be nil.
@property (nonatomic, readonly, nullable) NSData *data API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @property defaultMediaDataStorage
- @abstract The default storage container for media data added to a movie.
- @discussion The value of this property is an AVMediaDataStorage object that indicates where sample data that is added to a movie should be written by default.
-*/
+/// The default storage container for media data added to a movie.
+///
+/// The value of this property is an AVMediaDataStorage object that indicates where sample data that is added to a movie should be written by default.
@property (nonatomic, readonly, nullable) AVMediaDataStorage *defaultMediaDataStorage API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @property tracks
- @abstract The tracks in a movie.
- @discussion The value of this property is an array of tracks the movie contains; the tracks are of type AVMovieTrack.
-*/
+/// The tracks in a movie.
+///
+/// The value of this property is an array of tracks the movie contains; the tracks are of type AVMovieTrack.
@property (nonatomic, readonly) NSArray<AVMovieTrack *> *tracks;
-/*!
- @property canContainMovieFragments
- @abstract Indicates whether the movie file is capable of being extended by fragments.
- @discussion The value of this property is YES if an 'mvex' box is present in the 'moov' box. The 'mvex' box is necessary in order to signal the possible presence of later 'moof' boxes.
-*/
+/// Indicates whether the movie file is capable of being extended by fragments.
+///
+/// The value of this property is YES if an 'mvex' box is present in the 'moov' box. The 'mvex' box is necessary in order to signal the possible presence of later 'moof' boxes.
@property (nonatomic, readonly) BOOL canContainMovieFragments;
-/*!
- @property containsMovieFragments
- @abstract Indicates whether the movie file is extended by at least one movie fragment.
- @discussion The value of this property is YES if canContainMovieFragments is YES and at least one 'moof' box is present after the 'moov' box.
-*/
+/// Indicates whether the movie file is extended by at least one movie fragment.
+///
+/// The value of this property is YES if canContainMovieFragments is YES and at least one 'moof' box is present after the 'moov' box.
@property (nonatomic, readonly) BOOL containsMovieFragments API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
@end
-/*!
- @enum AVMovieWritingOptions
- @abstract These options can be passed into writeMovieHeaderToURL:fileType:options:error: to control the writing of a movie header to a destination URL.
- @constant AVMovieWritingAddMovieHeaderToDestination
- Writing the movie header will remove any existing movie header in the destination file and add a new movie header, preserving any other data in the file. If the destination file was empty, a file type box will be written at the beginning of the file.
- @constant AVMovieWritingTruncateDestinationToMovieHeaderOnly
- If set, writing the movie header will truncate all existing data in the destination file and write a new movie header, thereby creating a pure reference movie file. A file type box will be written at the beginning of the file.
- @discussion You would not want to use the AVMovieWritingTruncateDestinationToMovieHeaderOnly option if you had written sample data to the destination file using (for example) -[AVMutableMovie insertTimeRange:ofAsset:atTime:copySampleData:error:] with copySampleData set to YES, since that data would be lost.
- */
+/// These options can be passed into writeMovieHeaderToURL:fileType:options:error: to control the writing of a movie header to a destination URL.
+///
+/// You would not want to use the AVMovieWritingTruncateDestinationToMovieHeaderOnly option if you had written sample data to the destination file using (for example) -[AVMutableMovie insertTimeRange:ofAsset:atTime:copySampleData:error:] with copySampleData set to YES, since that data would be lost.
typedef NS_OPTIONS(NSUInteger, AVMovieWritingOptions) {
+ /// Writing the movie header will remove any existing movie header in the destination file and add a new movie header, preserving any other data in the file. If the destination file was empty, a file type box will be written at the beginning of the file.
AVMovieWritingAddMovieHeaderToDestination = 0,
+ /// If set, writing the movie header will truncate all existing data in the destination file and write a new movie header, thereby creating a pure reference movie file. A file type box will be written at the beginning of the file.
AVMovieWritingTruncateDestinationToMovieHeaderOnly = (1UL << 0)
} API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMovie (AVMovieMovieHeaderSupport)
-/*!
- @method movieHeaderWithFileType:error:
- @abstract Creates an NSData object containing the movie header of the AVMovie object.
- @param fileType
- A UTI indicating the specific file format of the movie header (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
- @param outError
- If an error occurs reading the movie header, describes the nature of the failure.
- @result An NSData object.
- @discussion The movie header will be a pure reference movie, with no base URL, suitable for use on the pasteboard.
-*/
+/// Creates an NSData object containing the movie header of the AVMovie object.
+///
+/// The movie header will be a pure reference movie, with no base URL, suitable for use on the pasteboard.
+///
+/// - Parameter fileType: A UTI indicating the specific file format of the movie header (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
+/// - Parameter outError: If an error occurs reading the movie header, describes the nature of the failure.
+///
+/// - Returns: An NSData object.
- (nullable NSData *)movieHeaderWithFileType:(AVFileType)fileType error:(NSError * _Nullable * _Nullable)outError API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @method writeMovieHeaderToURL:fileType:options:error:
- @abstract Writes the movie header to a destination URL.
- @param URL
- An NSURL object indicating where to write the movie header.
- @param fileType
- A UTI indicating the specific file format (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
- @param options
- An NSUInteger whose bits specify options for the writing of the movie header. See AVMovieWritingOptions above.
- @param outError
- If an error occurs writing the movie header, describes the nature of the failure.
- @discussion Note that modifications to instances of AVMutableMovie, to their constituent AVMutableMovieTracks, or to their collections of metadata are committed to storage when their movie headers are written.
-*/
+/// Writes the movie header to a destination URL.
+///
+/// Note that modifications to instances of AVMutableMovie, to their constituent AVMutableMovieTracks, or to their collections of metadata are committed to storage when their movie headers are written.
+///
+/// - Parameter URL: An NSURL object indicating where to write the movie header.
+/// - Parameter fileType: A UTI indicating the specific file format (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
+/// - Parameter options: An NSUInteger whose bits specify options for the writing of the movie header. See AVMovieWritingOptions above.
+/// - Parameter outError: If an error occurs writing the movie header, describes the nature of the failure.
- (BOOL)writeMovieHeaderToURL:(NSURL *)URL fileType:(AVFileType)fileType options:(AVMovieWritingOptions)options error:(NSError * _Nullable * _Nullable)outError API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @method isCompatibleWithFileType:
- @abstract Indicates whether a movie header for the AVMovie object can be created for the specified file type.
- @param fileType
- A UTI indicating a movie file format (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
- @discussion This method returns a BOOL that indicates whether a movie header of the specified type can be created for the receiver. For example, this method returns NO if the movie contains tracks whose media types or media subtypes are not allowed by the specified file type.
-*/
+/// Indicates whether a movie header for the AVMovie object can be created for the specified file type.
+///
+/// This method returns a BOOL that indicates whether a movie header of the specified type can be created for the receiver. For example, this method returns NO if the movie contains tracks whose media types or media subtypes are not allowed by the specified file type.
+///
+/// - Parameter fileType: A UTI indicating a movie file format (e.g. AVFileTypeQuickTimeMovie for a QuickTime movie).
- (BOOL)isCompatibleWithFileType:(AVFileType)fileType API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
@end
@@ -235,14 +187,13 @@
API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMovie (AVMovieTrackInspection)
-/*!
- @method trackWithTrackID:
- @abstract Provides an instance of AVMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVMovieTrack.
- @result An instance of AVMovieTrack; may be nil if no track of the specified trackID is available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an instance of AVMovieTrack that represents the track of the specified trackID.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter trackID: The trackID of the requested AVMovieTrack.
+///
+/// - Returns: An instance of AVMovieTrack; may be nil if no track of the specified trackID is available.
- (nullable AVMovieTrack *)trackWithTrackID:(CMPersistentTrackID)trackID
#if __swift__
API_DEPRECATED("Use loadTrack(withTrackID:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -250,24 +201,19 @@
API_DEPRECATED("Use loadTrackWithTrackID:completionHandler: instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTrackWithTrackID:completionHandler:
- @abstract Loads an instance of AVMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVMovieTrack.
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
-*/
+/// Loads an instance of AVMovieTrack that represents the track of the specified trackID.
+///
+/// - Parameter trackID: The trackID of the requested AVMovieTrack.
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
- (void)loadTrackWithTrackID:(CMPersistentTrackID)trackID completionHandler:(void (^ NS_SWIFT_SENDABLE)(AVMovieTrack * _Nullable_result, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaType:
- @abstract Provides an array of AVMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which the receiver filters its AVMovieTracks. (Media types are defined in AVMediaFormat.h)
- @result An NSArray of AVMovieTracks; may be empty if no tracks of the specified media type are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVMovieTracks of the asset that present media of the specified media type.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaType: The media type according to which the receiver filters its AVMovieTracks. (Media types are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVMovieTracks; may be empty if no tracks of the specified media type are available.
- (NSArray<AVMovieTrack *> *)tracksWithMediaType:(AVMediaType)mediaType
#if __swift__
API_DEPRECATED("Use loadTracks(withMediaType:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -275,24 +221,19 @@
API_DEPRECATED("Use loadTracksWithMediaType:completionHandler: instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTracksWithMediaType:completionHandler:
- @abstract Loads an array of AVMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which AVAsset filters its AVMovieTracks. (Media types are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
-*/
+/// Loads an array of AVMovieTracks of the asset that present media of the specified media type.
+///
+/// - Parameter mediaType: The media type according to which AVAsset filters its AVMovieTracks. (Media types are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
- (void)loadTracksWithMediaType:(AVMediaType)mediaType completionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaCharacteristic:
- @abstract Provides an array of AVMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which the receiver filters its AVMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
- @result An NSArray of AVMovieTracks; may be empty if no tracks with the specified characteristic are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVMovieTracks of the asset that present media with the specified characteristic.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which the receiver filters its AVMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVMovieTracks; may be empty if no tracks with the specified characteristic are available.
- (NSArray<AVMovieTrack *> *)tracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic
#if __swift__
API_DEPRECATED("Use loadTracks(withMediaCharacteristic:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -300,14 +241,10 @@
API_DEPRECATED("Use loadTracksWithMediaCharacteristic:completionHandler: instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTracksWithMediaCharacteristic:completionHandler:
- @abstract Loads an array of AVMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which AVAsset filters its AVMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
-*/
+/// Loads an array of AVMovieTracks of the asset that present media with the specified characteristic.
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which AVAsset filters its AVMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
- (void)loadTracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic completionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
@end
@@ -319,14 +256,10 @@
@class AVMutableMovieInternal;
#pragma mark --- AVMutableMovie ---
-/*!
- @class AVMutableMovie
- @abstract AVMutableMovie adds to its immutable superclass, AVMovie, several categories of methods for editing QuickTime movie files, e.g. inserting and removing time ranges of media, adding and removing tracks, and modifying the metadata collections stored therein.
-
- @discussion By default, after creating an AVMutableMovie the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
-
+/// AVMutableMovie adds to its immutable superclass, AVMovie, several categories of methods for editing QuickTime movie files, e.g. inserting and removing time ranges of media, adding and removing tracks, and modifying the metadata collections stored therein.
+///
+/// By default, after creating an AVMutableMovie the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie : AVMovie
@@ -335,135 +268,102 @@
AVMutableMovieInternal *_mutableMovieInternal;
}
-/*!
- @method movieWithURL:options:error:
- @abstract Creates an AVMutableMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
- @param URL
- An NSURL object that specifies a file containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
- to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
+/// to indicate where the sample data should be written.
+///
+/// - Parameter URL: An NSURL object that specifies a file containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
+ (nullable instancetype)movieWithURL:(NSURL *)URL options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError;
-/*!
- @method initWithURL:options:error:
- @abstract Creates an AVMutableMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
- @param URL
- An NSURL object that specifies a file containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
- to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object from a movie header stored in a QuickTime movie file or ISO base media file.
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from a file and then append sample buffers to any of its tracks, you must first set one of these properties
+/// to indicate where the sample data should be written.
+///
+/// - Parameter URL: An NSURL object that specifies a file containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
- (nullable instancetype)initWithURL:(NSURL *)URL options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError NS_DESIGNATED_INITIALIZER;
-/*!
- @method movieWithData:options:error:
- @abstract Creates an AVMutableMovie object from a movie header stored in an NSData object.
- @param data
- An NSData object containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
-
- By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object from a movie header stored in an NSData object.
+///
+/// You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter data: An NSData object containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
+ (nullable instancetype)movieWithData:(NSData *)data options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @method initWithData:options:error:
- @abstract Creates an AVMutableMovie object from a movie header stored in an NSData object.
- @param data
- An NSData object containing a movie header.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
-
- By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object from a movie header stored in an NSData object.
+///
+/// You can use this method to operate on movie headers that are not stored in files. In general you should avoid loading an entire movie file with its media data into an instance of NSData!
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMutableMovieTrack's mediaDataStorage property will be nil. If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter data: An NSData object containing a movie header.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
- (nullable instancetype)initWithData:(NSData *)data options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError NS_DESIGNATED_INITIALIZER;
-/*!
- @method movieWithSettingsFromMovie:options:error:
- @abstract Creates an AVMutableMovie object without tracks (and therefore without media).
- @param movie
- If you wish to transfer settings from an existing movie (including movie userdata and metadata, preferred rate, preferred volume, etc.), pass a reference to an AVMovie object representing that movie. Otherwise pass nil. The userdata and metadata from the source movie may need to be converted if the format of that movie differs from fileType; you may wish to inspect the userdata or metadata of the receiver to ensure that important data was copied.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object. Pass nil for default initialization behavior.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion
- By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object without tracks (and therefore without media).
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter movie: If you wish to transfer settings from an existing movie (including movie userdata and metadata, preferred rate, preferred volume, etc.), pass a reference to an AVMovie object representing that movie. Otherwise pass nil. The userdata and metadata from the source movie may need to be converted if the format of that movie differs from fileType; you may wish to inspect the userdata or metadata of the receiver to ensure that important data was copied.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object. Pass nil for default initialization behavior.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
+ (nullable instancetype)movieWithSettingsFromMovie:(nullable AVMovie *)movie options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError;
-/*!
- @method initWithSettingsFromMovie:options:error:
- @abstract Creates an AVMutableMovie object without tracks (and therefore without media).
- @param movie
- If you wish to transfer settings from an existing movie (including movie userdata and metadata, preferred rate, preferred volume, etc.), pass a reference to an AVMovie object representing that movie. Otherwise pass nil. The userdata and metadata from the source movie may need to be converted if the format of that movie differs from fileType; you may wish to inspect the userdata or metadata of the receiver to ensure that important data was copied.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object. Pass nil for default initialization behavior.
- @param outError
- If an error occurs creating a movie, describes the nature of the failure.
- @result An AVMutableMovie object
- @discussion
- By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
- If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
-*/
+/// Creates an AVMutableMovie object without tracks (and therefore without media).
+///
+/// By default, the defaultMediaDataStorage property will be nil and each associated AVMovieTrack's mediaDataStorage property will be nil.
+/// If you want to create an AVMutableMovie from an NSData object and then append sample buffers to any of its tracks, you must first set one of these properties to indicate where the sample data should be written.
+///
+/// - Parameter movie: If you wish to transfer settings from an existing movie (including movie userdata and metadata, preferred rate, preferred volume, etc.), pass a reference to an AVMovie object representing that movie. Otherwise pass nil. The userdata and metadata from the source movie may need to be converted if the format of that movie differs from fileType; you may wish to inspect the userdata or metadata of the receiver to ensure that important data was copied.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMutableMovie object. Pass nil for default initialization behavior.
+/// - Parameter outError: If an error occurs creating a movie, describes the nature of the failure.
+///
+/// - Returns: An AVMutableMovie object
- (nullable instancetype)initWithSettingsFromMovie:(nullable AVMovie *)movie options:(nullable NSDictionary<NSString *, id> *)options error:(NSError * _Nullable * _Nullable)outError NS_DESIGNATED_INITIALIZER;
-/*!
- @property preferredRate
- @abstract The natural rate at which the movie is to be played; often but not always 1.0.
-*/
+/// The natural rate at which the movie is to be played; often but not always 1.0.
@property (nonatomic) float preferredRate;
-/*!
- @property preferredVolume
- @abstract The preferred volume of the audible media data of the movie; often but not always 1.0.
-*/
+/// The preferred volume of the audible media data of the movie; often but not always 1.0.
@property (nonatomic) float preferredVolume;
-/*!
- @property preferredTransform
- @abstract A CGAffineTransform indicating the transform specified in the movie's storage container as the preferred transformation of the visual media data for display purposes; the value is often but not always CGAffineTransformIdentity.
-*/
+/// A CGAffineTransform indicating the transform specified in the movie's storage container as the preferred transformation of the visual media data for display purposes; the value is often but not always CGAffineTransformIdentity.
@property (nonatomic) CGAffineTransform preferredTransform;
-/*!
- @property timescale
- @abstract For file types that contain a 'moov' atom, such as QuickTime Movie files, specifies the time scale of the movie.
- @discussion The default movie time scale is 600. In certain cases, you may want to set this to a different value. For instance, a movie that
- contains a single audio track should typically have the movie time scale set to the media time scale of that track.
-
- This property should be set on a new empty movie before any edits are performed on the movie.
-*/
+/// For file types that contain a 'moov' atom, such as QuickTime Movie files, specifies the time scale of the movie.
+///
+/// The default movie time scale is 600. In certain cases, you may want to set this to a different value. For instance, a movie that
+/// contains a single audio track should typically have the movie time scale set to the media time scale of that track.
+///
+/// This property should be set on a new empty movie before any edits are performed on the movie.
@property (nonatomic, readwrite) CMTimeScale timescale;
-/*!
- @property tracks
- @abstract The tracks in a mutable movie.
- @discussion The value of this property is an array of tracks the mutable movie contains; the tracks are of type AVMutableMovieTrack.
-*/
+/// The tracks in a mutable movie.
+///
+/// The value of this property is an array of tracks the mutable movie contains; the tracks are of type AVMutableMovieTrack.
@property (nonatomic, readonly) NSArray<AVMutableMovieTrack *> *tracks;
@end
@@ -471,76 +371,50 @@
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie (AVMutableMovieMovieLevelEditing)
-/*!
- @property modified
- @abstract Whether a movie has been modified.
- @discussion The value of this property is a BOOL that indicates whether the AVMutableMovie object has been modified since it was created, was last written, or had its modified state cleared via a call to setModified:NO.
-*/
+/// Whether a movie has been modified.
+///
+/// The value of this property is a BOOL that indicates whether the AVMutableMovie object has been modified since it was created, was last written, or had its modified state cleared via a call to setModified:NO.
@property (nonatomic, getter=isModified) BOOL modified;
-/*!
- @property defaultMediaDataStorage
- @abstract The default storage container for media data added to a movie.
- @discussion The value of this property is an AVMediaDataStorage object that indicates where sample data that is added to a movie should be written, for any track for whose mediaDataStorage property is nil.
-*/
+/// The default storage container for media data added to a movie.
+///
+/// The value of this property is an AVMediaDataStorage object that indicates where sample data that is added to a movie should be written, for any track for whose mediaDataStorage property is nil.
@property (nonatomic, copy, nullable) AVMediaDataStorage *defaultMediaDataStorage;
-/*!
- @property interleavingPeriod
- @abstract A CMTime that indicates the duration for interleaving runs of samples of each track.
- @discussion The default interleaving period is 0.5 seconds.
- */
+/// A CMTime that indicates the duration for interleaving runs of samples of each track.
+///
+/// The default interleaving period is 0.5 seconds.
@property (nonatomic) CMTime interleavingPeriod;
-/*!
- @method insertTimeRange:ofAsset:atTime:copySampleData:error:
- @abstract Inserts all the tracks of a timeRange of an asset into a movie.
- @param timeRange
- The time range of the asset to be inserted.
- @param asset
- An AVAsset object indicating the source of the inserted media. Only instances of AVURLAsset and AVComposition are supported.
- Must not be nil.
- @param startTime
- The time in the target movie at which the media is to be inserted.
- @param copySampleData
- A BOOL value that indicates whether sample data is to be copied from the source to the destination during edits.
- If YES, the sample data is written to the location specified by the track property mediaDataStorage if non-nil,
- or else by the movie property defaultMediaDataStorage if non-nil; if both are nil, the method will fail and return NO.
- If NO, sample data will not be written and sample references to the samples in their original container will be added as necessary.
- Note that in this case, this method will fail if the source AVAsset is not able to provide sample reference information for the original container.
- @param outError
- If the insertion fails, an NSError object that describes the nature of the failure.
- @result A BOOL value that indicates the success of the insertion.
- @discussion This method may add new tracks to the target movie to ensure that all tracks of the asset are represented in the inserted timeRange.
- Existing content at the specified startTime will be pushed out by the duration of timeRange.
- Note that metadata will not be automatically copied.
-*/
+/// Inserts all the tracks of a timeRange of an asset into a movie.
+///
+/// This method may add new tracks to the target movie to ensure that all tracks of the asset are represented in the inserted timeRange.
+/// Existing content at the specified startTime will be pushed out by the duration of timeRange.
+/// Note that metadata will not be automatically copied.
+///
+/// - Parameter timeRange: The time range of the asset to be inserted.
+/// - Parameter asset: An AVAsset object indicating the source of the inserted media. Only instances of AVURLAsset and AVComposition are supported. Must not be nil.
+/// - Parameter startTime: The time in the target movie at which the media is to be inserted.
+/// - Parameter copySampleData: A BOOL value that indicates whether sample data is to be copied from the source to the destination during edits. If YES, the sample data is written to the location specified by the track property mediaDataStorage if non-nil, or else by the movie property defaultMediaDataStorage if non-nil; if both are nil, the method will fail and return NO. If NO, sample data will not be written and sample references to the samples in their original container will be added as necessary. Note that in this case, this method will fail if the source AVAsset is not able to provide sample reference information for the original container.
+/// - Parameter outError: If the insertion fails, an NSError object that describes the nature of the failure.
+///
+/// - Returns: A BOOL value that indicates the success of the insertion.
- (BOOL)insertTimeRange:(CMTimeRange)timeRange ofAsset:(AVAsset *)asset atTime:(CMTime)startTime copySampleData:(BOOL)copySampleData error:(NSError * _Nullable * _Nullable)outError;
-/*!
- @method insertEmptyTimeRange:
- @abstract Adds an empty time range to the target movie.
- @param timeRange
- The time range to be made empty. Note that you cannot add empty time ranges to the end of a movie.
-*/
+/// Adds an empty time range to the target movie.
+///
+/// - Parameter timeRange: The time range to be made empty. Note that you cannot add empty time ranges to the end of a movie.
- (void)insertEmptyTimeRange:(CMTimeRange)timeRange;
-/*!
- @method removeTimeRange:
- @abstract Removes a specified time range from a movie.
- @param timeRange
- The time range to be removed.
-*/
+/// Removes a specified time range from a movie.
+///
+/// - Parameter timeRange: The time range to be removed.
- (void)removeTimeRange:(CMTimeRange)timeRange;
-/*!
- @method scaleTimeRange:toDuration:
- @abstract Changes the duration of a time range of a movie.
- @param timeRange
- The time range to be scaled.
- @param duration
- The new duration of the time range.
-*/
+/// Changes the duration of a time range of a movie.
+///
+/// - Parameter timeRange: The time range to be scaled.
+/// - Parameter duration: The new duration of the time range.
- (void)scaleTimeRange:(CMTimeRange)timeRange toDuration:(CMTime)duration;
@end
@@ -549,58 +423,48 @@
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie (AVMutableMovieTrackLevelEditing)
-/*!
- @method mutableTrackCompatibleWithTrack:
- @abstract Provides a reference to a track of a mutable movie into which any time range of an AVAssetTrack
- can be inserted (via -[AVMutableMovieTrack insertTimeRange:ofTrack:atTime:copySampleData:error:]).
- @param track
- A reference to the AVAssetTrack from which a time range may be inserted.
- @result An AVMutableMovieTrack that can accommodate the insertion.
- If no such track is available, the result is nil. A new track of the same media type
- as the AVAssetTrack can be created via -addMutableTrackWithMediaType:copySettingsFromTrack:options:,
- and this new track will be compatible.
- @discussion For best performance, the number of tracks in a movie should be kept to a minimum, corresponding to the
- number for which media data must be presented in parallel. If media data of the same type is to be presented
- serially, even from multiple assets, a single track of that media type should be used. This method,
- -mutableTrackCompatibleWithTrack:, can help the client to identify an existing target track for an insertion.
-*/
+/// Provides a reference to a track of a mutable movie into which any time range of an AVAssetTrack can be inserted (via -[AVMutableMovieTrack insertTimeRange:ofTrack:atTime:copySampleData:error:]).
+///
+/// For best performance, the number of tracks in a movie should be kept to a minimum, corresponding to the
+/// number for which media data must be presented in parallel. If media data of the same type is to be presented
+/// serially, even from multiple assets, a single track of that media type should be used. This method,
+/// -mutableTrackCompatibleWithTrack:, can help the client to identify an existing target track for an insertion.
+///
+/// - Parameter track: A reference to the AVAssetTrack from which a time range may be inserted.
+///
+/// - Returns: An AVMutableMovieTrack that can accommodate the insertion.
+/// If no such track is available, the result is nil. A new track of the same media type
+/// as the AVAssetTrack can be created via -addMutableTrackWithMediaType:copySettingsFromTrack:options:,
+/// and this new track will be compatible.
- (nullable AVMutableMovieTrack *)mutableTrackCompatibleWithTrack:(AVAssetTrack *)track;
-/*!
- @method addMutableTrackWithMediaType:copySettingsFromTrack:options:
- @abstract Adds an empty track to the target movie.
- @param mediaType
- The media type of the new track (e.g. AVMediaTypeVideo for a video track).
- @param track
- If you wish to transfer settings from an existing track, including width, height, preferred volume, etc., pass a reference to an AVAssetTrack representing that track. Otherwise pass nil.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the new AVMutableMovieTrack object. Pass nil for default initialization behavior.
- @result An AVMutableMovieTrack object
- @discussion The trackID of the newly added track is a property of the returned instance of AVMutableMovieTrack.
- This method throws an exception if media type is not equal to the track's media type, or if any option is invalid.
- Note that metadata will not be automatically copied.
-*/
+/// Adds an empty track to the target movie.
+///
+/// The trackID of the newly added track is a property of the returned instance of AVMutableMovieTrack.
+/// This method throws an exception if media type is not equal to the track's media type, or if any option is invalid.
+/// Note that metadata will not be automatically copied.
+///
+/// - Parameter mediaType: The media type of the new track (e.g. AVMediaTypeVideo for a video track).
+/// - Parameter track: If you wish to transfer settings from an existing track, including width, height, preferred volume, etc., pass a reference to an AVAssetTrack representing that track. Otherwise pass nil.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the new AVMutableMovieTrack object. Pass nil for default initialization behavior.
+///
+/// - Returns: An AVMutableMovieTrack object
- (nullable AVMutableMovieTrack *)addMutableTrackWithMediaType:(AVMediaType)mediaType copySettingsFromTrack:(nullable AVAssetTrack *)track options:(nullable NSDictionary<NSString *, id> *)options;
-/*!
- @method addMutableTracksCopyingSettingsFromTracks:options:
- @abstract Adds one or more empty tracks to the target movie, copying track settings from the source tracks.
- @param existingTracks
- An array of AVAssetTrack objects.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the new AVMutableMovieTrack objects. Pass nil for default initialization behavior.
- @result An array of AVMutableMovieTrack objects; the index of a track in this array is the same as the index of its source track in the existingTracks array.
- @discussion This method creates one or more empty tracks in the target movie and configures those tracks with settings (such as track userdata and metadata, width, height, and preferred volume) copied from the source tracks in the existingTracks array. Also, properties involving pairs of tracks (such as track references) are copied from the source tracks to the target tracks.
- This method throws an exception if any option is invalid.
-*/
+/// Adds one or more empty tracks to the target movie, copying track settings from the source tracks.
+///
+/// This method creates one or more empty tracks in the target movie and configures those tracks with settings (such as track userdata and metadata, width, height, and preferred volume) copied from the source tracks in the existingTracks array. Also, properties involving pairs of tracks (such as track references) are copied from the source tracks to the target tracks.
+/// This method throws an exception if any option is invalid.
+///
+/// - Parameter existingTracks: An array of AVAssetTrack objects.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the new AVMutableMovieTrack objects. Pass nil for default initialization behavior.
+///
+/// - Returns: An array of AVMutableMovieTrack objects; the index of a track in this array is the same as the index of its source track in the existingTracks array.
- (NSArray<AVMutableMovieTrack *> *)addMutableTracksCopyingSettingsFromTracks:(NSArray<AVAssetTrack *> *)existingTracks options:(nullable NSDictionary<NSString *, id> *)options;
-/*!
- @method removeTrack:
- @abstract Removes a track from the target movie.
- @param track
- The track to be removed.
-*/
+/// Removes a track from the target movie.
+///
+/// - Parameter track: The track to be removed.
- (void)removeTrack:(AVMovieTrack *)track;
@end
@@ -609,11 +473,9 @@
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie (AVMutableMovieMetadataEditing)
-/*!
- @property metadata
- @abstract A collection of metadata stored by the movie.
- @discussion The value of this property is an array of AVMetadataItem objects representing the collection of metadata stored by the movie.
-*/
+/// A collection of metadata stored by the movie.
+///
+/// The value of this property is an array of AVMetadataItem objects representing the collection of metadata stored by the movie.
@property (nonatomic, copy) NSArray<AVMetadataItem *> *metadata;
@end
@@ -621,64 +483,49 @@
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie (AVMutableMovieTrackInspection)
-/*!
- @method trackWithTrackID:
- @abstract Provides an instance of AVMutableMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVMutableMovieTrack.
- @result An instance of AVMutableMovieTrack; may be nil if no track of the specified trackID is available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an instance of AVMutableMovieTrack that represents the track of the specified trackID.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter trackID: The trackID of the requested AVMutableMovieTrack.
+///
+/// - Returns: An instance of AVMutableMovieTrack; may be nil if no track of the specified trackID is available.
- (nullable AVMutableMovieTrack *)trackWithTrackID:(CMPersistentTrackID)trackID;
-/*!
- @method loadTrackWithTrackID:completionHandler:
- @abstract Loads an instance of AVMutableMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVMutableMovieTrack.
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
-*/
+/// Loads an instance of AVMutableMovieTrack that represents the track of the specified trackID.
+///
+/// - Parameter trackID: The trackID of the requested AVMutableMovieTrack.
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
- (void)loadTrackWithTrackID:(CMPersistentTrackID)trackID completionHandler:(void (^ NS_SWIFT_SENDABLE)(AVMutableMovieTrack * _Nullable_result, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaType:
- @abstract Provides an array of AVMutableMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which the receiver filters its AVMutableMovieTracks. (Media types are defined in AVMediaFormat.h)
- @result An NSArray of AVMutableMovieTracks; may be empty if no tracks of the specified media type are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVMutableMovieTracks of the asset that present media of the specified media type.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaType: The media type according to which the receiver filters its AVMutableMovieTracks. (Media types are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVMutableMovieTracks; may be empty if no tracks of the specified media type are available.
- (NSArray<AVMutableMovieTrack *> *)tracksWithMediaType:(AVMediaType)mediaType;
-/*!
- @method loadTracksWithMediaType:completionHandler:
- @abstract Loads an array of AVMutableMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which AVAsset filters its AVMutableMovieTracks. (Media types are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
-*/
+/// Loads an array of AVMutableMovieTracks of the asset that present media of the specified media type.
+///
+/// - Parameter mediaType: The media type according to which AVAsset filters its AVMutableMovieTracks. (Media types are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
- (void)loadTracksWithMediaType:(AVMediaType)mediaType completionHandler:(void ( NS_SWIFT_SENDABLE^)(NSArray<AVMutableMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaCharacteristic:
- @abstract Provides an array of AVMutableMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which the receiver filters its AVMutableMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
- @result An NSArray of AVMutableMovieTracks; may be empty if no tracks with the specified characteristic are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVMutableMovieTracks of the asset that present media with the specified characteristic.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which the receiver filters its AVMutableMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVMutableMovieTracks; may be empty if no tracks with the specified characteristic are available.
- (NSArray<AVMutableMovieTrack *> *)tracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic;
-/*!
- @method loadTracksWithMediaCharacteristic:completionHandler:
- @abstract Loads an array of AVMutableMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which AVAsset filters its AVMutableMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
-*/
+/// Loads an array of AVMutableMovieTracks of the asset that present media with the specified characteristic.
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which AVAsset filters its AVMutableMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
- (void)loadTracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic completionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVMutableMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
@end
@@ -687,11 +534,9 @@
#pragma mark --- AVMediaDataStorage ---
@class AVMediaDataStorageInternal;
-/*!
- @class AVMediaDataStorage
- @abstract Media sample data storage file.
- @discussion Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
-*/
+/// Media sample data storage file.
+///
+/// Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
NS_SWIFT_SENDABLE
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMediaDataStorage : NSObject {
@@ -700,55 +545,37 @@
}
AV_INIT_UNAVAILABLE
-/*!
- @method initWithURL:options:
- @abstract Creates an AVMediaDataStorage object associated with a file URL.
- @param URL
- An NSURL object that specifies a file where sample data that is added to a movie or track should be written.
- @param options
- An NSDictionary object that contains keys for specifying options for the initialization of the AVMediaDataStorage object. Currently no keys are defined.
- @result An AVMediaDataStorage object
-*/
+/// Creates an AVMediaDataStorage object associated with a file URL.
+///
+/// - Parameter URL: An NSURL object that specifies a file where sample data that is added to a movie or track should be written.
+/// - Parameter options: An NSDictionary object that contains keys for specifying options for the initialization of the AVMediaDataStorage object. Currently no keys are defined.
+///
+/// - Returns: An AVMediaDataStorage object
- (instancetype)initWithURL:(NSURL *)URL options:(nullable NSDictionary<NSString *, id> *)options NS_DESIGNATED_INITIALIZER;
-/*!
- @method URL
- @abstract The URL from which the receiver was initialized; may be nil.
-*/
+/// The URL from which the receiver was initialized; may be nil.
- (nullable NSURL *)URL;
@end
#pragma mark --- AVFragmentedMovie ---
-/*!
- @class AVFragmentedMovie
-
- @abstract A subclass of AVMovie for handling fragmented movie files. An AVFragmentedMovie is capable of changing the values of certain of its properties and those of its tracks, if it's associated with an instance of AVFragmentedMovieMinder when one or more movie fragments are appended to the movie file.
-
- @discussion Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
-*/
-/*!
- @constant AVFragmentedMovieContainsMovieFragmentsDidChangeNotification
- @abstract Posted after the value of @"containsMovieFragments" has already been loaded and the AVFragmentedMovie is added to an AVFragmentedMovieMinder, either when 1) movie fragments are detected in the movie file on disk after it had previously contained none or when 2) no movie fragments are detected in the movie file on disk after it had previously contained one or more.
-*/
+
+/// Posted after the value of @"containsMovieFragments" has already been loaded and the AVFragmentedMovie is added to an AVFragmentedMovieMinder, either when 1) movie fragments are detected in the movie file on disk after it had previously contained none or when 2) no movie fragments are detected in the movie file on disk after it had previously contained one or more.
AVF_EXPORT NSString *const AVFragmentedMovieContainsMovieFragmentsDidChangeNotification API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @constant AVFragmentedMovieDurationDidChangeNotification
- @abstract Posted when the duration of an AVFragmentedMovie changes while it's being minded by an AVFragmentedMovieMinder, but only for changes that occur after the status of the value of @"duration" has reached AVKeyValueStatusLoaded.
-*/
+/// Posted when the duration of an AVFragmentedMovie changes while it's being minded by an AVFragmentedMovieMinder, but only for changes that occur after the status of the value of @"duration" has reached AVKeyValueStatusLoaded.
AVF_EXPORT NSString *const AVFragmentedMovieDurationDidChangeNotification API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
-/*!
- @constant AVFragmentedMovieWasDefragmentedNotification
- @abstract Posted when the movie file on disk is defragmented while an AVFragmentedMovie is being minded by an AVFragmentedMovieMinder, but only if the defragmentation occurs after the status of the value of @"canContainMovieFragments" has reached AVKeyValueStatusLoaded.
-*/
+/// Posted when the movie file on disk is defragmented while an AVFragmentedMovie is being minded by an AVFragmentedMovieMinder, but only if the defragmentation occurs after the status of the value of @"canContainMovieFragments" has reached AVKeyValueStatusLoaded.
AVF_EXPORT NSString *const AVFragmentedMovieWasDefragmentedNotification API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos);
@class AVFragmentedMovieInternal;
+/// A subclass of AVMovie for handling fragmented movie files. An AVFragmentedMovie is capable of changing the values of certain of its properties and those of its tracks, if it's associated with an instance of AVFragmentedMovieMinder when one or more movie fragments are appended to the movie file.
+///
+/// Subclasses of this type that are used from Swift must fulfill the requirements of a Sendable type.
NS_SWIFT_SENDABLE
API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVFragmentedMovie : AVMovie <AVFragmentMinding>
@@ -756,11 +583,9 @@
@private
}
-/*!
- @property tracks
- @abstract The tracks in a movie.
- @discussion The value of this property is an array of tracks the movie contains; the tracks are of type AVFragmentedMovieTrack.
-*/
+/// The tracks in a movie.
+///
+/// The value of this property is an array of tracks the movie contains; the tracks are of type AVFragmentedMovieTrack.
@property (nonatomic, readonly) NSArray<AVFragmentedMovieTrack *> *tracks;
@end
@@ -768,14 +593,13 @@
API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVFragmentedMovie (AVFragmentedMovieTrackInspection)
-/*!
- @method trackWithTrackID:
- @abstract Provides an instance of AVFragmentedMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVFragmentedMovieTrack.
- @result An instance of AVFragmentedMovieTrack; may be nil if no track of the specified trackID is available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an instance of AVFragmentedMovieTrack that represents the track of the specified trackID.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter trackID: The trackID of the requested AVFragmentedMovieTrack.
+///
+/// - Returns: An instance of AVFragmentedMovieTrack; may be nil if no track of the specified trackID is available.
- (nullable AVFragmentedMovieTrack *)trackWithTrackID:(CMPersistentTrackID)trackID
#if __swift__
API_DEPRECATED("Use loadTrack(withTrackID:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -783,24 +607,19 @@
API_DEPRECATED("Use loadTrackWithTrackID:completionHandler: instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTrackWithTrackID:completionHandler:
- @abstract Loads an instance of AVFragmentedMovieTrack that represents the track of the specified trackID.
- @param trackID
- The trackID of the requested AVFragmentedMovieTrack.
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
-*/
+/// Loads an instance of AVFragmentedMovieTrack that represents the track of the specified trackID.
+///
+/// - Parameter trackID: The trackID of the requested AVFragmentedMovieTrack.
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded track (which may be nil if no track of the specified trackID is available) or an error.
- (void)loadTrackWithTrackID:(CMPersistentTrackID)trackID completionHandler:(void (^ NS_SWIFT_SENDABLE)(AVFragmentedMovieTrack * _Nullable_result, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaType:
- @abstract Provides an array of AVFragmentedMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which the receiver filters its AVFragmentedMovieTracks. (Media types are defined in AVMediaFormat.h)
- @result An NSArray of AVFragmentedMovieTracks; may be empty if no tracks of the specified media type are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVFragmentedMovieTracks of the asset that present media of the specified media type.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaType: The media type according to which the receiver filters its AVFragmentedMovieTracks. (Media types are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVFragmentedMovieTracks; may be empty if no tracks of the specified media type are available.
- (NSArray<AVFragmentedMovieTrack *> *)tracksWithMediaType:(AVMediaType)mediaType
#if __swift__
API_DEPRECATED("Use loadTracks(withMediaType:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -808,24 +627,19 @@
API_DEPRECATED("Use loadTracksWithMediaType:completionHandler: instead", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTracksWithMediaType:completionHandler:
- @abstract Loads an array of AVFragmentedMovieTracks of the asset that present media of the specified media type.
- @param mediaType
- The media type according to which AVAsset filters its AVFragmentedMovieTracks. (Media types are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
-*/
+/// Loads an array of AVFragmentedMovieTracks of the asset that present media of the specified media type.
+///
+/// - Parameter mediaType: The media type according to which AVAsset filters its AVFragmentedMovieTracks. (Media types are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks of the specified media type are available) or an error.
- (void)loadTracksWithMediaType:(AVMediaType)mediaType completionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVFragmentedMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
-/*!
- @method tracksWithMediaCharacteristic:
- @abstract Provides an array of AVFragmentedMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which the receiver filters its AVFragmentedMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
- @result An NSArray of AVFragmentedMovieTracks; may be empty if no tracks with the specified characteristic are available.
- @discussion Becomes callable without blocking when the key @"tracks" has been loaded
-*/
+/// Provides an array of AVFragmentedMovieTracks of the asset that present media with the specified characteristic.
+///
+/// Becomes callable without blocking when the key @"tracks" has been loaded
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which the receiver filters its AVFragmentedMovieTracks. (Media characteristics are defined in AVMediaFormat.h)
+///
+/// - Returns: An NSArray of AVFragmentedMovieTracks; may be empty if no tracks with the specified characteristic are available.
- (NSArray<AVFragmentedMovieTrack *> *)tracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic
#if __swift__
API_DEPRECATED("Use loadTracks(withMediaCharacteristic:) instead", macos(10.7, 13.0), ios(4.0, 16.0), tvos(9.0, 16.0), watchos(1.0, 9.0)) API_UNAVAILABLE(visionos);
@@ -833,86 +647,60 @@
API_DEPRECATED("loadTracksWithMediaCharacteristic:completionHandler:", macos(10.7, 15.0), ios(4.0, 18.0), tvos(9.0, 18.0), watchos(1.0, 11.0)) API_UNAVAILABLE(visionos);
#endif
-/*!
- @method loadTracksWithMediaCharacteristic:completionHandler:
- @abstract Loads an array of AVFragmentedMovieTracks of the asset that present media with the specified characteristic.
- @param mediaCharacteristic
- The media characteristic according to which AVAsset filters its AVFragmentedMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
- @param completionHandler
- A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
-*/
+/// Loads an array of AVFragmentedMovieTracks of the asset that present media with the specified characteristic.
+///
+/// - Parameter mediaCharacteristic: The media characteristic according to which AVAsset filters its AVFragmentedMovieTracks. (Media characteristics are defined in AVMediaFormat.h.)
+/// - Parameter completionHandler: A block that is called when the loading is finished, with either the loaded tracks (which may be empty if no tracks with the specified characteristic are available) or an error.
- (void)loadTracksWithMediaCharacteristic:(AVMediaCharacteristic)mediaCharacteristic completionHandler:(void (^ NS_SWIFT_SENDABLE)(NSArray<AVFragmentedMovieTrack *> * _Nullable, NSError * _Nullable))completionHandler API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), watchos(8.0), visionos(1.0));
@end
#pragma mark --- AVFragmentedMovieMinder ---
-/*!
- @class AVFragmentedMovieMinder
- @abstract A class that periodically checks whether additional movie fragments have been appended to fragmented movie files.
- @discussion AVFragmentedMovieMinder is identical to AVFragmentedAssetMinder except that it's capable of minding only assets of class AVFragmentedMovie.
-*/
+
+/// A class that periodically checks whether additional movie fragments have been appended to fragmented movie files.
+///
+/// AVFragmentedMovieMinder is identical to AVFragmentedAssetMinder except that it's capable of minding only assets of class AVFragmentedMovie.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(10.10), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVFragmentedMovieMinder : AVFragmentedAssetMinder
-/*!
- @method fragmentedMovieMinderWithMovie:mindingInterval:
- @abstract Creates an AVFragmentedMovieMinder, adds the specified movie to it, and sets the mindingInterval to the specified value.
- @param movie
- An instance of AVFragmentedMovie to add to the AVFragmentedMovieMinder
- @param mindingInterval
- The initial minding interval of the AVFragmentedMovieMinder.
- @result A new instance of AVFragmentedMovieMinder.
-*/
+/// Creates an AVFragmentedMovieMinder, adds the specified movie to it, and sets the mindingInterval to the specified value.
+///
+/// - Parameter movie: An instance of AVFragmentedMovie to add to the AVFragmentedMovieMinder
+/// - Parameter mindingInterval: The initial minding interval of the AVFragmentedMovieMinder.
+///
+/// - Returns: A new instance of AVFragmentedMovieMinder.
+ (instancetype)fragmentedMovieMinderWithMovie:(AVFragmentedMovie *)movie mindingInterval:(NSTimeInterval)mindingInterval;
-/*!
- @method initWithMovie:mindingInterval:
- @abstract Creates an AVFragmentedMovieMinder, adds the specified movie to it, and sets the mindingInterval to the specified value.
- @param movie
- An instance of AVFragmentedMovie to add to the AVFragmentedMovieMinder
- @param mindingInterval
- The initial minding interval of the AVFragmentedMovieMinder.
- @result A new instance of AVFragmentedMovieMinder.
-*/
+/// Creates an AVFragmentedMovieMinder, adds the specified movie to it, and sets the mindingInterval to the specified value.
+///
+/// - Parameter movie: An instance of AVFragmentedMovie to add to the AVFragmentedMovieMinder
+/// - Parameter mindingInterval: The initial minding interval of the AVFragmentedMovieMinder.
+///
+/// - Returns: A new instance of AVFragmentedMovieMinder.
- (instancetype)initWithMovie:(AVFragmentedMovie *)movie mindingInterval:(NSTimeInterval)mindingInterval NS_DESIGNATED_INITIALIZER;
-/*!
- @property mindingInterval
- @abstract An NSTimeInterval indicating how often a check for additional movie fragments should be performed. The default interval is 10.0.
-*/
+/// An NSTimeInterval indicating how often a check for additional movie fragments should be performed. The default interval is 10.0.
@property (nonatomic) NSTimeInterval mindingInterval;
-/*!
- @property movies
- @abstract An NSArray of the AVFragmentedMovie objects being minded.
-*/
+/// An NSArray of the AVFragmentedMovie objects being minded.
@property (nonatomic, readonly) NSArray<AVFragmentedMovie *> *movies;
-/*!
- @method addFragmentedMovie:
- @abstract Adds a fragmented movie to the array of movies being minded.
- @param movie
- The fragmented movie to add to the minder.
-*/
+/// Adds a fragmented movie to the array of movies being minded.
+///
+/// - Parameter movie: The fragmented movie to add to the minder.
- (void)addFragmentedMovie:(AVFragmentedMovie *)movie;
-/*!
- @method removeFragmentedMovie:
- @abstract Removes a fragmented movie from the array of movies being minded.
- @param movie
- The fragmented movie to remove from the minder.
-*/
+/// Removes a fragmented movie from the array of movies being minded.
+///
+/// - Parameter movie: The fragmented movie to remove from the minder.
- (void)removeFragmentedMovie:(AVFragmentedMovie *)movie;
@end
-/*!
- @category AVMutableMovie (SynchronousAssetInterface)
- @abstract Redeclarations of async-only AVAsset interfaces to allow synchronous usage in the synchronous subclass.
- @discussion
- See AVAsset's interface for more information about these interfaces.
- */
+/// Redeclarations of async-only AVAsset interfaces to allow synchronous usage in the synchronous subclass.
+///
+/// See AVAsset's interface for more information about these interfaces.
API_AVAILABLE(macos(10.11), ios(13.0), watchos(6.0), visionos(1.0)) API_UNAVAILABLE(tvos)
@interface AVMutableMovie (SynchronousAssetInterface)
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVPlayerLayer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVPlayerLayer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVPlayerLayer.h 2026-05-29 23:09:27
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVPlayerLayer.h 2026-06-12 02:20:08
@@ -9,33 +9,7 @@
*/
-/*!
- @class AVPlayerLayer
- @abstract AVPlayerLayer is a subclass of CALayer to which an AVPlayer can direct its visual output.
-
- @discussion To create an AVPlayerLayer instance:
-
- AVPlayer *player = ...;
- // ... set up an AVPlayer
-
- CALayer *superlayer = ...;
- AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:player];
-
- // ... set up the AVPlayerLayer's geometry. For example: set the AVPlayerLayer frame according to the presentationSize of the AVPlayer's currentItem.
-
- [superlayer addSublayer:playerLayer];
-
- AVPlayerLayer provides a property 'videoGravity' that defines how the video content is displayed within the AVPlayerLayer property 'bounds' rect.
- The value for the @"contents" key of an AVPlayerLayer is opaque and effectively read-only.
-
- Note that during playback AVPlayer may compensate for temporal drift between its visual output
- and its audible output to one or more independently-clocked audio output devices by adjusting the timing of its
- associated AVPlayerLayers. The effects of these adjustments are usually very minute; however, clients that
- wish to remain entirely unaffected by such adjustments may wish to place other layers for which timing is
- important into indepedently timed subtrees of their layer trees.
-*/
-
#import <AVFoundation/AVBase.h>
#import <AVFoundation/AVAnimation.h>
#import <CoreVideo/CVPixelBuffer.h>
@@ -48,6 +22,28 @@
NS_ASSUME_NONNULL_BEGIN
+/// AVPlayerLayer is a subclass of CALayer to which an AVPlayer can direct its visual output.
+///
+/// To create an AVPlayerLayer instance:
+///
+/// AVPlayer *player = ...;
+/// // ... set up an AVPlayer
+///
+/// CALayer *superlayer = ...;
+/// AVPlayerLayer *playerLayer = [AVPlayerLayer playerLayerWithPlayer:player];
+///
+/// // ... set up the AVPlayerLayer's geometry. For example: set the AVPlayerLayer frame according to the presentationSize of the AVPlayer's currentItem.
+///
+/// [superlayer addSublayer:playerLayer];
+///
+/// AVPlayerLayer provides a property 'videoGravity' that defines how the video content is displayed within the AVPlayerLayer property 'bounds' rect.
+/// The value for the @"contents" key of an AVPlayerLayer is opaque and effectively read-only.
+///
+/// Note that during playback AVPlayer may compensate for temporal drift between its visual output
+/// and its audible output to one or more independently-clocked audio output devices by adjusting the timing of its
+/// associated AVPlayerLayers. The effects of these adjustments are usually very minute; however, clients that
+/// wish to remain entirely unaffected by such adjustments may wish to place other layers for which timing is
+/// important into indepedently timed subtrees of their layer trees.
API_AVAILABLE(macos(10.7), ios(4.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVPlayerLayer : CALayer
{
@@ -55,59 +51,34 @@
AVPlayerLayerInternal *_playerLayer;
}
-/*!
- @method layerWithPlayer:
- @abstract Returns an instance of AVPlayerLayer to display the visual output of the specified AVPlayer.
- @result An instance of AVPlayerLayer.
-*/
+/// Returns an instance of AVPlayerLayer to display the visual output of the specified AVPlayer.
+///
+/// - Returns: An instance of AVPlayerLayer.
+ (AVPlayerLayer *)playerLayerWithPlayer:(nullable AVPlayer *)player;
-/*!
- @property player
- @abstract Indicates the instance of AVPlayer for which the AVPlayerLayer displays visual output
-*/
+/// Indicates the instance of AVPlayer for which the AVPlayerLayer displays visual output
@property (nonatomic, retain, nullable) AVPlayer *player;
-/*!
- @property videoGravity
- @abstract A string defining how the video is displayed within an AVPlayerLayer bounds rect.
- @discusssion Options are AVLayerVideoGravityResizeAspect, AVLayerVideoGravityResizeAspectFill
- and AVLayerVideoGravityResize. AVLayerVideoGravityResizeAspect is default.
- See <AVFoundation/AVAnimation.h> for a description of these options.
- */
+/// A string defining how the video is displayed within an AVPlayerLayer bounds rect. @discusssion Options are AVLayerVideoGravityResizeAspect, AVLayerVideoGravityResizeAspectFill and AVLayerVideoGravityResize. AVLayerVideoGravityResizeAspect is default. See <AVFoundation/AVAnimation.h> for a description of these options.
@property (copy) AVLayerVideoGravity videoGravity;
-/*!
- @property readyForDisplay
- @abstract Boolean indicating that the first video frame has been made ready for display for the current item of the associated AVPlayer.
- @discusssion Use this property as an indicator of when best to show or animate-in an AVPlayerLayer into view.
- An AVPlayerLayer may be displayed, or made visible, while this property is NO, however the layer will not have any user-visible content until the value becomes YES. Note that if an animation is added to an AVPlayerLayer before it becomes readyForDisplay the video image displayed inside might not animate with the receiver.
- This property remains NO for an AVPlayer currentItem whose AVAsset contains no enabled video tracks.
- This property is key-value observable.
- */
+/// Boolean indicating that the first video frame has been made ready for display for the current item of the associated AVPlayer. @discusssion Use this property as an indicator of when best to show or animate-in an AVPlayerLayer into view. An AVPlayerLayer may be displayed, or made visible, while this property is NO, however the layer will not have any user-visible content until the value becomes YES. Note that if an animation is added to an AVPlayerLayer before it becomes readyForDisplay the video image displayed inside might not animate with the receiver. This property remains NO for an AVPlayer currentItem whose AVAsset contains no enabled video tracks. This property is key-value observable.
@property (nonatomic, readonly, getter=isReadyForDisplay) BOOL readyForDisplay;
-/*!
- @property videoRect
- @abstract The current size and position of the video image as displayed within the receiver's bounds.
- */
+/// The current size and position of the video image as displayed within the receiver's bounds.
@property (nonatomic, readonly) CGRect videoRect API_AVAILABLE(macos(10.9), ios(7.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @property pixelBufferAttributes
- @abstract The client requirements for the visual output displayed in AVPlayerLayer during playback.
- @discussion Pixel buffer attribute keys are defined in <CoreVideo/CVPixelBuffer.h>
- This property is key-value observable.
- */
+/// The client requirements for the visual output displayed in AVPlayerLayer during playback.
+///
+/// Pixel buffer attribute keys are defined in <CoreVideo/CVPixelBuffer.h>
+/// This property is key-value observable.
@property (nonatomic, copy, nullable) NSDictionary<NSString *, id> *pixelBufferAttributes API_AVAILABLE(macos(10.11), ios(9.0), tvos(9.0), visionos(1.0)) API_UNAVAILABLE(watchos);
-/*!
- @method copyDisplayedPixelBuffer
- @abstract Returns a retained reference to the pixel buffer currently displayed in this AVPlayerLayer. This will return NULL if the displayed pixel buffer is protected, no image is currently being displayed, if the current player's rate is non-zero or if the image is unavailable.
- @discussion This will only return the current image while the media is paused, otherwise this will return nil. Clients must release the pixel buffer after use.
-
- Do not write to the returned CVPixelBuffer's attachments or pixel data.
- */
+/// Returns a retained reference to the pixel buffer currently displayed in this AVPlayerLayer. This will return NULL if the displayed pixel buffer is protected, no image is currently being displayed, if the current player's rate is non-zero or if the image is unavailable.
+///
+/// This will only return the current image while the media is paused, otherwise this will return nil. Clients must release the pixel buffer after use.
+///
+/// Do not write to the returned CVPixelBuffer's attachments or pixel data.
- (nullable CVPixelBufferRef)copyDisplayedPixelBuffer CF_RETURNS_RETAINED
#if defined(__swift__)
API_DEPRECATED_WITH_REPLACEMENT("displayedReadOnlyPixelBuffer", macos(13.0, 27.0), ios(16.0, 27.0), tvos(16.0, 27.0), watchos(1.0, 27.0), visionos(1.0, 27.0))
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVQueuedSampleBufferRendering.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVQueuedSampleBufferRendering.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVQueuedSampleBufferRendering.h 2026-05-27 00:52:40
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVQueuedSampleBufferRendering.h 2026-06-13 01:14:46
@@ -14,19 +14,13 @@
NS_ASSUME_NONNULL_BEGIN
-/*!
- @enum AVQueuedSampleBufferRenderingStatus
- @abstract These constants are the possible status values for queued sample buffer renderers.
- @constant AVQueuedSampleBufferRenderingStatusUnknown
- Indicates that the receiver is in a fresh state without any sample buffers enqueued on it.
- @constant AVQueuedSampleBufferRenderingStatusRendering
- Indicates at least one sample buffer has been enqueued on the receiver.
- @constant AVQueuedSampleBufferRenderingStatusFailed
- Indicates that the receiver cannot currently enqueue or render sample buffers because of an error.
- */
+/// These constants are the possible status values for queued sample buffer renderers.
typedef NS_ENUM(NSInteger, AVQueuedSampleBufferRenderingStatus) {
+ /// Indicates that the receiver is in a fresh state without any sample buffers enqueued on it.
AVQueuedSampleBufferRenderingStatusUnknown = 0,
+ /// Indicates at least one sample buffer has been enqueued on the receiver.
AVQueuedSampleBufferRenderingStatusRendering = 1,
+ /// Indicates that the receiver cannot currently enqueue or render sample buffers because of an error.
AVQueuedSampleBufferRenderingStatusFailed = 2
}
#if defined(__swift__)
@@ -36,39 +30,30 @@
#endif
;
-/*
- @protocol AVQueuedSampleBufferRendering
- @abstract Defines methods for enqueueing CMSampleBuffers for presentation.
- @discussion
- AVSampleBufferDisplayLayer and AVSampleBufferAudioRenderer conform to this protocol. When used in conjunction with an AVSampleBufferRenderSynchronizer, an object conforming to AVQueuedSampleBufferRendering can only be attached to a single synchronizer.
-*/
+/// Defines methods for enqueueing CMSampleBuffers for presentation.
+///
+/// AVSampleBufferDisplayLayer and AVSampleBufferAudioRenderer conform to this protocol. When used in conjunction with an AVSampleBufferRenderSynchronizer, an object conforming to AVQueuedSampleBufferRendering can only be attached to a single synchronizer.
API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0), visionos(1.0))
@protocol AVQueuedSampleBufferRendering <NSObject>
-/*!
- @property timebase
- @abstract The renderer's timebase, which governs how time stamps are interpreted.
- @discussion
- The timebase is used to interpret time stamps.
-
- The timebase is read-only. Use the AVSampleBufferRenderSynchronizer to set the rate or time.
-*/
+/// The renderer's timebase, which governs how time stamps are interpreted.
+///
+/// The timebase is used to interpret time stamps.
+///
+/// The timebase is read-only. Use the AVSampleBufferRenderSynchronizer to set the rate or time.
@property (retain, readonly) __attribute__((NSObject)) CMTimebaseRef timebase;
-/*!
- @method enqueueSampleBuffer:
- @abstract Sends a sample buffer in order to render its contents.
- @discussion
- Video-specific notes:
-
- If sampleBuffer has the kCMSampleAttachmentKey_DoNotDisplay attachment set to kCFBooleanTrue, the frame will be decoded but not displayed. Otherwise, if sampleBuffer has the kCMSampleAttachmentKey_DisplayImmediately attachment set to kCFBooleanTrue, the decoded image will be displayed as soon as possible, replacing all previously enqueued images regardless of their timestamps. Otherwise, the decoded image will be displayed at sampleBuffer's output presentation timestamp, as interpreted by the timebase.
-
- To schedule the removal of previous images at a specific timestamp, enqueue a marker sample buffer containing no samples, with the kCMSampleBufferAttachmentKey_EmptyMedia attachment set to kCFBooleanTrue.
-
- IMPORTANT NOTE: attachments with the kCMSampleAttachmentKey_ prefix must be set via CMSampleBufferGetSampleAttachmentsArray and CFDictionarySetValue. Attachments with the kCMSampleBufferAttachmentKey_ prefix must be set via CMSetAttachment.
-
- The combination of either a non-NULL controlTimebase or an AVSampleBufferRenderSynchronizer with the use of kCMSampleAttachmentKey_DisplayImmediately as an attachment to the CMSampleBuffers that are enqueued for display is not recommended.
-*/
+/// Sends a sample buffer in order to render its contents.
+///
+/// Video-specific notes:
+///
+/// If sampleBuffer has the kCMSampleAttachmentKey_DoNotDisplay attachment set to kCFBooleanTrue, the frame will be decoded but not displayed. Otherwise, if sampleBuffer has the kCMSampleAttachmentKey_DisplayImmediately attachment set to kCFBooleanTrue, the decoded image will be displayed as soon as possible, replacing all previously enqueued images regardless of their timestamps. Otherwise, the decoded image will be displayed at sampleBuffer's output presentation timestamp, as interpreted by the timebase.
+///
+/// To schedule the removal of previous images at a specific timestamp, enqueue a marker sample buffer containing no samples, with the kCMSampleBufferAttachmentKey_EmptyMedia attachment set to kCFBooleanTrue.
+///
+/// IMPORTANT NOTE: attachments with the kCMSampleAttachmentKey_ prefix must be set via CMSampleBufferGetSampleAttachmentsArray and CFDictionarySetValue. Attachments with the kCMSampleBufferAttachmentKey_ prefix must be set via CMSetAttachment.
+///
+/// The combination of either a non-NULL controlTimebase or an AVSampleBufferRenderSynchronizer with the use of kCMSampleAttachmentKey_DisplayImmediately as an attachment to the CMSampleBuffers that are enqueued for display is not recommended.
- (void)enqueueSampleBuffer:(CMSampleBufferRef)sampleBuffer
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver's enqueue(_:) async or enqueueImmediately(_:) methods instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -78,16 +63,13 @@
#endif
;
-/*!
- @method flush
- @abstract Instructs the receiver to discard pending enqueued sample buffers.
- @discussion
- Additional sample buffers can be appended after -flush.
-
- Video-specific notes:
-
- It is not possible to determine which sample buffers have been decoded, so the next frame passed to enqueueSampleBuffer: should be an IDR frame (also known as a key frame or sync sample).
-*/
+/// Instructs the receiver to discard pending enqueued sample buffers.
+///
+/// Additional sample buffers can be appended after -flush.
+///
+/// Video-specific notes:
+///
+/// It is not possible to determine which sample buffers have been decoded, so the next frame passed to enqueueSampleBuffer: should be an IDR frame (also known as a key frame or sync sample).
- (void)flush
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver's flush() method instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -97,22 +79,19 @@
#endif
;
-/*!
- @property readyForMoreMediaData
- @abstract Indicates the readiness of the receiver to accept more sample buffers.
- @discussion
- An object conforming to AVQueuedSampleBufferRendering keeps track of the occupancy levels of its internal queues for the benefit of clients that enqueue sample buffers from non-real-time sources -- i.e., clients that can supply sample buffers faster than they are consumed, and so need to decide when to hold back.
-
- Clients enqueueing sample buffers from non-real-time sources may hold off from generating or obtaining more sample buffers to enqueue when the value of readyForMoreMediaData is NO.
-
- It is safe to call enqueueSampleBuffer: when readyForMoreMediaData is NO, but it is a bad idea to enqueue sample buffers without bound.
-
- To help with control of the non-real-time supply of sample buffers, such clients can use -requestMediaDataWhenReadyOnQueue:usingBlock in order to specify a block that the receiver should invoke whenever it's ready for sample buffers to be appended.
-
- The value of readyForMoreMediaData will often change from NO to YES asynchronously, as previously supplied sample buffers are decoded and rendered.
-
- This property is not key value observable.
-*/
+/// Indicates the readiness of the receiver to accept more sample buffers.
+///
+/// An object conforming to AVQueuedSampleBufferRendering keeps track of the occupancy levels of its internal queues for the benefit of clients that enqueue sample buffers from non-real-time sources -- i.e., clients that can supply sample buffers faster than they are consumed, and so need to decide when to hold back.
+///
+/// Clients enqueueing sample buffers from non-real-time sources may hold off from generating or obtaining more sample buffers to enqueue when the value of readyForMoreMediaData is NO.
+///
+/// It is safe to call enqueueSampleBuffer: when readyForMoreMediaData is NO, but it is a bad idea to enqueue sample buffers without bound.
+///
+/// To help with control of the non-real-time supply of sample buffers, such clients can use -requestMediaDataWhenReadyOnQueue:usingBlock in order to specify a block that the receiver should invoke whenever it's ready for sample buffers to be appended.
+///
+/// The value of readyForMoreMediaData will often change from NO to YES asynchronously, as previously supplied sample buffers are decoded and rendered.
+///
+/// This property is not key value observable.
@property (readonly, getter=isReadyForMoreMediaData) BOOL readyForMoreMediaData
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver's enqueue(_:) async method on its own detached Task to suspend until it is ready for more media data instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), watchos(4.0, 27.0), visionos(1.0, 27.0))
@@ -121,16 +100,13 @@
#endif
;
-/*!
- @method requestMediaDataWhenReadyOnQueue:usingBlock:
- @abstract Instructs the target to invoke a client-supplied block repeatedly, at its convenience, in order to gather sample buffers for playback.
- @discussion
- The block should enqueue sample buffers to the receiver either until the receiver's readyForMoreMediaData property becomes NO or until there is no more data to supply. When the receiver has decoded enough of the media data it has received that it becomes ready for more media data again, it will invoke the block again in order to obtain more.
-
- If this method is called multiple times, only the last call is effective. Call stopRequestingMediaData to cancel this request.
-
- Each call to requestMediaDataWhenReadyOnQueue:usingBlock: should be paired with a corresponding call to stopRequestingMediaData:. Releasing the AVQueuedSampleBufferRendering object without a call to stopRequestingMediaData will result in undefined behavior.
-*/
+/// Instructs the target to invoke a client-supplied block repeatedly, at its convenience, in order to gather sample buffers for playback.
+///
+/// The block should enqueue sample buffers to the receiver either until the receiver's readyForMoreMediaData property becomes NO or until there is no more data to supply. When the receiver has decoded enough of the media data it has received that it becomes ready for more media data again, it will invoke the block again in order to obtain more.
+///
+/// If this method is called multiple times, only the last call is effective. Call stopRequestingMediaData to cancel this request.
+///
+/// Each call to requestMediaDataWhenReadyOnQueue:usingBlock: should be paired with a corresponding call to stopRequestingMediaData:. Releasing the AVQueuedSampleBufferRendering object without a call to stopRequestingMediaData will result in undefined behavior.
- (void)requestMediaDataWhenReadyOnQueue:(dispatch_queue_t)queue usingBlock:(void (^ NS_SWIFT_SENDABLE)(void))block
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver to enqueue samples on a detached Task instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -140,12 +116,9 @@
#endif
;
-/*!
- @method stopRequestingMediaData
- @abstract Cancels any current requestMediaDataWhenReadyOnQueue:usingBlock: call.
- @discussion
- This method may be called from outside the block or from within the block.
-*/
+/// Cancels any current requestMediaDataWhenReadyOnQueue:usingBlock: call.
+///
+/// This method may be called from outside the block or from within the block.
- (void)stopRequestingMediaData
#if defined(__swift__)
API_DEPRECATED("Cancel the receiver's Task instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -155,11 +128,9 @@
#endif
;
-/*!
- @property hasSufficientMediaDataForReliablePlaybackStart
- @abstract Indicates whether the enqueued media data meets the renderer's preroll level.
- @discussion Clients should fetch the value of this property to learn if the renderer has had enough media data enqueued to start playback reliably. Starting playback when this property is NO may prevent smooth playback following an immediate start.
- */
+/// Indicates whether the enqueued media data meets the renderer's preroll level.
+///
+/// Clients should fetch the value of this property to learn if the renderer has had enough media data enqueued to start playback reliably. Starting playback when this property is NO may prevent smooth playback following an immediate start.
@property (nonatomic, readonly) BOOL hasSufficientMediaDataForReliablePlaybackStart
#if defined(__swift__)
API_DEPRECATED("For smooth playback, attach the renderer to a render synchronizer and set the synchronizer's delaysRateChangeUntilHasSufficientMediaData property to true instead", macos(11.3, 27.0), ios(14.5, 27.0), tvos(14.5, 27.0), visionos(1.0, 27.0))
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferAudioRenderer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferAudioRenderer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferAudioRenderer.h 2026-05-29 23:09:27
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferAudioRenderer.h 2026-06-12 02:20:55
@@ -15,12 +15,9 @@
@class AVSampleBufferAudioRendererInternal;
-/*
- @class AVSampleBufferAudioRenderer
- @abstract AVSampleBufferAudioRenderer can decompress and play compressed or uncompressed audio.
- @discussion
- An instance of AVSampleBufferAudioRenderer must be added to an AVSampleBufferRenderSynchronizer before the first sample buffer is enqueued.
-*/
+/// AVSampleBufferAudioRenderer can decompress and play compressed or uncompressed audio.
+///
+/// An instance of AVSampleBufferAudioRenderer must be added to an AVSampleBufferRenderSynchronizer before the first sample buffer is enqueued.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(10.13), ios(11.0), tvos(11.0), watchos(4.0), visionos(1.0))
@interface AVSampleBufferAudioRenderer : NSObject <AVQueuedSampleBufferRendering>
@@ -29,18 +26,15 @@
AVSampleBufferAudioRendererInternal *_audioRendererInternal;
}
-/*
- @property status
- @abstract Indicates the status of the audio renderer.
- @discussion
- A renderer begins with status AVQueuedSampleBufferRenderingStatusUnknown.
-
- As sample buffers are enqueued for rendering using -enqueueSampleBuffer:, the renderer will transition to either AVQueuedSampleBufferRenderingStatusRendering or AVQueuedSampleBufferRenderingStatusFailed.
-
- If the status is AVQueuedSampleBufferRenderingStatusFailed, check the value of the renderer's error property for information on the error encountered. This is terminal status from which recovery is not always possible.
-
- This property is key value observable.
-*/
+/// Indicates the status of the audio renderer.
+///
+/// A renderer begins with status AVQueuedSampleBufferRenderingStatusUnknown.
+///
+/// As sample buffers are enqueued for rendering using -enqueueSampleBuffer:, the renderer will transition to either AVQueuedSampleBufferRenderingStatusRendering or AVQueuedSampleBufferRenderingStatusFailed.
+///
+/// If the status is AVQueuedSampleBufferRenderingStatusFailed, check the value of the renderer's error property for information on the error encountered. This is terminal status from which recovery is not always possible.
+///
+/// This property is key value observable.
@property (nonatomic, readonly) AVQueuedSampleBufferRenderingStatus status
#if defined(__swift__)
API_DEPRECATED("Use EnqueueResult from enqueue(_:) and enqueueImmediately(_:), and RenderingEvent from renderingEventsAfterFinishedEnqueuing instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -50,12 +44,9 @@
#endif
;
-/*
- @property error
- @abstract If the renderer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
- @discussion
- The value of this property is an NSError that describes what caused the renderer to no longer be able to render sample buffers. The value of this property is nil unless the value of status is AVQueuedSampleBufferRenderingStatusFailed.
-*/
+/// If the renderer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
+///
+/// The value of this property is an NSError that describes what caused the renderer to no longer be able to render sample buffers. The value of this property is nil unless the value of status is AVQueuedSampleBufferRenderingStatusFailed.
@property (nonatomic, readonly, nullable) NSError *error
#if defined(__swift__)
API_DEPRECATED("Use EnqueueResult from enqueue(_:) and enqueueImmediately(_:), and RenderingEvent from renderingEventsAfterFinishedEnqueuing instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -65,83 +56,66 @@
#endif
;
-/*!
- @property audioOutputDeviceUniqueID
- @abstract Specifies the unique ID of the Core Audio output device used to play audio.
- @discussion
- By default, the value of this property is nil, indicating that the default audio output device is used. Otherwise the value of this property is an NSString containing the unique ID of the Core Audio output device to be used for audio output.
- Core Audio's kAudioDevicePropertyDeviceUID is a suitable source of audio output device unique IDs.
-
- Modifying this property while the timebase's rate is not 0.0 may cause the rate to briefly change to 0.0.
-
- On macOS, the audio device clock may be used as the AVSampleBufferRenderSynchronizer's and all attached AVQueuedSampleBufferRendering's timebase's clocks. If the audioOutputDeviceUniqueID is modified, the clocks of all these timebases may also change.
-
- If multiple AVSampleBufferAudioRenderers with different values for audioOutputDeviceUniqueID are attached to the same AVSampleBufferRenderSynchronizer, audio may not stay in sync during playback. To avoid this, ensure that all synchronized AVSampleBufferAudioRenderers are using the same audio output device.
-*/
+/// Specifies the unique ID of the Core Audio output device used to play audio.
+///
+/// By default, the value of this property is nil, indicating that the default audio output device is used. Otherwise the value of this property is an NSString containing the unique ID of the Core Audio output device to be used for audio output.
+///
+/// Core Audio's kAudioDevicePropertyDeviceUID is a suitable source of audio output device unique IDs.
+///
+/// Modifying this property while the timebase's rate is not 0.0 may cause the rate to briefly change to 0.0.
+///
+/// On macOS, the audio device clock may be used as the AVSampleBufferRenderSynchronizer's and all attached AVQueuedSampleBufferRendering's timebase's clocks. If the audioOutputDeviceUniqueID is modified, the clocks of all these timebases may also change.
+///
+/// If multiple AVSampleBufferAudioRenderers with different values for audioOutputDeviceUniqueID are attached to the same AVSampleBufferRenderSynchronizer, audio may not stay in sync during playback. To avoid this, ensure that all synchronized AVSampleBufferAudioRenderers are using the same audio output device.
@property (nonatomic, copy, nullable) NSString *audioOutputDeviceUniqueID API_AVAILABLE(macos(10.13)) API_UNAVAILABLE(ios, tvos, watchos, visionos);
-/*!
- @property audioTimePitchAlgorithm
- @abstract Indicates the processing algorithm used to manage audio pitch at varying rates.
- @discussion
- Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
-
- The default value for applications linked on or after iOS 15.0 or macOS 12.0 is AVAudioTimePitchAlgorithmTimeDomain. For iOS versions prior to 15.0 the default value is AVAudioTimePitchAlgorithmLowQualityZeroLatency.
- For macOS versions prior to 12.0 the default value is AVAudioTimePitchAlgorithmSpectral.
-
- If the timebase's rate is not supported by the audioTimePitchAlgorithm, audio will be muted.
-
- Modifying this property while the timebase's rate is not 0.0 may cause the rate to briefly change to 0.0.
-*/
+/// Indicates the processing algorithm used to manage audio pitch at varying rates.
+///
+/// Constants for various time pitch algorithms, e.g. AVAudioTimePitchSpectral, are defined in AVAudioProcessingSettings.h.
+///
+/// The default value for applications linked on or after iOS 15.0 or macOS 12.0 is AVAudioTimePitchAlgorithmTimeDomain. For iOS versions prior to 15.0 the default value is AVAudioTimePitchAlgorithmLowQualityZeroLatency.
+/// For macOS versions prior to 12.0 the default value is AVAudioTimePitchAlgorithmSpectral.
+///
+/// If the timebase's rate is not supported by the audioTimePitchAlgorithm, audio will be muted.
+///
+/// Modifying this property while the timebase's rate is not 0.0 may cause the rate to briefly change to 0.0.
@property (nonatomic, copy) AVAudioTimePitchAlgorithm audioTimePitchAlgorithm;
-/*!
- @property allowedAudioSpatializationFormats
- @abstract Indicates the source audio channel layouts allowed by the receiver for spatialization.
- @discussion
- Spatialization uses psychoacoustic methods to create a more immersive audio rendering when the content is played on specialized headphones and speaker arrangements. When an AVSampleBufferAudioRenderer's allowedAudioSpatializationFormats property is set to AVAudioSpatializationFormatMonoAndStereo the AVSampleBufferAudioRenderer will attempt to spatialize content tagged with a stereo channel layout, two-channel content with no layout specified as well as mono. It is considered incorrect to render a binaural recording with spatialization. A binaural recording is captured using two carefully placed microphones at each ear where the intent, when played on headphones, is to reproduce a naturally occurring spatial effect. Content tagged with a binaural channel layout will ignore this property value. When an AVSampleBufferAudioRenderer's allowedAudioSpatializationFormats property is set to AVAudioSpatializationFormatMultichannel the AVSampleBufferAudioRenderer will attempt to spatialize any decodable multichannel layout. Setting this property to AVAudioSpatializationFormatMonoStereoAndMultichannel indicates that the sender allows the AVSampleBufferAudioRenderer to spatialize any decodable mono, stereo or multichannel layout. This property is not observable. The default value for this property is AVAudioSpatializationFormatMultichannel.
- */
+/// Indicates the source audio channel layouts allowed by the receiver for spatialization.
+///
+/// Spatialization uses psychoacoustic methods to create a more immersive audio rendering when the content is played on specialized headphones and speaker arrangements. When an AVSampleBufferAudioRenderer's allowedAudioSpatializationFormats property is set to AVAudioSpatializationFormatMonoAndStereo the AVSampleBufferAudioRenderer will attempt to spatialize content tagged with a stereo channel layout, two-channel content with no layout specified as well as mono. It is considered incorrect to render a binaural recording with spatialization. A binaural recording is captured using two carefully placed microphones at each ear where the intent, when played on headphones, is to reproduce a naturally occurring spatial effect. Content tagged with a binaural channel layout will ignore this property value. When an AVSampleBufferAudioRenderer's allowedAudioSpatializationFormats property is set to AVAudioSpatializationFormatMultichannel the AVSampleBufferAudioRenderer will attempt to spatialize any decodable multichannel layout. Setting this property to AVAudioSpatializationFormatMonoStereoAndMultichannel indicates that the sender allows the AVSampleBufferAudioRenderer to spatialize any decodable mono, stereo or multichannel layout. This property is not observable. The default value for this property is AVAudioSpatializationFormatMultichannel.
@property (nonatomic, assign) AVAudioSpatializationFormats allowedAudioSpatializationFormats API_AVAILABLE(macos(12.0), ios(15.0), tvos(15.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@interface AVSampleBufferAudioRenderer (AVSampleBufferAudioRendererVolumeControl)
-/*
- @property volume
- @abstract Indicates the current audio volume of the AVSampleBufferAudioRenderer.
- @discussion
- A value of 0.0 means "silence all audio", while 1.0 means "play at the full volume of the audio media".
-
- This property should be used for frequent volume changes, for example via a volume knob or fader.
-
- This property is most useful on iOS to control the volume of the AVSampleBufferAudioRenderer relative to other audio output, not for setting absolute volume.
-*/
+/// Indicates the current audio volume of the AVSampleBufferAudioRenderer.
+///
+/// A value of 0.0 means "silence all audio", while 1.0 means "play at the full volume of the audio media".
+///
+/// This property should be used for frequent volume changes, for example via a volume knob or fader.
+///
+/// This property is most useful on iOS to control the volume of the AVSampleBufferAudioRenderer relative to other audio output, not for setting absolute volume.
@property (nonatomic) float volume;
-/*
- @property muted
- @abstract Indicates whether or not audio output of the AVSampleBufferAudioRenderer is muted.
- @discussion
- Setting this property only affects audio muting for the renderer instance and not for the device.
- */
+/// Indicates whether or not audio output of the AVSampleBufferAudioRenderer is muted.
+///
+/// Setting this property only affects audio muting for the renderer instance and not for the device.
@property (nonatomic, getter=isMuted) BOOL muted;
@end
@interface AVSampleBufferAudioRenderer (AVSampleBufferAudioRendererQueueManagement)
-/*!
- @method flushFromSourceTime:completionHandler:
- @abstract Flushes enqueued sample buffers with presentation time stamps later than or equal to the specified time.
- @param completionHandler
- A block that is invoked, possibly asynchronously, after the flush operation completes or fails.
- @discussion
- This method can be used to replace media data scheduled to be rendered in the future, without interrupting playback. One example of this is when the data that has already been enqueued is from a sequence of two songs and the second song is swapped for a new song. In this case, this method would be called with the time stamp of the first sample buffer from the second song. After the completion handler is executed with a YES parameter, media data may again be enqueued with timestamps at the specified time.
-
- If NO is provided to the completion handler, the flush did not succeed and the set of enqueued sample buffers remains unchanged. A flush can fail becuse the source time was too close to (or earlier than) the current time or because the current configuration of the receiver does not support flushing at a particular time. In these cases, the caller can choose to flush all enqueued media data by invoking the -flush method.
- */
+/// Flushes enqueued sample buffers with presentation time stamps later than or equal to the specified time.
+///
+/// This method can be used to replace media data scheduled to be rendered in the future, without interrupting playback. One example of this is when the data that has already been enqueued is from a sequence of two songs and the second song is swapped for a new song. In this case, this method would be called with the time stamp of the first sample buffer from the second song. After the completion handler is executed with a YES parameter, media data may again be enqueued with timestamps at the specified time.
+///
+/// If NO is provided to the completion handler, the flush did not succeed and the set of enqueued sample buffers remains unchanged. A flush can fail becuse the source time was too close to (or earlier than) the current time or because the current configuration of the receiver does not support flushing at a particular time. In these cases, the caller can choose to flush all enqueued media data by invoking the -flush method.
+///
+/// - Parameter completionHandler: A block that is invoked, possibly asynchronously, after the flush operation completes or fails.
- (void)flushFromSourceTime:(CMTime)time completionHandler:(void (^ NS_SWIFT_SENDABLE)(BOOL flushSucceeded))completionHandler
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver's flush(fromSourceTime:) method instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -151,16 +125,13 @@
#endif
;
-/*!
- @constant AVSampleBufferAudioRendererWasFlushedAutomaticallyNotification
- @abstract A notification that fires whenever the receiver's enqueued media data has been flushed for a reason other than a call to the -flush method.
- @discussion
- The renderer may flush enqueued media data when the user routes playback to a new destination. The renderer may also flush enqueued media data when the playback rate of the attached AVSampleBufferRenderSynchronizer is changed (e.g. 1.0 -> 2.0 or 1.0 -> 0.0 -> 2.0), however no flush will occur for normal pauses (non-zero -> 0.0) and resumes (0.0 -> same non-zero rate as before).
-
- When an automatic flush occurs, the attached render synchronizer's timebase will remain running at its current rate. It is typically best to respond to this notification by enqueueing media data with timestamps starting at the timebase's current time. To the listener, this will sound similar to muting the audio for a short period of time. If it is more desirable to ensure that all audio is played than to keep the timeline moving, you may also stop the synchronizer, set the synchronizer's current time to the value of AVSampleBufferAudioRendererFlushTimeKey, start reenqueueing sample buffers with timestamps starting at that time, and restart the synchronizer. To the listener, this will sound similar to pausing the audio for a short period of time.
-
- This notification is delivered on an arbitrary thread. If sample buffers are being enqueued with the renderer concurrently with the receipt of this notification, it is possible that one or more sample buffers will remain enqueued in the renderer. This is generally undesirable, because the sample buffers that remain will likely have timestamps far ahead of the timebase's current time and so won't be rendered for some time. The best practice is to invoke the -flush method, in a manner that is serialized with enqueueing sample buffers, after receiving this notification and before resuming the enqueueing of sample buffers.
- */
+/// A notification that fires whenever the receiver's enqueued media data has been flushed for a reason other than a call to the -flush method.
+///
+/// The renderer may flush enqueued media data when the user routes playback to a new destination. The renderer may also flush enqueued media data when the playback rate of the attached AVSampleBufferRenderSynchronizer is changed (e.g. 1.0 -> 2.0 or 1.0 -> 0.0 -> 2.0), however no flush will occur for normal pauses (non-zero -> 0.0) and resumes (0.0 -> same non-zero rate as before).
+///
+/// When an automatic flush occurs, the attached render synchronizer's timebase will remain running at its current rate. It is typically best to respond to this notification by enqueueing media data with timestamps starting at the timebase's current time. To the listener, this will sound similar to muting the audio for a short period of time. If it is more desirable to ensure that all audio is played than to keep the timeline moving, you may also stop the synchronizer, set the synchronizer's current time to the value of AVSampleBufferAudioRendererFlushTimeKey, start reenqueueing sample buffers with timestamps starting at that time, and restart the synchronizer. To the listener, this will sound similar to pausing the audio for a short period of time.
+///
+/// This notification is delivered on an arbitrary thread. If sample buffers are being enqueued with the renderer concurrently with the receipt of this notification, it is possible that one or more sample buffers will remain enqueued in the renderer. This is generally undesirable, because the sample buffers that remain will likely have timestamps far ahead of the timebase's current time and so won't be rendered for some time. The best practice is to invoke the -flush method, in a manner that is serialized with enqueueing sample buffers, after receiving this notification and before resuming the enqueueing of sample buffers.
AVF_EXPORT NSNotificationName const AVSampleBufferAudioRendererWasFlushedAutomaticallyNotification
#if defined(__swift__)
API_DEPRECATED("Use the result of AVSampleBufferAudioRenderer.Receiver enqueue(_:) and enqueueImmediately(_:) for .successWithSuggestedFlushReason instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
@@ -170,12 +141,9 @@
#endif
;
-/*!
- @constant AVSampleBufferAudioRendererOutputConfigurationDidChangeNotification
- @abstract A notification that indicates the hardware configuration does not match the enqueued data format.
- @discussion
- The output configuration of the playback hardware might change during the playback session if other clients play content with different format. In such cases, if the media content format does not match the hardware configuration it would produce suboptimal rendering of the enqueued media data. When the framework detects such mismatch it will issue this notification, so the client can flush the renderer and re-enqueue the sample buffers from the current media playhead, which will configure the hardware based on the format of newly enqueued sample buffers.
- */
+/// A notification that indicates the hardware configuration does not match the enqueued data format.
+///
+/// The output configuration of the playback hardware might change during the playback session if other clients play content with different format. In such cases, if the media content format does not match the hardware configuration it would produce suboptimal rendering of the enqueued media data. When the framework detects such mismatch it will issue this notification, so the client can flush the renderer and re-enqueue the sample buffers from the current media playhead, which will configure the hardware based on the format of newly enqueued sample buffers.
AVF_EXPORT NSNotificationName const AVSampleBufferAudioRendererOutputConfigurationDidChangeNotification
#if defined(__swift__)
API_DEPRECATED("Use the result of AVSampleBufferAudioRenderer.Receiver enqueue(_:) and enqueueImmediately(_:) for .successWithSuggestedFlushReason instead", macos(12.0, 27.0), ios(15.0, 27.0), tvos(15.0, 27.0), visionos(1.0, 27.0))
@@ -185,13 +153,10 @@
#endif
;
- /*!
- @constant AVSampleBufferAudioRendererFlushTimeKey
- @abstract The presentation timestamp of the first enqueued sample that was flushed.
- @discussion
- The value of this key is an NSValue wrapping a CMTime.
- */
- AVF_EXPORT NSString * const AVSampleBufferAudioRendererFlushTimeKey
+/// The presentation timestamp of the first enqueued sample that was flushed.
+///
+/// The value of this key is an NSValue wrapping a CMTime.
+AVF_EXPORT NSString * const AVSampleBufferAudioRendererFlushTimeKey
#if defined(__swift__)
API_DEPRECATED("Use the result of AVSampleBufferAudioRenderer.Receiver enqueue(_:) and enqueueImmediately(_:) for .successWithSuggestedFlushReason instead", macos(10.13, 27.0), ios(11.0, 27.0), tvos(11.0, 27.0), visionos(1.0, 27.0))
API_DEPRECATED("Use the result of AVSampleBufferAudioRenderer.Receiver enqueue(_:) and enqueueImmediately(_:) for .successWithSuggestedFlushReason instead", watchos(4.0, 27.0))
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferDisplayLayer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferDisplayLayer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferDisplayLayer.h 2026-05-29 23:09:28
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferDisplayLayer.h 2026-06-13 20:53:44
@@ -8,12 +8,7 @@
*/
-/*!
- @class AVSampleBufferDisplayLayer
- @abstract AVSampleBufferDisplayLayer is a subclass of CALayer that can decompress and display compressed or uncompressed video frames.
-*/
-
#import <AVFoundation/AVBase.h>
#import <AVFoundation/AVAnimation.h>
#import <AVFoundation/AVQueuedSampleBufferRendering.h>
@@ -36,46 +31,32 @@
AVF_EXPORT NSNotificationName const AVSampleBufferDisplayLayerReadyForDisplayDidChangeNotification API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos); // see readyForDisplay property
+/// AVSampleBufferDisplayLayer is a subclass of CALayer that can decompress and display compressed or uncompressed video frames.
NS_SWIFT_UI_ACTOR
API_AVAILABLE(macos(10.8), ios(8.0), tvos(10.2), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferDisplayLayer : CALayer
-/*!
- @property controlTimebase
- @abstract The layer's control timebase, which governs how time stamps are interpreted.
- @discussion By default, this property is NULL, in which case time stamps will be interpreted
- according to the host time clock (mach_absolute_time with the appropriate timescale
- conversion; this is the same as Core Animation's CACurrentMediaTime). With no
- control timebase, once frames are enqueued, it is not possible to adjust exactly
- when they are displayed.
-
- If a non-NULL control timebase is set, it will be used to interpret time stamps.
- You can control the timing of frame display by setting the rate and time of the
- control timebase.
- If you are synchronizing video to audio, you can use a timebase whose source clock
- is a CMAudioDeviceClock for the appropriate audio device to prevent drift.
-
- Note that prior to OSX 10.10 and iOS 8.0, the control timebase could not be changed after enqueueSampleBuffer: was called. As of OSX 10.10 and iOS 8.0, the control timebase may be changed at any time.
-*/
+/// The layer's control timebase, which governs how time stamps are interpreted.
+///
+/// By default, this property is NULL, in which case time stamps will be interpreted
+/// according to the host time clock (mach_absolute_time with the appropriate timescale
+/// conversion; this is the same as Core Animation's CACurrentMediaTime). With no
+/// control timebase, once frames are enqueued, it is not possible to adjust exactly
+/// when they are displayed.
+///
+/// If a non-NULL control timebase is set, it will be used to interpret time stamps.
+/// You can control the timing of frame display by setting the rate and time of the
+/// control timebase.
+/// If you are synchronizing video to audio, you can use a timebase whose source clock
+/// is a CMAudioDeviceClock for the appropriate audio device to prevent drift.
+///
+/// Note that prior to OSX 10.10 and iOS 8.0, the control timebase could not be changed after enqueueSampleBuffer: was called. As of OSX 10.10 and iOS 8.0, the control timebase may be changed at any time.
@property (retain, nullable) __attribute__((NSObject)) CMTimebaseRef controlTimebase;
-/*!
- @property videoGravity
- @abstract A string defining how the video is displayed within an AVSampleBufferDisplayLayer bounds rect.
- @discusssion Options are AVLayerVideoGravityResizeAspect, AVLayerVideoGravityResizeAspectFill
- and AVLayerVideoGravityResize. AVLayerVideoGravityResizeAspect is default.
- See <AVFoundation/AVAnimation.h> for a description of these options.
- */
+/// A string defining how the video is displayed within an AVSampleBufferDisplayLayer bounds rect. @discusssion Options are AVLayerVideoGravityResizeAspect, AVLayerVideoGravityResizeAspectFill and AVLayerVideoGravityResize. AVLayerVideoGravityResizeAspect is default. See <AVFoundation/AVAnimation.h> for a description of these options.
@property(copy) AVLayerVideoGravity videoGravity;
-/*!
- @property readyForDisplay
- @abstract Boolean indicating that the first video frame has been made ready for display.
- @discusssion Use this property as an indicator of when best to show or animate-in an AVSampleBufferDisplayLayer into view.
- An AVSampleBufferDisplayLayer may be displayed, or made visible, while this property is NO, however the layer will not have any user-visible content until the value becomes YES. Note that if an animation is added to an AVSampleBufferDisplayLayer before it becomes readyForDisplay the video image displayed inside might not animate with the receiver.
- readyForDisplay will change to NO when the layer can no longer display frames. readyForDisplay will be YES when the first video frame has been made ready for display.
- This property is not key-value observable. AVSampleBufferDisplayLayerReadyForDisplayDidChangeNotification is posted when this value changes.
- */
+/// Boolean indicating that the first video frame has been made ready for display. @discusssion Use this property as an indicator of when best to show or animate-in an AVSampleBufferDisplayLayer into view. An AVSampleBufferDisplayLayer may be displayed, or made visible, while this property is NO, however the layer will not have any user-visible content until the value becomes YES. Note that if an animation is added to an AVSampleBufferDisplayLayer before it becomes readyForDisplay the video image displayed inside might not animate with the receiver. readyForDisplay will change to NO when the layer can no longer display frames. readyForDisplay will be YES when the first video frame has been made ready for display. This property is not key-value observable. AVSampleBufferDisplayLayerReadyForDisplayDidChangeNotification is posted when this value changes.
@property (nonatomic, readonly, getter=isReadyForDisplay) BOOL readyForDisplay API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
@end
@@ -84,146 +65,122 @@
API_AVAILABLE(macos(10.8), ios(8.0), tvos(10.2), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferDisplayLayer (AVSampleBufferDisplayLayerQueueManagement) <AVQueuedSampleBufferRendering>
-/*!
- @property timebase
- @abstract The renderer's timebase, which governs how time stamps are interpreted.
- @discussion
- The timebase is used to interpret time stamps.
-
- The timebase is read-only. Use the AVSampleBufferRenderSynchronizer to set the rate or time.
-*/
+/// The renderer's timebase, which governs how time stamps are interpreted.
+///
+/// The timebase is used to interpret time stamps.
+///
+/// The timebase is read-only. Use the AVSampleBufferRenderSynchronizer to set the rate or time.
@property (retain, readonly) __attribute__((NSObject)) CMTimebaseRef timebase API_DEPRECATED("Use sampleBufferRenderer's timebase instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @property status
- @abstract The ability of the display layer to be used for enqueuing sample buffers.
- @discussion The value of this property is an AVQueuedSampleBufferRenderingStatus that indicates whether the receiver can be used for enqueuing and rendering sample buffers. When the value of this property is AVQueuedSampleBufferRenderingStatusFailed, clients can check the value of the error property to determine the failure. To resume rendering sample buffers using the display layer after a failure, clients must first reset the status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the display layer.
-
- This property is key value observable.
- */
+/// The ability of the display layer to be used for enqueuing sample buffers.
+///
+/// The value of this property is an AVQueuedSampleBufferRenderingStatus that indicates whether the receiver can be used for enqueuing and rendering sample buffers. When the value of this property is AVQueuedSampleBufferRenderingStatusFailed, clients can check the value of the error property to determine the failure. To resume rendering sample buffers using the display layer after a failure, clients must first reset the status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the display layer.
+///
+/// This property is key value observable.
@property (nonatomic, readonly) AVQueuedSampleBufferRenderingStatus status API_DEPRECATED("Use sampleBufferRenderer's status instead", macos(10.10, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @property error
- @abstract If the display layer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
- @discussion The value of this property is an NSError that describes what caused the display layer to no longer be able to enqueue sample buffers. If the status is not AVQueuedSampleBufferRenderingStatusFailed, the value of this property is nil.
- */
+/// If the display layer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
+///
+/// The value of this property is an NSError that describes what caused the display layer to no longer be able to enqueue sample buffers. If the status is not AVQueuedSampleBufferRenderingStatusFailed, the value of this property is nil.
@property (nonatomic, readonly, nullable) NSError *error API_DEPRECATED("Use sampleBufferRenderer's error instead", macos(10.10, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @method enqueueSampleBuffer:
- @abstract Sends a sample buffer for display.
- @discussion If sampleBuffer has the kCMSampleAttachmentKey_DoNotDisplay attachment set to
- kCFBooleanTrue, the frame will be decoded but not displayed.
- Otherwise, if sampleBuffer has the kCMSampleAttachmentKey_DisplayImmediately
- attachment set to kCFBooleanTrue, the decoded image will be displayed as soon
- as possible, replacing all previously enqueued images regardless of their timestamps.
- Otherwise, the decoded image will be displayed at sampleBuffer's output presentation
- timestamp, as interpreted by the control timebase (or the mach_absolute_time timeline
- if there is no control timebase).
-
- To schedule the removal of previous images at a specific timestamp, enqueue
- a marker sample buffer containing no samples, with the
- kCMSampleBufferAttachmentKey_EmptyMedia attachment set to kCFBooleanTrue.
-
- IMPORTANT NOTE: attachments with the kCMSampleAttachmentKey_ prefix must be set via
- CMSampleBufferGetSampleAttachmentsArray and CFDictionarySetValue.
- Attachments with the kCMSampleBufferAttachmentKey_ prefix must be set via
- CMSetAttachment.
-
- IMPORTANT NOTE: When using CMSampleBuffers that wrap CVPixelBuffer, it is important that such CVPixelBuffers be IOSurface-backed.
- CoreVideo allocates IOSurface-backed CVPixelBuffers when the pixel buffer attribute dictionary passed to CVPixelBufferPoolCreate contains
- an entry with key kCVPixelBufferIOSurfacePropertiesKey and value being a dictionary (which can be an empty dictionary).
-
- The combination of either a non-NULL controlTimebase or an AVSampleBufferRenderSynchronizer with the use of kCMSampleAttachmentKey_DisplayImmediately as an attachment to the CMSampleBuffers that are enqueued for display is not recommended.
- */
+/// Sends a sample buffer for display.
+///
+/// If sampleBuffer has the kCMSampleAttachmentKey_DoNotDisplay attachment set to
+/// kCFBooleanTrue, the frame will be decoded but not displayed.
+/// Otherwise, if sampleBuffer has the kCMSampleAttachmentKey_DisplayImmediately
+/// attachment set to kCFBooleanTrue, the decoded image will be displayed as soon
+/// as possible, replacing all previously enqueued images regardless of their timestamps.
+/// Otherwise, the decoded image will be displayed at sampleBuffer's output presentation
+/// timestamp, as interpreted by the control timebase (or the mach_absolute_time timeline
+/// if there is no control timebase).
+///
+/// To schedule the removal of previous images at a specific timestamp, enqueue
+/// a marker sample buffer containing no samples, with the
+/// kCMSampleBufferAttachmentKey_EmptyMedia attachment set to kCFBooleanTrue.
+///
+/// IMPORTANT NOTE: attachments with the kCMSampleAttachmentKey_ prefix must be set via
+/// CMSampleBufferGetSampleAttachmentsArray and CFDictionarySetValue.
+/// Attachments with the kCMSampleBufferAttachmentKey_ prefix must be set via
+/// CMSetAttachment.
+///
+/// IMPORTANT NOTE: When using CMSampleBuffers that wrap CVPixelBuffer, it is important that such CVPixelBuffers be IOSurface-backed.
+/// CoreVideo allocates IOSurface-backed CVPixelBuffers when the pixel buffer attribute dictionary passed to CVPixelBufferPoolCreate contains
+/// an entry with key kCVPixelBufferIOSurfacePropertiesKey and value being a dictionary (which can be an empty dictionary).
+///
+/// The combination of either a non-NULL controlTimebase or an AVSampleBufferRenderSynchronizer with the use of kCMSampleAttachmentKey_DisplayImmediately as an attachment to the CMSampleBuffers that are enqueued for display is not recommended.
- (void)enqueueSampleBuffer:(CMSampleBufferRef)sampleBuffer API_DEPRECATED("Use sampleBufferRenderer's enqueueSampleBuffer: instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @method flush
- @abstract Instructs the layer to discard pending enqueued sample buffers.
- @discussion It is not possible to determine which sample buffers have been decoded,
- so the next frame passed to enqueueSampleBuffer: should be an IDR frame
- (also known as a key frame or sync sample).
-*/
+/// Instructs the layer to discard pending enqueued sample buffers.
+///
+/// It is not possible to determine which sample buffers have been decoded,
+/// so the next frame passed to enqueueSampleBuffer: should be an IDR frame
+/// (also known as a key frame or sync sample).
- (void)flush API_DEPRECATED("Use sampleBufferRenderer's flush instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @method flushAndRemoveImage
- @abstract Instructs the layer to discard pending enqueued sample buffers and remove any
- currently displayed image.
- @discussion It is not possible to determine which sample buffers have been decoded,
- so the next frame passed to enqueueSampleBuffer: should be an IDR frame
- (also known as a key frame or sync sample).
-*/
+/// Instructs the layer to discard pending enqueued sample buffers and remove any currently displayed image.
+///
+/// It is not possible to determine which sample buffers have been decoded,
+/// so the next frame passed to enqueueSampleBuffer: should be an IDR frame
+/// (also known as a key frame or sync sample).
- (void)flushAndRemoveImage API_DEPRECATED("Use sampleBufferRenderer's flushWithRemovalOfDisplayedImage:completionHandler: instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @property requiresFlushToResumeDecoding
- @abstract Indicates that the receiver is in a state where it requires a call to -flush to continue decoding frames.
- @discussion When the application enters a state where use of video decoder resources is not permissible, the value of this property changes to YES along with the display layer's status changing to AVQueuedSampleBufferRenderingStatusFailed.
- To resume rendering sample buffers using the display layer after this property's value is YES, clients must first reset the display layer's status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the display layer.
- Clients can track changes to this property via AVSampleBufferDisplayLayerRequiresFlushToResumeDecodingDidChangeNotification.
- This property is not key value observable.
-*/
+/// Indicates that the receiver is in a state where it requires a call to -flush to continue decoding frames.
+///
+/// When the application enters a state where use of video decoder resources is not permissible, the value of this property changes to YES along with the display layer's status changing to AVQueuedSampleBufferRenderingStatusFailed.
+/// To resume rendering sample buffers using the display layer after this property's value is YES, clients must first reset the display layer's status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the display layer.
+/// Clients can track changes to this property via AVSampleBufferDisplayLayerRequiresFlushToResumeDecodingDidChangeNotification.
+/// This property is not key value observable.
@property (nonatomic, readonly) BOOL requiresFlushToResumeDecoding API_DEPRECATED("Use sampleBufferRenderer's requiresFlushToResumeDecoding instead", macos(11.0, 15.0), ios(14.0, 18.0), tvos(14.0, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @property readyForMoreMediaData
- @abstract Indicates the readiness of the layer to accept more sample buffers.
- @discussion AVSampleBufferDisplayLayer keeps track of the occupancy levels of its internal queues
- for the benefit of clients that enqueue sample buffers from non-real-time sources --
- i.e., clients that can supply sample buffers faster than they are consumed, and so
- need to decide when to hold back.
-
- Clients enqueueing sample buffers from non-real-time sources may hold off from
- generating or obtaining more sample buffers to enqueue when the value of
- readyForMoreMediaData is NO.
-
- It is safe to call enqueueSampleBuffer: when readyForMoreMediaData is NO, but
- it is a bad idea to enqueue sample buffers without bound.
-
- To help with control of the non-real-time supply of sample buffers, such clients can use
- -requestMediaDataWhenReadyOnQueue:usingBlock
- in order to specify a block that the layer should invoke whenever it's ready for
- sample buffers to be appended.
-
- The value of readyForMoreMediaData will often change from NO to YES asynchronously,
- as previously supplied sample buffers are decoded and displayed.
-
- This property is not key value observable.
-*/
+
+/// Indicates the readiness of the layer to accept more sample buffers.
+///
+/// AVSampleBufferDisplayLayer keeps track of the occupancy levels of its internal queues
+/// for the benefit of clients that enqueue sample buffers from non-real-time sources --
+/// i.e., clients that can supply sample buffers faster than they are consumed, and so
+/// need to decide when to hold back.
+///
+/// Clients enqueueing sample buffers from non-real-time sources may hold off from
+/// generating or obtaining more sample buffers to enqueue when the value of
+/// readyForMoreMediaData is NO.
+///
+/// It is safe to call enqueueSampleBuffer: when readyForMoreMediaData is NO, but
+/// it is a bad idea to enqueue sample buffers without bound.
+///
+/// To help with control of the non-real-time supply of sample buffers, such clients can use
+/// -requestMediaDataWhenReadyOnQueue:usingBlock
+/// in order to specify a block that the layer should invoke whenever it's ready for
+/// sample buffers to be appended.
+///
+/// The value of readyForMoreMediaData will often change from NO to YES asynchronously,
+/// as previously supplied sample buffers are decoded and displayed.
+///
+/// This property is not key value observable.
@property (readonly, getter=isReadyForMoreMediaData) BOOL readyForMoreMediaData API_DEPRECATED("Use sampleBufferRenderer's readyForMoreMediaData instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @method requestMediaDataWhenReadyOnQueue:usingBlock:
- @abstract Instructs the target to invoke a client-supplied block repeatedly,
- at its convenience, in order to gather sample buffers for display.
- @discussion The block should enqueue sample buffers to the layer either until the layer's
- readyForMoreMediaData property becomes NO or until there is no more data
- to supply. When the layer has decoded enough of the media data it has received
- that it becomes ready for more media data again, it will invoke the block again
- in order to obtain more.
- If this function is called multiple times, only the last call is effective.
- Call stopRequestingMediaData to cancel this request.
- Each call to requestMediaDataWhenReadyOnQueue:usingBlock: should be paired
- with a corresponding call to stopRequestingMediaData:. Releasing the
- AVSampleBufferDisplayLayer without a call to stopRequestingMediaData will result
- in undefined behavior.
-*/
+/// Instructs the target to invoke a client-supplied block repeatedly, at its convenience, in order to gather sample buffers for display.
+///
+/// The block should enqueue sample buffers to the layer either until the layer's
+/// readyForMoreMediaData property becomes NO or until there is no more data
+/// to supply. When the layer has decoded enough of the media data it has received
+/// that it becomes ready for more media data again, it will invoke the block again
+/// in order to obtain more.
+/// If this function is called multiple times, only the last call is effective.
+/// Call stopRequestingMediaData to cancel this request.
+/// Each call to requestMediaDataWhenReadyOnQueue:usingBlock: should be paired
+/// with a corresponding call to stopRequestingMediaData:. Releasing the
+/// AVSampleBufferDisplayLayer without a call to stopRequestingMediaData will result
+/// in undefined behavior.
- (void)requestMediaDataWhenReadyOnQueue:(dispatch_queue_t)queue usingBlock:(void (^ NS_SWIFT_SENDABLE)(void))block API_DEPRECATED("Use sampleBufferRenderer's requestMediaDataWhenReadyOnQueue:usingBlock: instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @method stopRequestingMediaData
- @abstract Cancels any current requestMediaDataWhenReadyOnQueue:usingBlock: call.
- @discussion This method may be called from outside the block or from within the block.
-*/
+/// Cancels any current requestMediaDataWhenReadyOnQueue:usingBlock: call.
+///
+/// This method may be called from outside the block or from within the block.
- (void)stopRequestingMediaData API_DEPRECATED("Use sampleBufferRenderer's stopRequestingMediaData instead", macos(10.8, 15.0), ios(8.0, 18.0), tvos(10.2, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
-/*!
- @property hasSufficientMediaDataForReliablePlaybackStart
- @abstract Indicates whether the enqueued media data meets the renderer's preroll level.
- @discussion Clients should fetch the value of this property to learn if the renderer has had enough media data enqueued to start playback reliably. Starting playback when this property is NO may prevent smooth playback following an immediate start.
- */
+/// Indicates whether the enqueued media data meets the renderer's preroll level.
+///
+/// Clients should fetch the value of this property to learn if the renderer has had enough media data enqueued to start playback reliably. Starting playback when this property is NO may prevent smooth playback following an immediate start.
@property (nonatomic, readonly) BOOL hasSufficientMediaDataForReliablePlaybackStart API_DEPRECATED("Use sampleBufferRenderer's hasSufficientMediaDataForReliablePlaybackStart instead", macos(11.3, 15.0), ios(14.5, 18.0), tvos(14.5, 18.0), visionos(1.0, 2.0)) API_UNAVAILABLE(watchos);
@end
@@ -231,10 +188,7 @@
API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferDisplayLayer (AVSampleBufferDisplayLayerImageProtection)
-/*!
- @property preventsCapture
- @abstract Indicates that image data should be protected from capture.
- */
+/// Indicates that image data should be protected from capture.
@property (nonatomic) BOOL preventsCapture API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
@@ -242,14 +196,11 @@
API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0)) API_UNAVAILABLE(watchos, visionos)
@interface AVSampleBufferDisplayLayer (AVSampleBufferDisplayLayerVideoDisplaySleepPrevention)
-/*!
- @property preventsDisplaySleepDuringVideoPlayback
- @abstract Indicates whether video playback prevents display and device sleep.
- @discussion
- Default is YES on iOS, tvOS and in Mac Catalyst apps. Default is NO on macOS.
- Setting this property to NO does not force the display to sleep, it simply stops preventing display sleep. Other apps or frameworks within your app may still be preventing display sleep for various reasons.
- Note: If sample buffers are being enqueued for playback at the user's request, you should ensure that the value of this property is set to YES. If video is not being displayed as part of the user's primary focus, you should ensure that the value of this property is set to NO.
- */
+/// Indicates whether video playback prevents display and device sleep.
+///
+/// Default is YES on iOS, tvOS and in Mac Catalyst apps. Default is NO on macOS.
+/// Setting this property to NO does not force the display to sleep, it simply stops preventing display sleep. Other apps or frameworks within your app may still be preventing display sleep for various reasons.
+/// Note: If sample buffers are being enqueued for playback at the user's request, you should ensure that the value of this property is set to YES. If video is not being displayed as part of the user's primary focus, you should ensure that the value of this property is set to NO.
@property (nonatomic) BOOL preventsDisplaySleepDuringVideoPlayback API_AVAILABLE(macos(10.15), ios(13.0), tvos(13.0)) API_UNAVAILABLE(watchos, visionos);
@end
@@ -257,14 +208,11 @@
API_AVAILABLE(visionos(1.0)) API_UNAVAILABLE(macos, ios, tvos, watchos)
@interface AVSampleBufferDisplayLayer (AVSampleBufferDisplayLayerAutomaticBackgroundPrevention)
-/*!
- @property preventsAutomaticBackgroundingDuringVideoPlayback
- @abstract Indicates whether video playback prevents the app from automatically getting backgrounded.
- @discussion
- Default is YES.
- Setting this property to YES prevents an application that is playing video from automatically getting backgrounded. This property does not prevent the user from backgrounding the application.
- Note: If sample buffers are being enqueued for playback at the user's request, you should ensure that the value of this property is set to YES. If video is not being displayed as part of the user's primary focus, you should ensure that the value of this property is set to NO.
- */
+/// Indicates whether video playback prevents the app from automatically getting backgrounded.
+///
+/// Default is YES.
+/// Setting this property to YES prevents an application that is playing video from automatically getting backgrounded. This property does not prevent the user from backgrounding the application.
+/// Note: If sample buffers are being enqueued for playback at the user's request, you should ensure that the value of this property is set to YES. If video is not being displayed as part of the user's primary focus, you should ensure that the value of this property is set to NO.
@property (nonatomic) BOOL preventsAutomaticBackgroundingDuringVideoPlayback API_AVAILABLE(visionos(1.0)) API_UNAVAILABLE(macos, ios, tvos, watchos);
@end
@@ -272,35 +220,29 @@
API_AVAILABLE(macos(11.3), ios(14.5), tvos(14.5), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferDisplayLayer (ProtectedContent)
-/*!
- @property outputObscuredDueToInsufficientExternalProtection
- @abstract Whether or not decoded output is being obscured due to insufficient external protection.
-
- @discussion
- The value of this property indicates whether the layer is purposefully obscuring its visual output
- because the requirement for an external protection mechanism is not met by the current device
- configuration. The change of this property can be observed through AVSampleBufferDisplayLayerOutputObscuredDueToInsufficientExternalProtectionDidChangeNotification
-
- It is highly recommended that clients whose content requires external
- protection observe this property and set the playback rate to zero and display an appropriate user
- interface when the value changes to YES.
-
- Note that the value of this property is dependent on the external protection requirements of the
- media being displayed by the layer. These requirements are inherent to the content itself and cannot
- be externally specified. If the content does not require external protection, the value of this
- property will be NO.
- */
+/// Whether or not decoded output is being obscured due to insufficient external protection.
+///
+/// The value of this property indicates whether the layer is purposefully obscuring its visual output
+/// because the requirement for an external protection mechanism is not met by the current device
+/// configuration. The change of this property can be observed through AVSampleBufferDisplayLayerOutputObscuredDueToInsufficientExternalProtectionDidChangeNotification
+///
+/// It is highly recommended that clients whose content requires external
+/// protection observe this property and set the playback rate to zero and display an appropriate user
+/// interface when the value changes to YES.
+///
+/// Note that the value of this property is dependent on the external protection requirements of the
+/// media being displayed by the layer. These requirements are inherent to the content itself and cannot
+/// be externally specified. If the content does not require external protection, the value of this
+/// property will be NO.
@property (nonatomic, readonly) BOOL outputObscuredDueToInsufficientExternalProtection API_AVAILABLE(macos(11.3), ios(14.5), tvos(14.5), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferDisplayLayer (AVSampleBufferDisplayLayerRenderer)
-/*!
- @property sampleBufferRenderer
- @abstract An AVSampleBufferVideoRenderer instance that allows enqueuing sample buffers for rendering.
- @discussion Although AVSampleBufferDisplayLayer conforms to the AVQueuedSampleBufferRendering protocol, the sampleBufferRenderer should be used to enqueue sample buffers. sampleBufferRenderer allows the client to safely enqueue sample buffers from a background thread. NOTE: Do not use AVSampleBufferDisplayLayer's AVQueuedSampleBufferRendering functions when using sampleBufferRenderer.
- */
+/// An AVSampleBufferVideoRenderer instance that allows enqueuing sample buffers for rendering.
+///
+/// Although AVSampleBufferDisplayLayer conforms to the AVQueuedSampleBufferRendering protocol, the sampleBufferRenderer should be used to enqueue sample buffers. sampleBufferRenderer allows the client to safely enqueue sample buffers from a background thread. NOTE: Do not use AVSampleBufferDisplayLayer's AVQueuedSampleBufferRendering functions when using sampleBufferRenderer.
@property (nonatomic, readonly) AVSampleBufferVideoRenderer *sampleBufferRenderer API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), visionos(1.0)) API_UNAVAILABLE(watchos);
@end
diff -ruN /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferVideoRenderer.h /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferVideoRenderer.h
--- /Applications/Xcode_27.0.0-beta.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferVideoRenderer.h 2026-05-27 01:19:14
+++ /Applications/Xcode_27.0.0-beta2.app/Contents/Developer/Platforms/AppleTVOS.platform/Developer/SDKs/AppleTVOS.sdk/System/Library/Frameworks/AVFoundation.framework/Headers/AVSampleBufferVideoRenderer.h 2026-06-12 02:20:57
@@ -8,12 +8,7 @@
*/
-/*!
- @class AVSampleBufferVideoRenderer
- @abstract AVSampleBufferVideoRenderer provides a mechanism to enqueue sample buffers for rendering.
-*/
-
#import <AVFoundation/AVBase.h>
#import <AVFoundation/AVQueuedSampleBufferRendering.h>
@@ -56,16 +51,15 @@
#endif
;
+/// AVSampleBufferVideoRenderer provides a mechanism to enqueue sample buffers for rendering.
NS_SWIFT_NONSENDABLE
API_AVAILABLE(macos(14.0), ios(17.0), tvos(17.0), visionos(1.0)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferVideoRenderer : NSObject <AVQueuedSampleBufferRendering>
-/*!
- @property status
- @abstract The ability of the video renderer to be used for enqueueing sample buffers.
- @discussion The value of this property is an AVQueuedSampleBufferRenderingStatus that indicates whether the receiver can be used for enqueueing and rendering sample buffers. When the value of this property is AVQueuedSampleBufferRenderingStatusFailed, clients can check the value of the error property to determine the failure. To resume rendering sample buffers using the video renderer after a failure, clients must first reset the status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the video renderer.
- This property is key value observable.
-*/
+/// The ability of the video renderer to be used for enqueueing sample buffers.
+///
+/// The value of this property is an AVQueuedSampleBufferRenderingStatus that indicates whether the receiver can be used for enqueueing and rendering sample buffers. When the value of this property is AVQueuedSampleBufferRenderingStatusFailed, clients can check the value of the error property to determine the failure. To resume rendering sample buffers using the video renderer after a failure, clients must first reset the status to AVQueuedSampleBufferRenderingStatusUnknown. This can be achieved by invoking -flush on the video renderer.
+/// This property is key value observable.
@property (readonly) AVQueuedSampleBufferRenderingStatus status
#if defined(__swift__)
API_DEPRECATED("Use EnqueueResult from enqueue(_:) and enqueueImmediately(_:), and RenderingEvent from renderingEventsAfterFinishedEnqueuing instead", macos(14.0, 27.0), ios(17.0, 27.0), tvos(17.0, 27.0), visionos(1.0, 27.0))
@@ -75,11 +69,9 @@
#endif
;
-/*!
- @property error
- @abstract If the video renderer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
- @discussion The value of this property is an NSError that describes what caused the video renderer to no longer be able to enqueue sample buffers. If the status is not AVQueuedSampleBufferRenderingStatusFailed, the value of this property is nil.
-*/
+/// If the video renderer's status is AVQueuedSampleBufferRenderingStatusFailed, this describes the error that caused the failure.
+///
+/// The value of this property is an NSError that describes what caused the video renderer to no longer be able to enqueue sample buffers. If the status is not AVQueuedSampleBufferRenderingStatusFailed, the value of this property is nil.
@property (readonly, nullable) NSError *error
#if defined(__swift__)
API_DEPRECATED("Use EnqueueResult from enqueue(_:) and enqueueImmediately(_:), and RenderingEvent from renderingEventsAfterFinishedEnqueuing instead", macos(14.0, 27.0), ios(17.0, 27.0), tvos(17.0, 27.0), visionos(1.0, 27.0))
@@ -89,14 +81,12 @@
#endif
;
-/*!
- @property requiresFlushToResumeDecoding
- @abstract Indicates that the receiver is in a state where it requires a call to -flush to continue decoding frames.
- @discussion When the application enters a state where use of video decoder resources is not permissible, the value of this property changes to YES along with the video renderer's status changing to AVQueuedSampleBufferRenderingStatusFailed.
- To resume rendering sample buffers using the video renderer after this property's value is YES, clients must first reset the video renderer by calling flush or flushWithRemovalOfDisplayedImage:completionHandler:.
- Clients can track changes to this property via AVSampleBufferVideoRendererRequiresFlushToResumeDecodingDidChangeNotification.
- This property is not key value observable.
-*/
+/// Indicates that the receiver is in a state where it requires a call to -flush to continue decoding frames.
+///
+/// When the application enters a state where use of video decoder resources is not permissible, the value of this property changes to YES along with the video renderer's status changing to AVQueuedSampleBufferRenderingStatusFailed.
+/// To resume rendering sample buffers using the video renderer after this property's value is YES, clients must first reset the video renderer by calling flush or flushWithRemovalOfDisplayedImage:completionHandler:.
+/// Clients can track changes to this property via AVSampleBufferVideoRendererRequiresFlushToResumeDecodingDidChangeNotification.
+/// This property is not key value observable.
@property (readonly) BOOL requiresFlushToResumeDecoding
#if defined(__swift__)
API_DEPRECATED("Use the result of AVSampleBufferVideoRenderer.Receiver enqueue(_:) and enqueueImmediately(_:) for .requiresFlushToResumeDecoding instead", macos(14.0, 27.0), ios(17.0, 27.0), tvos(17.0, 27.0), visionos(1.0, 27.0))
@@ -106,16 +96,12 @@
#endif
;
-/*!
- @method flushWithRemovalOfDisplayedImage:completionHandler:
- @abstract Instructs the video renderer to discard pending enqueued sample buffers and call the provided block when complete.
- @param removeDisplayedImage
- Set YES to remove any currently displayed image, NO to preserve any current image.
- @param handler
- The handler to invoke when flush operation is complete. May be nil.
- @discussion A flush resets decoder state. The next frame passed to enqueueSampleBuffer: should be an IDR frame (also known as a key frame or sync sample).
-*/
-
+/// Instructs the video renderer to discard pending enqueued sample buffers and call the provided block when complete.
+///
+/// A flush resets decoder state. The next frame passed to enqueueSampleBuffer: should be an IDR frame (also known as a key frame or sync sample).
+///
+/// - Parameter removeDisplayedImage: Set YES to remove any currently displayed image, NO to preserve any current image.
+/// - Parameter handler: The handler to invoke when flush operation is complete. May be nil.
- (void)flushWithRemovalOfDisplayedImage:(BOOL)removeDisplayedImage completionHandler:(nullable void (^ NS_SWIFT_SENDABLE)(void))handler
#if defined(__swift__)
API_DEPRECATED("Attach renderer to a render synchronizer with sampleBufferReceiver(adding:) and use the receiver's flush(removingDisplayedImage:) method instead", macos(14.0, 27.0), ios(17.0, 27.0), tvos(17.0, 27.0), visionos(1.0, 27.0))
@@ -129,13 +115,12 @@
API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferVideoRenderer (AVSampleBufferVideoRendererPixelBufferOutput)
-/*!
- @method copyDisplayedPixelBuffer
- @abstract Returns a retained reference to the pixel buffer currently displayed in the AVSampleBufferVideoRenderer's target. This will return NULL if the displayed pixel buffer is protected, no image is currently being displayed, or if the image is unavailable.
- @discussion This will return NULL if the rate is non-zero. Clients must release the pixel buffer after use.
-
- Do not write to the returned CVPixelBuffer's attachments or pixel data.
- */
+
+/// Returns a retained reference to the pixel buffer currently displayed in the AVSampleBufferVideoRenderer's target. This will return NULL if the displayed pixel buffer is protected, no image is currently being displayed, or if the image is unavailable.
+///
+/// This will return NULL if the rate is non-zero. Clients must release the pixel buffer after use.
+///
+/// Do not write to the returned CVPixelBuffer's attachments or pixel data.
- (nullable CVPixelBufferRef)copyDisplayedPixelBuffer CF_RETURNS_RETAINED API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
@end
@@ -143,43 +128,34 @@
API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferVideoRenderer (AVSampleBufferVideoRendererPowerOptimization)
-/*!
- @method expectMinimumUpcomingSampleBufferPresentationTime:
- @abstract Promises, for the purpose of enabling power optimizations, that future sample buffers will have PTS values no less than a specified lower-bound PTS.
- @discussion Only applicable for forward playback.
- Sending this message and later calling -enqueueSampleBuffer: with a buffer with a lower PTS has the potential to lead to dropping that later buffer.
- For best results, call -expectMinimumUpcomingSampleBufferPresentationTime: regularly, in between calls to -enqueueSampleBuffer:, to advance the lower-bound PTS.
- Messaging -flush resets such expectations.
- (For example, it's OK to make this expectation, then in response to a seek back, flush and then enqueue buffers with lower PTS values.)
- @param minimumUpcomingPresentationTime
- A lower bound on PTS values for buffers that will be passed to -enqueueSampleBuffer: in the future.
-*/
+/// Promises, for the purpose of enabling power optimizations, that future sample buffers will have PTS values no less than a specified lower-bound PTS.
+///
+/// Only applicable for forward playback.
+/// Sending this message and later calling -enqueueSampleBuffer: with a buffer with a lower PTS has the potential to lead to dropping that later buffer.
+/// For best results, call -expectMinimumUpcomingSampleBufferPresentationTime: regularly, in between calls to -enqueueSampleBuffer:, to advance the lower-bound PTS.
+/// Messaging -flush resets such expectations.
+/// (For example, it's OK to make this expectation, then in response to a seek back, flush and then enqueue buffers with lower PTS values.)
+///
+/// - Parameter minimumUpcomingPresentationTime: A lower bound on PTS values for buffers that will be passed to -enqueueSampleBuffer: in the future.
- (void)expectMinimumUpcomingSampleBufferPresentationTime:(CMTime)minimumUpcomingPresentationTime NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
-
-/*!
- @method expectMonotonicallyIncreasingUpcomingSampleBufferPresentationTimes
- @abstract Promises, for the purpose of enabling power optimizations, that future sample buffers will have monotonically increasing PTS values.
- @discussion Only applicable for forward playback.
- Sending this message and later calling -enqueueSampleBuffer: with a buffer with a lower PTS than any previously enqueued PTS has the potential to lead to dropped buffers.
- Messaging -flush resets such expectations.
-*/
+/// Promises, for the purpose of enabling power optimizations, that future sample buffers will have monotonically increasing PTS values.
+///
+/// Only applicable for forward playback.
+/// Sending this message and later calling -enqueueSampleBuffer: with a buffer with a lower PTS than any previously enqueued PTS has the potential to lead to dropped buffers.
+/// Messaging -flush resets such expectations.
- (void)expectMonotonicallyIncreasingUpcomingSampleBufferPresentationTimes NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
-/*!
- @method resetUpcomingSampleBufferPresentationTimeExpectations:
- @abstract Resets previously-promised expectations about upcoming sample buffer PTSs.
- @discussion This undoes the state set by messaging -expectMinimumUpcomingSampleBufferPresentationTime: or -expectMonotonicallyIncreasingUpcomingSampleBufferPresentationTimes.
- If you didn't use either of those, you don't have to use this.
-*/
+/// Resets previously-promised expectations about upcoming sample buffer PTSs.
+///
+/// This undoes the state set by messaging -expectMinimumUpcomingSampleBufferPresentationTime: or -expectMonotonicallyIncreasingUpcomingSampleBufferPresentationTimes.
+/// If you didn't use either of those, you don't have to use this.
- (void)resetUpcomingSampleBufferPresentationTimeExpectations NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
-/*!
- @property recommendedPixelBufferAttributes
- @abstract Recommended pixel buffer attributes for optimal performance when using CMSampleBuffers containing CVPixelBuffers.
- @discussion The returned dictionary does not contain all of the attributes needed for creating pixel buffers.
- Use ``CVPixelBufferCreateResolvedAttributesDictionary()`` to reconcile these attributes with the pixel buffer creation attributes.
-*/
+/// Recommended pixel buffer attributes for optimal performance when using CMSampleBuffers containing CVPixelBuffers.
+///
+/// The returned dictionary does not contain all of the attributes needed for creating pixel buffers.
+/// Use ``CVPixelBufferCreateResolvedAttributesDictionary()`` to reconcile these attributes with the pixel buffer creation attributes.
@property (readonly, nonnull) NSDictionary<NSString*, NS_SWIFT_SENDABLE id> *recommendedPixelBufferAttributes NS_REFINED_FOR_SWIFT API_AVAILABLE(macos(26.0), ios(26.0), tvos(26.0), visionos(26.0)) API_UNAVAILABLE(watchos);
@end
@@ -187,13 +163,11 @@
API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos)
@interface AVSampleBufferVideoRenderer (AVSampleBufferVideoRendererVideoPerformanceMetrics)
-/*!
- @method loadVideoPerformanceMetricsWithCompletionHandler:
- @abstract Gathers a snapshot of the video performance metrics and calls the completion handler with the results.
- @param completionHandler
- The handler to invoke with the video performance metrics.
- @discussion If there are no performance metrics available, the completion handler will be called with nil videoPerformanceMetrics.
-*/
+/// Gathers a snapshot of the video performance metrics and calls the completion handler with the results.
+///
+/// If there are no performance metrics available, the completion handler will be called with nil videoPerformanceMetrics.
+///
+/// - Parameter completionHandler: The handler to invoke with the video performance metrics.
- (void)loadVideoPerformanceMetricsWithCompletionHandler:(void (^ NS_SWIFT_SENDABLE)(AVVideoPerformanceMetrics * _Nullable_result videoPerformanceMetrics))completionHandler NS_SWIFT_ASYNC_NAME(getter:videoPerformanceMetrics()) API_AVAILABLE(macos(14.4), ios(17.4), tvos(17.4), visionos(1.1)) API_UNAVAILABLE(watchos);
@end