iOS Developer Library

Developer

AVFoundation 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:

  • AVMutableComposition *myMutableComposition =
  • <#a mutable composition you want to inspect or play in its current state#>;
  • AVComposition *immutableSnapshotOfMyComposition = [myMutableComposition copy];
  • // Create a player to inspect and play the composition.
  • AVPlayerItem *playerItemForSnapshottedComposition =
  • [[AVPlayerItem alloc] initWithAsset:immutableSnapshotOfMyComposition];

Inheritance


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.
  • 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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    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, error outError: NSErrorPointer) -> Bool

    Objective-C

    - (BOOL)insertTimeRange:(CMTimeRange)timeRange ofAsset:(AVAsset *)asset atTime:(CMTime)startTime error:(NSError **)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:.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Returns a new, empty, mutable composition.

    Declaration

    Objective-C

    + (AVMutableComposition *)composition

    Return Value

    A new, empty, mutable composition.

    Import Statement

    Objective-C

    @import AVFoundation;

    Availability

    Available in iOS 4.0 and later.

  • tracks tracks Property

    An array of AVMutableCompositionTrack objects contained by the composition. (read-only)

    Declaration

    Swift

    var tracks: [AnyObject]! { get }

    Objective-C

    @property(nonatomic, readonly) NSArray *tracks

    Discussion

    In a mutable composition, the tracks are instances of AVMutableCompositionTrack, whereas in AVComposition the tracks are instances of AVCompositionTrack.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Adds an empty track to the receiver.

    Declaration

    Swift

    func addMutableTrackWithMediaType(_ mediaType: String!, preferredTrackID preferredTrackID: CMPersistentTrackID) -> AVMutableCompositionTrack!

    Objective-C

    - (AVMutableCompositionTrack *)addMutableTrackWithMediaType:(NSString *)mediaType preferredTrackID:(CMPersistentTrackID)preferredTrackID

    Parameters

    mediaType

    The media type of the new track.

    preferredTrackID

    The preferred track ID for the new track. If you do not need to specify a preferred track ID, pass kCMPersistentTrackID_Invalid.

    The preferred track ID will be used for the new track provided that it is not currently in use and has not previously been used. If the preferred track ID you specify is not available, or if you pass in kCMPersistentTrackID_Invalid, a unique track ID is generated.

    Return Value

    An instance of AVMutableCompositionTrack representing the new track.

    Discussion

    You can get the actual trackID of the new track through its @"trackID" key.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Removes a specified track from the receiver.

    Declaration

    Swift

    func removeTrack(_ track: AVCompositionTrack!)

    Objective-C

    - (void)removeTrack:(AVCompositionTrack *)track

    Parameters

    track

    The track to remove.

    Discussion

    When it is removed track’s @"composition" key is set to nil. The values of its other keys remain intact, for arbitrary use.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Returns a track in the receiver into which any time range of a given asset track can be inserted.

    Declaration

    Swift

    func mutableTrackCompatibleWithTrack(_ track: AVAssetTrack!) -> AVMutableCompositionTrack!

    Objective-C

    - (AVMutableCompositionTrack *)mutableTrackCompatibleWithTrack:(AVAssetTrack *)track

    Parameters

    track

    An AVAssetTrack from which a time range may be inserted.

    Return Value

    A mutable track in the receiver into which any time range of track can be inserted. If no such track is available, the returns nil.

    Discussion

    For best performance, you should keep the number of tracks of a composition should be kept to a minimum, corresponding to the number for which media data must be presented in parallel. If you want to present media data of the same type serially, even from multiple assets, you should use a single track of that media type. You use this method to identify a suitable existing target track for an insertion.

    If there is no compatible track available, you can create a new track of the same media type as track using addMutableTrackWithMediaType:preferredTrackID:.

    This method is similar to compatibleTrackForCompositionTrack: (AVAsset).

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.