iOS Developer Library

Developer

AVFoundation Framework Reference AVAssetImageGenerator Class Reference

Options
Deployment Target:

On This Page
Language:

AVAssetImageGenerator

An AVAssetImageGenerator object provides thumbnail or preview images of assets independently of playback.

AVAssetImageGenerator uses the default enabled video track(s) to generate images. Generating a single image in isolation can require the decoding of a large number of video frames with complex interdependencies. If you require a series of images, you can achieve far greater efficiency using the asynchronous method, generateCGImagesAsynchronouslyForTimes:completionHandler:, which employs decoding efficiencies similar to those used during playback.

You create an asset generator using initWithAsset: or assetImageGeneratorWithAsset:. These methods may succeed even if the asset possesses no visual tracks at the time of initialization. You can test whether an asset has any tracks with the visual characteristic using the AVAsset class’s methodtracksWithMediaCharacteristic:.

The actual time of a generated image is within the range [requestedTime-requestedTimeToleranceBefore, requestedTime+requestedTimeToleranceAfter] and may differ from the requested time for efficiency.

Assets that represent mutable compositions or mutable movies may gain visual tracks after initialization of an associated image generator.

Inheritance


Conforms To


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.
  • Initializes an image generator for use with a specified asset.

    Declaration

    Swift

    init!(asset asset: AVAsset!)

    Objective-C

    - (instancetype)initWithAsset:(AVAsset *)asset

    Parameters

    asset

    The asset from which images will be extracted.

    Return Value

    An image generator initialized for use with asset.

    Discussion

    This method may succeed even if the asset possesses no visual tracks at the time of initialization.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Returns an image generator for use with a specified asset.

    Declaration

    Objective-C

    + (AVAssetImageGenerator *)assetImageGeneratorWithAsset:(AVAsset *)asset

    Parameters

    asset

    The asset from which images will be extracted.

    Return Value

    An image generator for use with asset.

    Discussion

    This method may succeed even if the asset possesses no visual tracks at the time of initialization.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

  • The maximum length of time before a requested time for which an image may be generated.

    Declaration

    Swift

    var requestedTimeToleranceBefore: CMTime

    Objective-C

    @property(nonatomic) CMTime requestedTimeToleranceBefore

    Discussion

    The default value is kCMTimePositiveInfinity.

    Set the values of requestedTimeToleranceBefore and requestedTimeToleranceAfter to kCMTimeZero to request frame-accurate image generation; this may incur additional decoding delay.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.

  • The maximum length of time after a requested time for which an image may be generated.

    Declaration

    Swift

    var requestedTimeToleranceAfter: CMTime

    Objective-C

    @property(nonatomic) CMTime requestedTimeToleranceAfter

    Discussion

    The default value is kCMTimePositiveInfinity.

    Set the values of requestedTimeToleranceBefore and requestedTimeToleranceAfter to kCMTimeZero to request frame-accurate image generation; this may incur additional decoding delay.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.

  • Specifies the aperture mode for the generated image.

    Declaration

    Swift

    var apertureMode: String!

    Objective-C

    @property(nonatomic, copy) NSString *apertureMode

    Discussion

    The default value is AVAssetImageGeneratorApertureModeCleanAperture.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Specifies whether to apply the track matrix (or matrices) when extracting an image from the asset.

    Declaration

    Swift

    var appliesPreferredTrackTransform: Bool

    Objective-C

    @property(nonatomic) BOOL appliesPreferredTrackTransform

    Discussion

    The default is NOfalse. AVAssetImageGenerator only supports rotation by 90, 180, or 270 degrees.

    This property is ignored if you set a value for the videoComposition property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • asset asset Property

    The instance of AVAsset with which the AVAssetImageGenerator was initialized. (read-only)

    Declaration

    Swift

    var asset: AVAsset! { get }

    Objective-C

    @property(nonatomic, readonly) AVAsset *asset

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

  • Specifies the maximum dimensions for generated image.

    Declaration

    Swift

    var maximumSize: CGSize

    Objective-C

    @property(nonatomic) CGSize maximumSize

    Discussion

    The default value is CGSizeZero, which specifies the asset’s unscaled dimensions.

    AVAssetImageGenerator scales images such that they fit within the defined bounding box. Images are never scaled up. The aspect ratio of the scaled image is defined by the apertureMode property.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • The video composition to use when extracting images from assets with multiple video tracks.

    Declaration

    Swift

    @NSCopying var videoComposition: AVVideoComposition!

    Objective-C

    @property(nonatomic, copy) AVVideoComposition *videoComposition

    Discussion

    If no video composition is specified, only the first enabled video track will be used. If a video composition is specified, the appliesPreferredTrackTransform property is ignored.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var customVideoCompositor: AVVideoCompositing! { get }

    Objective-C

    @property(nonatomic, readonly) 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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

