AVAssetImageGenerator Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in OS X v10.7 and later.
Declared in
AVAssetImageGenerator.h
Related sample code

Overview

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.

Tasks

Creating a Generator

Generating Images

Managing Generation Time Tolerance

Generation Behavior

Properties

apertureMode

Specifies the aperture mode for the generated image.

@property(nonatomic, copy) NSString *apertureMode
Discussion

The default value is AVAssetImageGeneratorApertureModeCleanAperture.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

appliesPreferredTrackTransform

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

@property(nonatomic) BOOL appliesPreferredTrackTransform
Discussion

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

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

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

asset

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

@property(nonatomic, readonly) AVAsset *asset
Availability
  • Available in OS X v10.9 and later.
Declared In
AVAssetImageGenerator.h

customVideoCompositor

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

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

Availability
  • Available in OS X v10.9 and later.
Declared In
AVAssetImageGenerator.h

maximumSize

Specifies the maximum dimensions for generated image.

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

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

requestedTimeToleranceAfter

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

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

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

requestedTimeToleranceBefore

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

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

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

videoComposition

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

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

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

Class Methods

assetImageGeneratorWithAsset:

Returns an image generator for use with a specified asset.

+ (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.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

Instance Methods

cancelAllCGImageGeneration

Cancels all pending image generation requests.

- (void)cancelAllCGImageGeneration
Discussion

This method calls the handler block with AVAssetImageGeneratorCancelled for each image time in every previous invocation of generateCGImagesAsynchronouslyForTimes:completionHandler: for which images have not yet been supplied.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

copyCGImageAtTime:actualTime:error:

Returns a CGImage for the asset at or near a specified time.

- (CGImageRef)copyCGImageAtTime:(CMTime)requestedTime actualTime:(CMTime *)actualTime error:(NSError **)outError
Parameters
requestedTime

The time at which the image of the asset is to be created.

actualTime

Upon return, contains the time at which the image was actually generated.

If you are not interested in this information, pass NULL.

outError

If an error occurs, upon return contains an NSError object that describes the problem.

If you are not interested in this information, pass NULL.

Return Value

A CGImage for the asset at or near a specified time, or NULL if the image could not be created.

This method follows “The Create Rule” in Memory Management Programming Guide for Core Foundation.

Discussion

This method returns the image synchronously.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

generateCGImagesAsynchronouslyForTimes:completionHandler:

Creates a series of CGImage objects for an asset at or near specified times.

- (void)generateCGImagesAsynchronouslyForTimes:(NSArray *)requestedTimes completionHandler:(AVAssetImageGeneratorCompletionHandler)handler
Parameters
requestedTimes

An array of NSValue objects, each containing a CMTime, specifying the asset times at which an image is requested.

handler

A block that is called when an image request is complete.

Discussion

This method uses an efficient “batch mode” to get images in time order.

The client receives exactly one handler callback for each requested time in requestedTimes. Changes to the generator’s properties (snap behavior, maximum size, and so on) do not affect pending asynchronous image generation requests.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

initWithAsset:

Initializes an image generator for use with a specified asset.

- (id)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.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

Constants

Aperture Modes

Constants to specify the aperture mode.

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

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

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorApertureModeProductionAperture

Only pixel aspect ratio will be applied.

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorApertureModeEncodedPixels

Neither pixel aspect ratio nor clean aperture will be applied.

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorCompletionHandler

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

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” in Memory Management Programming Guide for Core Foundation.

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.

Availability
  • Available in OS X v10.7 and later.
Declared In
AVAssetImageGenerator.h

AVAssetImageGeneratorResult

Constants to indicate the outcome of image generation.

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

Indicates that image generation succeeded.

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorFailed

Indicates that image generation failed.

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorCancelled

Indicates that image generation was cancelled.

Available in OS X v10.7 and later.

Declared in AVAssetImageGenerator.h.

Discussion

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