AVMutableComposition Class Reference

Inherits from
AVComposition : AVAsset : NSObject
Conforms to
NSMutableCopying (AVComposition)
NSCopying (AVAsset)
AVAsynchronousKeyValueLoading (AVAsset)
NSObject (NSObject)
Framework
/System/Library/Frameworks/AVFoundation.framework
Availability
Available in iOS 4.0 and later.
Declared in
AVComposition.h
Related sample code

Overview

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];

Tasks

Managing Time Ranges

Creating a Mutable Composition

Managing Tracks

Video Size

Properties

tracks

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

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

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

Class Methods

composition

Returns a new, empty, mutable composition.

+ (AVMutableComposition *)composition
Return Value

A new, empty, mutable composition.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
AVComposition.h

Instance Methods

addMutableTrackWithMediaType:preferredTrackID:

Adds an empty track to the receiver.

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

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVComposition.h

insertEmptyTimeRange:

Adds or extends an empty timeRange within all tracks of the composition.

- (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.
See Also
Declared In
AVComposition.h

insertTimeRange:ofAsset:atTime:error:

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

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

YES if the insertion was successful, otherwise NO.

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.
See Also
Declared In
AVComposition.h

mutableTrackCompatibleWithTrack:

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

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

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVComposition.h

removeTimeRange:

Removes a specified timeRange from all tracks of the composition.

- (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.
See Also
Declared In
AVComposition.h

removeTrack:

Removes a specified track from the receiver.

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

Availability
  • Available in iOS 4.0 and later.
See Also
Declared In
AVComposition.h

scaleTimeRange:toDuration:

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

- (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.
Declared In
AVComposition.h


© 2010 Apple Inc. All Rights Reserved. (Last updated: 2010-05-15)

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