AVVideoComposition Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
AVVideoComposition.h

Overview

An AVVideoComposition object represents an immutable video composition.

The AV Foundation framework also provides a mutable subclass, AVMutableVideoComposition, that you can use to create new videos.

A video composition describes, for any time in the aggregate time range of its instructions, the number and IDs of video tracks that are to be used in order to produce a composed video frame corresponding to that time. When AV Foundation’s built-in video compositor is used, the instructions an AVVideoComposition contain can specify a spatial transformation, an opacity value, and a cropping rectangle for each video source, and these can vary over time via simple linear ramping functions.

You can implement your own custom video compositor by implementing the AVVideoCompositing protocol; a custom video compositor is provided with pixel buffers for each of its video sources during playback and other operations and can perform arbitrary graphical operations on them in order to produce visual output.

Tasks

Creating a Video Composition Object

Getting Composition Properties

Validating the Time Range

Properties

animationTool

A video composition tool to use with Core Animation in offline rendering. (read-only)

@property(nonatomic, readonly, retain) AVVideoCompositionCoreAnimationTool *animationTool
Discussion

This attribute may be nil.

You set an animation tool if you are using the composition in conjunction with AVAssetExportSession for offline rendering, rather than with AVPlayer.

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

customVideoCompositorClass

A custom compositor class to use. (read-only)

@property(nonatomic, readonly) Class<AVVideoCompositing> *customVideoCompositorClass
Discussion

The default is nil, indicating the internal video compositor is used.

The customVideoCompositorClass must implement the AVVideoCompositing protocol.

Availability
  • Available in iOS 7.0 and later.
Declared In
AVVideoComposition.h

frameDuration

The interval for which the video composition should render composed video frames. (read-only)

@property(nonatomic, readonly) CMTime frameDuration
Availability
  • Available in iOS 4.0 and later.
Declared In
AVVideoComposition.h

instructions

The video composition instructions. (read-only)

@property(nonatomic, readonly, copy) NSArray *instructions
Discussion

The array contains of instances of AVVideoCompositionInstruction.

For the first instruction in the array, timeRange.start must be less than or equal to the earliest time for which playback or other processing will be attempted (typically kCMTimeZero). For subsequent instructions, timeRange.start must be equal to the prior instruction's end time. The end time of the last instruction must be greater than or equal to the latest time for which playback or other processing will be attempted (typically be the duration of the asset with which the instance of AVVideoComposition is associated).

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

renderScale

The scale at which the video composition should render. (read-only)

@property(nonatomic, readonly) float renderScale
Discussion

This value must be 1.0 unless the composition is set on an AVPlayerItem.

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

renderSize

The size at which the video composition should render. (read-only)

@property(nonatomic, readonly) CGSize renderSize
Availability
  • Available in iOS 4.0 and later.
Declared In
AVVideoComposition.h

Class Methods

videoCompositionWithPropertiesOfAsset:

Creates and returns a video composition object configured to present the video tracks of the specified asset.

+ (AVVideoComposition *)videoCompositionWithPropertiesOfAsset:(AVAsset *)asset
Parameters
asset

The asset whose configuration matches the intended use of the video composition.

Return Value

A new video composition object.

Discussion

This method creates the video composition object and configures it with the values and instructions suitable for presenting the video tracks of the specified asset. The returned object contains instructions that respect the spatial properties and time ranges of the specified asset’s video tracks. It also configures the object properties in the following way:

  • The value of the frameDuration property is set to a value short enough to accommodate the greatest nominal frame rate value among the asset’s video tracks, as indicated by the nominalFrameRate property of each track. If all of the asset tracks have a nominal frame rate of 0, a frame rate of 30 frames per second is used, with the frame duration set accordingly.

  • The value assigned to the renderSize property depends on whether the asset is an AVComposition object. If it is, the value is set to the value of the naturalSize property of the composition. If it is not, the value is set to a value that encompasses all of the asset’s video tracks.

  • The value of the renderScale property is set to 1.0.

  • The value of the animationTool property is set to nil.

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

Instance Methods

isValidForAsset:timeRange:validationDelegate:

Indicates whether the time ranges of the composition’s instructions conform to validation requirements.

- (BOOL)isValidForAsset:(AVAsset *)asset timeRange:(CMTimeRange)timeRange validationDelegate:(id<AVVideoCompositionValidationHandling>)validationDelegate
Parameters
asset

An AVAsset object, if you wish to validate the time ranges of the instructions against the duration of the asset and the track IDs of the layer instructions against the asset’s tracks.

Pass nil to skip that validation.

timeRange

A time range.

Only those instructions with time ranges that overlap with this time range will be validated. To validate all instructions that may be used for playback or other processing, regardless of time range, pass CMTimeRangeMake(kCMTimeZero, kCMTimePositiveInfinity).

validationDelegate

Indicates an object implementing the AVVideoCompositionValidationHandling protocol to receive detailed information about problematic portions of a video composition during processing.

Pass nil if you don’t want to be informed about details.

Return Value

YES if the time ranges of the composition’s instructions conform to validation requirements, otherwise NO.

Discussion

In the course of validation, the receiver will invoke its delegate (if there is one) with reference to any trouble spots in the video composition.

This method raises an exception if the delegate modifies the receiver’s array of instructions or the array of layer instructions of any AVVideoCompositionInstruction object contained therein during validation.

Availability
  • Available in iOS 5.0 and later.
Declared In
AVVideoComposition.h