iOS Developer Library

Developer

AV Foundation Framework Reference AVMutableComposition Class Reference

Options
Deployment Target:

On This Page
Language:

AVMutableComposition

AVMutableComposition is a mutable subclass of AVComposition you use when you want to create a new composition from existing assets. You can add and remove tracks, and you can add, remove, and scale time ranges.

You can make an immutable snapshot of a mutable composition for playback or inspection as follows:

  1. AVMutableComposition *myMutableComposition =
  2. <#a mutable composition you want to inspect or play in its current state#>;
  3. AVComposition *immutableSnapshotOfMyComposition = [myMutableComposition copy];
  4. // Create a player to inspect and play the composition.
  5. AVPlayerItem *playerItemForSnapshottedComposition =
  6. [[AVPlayerItem alloc] initWithAsset:immutableSnapshotOfMyComposition];
  • Adds or extends an empty timeRange within all tracks of the composition.

    Declaration

    Swift

    func insertEmptyTimeRange(_ timeRange: CMTimeRange)

    Objective-C

    - (void)insertEmptyTimeRange:(CMTimeRange)timeRange

    Parameters

    timeRange

    The empty time range to insert.

    Discussion

    If you insert an empty time range into the composition, any media that was presented during that interval prior to the insertion will be presented instead immediately afterward. You can use this method to reserve an interval in which you want a subsequently created track to present its media.

    Availability

    Available in iOS 4.0 and later.

  • Inserts all the tracks within a given time range of a specified asset into the receiver.

    Declaration

    Swift

    func insertTimeRange(_ timeRange: CMTimeRange, ofAsset asset: AVAsset, atTime startTime: CMTime) throws

    Objective-C

    - (BOOL)insertTimeRange:(CMTimeRange)timeRange ofAsset:(AVAsset *)asset atTime:(CMTime)startTime error:(NSError * _Nullable *)outError

    Parameters

    timeRange

    The time range of the asset to be inserted.

    asset

    An asset that contains the tracks to be inserted.

    startTime

    The time at which the inserted tracks should be presented by the receiver.

    outError

    If the insertion was not successful, on return contains an NSError object that describes the problem.

    Return Value

    YEStrue if the insertion was successful, otherwise NOfalse.

    Discussion

    This method may add new tracks to ensure that all tracks of the asset are represented in the inserted time range.

    Existing content at the specified start time is pushed out by the duration of the time range.

    Media data for the inserted time range is presented at its natural duration; you can scale it to a different duration using scaleTimeRange:toDuration:.

    Availability

    Available in iOS 4.0 and later.

  • Removes a specified timeRange from all tracks of the composition.

    Declaration

    Swift

    func removeTimeRange(_ timeRange: CMTimeRange)

    Objective-C

    - (void)removeTimeRange:(CMTimeRange)timeRange

    Parameters

    timeRange

    The time range to be removed.

    Discussion

    After removing, existing content after the time range will be pulled in.

    Removal of a time range does not cause any existing tracks to be removed from the composition, even if removing timeRange results in an empty track. Instead, it removes or truncates track segments that intersect with the time range.

    Availability

    Available in iOS 4.0 and later.

  • Changes the duration of all tracks in a given time range.

    Declaration

    Swift

    func scaleTimeRange(_ timeRange: CMTimeRange, toDuration duration: CMTime)

    Objective-C

    - (void)scaleTimeRange:(CMTimeRange)timeRange toDuration:(CMTime)duration

    Parameters

    timeRange

    The time range of the composition to be scaled.

    duration

    The new duration of timeRange.

    Discussion

    Each track segment affected by the scaling operation will be presented at a rate equal to source.duration / target.duration of its resulting time mapping.

    Availability

    Available in iOS 4.0 and later.

  • Returns a new, empty, mutable composition.

    Declaration

    Objective-C

    + (instancetype)composition

    Return Value

    A new, empty, mutable composition.

    Availability

    Available in iOS 4.0 and later.

  • The encoded or authored size of the visual portion of the asset.

    Declaration

    Swift

    var naturalSize: CGSize

    Objective-C

    @property(nonatomic) CGSize naturalSize

    Discussion

    If this value is not set, the default behavior is as defined by AVAsset; set the value to CGSizeZero to revert to the default behavior.

    Availability

    Available in iOS 4.0 and later.