iOS Developer Library

Developer

CoreMedia Framework Reference CMTimeRange Reference

Options
Deployment Target:

On This Page
Language:

CMTimeRange Reference

Inherits From


Not Applicable

Conforms To


Not Applicable

Import Statement


Swift

import CoreMedia

Objective-C

@import CoreMedia;

This document describes the API for creating and manipulating CMTimeRange structures.

CMTimeRange structs are non-opaque mutable structures that represent time ranges. A CMTimeRange is represented as two CMTime structs, one that specifies the start time of the range and another that specifies the duration of the range. A time range does not include the end time that would be calculated by adding the duration to the start time. The following expression will always evaluate to false:

  • CMTimeRangeContainsTime(range, CMTimeRangeGetEnd(range))

You can convert CMTimeRanges to and from CFDictionaries (see CFDictionaryRef) using CMTimeRangeCopyAsDictionary and CMTimeRangeMakeFromDictionary, for use in annotations and various Core Foundation containers.

The epoch in a CMTime that represents a duration should always be 0, and the value must be non-negative. The epoch in a CMTime that represents a timestamp may be non-zero, but range operations (such as CMTimeRangeGetUnion) can only be performed on ranges whose start fields have the same epoch. CMTimeRanges cannot span different epochs.

Additional functions for managing dates and times are described in Time Utilities Reference; see also AV Foundation Constants Reference.

