iOS Developer Library

Developer

AVFoundation Framework Reference AVVideoComposition Class Reference

Options
Deployment Target:

On This Page
Language:

AVVideoComposition

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.

Inheritance


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.
  • Creates and returns a video composition object configured to present the video tracks of the specified asset.

    Declaration

    Swift

    init!(propertiesOfAsset asset: AVAsset!) -> AVVideoComposition

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 6.0 and later.

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

    Declaration

    Swift

    var frameDuration: CMTime { get }

    Objective-C

    @property(nonatomic, readonly) CMTime frameDuration

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var renderSize: CGSize { get }

    Objective-C

    @property(nonatomic, readonly) CGSize renderSize

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • The video composition instructions. (read-only)

    Declaration

    Swift

    var instructions: [AnyObject]! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var animationTool: AVVideoCompositionCoreAnimationTool! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var renderScale: Float { get }

    Objective-C

    @property(nonatomic, readonly) float renderScale

    Discussion

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var customVideoCompositorClass: AnyObject.Type! { get }

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 7.0 and later.

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

    Declaration

    Swift

    func isValidForAsset(_ asset: AVAsset!, timeRange timeRange: CMTimeRange, validationDelegate validationDelegate: AVVideoCompositionValidationHandling!) -> Bool

    Objective-C

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

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

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.