iOS Developer Library

Developer

AVFoundation Framework Reference AVMutableCompositionTrack Class Reference

Options
Deployment Target:

On This Page
Language:

AVMutableCompositionTrack

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

Inheritance


Import Statement


Swift

import AVFoundation

Objective-C

@import AVFoundation;

Availability


Available in iOS 4.0 and later.
  • Adds or extends an empty time range within the receiver.

    Declaration

    Swift

    func insertEmptyTimeRange(_ timeRange: CMTimeRange)

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Inserts a time range of a source track.

    Declaration

    Swift

    func insertTimeRange(_ timeRange: CMTimeRange, ofTrack track: AVAssetTrack!, atTime startTime: CMTime, error error: NSErrorPointer) -> Bool

    Objective-C

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

    YEStrue if track was inserted successfully, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func insertTimeRanges(_ timeRanges: [AnyObject]!, ofTracks tracks: [AnyObject]!, atTime startTime: CMTime, error error: NSErrorPointer) -> Bool

    Objective-C

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

    YEStrue if the insertions were successful, otherwise NOfalse.

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 5.0 and later.

  • Removes a specified time range from the receiver.

    Declaration

    Swift

    func removeTimeRange(_ timeRange: CMTimeRange)

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • Changes the duration of a time range in the receiver.

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • segments segments Property

    The composition track’s array of track segments.

    Declaration

    Swift

    var segments: [AnyObject]!

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    func validateTrackSegments(_ trackSegments: [AnyObject]!, error error: NSErrorPointer) -> Bool

    Objective-C

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

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

    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.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var languageCode: String!

    Objective-C

    @property(nonatomic, copy) NSString *languageCode

    Discussion

    If not set, the value is nil.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var extendedLanguageTag: String!

    Objective-C

    @property(nonatomic, copy) NSString *extendedLanguageTag

    Discussion

    If not set, the value is nil.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

    See Also

    languageCode

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

    Declaration

    Swift

    var naturalTimeScale: CMTimeScale

    Objective-C

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

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

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

    Declaration

    Swift

    var preferredTransform: CGAffineTransform

    Objective-C

    @property(nonatomic) CGAffineTransform preferredTransform

    Discussion

    If not set, the value is CGAffineTransformIdentity.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.

  • The preferred volume of the audible media data.

    Declaration

    Swift

    var preferredVolume: Float

    Objective-C

    @property(nonatomic) float preferredVolume

    Discussion

    If not set, the value is 1.0.

    Import Statement

    Objective-C

    @import AVFoundation;

    Swift

    import AVFoundation

    Availability

    Available in iOS 4.0 and later.