Functions

  • For a given CMTime and CMTimeRange, returns the nearest CMTime inside that time range.

    Declaration

    Swift

    func CMTimeClampToRange(_ time: CMTime, _ range: CMTimeRange) -> CMTime

    Objective-C

    CMTime CMTimeClampToRange ( CMTime time, CMTimeRange range );

    Parameters

    time

    The time to be clamped.

    range

    The time range being interrogated.

    Return Value

    A CMTime structure inside the given time range.

    Discussion

    Times inside the given time range will be returned unmodified. Times before the start and after the end time of the time range will return the start and end time of the range respectively. If the CMTimeRange argument is empty, an invalid CMTime will be returned. If the given CMTime is invalid, the returned CMTime will be invalid.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Translates a duration through a mapping from CMTimeRange to CMTimeRange.

    Declaration

    Swift

    func CMTimeMapDurationFromRangeToRange(_ dur: CMTime, _ fromRange: CMTimeRange, _ toRange: CMTimeRange) -> CMTime

    Objective-C

    CMTime CMTimeMapDurationFromRangeToRange ( CMTime dur, CMTimeRange fromRange, CMTimeRange toRange );

    Parameters

    dur

    The duration to be translated.

    fromRange

    The time range from which duration is translated.

    toRange

    The time range to which duration is mapped to .

    Return Value

    A CMTime structure representing the translated duration.

    Discussion

    The duration will be scaled in proportion to the ratio between the ranges' durations:

    • result = dur*(toRange.duration/fromRange.duration)

    If dur does not have the epoch zero, an invalid CMTime will be returned.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Translates a time through a mapping from CMTimeRange to CMTimeRange.

    Declaration

    Swift

    func CMTimeMapTimeFromRangeToRange(_ t: CMTime, _ fromRange: CMTimeRange, _ toRange: CMTimeRange) -> CMTime

    Objective-C

    CMTime CMTimeMapTimeFromRangeToRange ( CMTime t, CMTimeRange fromRange, CMTimeRange toRange );

    Parameters

    t

    The CMTime to be translated.

    fromRange

    The time range from which CMTime is translated.

    toRange

    The time range to which CMTime is mapped to.

    Return Value

    A CMTime structure representing the translated time.

    Discussion

    The start and end time of fromRange will be mapped to the start and end time of toRange respectively. Other times will be mapped linearly, using the formula:

    • result = (t-fromRange.start)*(toRange.duration/fromRange.duration)+toRange.start

    If either CMTimeRange argument is empty, an invalid CMTime will be returned. If t does not have the same epoch as fromRange.start, an invalid CMTime will be returned. If both fromRange and toRange have duration kCMTimePositiveInfinity, t will be offset relative to the differences between their starts, but not scaled.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Indicates whether a time is contained within a time range.

    Declaration

    Swift

    func CMTimeRangeContainsTime(_ range: CMTimeRange, _ time: CMTime) -> Boolean

    Objective-C

    Boolean CMTimeRangeContainsTime ( CMTimeRange range, CMTime time );

    Parameters

    range

    CMTimeRange being interrogated.

    time

    CMTime to be tested for inclusion.

    Return Value

    Returns true if the specified time is contained within the specified time range, false if it is not.

    Discussion

    This function returns a Boolean value that indicates whether the time specified by the time parameter is contained within the range specified by the range parameter.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean that indicates whether a given time range is contained within another time range.

    Declaration

    Swift

    func CMTimeRangeContainsTimeRange(_ range1: CMTimeRange, _ range2: CMTimeRange) -> Boolean

    Objective-C

    Boolean CMTimeRangeContainsTimeRange ( CMTimeRange range1, CMTimeRange range2 );

    Parameters

    range1

    The CMTimeRange being interrogated.

    range2

    CMTimeRange to be tested for inclusion.

    Return Value

    Returns true if the second time range is contained within the first time range, false if it is not.

    Discussion

    This function returns a Boolean value that indicates whether the time range specified by the range1 parameter contains the range specified by the range2 parameter.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns a CFDictionary version of a CMTimeRange.

    Declaration

    Swift

    func CMTimeRangeCopyAsDictionary(_ range: CMTimeRange, _ allocator: CFAllocator!) -> CFDictionary!

    Objective-C

    CFDictionaryRef CMTimeRangeCopyAsDictionary ( CMTimeRange range, CFAllocatorRef allocator );

    Parameters

    range

    The CMTimeRange from which to create a dictionary.

    allocator

    CFAllocator with which to create a dictionary. Pass kCFAllocatorDefault to use the default allocator

    Return Value

    A CFDictionary version of the CMTimeRange.

    Discussion

    This is useful when putting CMTimeRanges in Core Foundation container types. For keys, see CFDictionary Keys.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Creates a CFString with a description of a CMTimeRange (similar to CFCopyDescription).

    Declaration

    Swift

    func CMTimeRangeCopyDescription(_ allocator: CFAllocator!, _ range: CMTimeRange) -> CFString!

    Objective-C

    CFStringRef CMTimeRangeCopyDescription ( CFAllocatorRef allocator, CMTimeRange range );

    Parameters

    allocator

    CFAllocator for allocating memory for description. Pass kCFAllocatorDefault to use the default allocator.

    range

    The CMTimeRange to describe.

    Return Value

    The created CFString description.

    Discussion

    This is used from within CFShow on an object that contains CMTimeRange fields. It is also useful from other client debugging code. The caller owns the returned CFString and is responsible for releasing it.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean value that indicates whether two CMTimeRanges are identical.

    Declaration

    Swift

    func CMTimeRangeEqual(_ range1: CMTimeRange, _ range2: CMTimeRange) -> Boolean

    Objective-C

    Boolean CMTimeRangeEqual ( CMTimeRange range1, CMTimeRange range2 );

    Parameters

    range1

    CMTimeRange to be compared for equality.

    range2

    Another CMTimeRange to be compared for equality.

    Return Value

    Returns true if the two time ranges are identical, false if they differ.

    Discussion

    This function returns a Boolean value that indicates whether the time ranges specified by the range1 and range2 parameters are identical.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Creates a valid CMTimeRange from the given start and end time.

    Declaration

    Swift

    func CMTimeRangeFromTimeToTime(_ start: CMTime, _ end: CMTime) -> CMTimeRange

    Objective-C

    CMTimeRange CMTimeRangeFromTimeToTime ( CMTime start, CMTime end );

    Parameters

    start

    CMTime structure representing start time for creating the range.

    end

    CMTime structure representing end time for creating the range.

    Return Value

    The resulting CMTimeRange.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns a CMTime structure representing the end of a time range.

    Declaration

    Swift

    func CMTimeRangeGetEnd(_ range: CMTimeRange) -> CMTime

    Objective-C

    CMTime CMTimeRangeGetEnd ( CMTimeRange range );

    Parameters

    range

    The CMTimeRange from which to find the end of time range.

    Return Value

    A CMTime structure representing the end of the specified time range.

    Discussion

    This function returns a CMTime structure that indicates the end of the time range specified by the range parameter. CMTimeRangeContainsTime(range, CMTimeRangeGetEnd(range)) is always false.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns the intersection of two CMTimeRanges.

    Declaration

    Swift

    func CMTimeRangeGetIntersection(_ range1: CMTimeRange, _ range2: CMTimeRange) -> CMTimeRange

    Objective-C

    CMTimeRange CMTimeRangeGetIntersection ( CMTimeRange range1, CMTimeRange range2 );

    Parameters

    range1

    CMTimeRange to be intersected.

    range2

    Another CMTimeRange to be intersected.

    Return Value

    The intersection of the two CMTimeRanges.

    Discussion

    This function returns a CMTimeRange structure that represents the intersection of the time ranges specified by the range1 and range2 parameters. This is the largest range that both ranges include.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns the union of two CMTimeRanges.

    Declaration

    Swift

    func CMTimeRangeGetUnion(_ range1: CMTimeRange, _ range2: CMTimeRange) -> CMTimeRange

    Objective-C

    CMTimeRange CMTimeRangeGetUnion ( CMTimeRange range1, CMTimeRange range2 );

    Parameters

    range1

    CMTimeRange to be unified.

    range2

    Another CMTimeRange to be unified.

    Return Value

    The union of the two CMTimeRanges.

    Discussion

    This function returns a CMTimeRange structure that represents the union of the time ranges specified by the range1 and range2 parameters. This is the smallest range that includes all times that are in either range.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Creates a valid CMTimeRange with the given start time and duration.

    Declaration

    Swift

    func CMTimeRangeMake(_ start: CMTime, _ duration: CMTime) -> CMTimeRange

    Objective-C

    CMTimeRange CMTimeRangeMake ( CMTime start, CMTime duration );

    Parameters

    start

    CMTime structure for initializing the start field of the resulting CMTimeRange.

    duration

    CMTime structure for initializing the duration field of the resulting CMTimeRange.

    Return Value

    The resulting CMTimeRange.

    Discussion

    The duration parameter must have an epoch of 0; otherwise an invalid time range will be returned.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Reconstitutes a CMTimeRange struct from a CFDictionary previously created by CMTimeRangeCopyAsDictionary.

    Declaration

    Swift

    func CMTimeRangeMakeFromDictionary(_ dict: CFDictionary!) -> CMTimeRange

    Objective-C

    CMTimeRange CMTimeRangeMakeFromDictionary ( CFDictionaryRef dict );

    Parameters

    dict

    CFDictionary from which to create a CMTimeRange.

    Return Value

    The reconstituted CMTimeRange.

    Discussion

    This is useful when getting CMTimeRanges from Core Foundation container types. If the CFDictionary does not have the requisite keyed values, an invalid time range is returned. For keys, see CFDictionary Keys.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Prints a description of the CMTimeRange to stderr (similar to CFShow).

    Declaration

    Swift

    func CMTimeRangeShow(_ range: CMTimeRange)

    Objective-C

    void CMTimeRangeShow ( CMTimeRange range );

    Parameters

    range

    The CMTimeRange to be printed.

    Discussion

    This is most useful from within gdb.

    Import Statement

    Objective-C

    @import CoreMedia;

    Swift

    import CoreMedia

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean value that indicates whether a given CMTimeRange has a duration of 0.

    Declaration

    Objective-C

    #define CMTIMERANGE_IS_EMPTY(range) ((Boolean)(CMTIMERANGE_IS_VALID(range) && (CMTIME_COMPARE_INLINE(range.duration, ==, kCMTimeZero))))

    Parameters

    range

    The time range to be tested for emptiness.

    Return Value

    true if range has a duration of 0; otherwise, false.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean value that indicates whether a given CMTimeRange is indefinite.

    Declaration

    Objective-C

    #define CMTIMERANGE_IS_INDEFINITE(range) ((Boolean)(CMTIMERANGE_IS_VALID(range) && (CMTIME_IS_INDEFINITE(range.start) || CMTIME_IS_INDEFINITE(range.duration))))

    Parameters

    range

    The time range to be tested for finiteness.

    Return Value

    true if range is indefinite; otherwise, false.

    Discussion

    An indefinite time range has either an indefinite start or an indefinite duration, or both.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean value that indicates whether a given CMTimeRange is invalid.

    Declaration

    Objective-C

    #define CMTIMERANGE_IS_INVALID(range) (! CMTIMERANGE_IS_VALID(range))

    Parameters

    range

    The time range to be tested for invalidity.

    Return Value

    true if range is invalid; otherwise, false.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

  • Returns a Boolean value that indicates whether a given CMTimeRange is valid.

    Declaration

    Objective-C

    #define CMTIMERANGE_IS_VALID(range) ((Boolean)(CMTIME_IS_VALID(range.start) && CMTIME_IS_VALID(range.duration) && (range.duration.epoch == 0) && (range.duration.value >= 0)))

    Parameters

    range

    The time range to be tested for validity.

    Return Value

    true if range is valid; otherwise, false.

    Import Statement

    Objective-C

    @import CoreMedia;

    Availability

    Available in iOS 4.0 and later

