AVAssetExportSession Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
AV Foundation Programming Guide
Declared in
AVAssetExportSession.h
Related sample code

Overview

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.

Tasks

Initializing a Session

Configuring Output

Export Presets

Exporting

Export Status

Accessing the Asset

Properties

asset

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

@property(nonatomic, retain, readonly) AVAsset *asset
Availability
  • Available in iOS 5.0 and later.
Declared In
AVAssetExportSession.h

audioMix

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

@property(nonatomic, copy) AVAudioMix *audioMix
Discussion

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAssetExportSession.h

error

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

@property(nonatomic, readonly) 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.
See Also
Declared In
AVAssetExportSession.h

estimatedOutputFileLength

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

@property(nonatomic, readonly) long long estimatedOutputFileLength
Availability
  • Available in iOS 5.0 and later.
Declared In
AVAssetExportSession.h

fileLengthLimit

The maximum number of bytes that the session is allowed to write to the output URL.

@property(nonatomic) long long fileLengthLimit
Discussion

The export will stop when the output reaches this size regardless of the duration of the source or the value of timeRange.

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAssetExportSession.h

maxDuration

The maximum duration that is allowed for export. (read-only)

@property(nonatomic, readonly) CMTime maxDuration
Discussion

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAssetExportSession.h

metadata

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

@property(nonatomic, copy) NSArray *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.
Declared In
AVAssetExportSession.h

outputFileType

The type of file to be written by the session.

@property(nonatomic, copy) 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.
See Also
Related Sample Code
Declared In
AVAssetExportSession.h

outputURL

The URL of the export session’s output.

@property(nonatomic, copy) NSURL *outputURL
Discussion

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAssetExportSession.h

presetName

The name of the preset with which the session was initialized. (read-only)

@property(nonatomic, readonly) NSString *presetName
Discussion

For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
AVAssetExportSession.h

progress

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

@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.
Declared In
AVAssetExportSession.h

shouldOptimizeForNetworkUse

Indicates whether the movie should be optimized for network use.

@property(nonatomic) BOOL shouldOptimizeForNetworkUse
Discussion

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVAssetExportSession.h

status

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

@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.
Related Sample Code
Declared In
AVAssetExportSession.h

supportedFileTypes

The types of files the session can write. (read-only)

@property(nonatomic, readonly) NSArray *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.
See Also
Declared In
AVAssetExportSession.h

timeRange

The time range to be exported from the source.

@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.
Declared In
AVAssetExportSession.h

videoComposition

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

@property(nonatomic, copy) AVVideoComposition *videoComposition
Discussion

You can observe this property using key-value observing.

Availability
  • Available in iOS 4.0 and later.
Declared In
AVAssetExportSession.h

Class Methods

allExportPresets

Returns all available export preset names.

+ (NSArray *)allExportPresets
Return Value

An array containing a string constant for each of the available preset names.

For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

Discussion

Not all presets are compatible with all assets.

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVAssetExportSession.h

determineCompatibilityOfExportPreset:withAsset:outputFileType:completionHandler:

Reports the compatibility of an export present, asset, and output file type to the specified block.

+ (void)determineCompatibilityOfExportPreset:(NSString *)presetName withAsset:(AVAsset *)asset outputFileType:(NSString *)outputFileType completionHandler:(void (^)(BOOL compatible))handler
Parameters
presetName

The name of the preset template for the export operation.

For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

asset

The asset object that you are planning to export.

outputFileType

The UTI string corresponding to the file type. For example, to specify a QuickTime movie file format, you could specify the constant AVFileTypeQuickTimeMovie. For a list of constants specifying UTIs for standard file types, see AV Foundation Constants Reference.

handler

The block to execute with the results. This method makes a copy of the specified block. This parameter must not be nil.

This block takes a single Boolean parameter and returns no result. The parameter contains the value YES if the combination of options is compatible or NO if they are not.

Discussion

Because not all export presets are compatible with all assets and file types, you can use this method to query the compatibility of specific combos before using them. To ensure that the export operation succeeds, you should not make any significant changes to the asset between the time of calling this method and performing the export operation.

This method performs its checks asynchronously on a secondary thread and returns immediately. The results are similarly reported to the specified block on a secondary thread.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAssetExportSession.h

exportPresetsCompatibleWithAsset:

Returns the identifiers compatible with a given asset.

+ (NSArray *)exportPresetsCompatibleWithAsset:(AVAsset *)asset
Parameters
asset

An asset that is ready to be exported.

Return Value

An array of NSString objects representing the identifiers compatible with asset.

The array is a complete list of the valid identifiers that can be used with exportSessionWithAsset:presetName: with the specified asset. For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

Discussion