Data Types

  • This type specifies the signature for the block invoked when generateCGImagesAsynchronouslyForTimes:completionHandler: has completed.

    Declaration

    Swift

    typealias AVAssetImageGeneratorCompletionHandler = (CMTime, CGImage!, CMTime, AVAssetImageGeneratorResult, NSError!) -> Void

    Objective-C

    typedef void (^AVAssetImageGeneratorCompletionHandler)(CMTime requestedTime, CGImageRef image, CMTime actualTime, AVAssetImageGeneratorResult result, NSError *error)

    Discussion

    The block takes five arguments:

    requestedTime

    The time for which you requested an image.

    image

    The image that was generated, or NULL if the image could not be generated.

    This parameter follows The Get Rule.

    actualTime

    The time at which the image was actually generated.

    result

    A result code indicating whether the image generation process succeeded, failed, or was cancelled.

    error

    If result is AVAssetImageGeneratorFailed, an error object that describes the problem.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Constants to specify the aperture mode.

    Declaration

    Swift

    let AVAssetImageGeneratorApertureModeCleanAperture: NSString! let AVAssetImageGeneratorApertureModeProductionAperture: NSString! let AVAssetImageGeneratorApertureModeEncodedPixels: NSString!

    Objective-C

    NSString *const AVAssetImageGeneratorApertureModeCleanAperture; NSString *const AVAssetImageGeneratorApertureModeProductionAperture; NSString *const AVAssetImageGeneratorApertureModeEncodedPixels;

    Constants

    • AVAssetImageGeneratorApertureModeCleanAperture

      AVAssetImageGeneratorApertureModeCleanAperture

      Both pixel aspect ratio and clean aperture will be applied..

      Available in iOS 4.0 and later.

    • AVAssetImageGeneratorApertureModeProductionAperture

      AVAssetImageGeneratorApertureModeProductionAperture

      Only pixel aspect ratio will be applied.

      Available in iOS 4.0 and later.

    • AVAssetImageGeneratorApertureModeEncodedPixels

      AVAssetImageGeneratorApertureModeEncodedPixels

      Neither pixel aspect ratio nor clean aperture will be applied.

      Available in iOS 4.0 and later.

  • Constants to indicate the outcome of image generation.

    Declaration

    Swift

    enum AVAssetImageGeneratorResult : Int { case Succeeded case Failed case Cancelled }

    Objective-C

    { AVAssetImageGeneratorSucceeded, AVAssetImageGeneratorFailed, AVAssetImageGeneratorCancelled, }; typedef NSInteger AVAssetImageGeneratorResult;

    Constants

    • Succeeded

      AVAssetImageGeneratorSucceeded

      Indicates that image generation succeeded.

      Available in iOS 4.0 and later.

    • Failed

      AVAssetImageGeneratorFailed

      Indicates that image generation failed.

      Available in iOS 4.0 and later.

    • Cancelled

      AVAssetImageGeneratorCancelled

      Indicates that image generation was cancelled.

      Available in iOS 4.0 and later.

    Discussion

    These constants are used in the block completion handler for generateCGImagesAsynchronouslyForTimes:completionHandler:.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.