Data Types

Miscellaneous

  • A time range represented as two CMTime structures.

    Declaration

    Swift

    struct CMTimeRange { var start: CMTime var duration: CMTime init() init(start start: CMTime, duration duration: CMTime) }

    Objective-C

    typedef struct { CMTime start; CMTime duration; } CMTimeRange;

    Fields

    start

    The start time of the time range.

    duration

    The duration of the time range.

    Availability

    Available in iOS 4.0 and later

  • A structure to specify the mapping of a segment of one time line into another.

    Declaration

    Swift

    struct CMTimeMapping { var source: CMTimeRange var target: CMTimeRange init() init(source source: CMTimeRange, target target: CMTimeRange) }

    Objective-C

    typedef struct { CMTimeRange source; CMTimeRange target; } CMTimeMapping;

    Fields

    source

    The time range on the source time line.

    For an empty edit, source.start is an invalid CMTime, in which case source.duration is ignored. Otherwise, source.start is the starting time within the source, and source.duration is the duration of the source timeline to be mapped to the target time range.

    target

    The time range on the target time line.

    If target.duration and source.duration are different, then the source segment should be played at the rate source.duration /target.duration to fit.

    Discussion

    A CMTimeMapping specifies the mapping of a segment of one time line (called the source) into another time line (called the target). When used for movie edit lists, the source time line is the media and the target time line is the track or movie.

    Availability

    Available in iOS 4.0 and later