Not all export presets are compatible with all assets. For example, a video-only asset is not compatible with an audio-only preset. This method returns only the identifiers for presets that are compatible with the given asset.

In order to ensure that the setup and running of an export operation will succeed using a given preset, you should not make significant changes to the asset (such as adding or deleting tracks) between retrieving compatible identifiers and performing the export operation.

If the asset’s tracks are not currently loaded, they may be loaded by this method before any checks are performed.

Availability
  • Available in iOS 4.0 and later.
See Also
Related Sample Code
Declared In
AVAssetExportSession.h

exportSessionWithAsset:presetName:

Returns an asset export session configured with a specified asset and preset.

+ (id)exportSessionWithAsset:(AVAsset *)asset presetName:(NSString *)presetName
Parameters
asset

The asset you want to export.

presetName

A string constant specifying the name of the preset template for the export.

For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

Return Value

An asset export session initialized to export asset using preset presetName.

Availability
  • Available in iOS 4.1 and later.
Declared In
AVAssetExportSession.h

Instance Methods

cancelExport

Cancels the execution of an export session.

- (void)cancelExport
Discussion

You can invoke this method when the export is running.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVAssetExportSession.h

determineCompatibleFileTypesWithCompletionHandler:

Reports the compatible file types for the current export session to the specified block.

- (void)determineCompatibleFileTypesWithCompletionHandler:(void (^)(NSArray *compatibleFileTypes))handler
Parameters
handler

The block to execute with the results. This method makes a copy of the specified block. This parameter must not be nil.

This block takes an array parameter and returns no result. The array contains zero or more NSString objects with the UTIs of the compatible file types. The file types are in no particular order. For a list of constants specifying UTIs for standard file types, see AV Foundation Constants Reference.

Discussion

This method operates on the asset object and preset information that was used to initialize the export session. It uses this information to determine the file types that the export session can write.

This method performs its checks asynchronously on a secondary thread and returns immediately. The results are similarly reported to the specified block on a secondary thread. Because this method actually inspects the asset’s tracks, the tracks are loaded if they have not been already.

Availability
  • Available in iOS 6.0 and later.
Declared In
AVAssetExportSession.h

exportAsynchronouslyWithCompletionHandler:

Starts the asynchronous execution of an export session.

- (void)exportAsynchronouslyWithCompletionHandler:(void (^)(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.
See Also
Declared In
AVAssetExportSession.h

initWithAsset:presetName:

Initializes an asset export session with a specified asset and preset.

- (id)initWithAsset:(AVAsset *)asset presetName:(NSString *)presetName
Parameters
asset

The asset you want to export.

presetName

A string constant specifying the name of the preset template for the export.

For possible values, see “Export Preset Names for Device-Appropriate QuickTime Files,” “Export Preset Names for QuickTime Files of a Given Size,” AVAssetExportSessionStatusCancelled, “Export Preset Name for iTunes Audio,” and “Export Preset Name for Pass-Through.”

Return Value

An asset export session initialized to export asset using preset presetName.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVAssetExportSession.h

Constants

AVAssetExportSessionStatus

Constants to indicate the status of the session.

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

Indicates that the status is unknown.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportSessionStatusWaiting

Indicates that the session is waiting to export more data.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportSessionStatusExporting

Indicates that the export session is in progress.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportSessionStatusCompleted

Indicates that the export session completed successfully.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportSessionStatusFailed

Indicates that the export session failed.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportSessionStatusCancelled

Indicates that the export session was cancelled.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

Export Preset Names for Device-Appropriate QuickTime Files

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

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

Specifies a low quality QuickTime file.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportPresetMediumQuality

Specifies a medium quality QuickTime file.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportPresetHighestQuality

Specifies a high quality QuickTime file.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

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.

Export Preset Names for QuickTime Files of a Given Size

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

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

Specifies output at 640x480 pixels.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportPreset960x540

Specifies output at 960x540 pixels.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportPreset1280x720

Specifies output at 1280x720 pixels.

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

AVAssetExportPreset1920x1080

Specifies output at 1920x1080 pixels.

Available in iOS 5.0 and later.

Declared in AVAssetExportSession.h.

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.

Export Preset Name for iTunes Audio

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

NSString *const AVAssetExportPresetAppleM4A;
Constants
AVAssetExportPresetAppleM4A

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

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

Export Preset Name for Pass-Through

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

NSString *const AVAssetExportPresetPassthrough;
Constants
AVAssetExportPresetPassthrough

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

Available in iOS 4.0 and later.

Declared in AVAssetExportSession.h.

Discussion

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



© 2012 Apple Inc. All Rights Reserved. (Last updated: 2012-09-19)

Did this document help you? Yes It's good, but... Not helpful...