CMTime

A struct representing a time value such as a timestamp or duration.

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

Topics

Creating Times

CMTimeMake

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

CMTimeMakeFromDictionary

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

CMTimeMakeWithEpoch

Makes a valid CMTime with value, scale and epoch.

CMTimeMakeWithSeconds

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

Performing Common Operations

CMTimeAdd

Returns the sum of two CMTimes.

CMTimeSubtract

Returns the difference of two CMTimes.

CMTimeMultiply

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

CMTimeMultiplyByFloat64

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

CMTimeMultiplyByRatio

Returns the result of multiplying a CMTime by an integer, then dividing by another integer.

CMTimeConvertScale

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

Inspecting and Evaluating Times

CMTimeCompare

Returns the numerical relationship of two CMTimes.

CMTimeAbsoluteValue

Returns the absolute value of a CMTime.

CMTimeGetSeconds

Converts a CMTime to seconds.

CMTimeMaximum

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

CMTimeMinimum

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

CMTIME_IS_VALID

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

CMTIME_IS_INVALID

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

CMTIME_IS_POSITIVE_INFINITY

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

CMTIME_IS_NEGATIVE_INFINITY

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

CMTIME_IS_INDEFINITE

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

CMTIME_IS_NUMERIC

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

CMTIME_HAS_BEEN_ROUNDED

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

CMTIME_COMPARE_INLINE

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

Utility Functions

CMTimeShow

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

CMTimeCopyDescription

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

CMTimeCopyAsDictionary

Returns a CFDictionary version of a CMTime.

Data Types

CMTime

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

CMTimeValue

Numerator of rational CMTime.

CMTimeScale

Denominator of rational CMTime.

CMTimeEpoch

The epoch to which a CMTime refers.

CMTimeFlags

A type to specify the flag bits for a CMTime.

CMTimeRoundingMethod

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

Constants

Time Constants

Constants to initialize CMTime structures.

Maximum Timescale

A constant to define the maximum timescale.

Rounding Methods

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

Dictionary Keys

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

See Also

Time Representation

CMTimeRange

A struct representing a range of time.

CMTimeMapping

A struct used to specify the mapping of a segment of one time line into another.