AVAssetImageGenerator Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 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, copyCGImageAtTime:actualTime:error:, 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 tracksWithMediaCharacteristic: (AVAsset).

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 iOS 4.0 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 iOS 4.0 and later.
See Also
Related Sample Code
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 iOS 6.0 and later.
See Also
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 iOS 4.0 and later.
Related Sample Code
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 iOS 5.0 and later.
See Also
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 iOS 5.0 and later.
See Also
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 iOS 4.0 and later.
See Also
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 iOS 4.0 and later.
See Also
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 iOS 4.0 and later.
See Also
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 iOS 4.0 and later.
See Also
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 iOS 4.0 and later.
See Also
Related Sample Code
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 iOS 4.0 and later.
See Also
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 iOS 4.0 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorApertureModeProductionAperture

Only pixel aspect ratio will be applied.

Available in iOS 4.0 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorApertureModeEncodedPixels

Neither pixel aspect ratio nor clean aperture will be applied.

Available in iOS 4.0 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 iOS 4.0 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 generation succeeded.

Available in iOS 4.0 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorFailed

Indicates that generation failed.

Available in iOS 4.0 and later.

Declared in AVAssetImageGenerator.h.

AVAssetImageGeneratorCancelled

Indicates that generation was cancelled.

Available in iOS 4.0 and later.

Declared in AVAssetImageGenerator.h.

Discussion

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



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

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