CMTime Reference

Overview

This document describes the API for creating and manipulating CMTime structs.

CMTime structs are non-opaque mutable structs representing times (either timestamps or durations).

A CMTime is represented as a rational number, with a numerator (an int64_t value), and a denominator (an int32_t timescale). Conceptually, the timescale specifies the fraction of a second each unit in the numerator occupies. Thus if the timescale is 4, each unit represents a quarter of a second; if the timescale is 10, each unit represents a tenth of a second, and so on. In addition to a simple time value, a CMTime can represent non-numeric values: +infinity, -infinity, and indefinite. Using a flag CMTime indicates whether the time been rounded at some point.

CMTimes contain an epoch number, which is usually set to 0, but can be used to distinguish unrelated timelines: for example, it could be incremented each time through a presentation loop, to differentiate between time N in loop 0 from time N in loop 1.

You can convert CMTimes to and from immutable CFDictionaries (see CFDictionaryRef) using CMTimeCopyAsDictionary and CMTimeMakeFromDictionary, for use in annotations and various Core Foundation containers.

Additional functions for managing dates and times are described in Time Utilities Reference. Note that CMTime is designed for media timelines whereas functions in Time Utilities Reference are designed for working with wall-clock time in Core Foundation framework; see also AV Foundation Constants Reference.

Functions by Task

Creating CMTime

• CMTimeMake
• CMTimeMakeFromDictionary
• CMTimeMakeWithEpoch
• CMTimeMakeWithSeconds

Working with CMTime

• CMTimeAbsoluteValue
• CMTimeAdd
• CMTimeCompare
• CMTimeConvertScale
• CMTimeCopyAsDictionary
• CMTimeCopyDescription
• CMTimeGetSeconds
• CMTimeMaximum
• CMTimeMinimum
• CMTimeMultiply
• CMTimeMultiplyByFloat64
• CMTimeShow
• CMTimeSubtract

Comparing CMTime

• CMTIME_COMPARE_INLINE
• CMTIME_IS_VALID
• CMTIME_IS_INVALID
• CMTIME_IS_POSITIVE_INFINITY
• CMTIME_IS_NEGATIVE_INFINITY
• CMTIME_IS_INDEFINITE
• CMTIME_IS_NUMERIC
• CMTIME_HAS_BEEN_ROUNDED

Functions

CMTimeAbsoluteValue

Returns the absolute value of a CMTime.

CMTime CMTimeAbsoluteValue (
   CMTime time
);

CMTimeAdd

Returns the sum of two CMTimes.

CMTime CMTimeAdd (
   CMTime addend1,
   CMTime addend2
);

CMTimeCompare

Returns the numerical relationship of two CMTimes.

int32_t CMTimeCompare (
   CMTime time1,
   CMTime time2
);

CMTimeConvertScale

Returns a new CMTime containing the source CMTime converted to a new timescale (rounding as requested).

CMTime CMTimeConvertScale (
   CMTime time,
   int32_t newTimescale,
   CMTimeRoundingMethod method
);

CMTimeCopyAsDictionary

Returns a CFDictionary version of a CMTime.

CFDictionaryRef CMTimeCopyAsDictionary (
   CMTime time,
   CFAllocatorRef allocator
);

CMTimeCopyDescription

Creates a CFString with a description of a CMTime ( Similar to CFCopyDescription ).

CFStringRef CMTimeCopyDescription (
   CFAllocatorRef allocator,
   CMTime time
);

CMTimeGetSeconds

Converts a CMTime to seconds.

Float64 CMTimeGetSeconds (
   CMTime time
);

CMTimeMake

Makes a valid CMTime with value and timescale. Epoch is implied to be 0.

CMTime CMTimeMake (
   int64_t value,
   int32_t timescale
);

CMTimeMakeFromDictionary

Reconstitutes a CMTime struct from a CFDictionary previously created by CMTimeCopyAsDictionary.

CMTime CMTimeMakeFromDictionary (
   CFDictionaryRef dict
);

CMTimeMakeWithEpoch

Makes a valid CMTime with value, scale and epoch.

CMTime CMTimeMakeWithEpoch (
   int64_t value,
   int32_t timescale,
   int64_t epoch
);

CMTimeMakeWithSeconds

Makes a CMTime from a Float64 number of seconds, and a preferred timescale.

CMTime CMTimeMakeWithSeconds (
   Float64 seconds,
   int32_t preferredTimeScale
);

CMTimeMaximum

Returns the greater of two CMTimes (as defined by CMTimeCompare).

CMTime CMTimeMaximum (
   CMTime time1,
   CMTime time2
);

CMTimeMinimum

Returns the lesser of two CMTimes (as defined by CMTimeCompare).

CMTime CMTimeMinimum (
   CMTime time1,
   CMTime time2
);

CMTimeMultiply

Returns the product of a CMTime and a 32-bit integer.

CMTime CMTimeMultiply (
   CMTime time,
   int32_t multiplier
);

