iOS Developer Library — Prerelease

Developer

AV Foundation Framework Reference AVAssetExportSession Class Reference

Options
Deployment Target:

On This Page
Language:

AVAssetExportSession

An AVAssetExportSession object transcodes the contents of an AVAsset source object to create an output of the form described by a specified export preset.

Prior to initializing an instance of AVAssetExportSession, you can use allExportPresets to get the complete list of presets available. Use exportPresetsCompatibleWithAsset: to get a list of presets that are compatible with a specific asset.

After you have initialized an export session with the asset that contains the source media, the export preset name (presetName), and the output file type (outputFileType), you can start the export running by invoking exportAsynchronouslyWithCompletionHandler:. Because the export is performed asynchronously, this method returns immediately—you can use progress to check on the progress. Depending on the capabilities of the device, some exports may be queued when multiple exports are attempted. When this happens, the status of a queued export will indicate that it's waiting (AVAssetExportSessionStatusWaiting).

The completion handler you supply to exportAsynchronouslyWithCompletionHandler: is called whether the export fails, completes, or is cancelled. 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.

  • The URL of the export session’s output.

    Declaration

    Swift

    @NSCopying var outputURL: NSURL?

    Objective-C

    @property(nonatomic, copy, nullable) NSURL *outputURL

    Discussion

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

    See Also

    outputFileType

  • An array containing the types of files the session can write. (read-only)

    Declaration

    Swift

    var supportedFileTypes: [String] { get }

    Objective-C

    @property(nonatomic, readonly, nonnull) NSArray <NSString *> *supportedFileTypes

    Discussion

    The types of files the session can write are determined by the asset and and export preset with which the session was initialized. If you need to determine the compatible file formats before initiating the export operation, use the determineCompatibleFileTypesWithCompletionHandler: method.

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • The type of file to be written by the session.

    Declaration

    Swift

    var outputFileType: String?

    Objective-C

    @property(nonatomic, copy, nullable) NSString *outputFileType

    Discussion

    The value is a UTI string corresponding to the file type to use when writing the asset. For a list of constants specifying UTIs for standard file types, see AV Foundation Constants Reference.

    You can observe this property using Key-value observing.

    Special Considerations

    You must set a value for this property.

    Availability

    Available in iOS 4.0 and later.

  • Indicates the file length that the output of the session should not exceed.

    Declaration

    Swift

    var fileLengthLimit: Int64

    Objective-C

    @property(nonatomic) long long fileLengthLimit

    Discussion

    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.

    You can observe this property using key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • The time range to be exported from the source.

    Declaration

    Swift

    var timeRange: CMTimeRange

    Objective-C

    @property(nonatomic) CMTimeRange timeRange

    Discussion

    The default time range of an export session is kCMTimeZero to kCMTimePositiveInfinity, meaning that (modulo a possible limit on file length) the full duration of the asset will be exported.

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • The metadata to be written to the output file by the export session.

    Declaration

    Swift

    var metadata: [AVMetadataItem]?

    Objective-C

    @property(nonatomic, copy, nullable) NSArray <AVMetadataItem *> *metadata

    Discussion

    The metadata is an array of AVMetadataItem objects.

    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 key space for the output file and written to the output.

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • Specifies a filter object to be used during export to determine which metadata items should be transferred from the source asset.

    Declaration

    Swift

    var metadataItemFilter: AVMetadataItemFilter?

    Objective-C

    @property(nonatomic, retain, nullable) AVMetadataItemFilter *metadataItemFilter

    Discussion

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

    Availability

    Available in iOS 7.0 and later.

  • Indicates whether non-default audio mixing is enabled for export, and supplies the parameters for audio mixing.

    Declaration

    Swift

    @NSCopying var audioMix: AVAudioMix?

    Objective-C

    @property(nonatomic, copy, nullable) AVAudioMix *audioMix

    Discussion

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • Indicates the processing algorithm used to manage audio pitch for scaled audio edits.

    Declaration

    Swift

    var audioTimePitchAlgorithm: String

    Objective-C

    @property(nonatomic, copy, nonnull) NSString *audioTimePitchAlgorithm

    Discussion

    An exception (NSInvalidArgumentException) is raised if this property is set to a value other than the constants defined in Time Pitch Algorithm Settings.

    The default value is AVAudioTimePitchAlgorithmSpectral.

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that indicates whether the movie should be optimized for network use.

    Declaration

    Swift

    var shouldOptimizeForNetworkUse: Bool

    Objective-C

    @property(nonatomic) BOOL shouldOptimizeForNetworkUse

    Discussion

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • Indicates whether video composition is enabled for export, and supplies the instructions for video composition.

    Declaration

    Swift

    @NSCopying var videoComposition: AVVideoComposition?

    Objective-C

    @property(nonatomic, copy, nullable) AVVideoComposition *videoComposition

    Discussion

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • Indicates the custom video compositor instance used, if any. (read-only)

    Declaration

    Swift

    var customVideoCompositor: AVVideoCompositing? { get }

    Objective-C

    @property(nonatomic, readonly, nullable) id< AVVideoCompositing > customVideoCompositor

    Discussion

    The custom video compositor instance that is used during image generation is accessible via this property after the value of videoComposition is set to an AVVideoComposition instance that specifies a custom video compositor class. Any additional communication between the application and that instance of the custom video compositor, if any is required for configuration or other purposes, can only occur once that has happened.

    If the value of videoComposition is changed from an AVVideoComposition that specifies a custom video compositor class to another instance of AVVideoComposition that specifies the same custom video compositor class, the instance of the custom video compositor that was previously created will receive the renderContextChanged: message and remain in use for subsequent image generation.

    This property is nil if there is no video compositor, or if the internal video compositor is in use.

    Availability

    Available in iOS 7.0 and later.

  • A Boolean value that determines if the export session can perform multiple passes over the source media to achieve better results.

    Declaration

    Swift

    var canPerformMultiplePassesOverSourceMediaData: Bool

    Objective-C

    @property(nonatomic) BOOL canPerformMultiplePassesOverSourceMediaData

    Discussion

    When the value for this property is YEStrue, the export session can produce higher quality results at the expense of longer export times. Setting this property to YEStrue 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 NOfalse. Not all export session configurations can benefit from performing multiple passes over the source media. In these cases, setting this property to YEStrue has no effect.

    This property cannot be set after the export has started.

    Availability

    Available in iOS 8.0 and later.

  • Specifies a directory that is suitable for containing temporary files generated during the export process.

    Declaration

    Swift

    @NSCopying var directoryForTemporaryFiles: NSURL?

    Objective-C

    @property(nonatomic, copy, nullable) NSURL *directoryForTemporaryFiles

    Discussion

    An asset export session may need to write temporary files, for example when canPerformMultiplePassesOverSourceMediaData is set to YEStrue. This property specifies 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).

    Availability

    Available in iOS 8.0 and later.

  • Starts the asynchronous execution of an export session.

    Declaration

    Swift

    func exportAsynchronouslyWithCompletionHandler(_ handler: () -> Void)

    Objective-C

    - (void)exportAsynchronouslyWithCompletionHandler:(void (^ _Nonnull)(void))handler

    Parameters

    handler

    A block that is invoked when writing is complete or in the event of writing failure.

    Discussion

    This method starts an asynchronous export operation and returns immediately. status signals the terminal state of the export session, and if a failure occurs, error describes the problem.

    If internal preparation for export fails, handler is invoked synchronously. The handler may also be called asynchronously, after the method 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. After the export session succeeds, having completely written its output to the outputURL.

    Availability

    Available in iOS 4.0 and later.

  • Cancels the execution of an export session.

    Declaration

    Swift

    func cancelExport()

    Objective-C

    - (void)cancelExport

    Discussion

    You can invoke this method when the export is running.

    Availability

    Available in iOS 4.0 and later.

  • Describes the error that occurred if the export status is AVAssetExportSessionStatusFailed or AVAssetExportSessionStatusCancelled. (read-only)

    Declaration

    Swift

    var error: NSError? { get }

    Objective-C

    @property(nonatomic, readonly, nullable) NSError *error

    Discussion

    If there is no error to report, the value of this property is nil.

    Availability

    Available in iOS 4.0 and later.

  • Indicates the estimated size in bytes of the exported file. (read-only)

    Declaration

    Swift

    var estimatedOutputFileLength: Int64 { get }

    Objective-C

    @property(nonatomic, readonly) long long estimatedOutputFileLength

    Availability

    Available in iOS 5.0 and later.

  • Provides an estimate of the maximum duration of the exported media. (read-only)

    Declaration

    Swift

    var maxDuration: CMTime { get }

    Objective-C

    @property(nonatomic, readonly) CMTime maxDuration

    Discussion

    Returns 0 when the export preset is AVAssetExportPresetPassthrough or AVAssetExportPresetAppleProRes422LPCM. This property will also return 0 if a numeric value (not invalid, indefinite, or infinite) for the timeRange property has not been set.

    You can observe this property using key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • The progress of the export on a scale from 0 to 1. (read-only)

    Declaration

    Swift

    var progress: Float { get }

    Objective-C

    @property(nonatomic, readonly) float progress

    Discussion

    A value of 0 means the export has not yet begun, 1 means the export is complete.

    Availability

    Available in iOS 4.0 and later.

  • The status of the export session. (read-only)

    Declaration

    Swift

    var status: AVAssetExportSessionStatus { get }

    Objective-C

    @property(nonatomic, readonly) AVAssetExportSessionStatus status

    Discussion

    For possible values, see AVAssetExportSessionStatus.

    You can observe this property using Key-value observing.

    Availability

    Available in iOS 4.0 and later.

  • The asset with which the export session was initialized. (read-only)

    Declaration

    Swift

    var asset: AVAsset { get }

    Objective-C

    @property(nonatomic, retain, readonly, nonnull) AVAsset *asset

    Availability

    Available in iOS 5.0 and later.

  • Constants to indicate the status of the session.

    Declaration

    Swift

    enum AVAssetExportSessionStatus : Int { case Unknown case Waiting case Exporting case Completed case Failed case Cancelled }

    Objective-C

    enum { AVAssetExportSessionStatusUnknown, AVAssetExportSessionStatusWaiting, AVAssetExportSessionStatusExporting, AVAssetExportSessionStatusCompleted, AVAssetExportSessionStatusFailed, AVAssetExportSessionStatusCancelled }; typedef NSInteger AVAssetExportSessionStatus;

    Constants

    • Unknown

      AVAssetExportSessionStatusUnknown

      Indicates that the status is unknown.

      Available in iOS 4.0 and later.

    • Waiting

      AVAssetExportSessionStatusWaiting

      Indicates that the session is waiting to export more data.

      Available in iOS 4.0 and later.

    • Exporting

      AVAssetExportSessionStatusExporting

      Indicates that the export session is in progress.

      Available in iOS 4.0 and later.

    • Completed

      AVAssetExportSessionStatusCompleted

      Indicates that the export session completed successfully.

      Available in iOS 4.0 and later.

    • Failed

      AVAssetExportSessionStatusFailed

      Indicates that the export session failed.

      Available in iOS 4.0 and later.

    • Cancelled

      AVAssetExportSessionStatusCancelled

      Indicates that the export session was cancelled.

      Available in iOS 4.0 and later.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • You use these export options to produce QuickTime .mov files with video size appropriate to the current device.

    Declaration

    Swift

    let AVAssetExportPresetLowQuality: String let AVAssetExportPresetMediumQuality: String let AVAssetExportPresetHighestQuality: String

    Objective-C

    NSString *const AVAssetExportPresetLowQuality; NSString *const AVAssetExportPresetMediumQuality; NSString *const AVAssetExportPresetHighestQuality;

    Constants

    • AVAssetExportPresetLowQuality

      AVAssetExportPresetLowQuality

      Specifies a low quality QuickTime file.

      Available in iOS 4.0 and later.

    • AVAssetExportPresetMediumQuality

      AVAssetExportPresetMediumQuality

      Specifies a medium quality QuickTime file.

      Available in iOS 4.0 and later.

    • AVAssetExportPresetHighestQuality

      AVAssetExportPresetHighestQuality

      Specifies a high quality QuickTime file.

      Available in iOS 4.0 and later.

    Discussion

    The export will not scale the video up from a smaller size. Video is compressed using H.264; audio is compressed using AAC.

    See also AVAssetExportSessionStatusCancelled.

  • You use these export options to produce QuickTime .mov files with a specified video size.

    Declaration

    Swift

    let AVAssetExportPreset640x480: String let AVAssetExportPreset960x540: String let AVAssetExportPreset1280x720: String let AVAssetExportPreset1920x1080: String

    Objective-C

    NSString *const AVAssetExportPreset640x480; NSString *const AVAssetExportPreset960x540; NSString *const AVAssetExportPreset1280x720; NSString *const AVAssetExportPreset1920x1080;

    Constants

    • AVAssetExportPreset640x480

      AVAssetExportPreset640x480

      Specifies output at 640x480 pixels.

      Available in iOS 4.0 and later.

    • AVAssetExportPreset960x540

      AVAssetExportPreset960x540

      Specifies output at 960x540 pixels.

      Available in iOS 4.0 and later.

    • AVAssetExportPreset1280x720

      AVAssetExportPreset1280x720

      Specifies output at 1280x720 pixels.

      Available in iOS 4.0 and later.

    • AVAssetExportPreset1920x1080

      AVAssetExportPreset1920x1080

      Specifies output at 1920x1080 pixels.

      Available in iOS 5.0 and later.

    Discussion

    The export will not scale the video up from a smaller size. Video is compressed using H.264; audio is compressed using AAC. Some devices cannot support some sizes.

  • You use this export option to produce an audio-only .m4a file with appropriate iTunes gapless playback data.

    Declaration

    Swift

    let AVAssetExportPresetAppleM4A: String

    Objective-C

    NSString *const AVAssetExportPresetAppleM4A;

    Constants

    • AVAssetExportPresetAppleM4A

      AVAssetExportPresetAppleM4A

      Specifies an audio-only .m4a file with appropriate iTunes gapless playback data.

      Available in iOS 4.0 and later.

  • You use this export option to let all tracks pass through.

    Declaration

    Swift

    let AVAssetExportPresetPassthrough: String

    Objective-C

    NSString *const AVAssetExportPresetPassthrough;

    Constants

    • AVAssetExportPresetPassthrough

      AVAssetExportPresetPassthrough

      Specifies that all tracks pass through, unless it is not possible.

      Available in iOS 4.0 and later.

    Discussion

    This option does not show up in the allExportPresets and exportPresetsCompatibleWithAsset: methods.