Constants

  • Keys for components in a CFDictionary representation of a CMTimeRange.

    Declaration

    Swift

    let kCMTimeRangeStartKey: CFString! let kCMTimeRangeDurationKey: CFString!

    Objective-C

    const CFStringRef kCMTimeRangeStartKey; const CFStringRef kCMTimeRangeDurationKey;

    Constants

    • kCMTimeRangeStartKey

      kCMTimeRangeStartKey

      The key for start field of a CMTimeRange (CMTime).

      Available in iOS 4.0 and later

    • kCMTimeRangeDurationKey

      kCMTimeRangeDurationKey

      The key for timescale of a CMTimeRange (CMTime).

      Available in iOS 4.0 and later

    Discussion

    To convert a CMTimeRange to and from a CFDictionary, see CMTimeRangeCopyAsDictionary and CMTimeRangeMakeFromDictionary.

  • These constants specify zero and invalid time ranges.

    Declaration

    Swift

    let kCMTimeRangeZero: CMTimeRange let kCMTimeRangeInvalid: CMTimeRange

    Objective-C

    const CMTimeRange kCMTimeRangeZero; const CMTimeRange kCMTimeRangeInvalid;

    Constants

    • kCMTimeRangeZero

      kCMTimeRangeZero

      Use this constant to generate an empty CMTimeRange at 0.

      Available in iOS 4.0 and later

    • kCMTimeRangeInvalid

      kCMTimeRangeInvalid

      Use this constant to generate an invalid CMTimeRange.

      Available in iOS 4.0 and later