CMTimeMultiplyByFloat64

Returns the product of a CMTime and a 64-bit float.

CMTime CMTimeMultiplyByFloat64 (
   CMTime time,
   Float64 multiplier
);

CMTimeShow

Prints a description of the CMTime (Similar to CFShow).

void CMTimeShow (
   CMTime time
);

CMTimeSubtract

Returns the difference of two CMTimes.

CMTime CMTimeSubtract (
   CMTime minuend,
   CMTime subtrahend
);

CMTIME_COMPARE_INLINE

Returns a Boolean value that indicates whether the specified comparison of two CMTimes is true.

#define CMTIME_COMPARE_INLINE(time1, comparator, time2) ((Boolean)(CMTimeCompare(time1, time2) comparator 0))

CMTIME_COMPARE_INLINE(time1, <=, time2)

CMTIME_HAS_BEEN_ROUNDED

Returns a Boolean value that indicates whether a given time has been rounded.

#define CMTIME_HAS_BEEN_ROUNDED(time) ((Boolean)(CMTIME_IS_NUMERIC(time) && (((time).flags & kCMTimeFlags_HasBeenRounded) != 0)))

CMTIME_IS_INDEFINITE

Returns a Boolean value that indicates whether a given time is indefinite.

#define CMTIME_IS_INDEFINITE(time) ((Boolean)(CMTIME_IS_VALID(time) && (((time).flags & kCMTimeFlags_Indefinite) != 0)))

CMTIME_IS_INVALID

Returns a Boolean value that indicates whether a given time is invalid.

#define CMTIME_IS_INVALID(time) (! CMTIME_IS_VALID(time))

CMTIME_IS_NEGATIVE_INFINITY

Returns a Boolean value that indicates whether a given time is negative infinity.

#define CMTIME_IS_NEGATIVE_INFINITY(time) ((Boolean)(CMTIME_IS_VALID(time) && (((time).flags & kCMTimeFlags_NegativeInfinity) != 0)))

CMTIME_IS_NUMERIC

Returns a Boolean value that indicates whether a given time is numeric.

#define CMTIME_IS_NUMERIC(time) ((Boolean)(((time).flags & (kCMTimeFlags_Valid | kCMTimeFlags_ImpliedValueFlagsMask)) == kCMTimeFlags_Valid))

CMTIME_IS_POSITIVE_INFINITY

Returns a Boolean value that indicates whether a given time is positive infinity.

#define CMTIME_IS_POSITIVE_INFINITY(time) ((Boolean)(CMTIME_IS_VALID(time) && (((time).flags & kCMTimeFlags_PositiveInfinity) != 0)))

CMTIME_IS_VALID

Returns a Boolean value that indicates whether a given time is valid.

#define CMTIME_IS_VALID(time) ((Boolean)(((time).flags & kCMTimeFlags_Valid) != 0))

Data Types

CMTime

Defines a structure that represents a rational time value int64/int32.

typedef struct {
   CMTimeValue    value;
   CMTimeScale    timescale;
   CMTimeFlags    flags;
   CMTimeEpoch    epoch;
} CMTime;

Fields

value

The value of the CMTime.

value/timescale = seconds.

timescale

The timescale of the CMTime.

value/timescale = seconds.

flags

A bitfield representing the flags set for the CMTime.

For example, kCMTimeFlags_Valid. See “CMTime Flags” for possible values.

epoch

The epoch of the CMTime.

You use the epoch to differentiate between equal timestamps that are actually different because of looping, multi-item sequencing, and so on.

The epoch is used during comparison: greater epochs happen after lesser ones. Addition or subtraction is only possible within a single epoch, however, since the epoch length may be unknown or variable.

CMTimeEpoch

The epoch to which a CMTime refers.

typedef int64_t CMTimeEpoch;

CMTimeFlags

A type to specify the flag bits for a CMTime.

typedef uint32_t CMTimeFlags;

CMTimeRoundingMethod

Type for constants used to specify the rounding method to use when computing time.value during timescale conversions.

typedef uint32_t CMTimeRoundingMethod;

CMTimeScale

Denominator of rational CMTime.

typedef int32_t CMTimeScale;

CMTimeValue

Numerator of rational CMTime.

typedef int64_t CMTimeValue;

Constants

Time Constants

Constants to initialize CMTime structures.

const CMTime kCMTimeInvalid;
const CMTime kCMTimeIndefinite;
const CMTime kCMTimePositiveInfinity;
const CMTime kCMTimeNegativeInfinity;
const CMTime kCMTimeZero;

Constants

kCMTimeInvalid

Use this constant to initialize an invalid CMTime.

All fields are 0, so you can calloc or fill with 0's to make lots of them. Do not test against this using (time == kCMTimeInvalid), there are many CMTimes other than this that are also invalid. Use CMTIME_IS_INVALID(time) instead.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeIndefinite

Use this constant to initialize an indefinite CMTime (for example, the duration of a live broadcast).

