AVMutableCompositionTrack Class Reference

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

Overview

AVMutableCompositionTrack is a mutable subclass of AVCompositionTrack that lets you for insert, remove, and scale track segments without affecting their low-level representation (that is, the operations you perform are non-destructive on the original).

AVCompositionTrack defines constraints for the temporal alignment of the track segments. If you set the array of track segments in a mutable composition (see trackSegments), you can test whether the segments meet the constraints using validateTrackSegments:error:.

Tasks

Managing Time Ranges

Validating Segments

Track Properties

Properties

extendedLanguageTag

The language tag associated with the track, as an RFC 4646 language tag.

@property(nonatomic, copy) NSString *extendedLanguageTag
Discussion

If not set, the value is nil.

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

languageCode

The language associated with the track, as an ISO 639-2/T language code.

@property(nonatomic, copy) NSString *languageCode
Discussion

If not set, the value is nil.

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

naturalTimeScale

The timescale in which time values for the track can be operated upon without extraneous numerical conversion.

@property(nonatomic) CMTimeScale naturalTimeScale
Discussion

If not set, the value is the natural time scale of the first non-empty edit, or 600 if there are no non-empty edits.

Set the value to 0 to revert to the default behavior.

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

preferredTransform

The preferred transformation of the visual media data for display purposes.

@property(nonatomic) CGAffineTransform preferredTransform
Discussion

If not set, the value is CGAffineTransformIdentity.

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

preferredVolume

The preferred volume of the audible media data.

@property(nonatomic) float preferredVolume
Discussion

If not set, the value is 1.0.

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

segments

The composition track’s array of track segments.

@property(nonatomic, copy) NSArray *segments
Special Considerations

The timeMapping.target.start of the first track segment must be kCMTimeZero, and the timeMapping.target.start of each subsequent track segment must equal CMTimeRangeGetEnd(<#previousTrackSegment#>.timeMapping.target). You can use validateTrackSegments:error: to ensure that an array of track segments conforms to this rule.

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

Instance Methods

insertEmptyTimeRange:

Adds or extends an empty time range within the receiver.

- (void)insertEmptyTimeRange:(CMTimeRange)timeRange
Parameters
timeRange

The empty time range to be inserted.

Discussion

If you insert an empty time range into the track, any media that was presented during that interval prior to the insertion will be presented instead immediately afterward.

The nature of the data inserted depends upon the media type of the track. For example, an empty time range in a sound track presents silence.

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

insertTimeRange:ofTrack:atTime:error:

Inserts a time range of a source track.

- (BOOL)insertTimeRange:(CMTimeRange)timeRange ofTrack:(AVAssetTrack *)track atTime:(CMTime)startTime error:(NSError **)error
Parameters
timeRange

The time range of the track to be inserted.

track

The source track to be inserted.

startTime

The time at which track is to be presented by the composition track.

error

If track is not inserted successfully, contains an NSError object that describes the problem.

Return Value

YES if track was inserted successfully, otherwise NO.

Discussion

By default, the inserted track’s time range is presented at its natural duration and rate. You can scale it to a different duration (so that it is presented at a different rate) using scaleTimeRange:toDuration:.

Insertion might fail if, for example, the asset that you try to insert is restricted by copy-protection.

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

insertTimeRanges:ofTracks:atTime:error:

Inserts the timeRanges of multiple source tracks into a track of a composition.

- (BOOL)insertTimeRanges:(NSArray *)timeRanges ofTracks:(NSArray *)tracks atTime:(CMTime)startTime error:(NSError **)error
Parameters
timeRanges

An array of NSValue objects containing CMTimeRange structures indicating the time ranges to be inserted.

tracks

The source tracks to be inserted.

Only instances of AVURLAsset are supported.

startTime

The time at which the inserted tracks are to be presented by the composition track.

error

In an error occurs, upon return contains an NSError object that describes the problem.

(For example, the asset that was selected for insertion in the composition is restricted by copy-protection.)

Return Value

YES if the insertions were successful, otherwise NO.

Discussion

This method is equivalent to (but more efficient than) calling -insertTimeRange:ofTrack:atTime:error:: for each timeRange/track pair.

If this method returns an error, none of the time ranges will be inserted into the composition track.

To specify an empty time range, pass an NSNull object for the track and a time range of starting at kCMTimeInvalid with a duration of the desired empty edit.

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

removeTimeRange:

Removes a specified time range from the receiver.

- (void)removeTimeRange:(CMTimeRange)timeRange
Parameters
timeRange

The time range to be removed.

Discussion

Removing a time range does not cause the track to be removed from the composition. Instead it removes or truncates track segments that intersect with the time range.

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

scaleTimeRange:toDuration:

Changes the duration of a time range in the receiver.

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

The time range of the track 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 timeMapping.

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

validateTrackSegments:error:

Returns a Boolean value that indicates whether a given array of track segments conform to the timing rules for a composition track.

- (BOOL)validateTrackSegments:(NSArray *)trackSegments error:(NSError **)error
Parameters
trackSegments

An array of AVCompositionTrackSegment objects.

error

If validation fails, on return contains an NSError object that describes the problem.

Return Value

YES if the track segments in trackSegments conform to the timing rules for a composition track, otherwise NO.

Discussion

You can use this method to ensure that an array of track segments is suitable for setting as the value of the trackSegments property. The timeMapping.target.start of the first track segment must be kCMTimeZero, and the timeMapping.target.start of each subsequent track segment must equal CMTimeRangeGetEnd(<#previousTrackSegment#>.timeMapping.target).

If you want to modify the existing trackSegments array, you can create a mutable copy of it, modify the mutable array, and then validate the mutable array using this method.

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