Do not test against this using (time == kCMTimeIndefinite), there are many CMTimes other than this that are also indefinite. Use CMTIME_IS_INDEFINITE(time) instead.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimePositiveInfinity

Use this constant to initialize a CMTime to +infinity.

Do not test against this using (time == kCMTimePositiveInfinity), there are many CMTimes other than this that are also +infinity. Use CMTIME_IS_POSITIVE_INFINITY(time) instead.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeNegativeInfinity

Use this constant to initialize a CMTime to -infinity.

Do not test against this using (time == kCMTimeNegativeInfinity), there are many CMTimes other than this that are also -infinity. Use CMTIME_IS_NEGATIVE_INFINITY(time) instead.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeZero

Use this constant to initialize a CMTime to 0.

Do not test against this using (time == kCMTimeZero), there are many CMTimes other than this that are also 0. Use CMTimeCompare(time, kCMTimeZero) instead.

Available in OS X v10.7 and later.

Declared in CMTime.h.

CMTime Flags

Constants to specify flags for CMTime.

enum {
   kCMTimeFlags_Valid = 1UL<<0,
   kCMTimeFlags_HasBeenRounded = 1UL<<1,
   kCMTimeFlags_PositiveInfinity = 1UL<<2,
   kCMTimeFlags_NegativeInfinity = 1UL<<3,
   kCMTimeFlags_Indefinite = 1UL<<4,
   kCMTimeFlags_ImpliedValueFlagsMask = kCMTimeFlags_PositiveInfinity | kCMTimeFlags_NegativeInfinity | kCMTimeFlags_Indefinite
};

Constants

kCMTimeFlags_Valid

Indicates that the time is valid.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlags_HasBeenRounded

Indicates that the time has been rounded.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlags_PositiveInfinity

Indicates that the time is +infinity.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlags_NegativeInfinity

Indicates that the time is -infinity.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlags_Indefinite

Indicates that the time is indefinite.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlags_ImpliedValueFlagsMask

Indicates that the time is +infinity, -infinity, or indefinite.

Available in OS X v10.7 and later.

Declared in CMTime.h.

Maximum Timescale

A constant to define the maximum timescale.

#define kCMTimeMaxTimescale 0x7fffffffL

Constants

kCMTimeMaxTimescale

The maximum timescale.

Available in OS X v10.7 and later.

Declared in CMTime.h.

Rounding Methods

Constants used to specify the rounding method to use when computing time.value during timescale conversions.

enum {
   kCMTimeRoundingMethod_RoundHalfAwayFromZero = 1,
   kCMTimeRoundingMethod_RoundTowardZero = 2,
   kCMTimeRoundingMethod_RoundAwayFromZero = 3,
   kCMTimeRoundingMethod_QuickTime = 4,
   kCMTimeRoundingMethod_RoundTowardPositiveInfinity = 5,
   kCMTimeRoundingMethod_RoundTowardNegativeInfinity = 6,
   
   kCMTimeRoundingMethod_Default = kCMTimeRoundingMethod_RoundHalfAwayFromZero
};

Constants

kCMTimeRoundingMethod_RoundHalfAwayFromZero

Round towards zero if abs(fraction) is < 0.5, away from 0 if abs(fraction) is >= 0.5.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_RoundTowardZero

Round towards zero if fraction is != 0.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_RoundAwayFromZero

Round away from zero if abs(fraction) is > 0.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_QuickTime

Use kCMTimeRoundingMethod_RoundTowardZero if converting from larger to smaller scale (that is, from more precision to less precision), but use kCMTimeRoundingMethod_RoundAwayFromZero if converting from smaller to larger scale (i.e. from less precision to more precision).

Also, never round a negative number down to 0; always return the smallest magnitude negative CMTime in this case (-1/newTimescale).

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_RoundTowardPositiveInfinity

Round towards +infinity if fraction is != 0.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_RoundTowardNegativeInfinity

Round towards -infinity if fraction is != 0.

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeRoundingMethod_Default

Synonym for kCMTimeRoundingMethod_RoundHalfAwayFromZero.

Available in OS X v10.7 and later.

Declared in CMTime.h.

Dictionary Keys

Keys to access values of a CMTime represented by a CFDictionary.

const CFStringRef kCMTimeValueKey;
const CFStringRef kCMTimeScaleKey;
const CFStringRef kCMTimeEpochKey;
const CFStringRef kCMTimeFlagsKey;

Constants

kCMTimeValueKey

CFDictionary key for the value field of CMTime (a CFNumber containing an int64_t value).

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeScaleKey

CFDictionary key for the timescale field of CMTime (a CFNumber containing an int32_t value).

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeEpochKey

CFDictionary key for the epoch field of CMTime (a CFNumber containing an int64_t value).

Available in OS X v10.7 and later.

Declared in CMTime.h.

kCMTimeFlagsKey

CFDictionary key for the flags field of CMTime (a CFNumber containing an int32_t value).

Available in OS X v10.7 and later.

Declared in CMTime.h.