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


Creating CMTime

func CMTimeMake(Int64, Int32)

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

func CMTimeMakeFromDictionary(CFDictionary?)

Reconstitutes a CMTime struct from a CFDictionary previously created by CMTimeCopyAsDictionary(_:_:).

func CMTimeMakeWithEpoch(Int64, Int32, Int64)

Makes a valid CMTime with value, scale and epoch.

func CMTimeMakeWithSeconds(Float64, Int32)

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

Working with CMTime

func CMTimeAbsoluteValue(CMTime)

Returns the absolute value of a CMTime.

func CMTimeAdd(CMTime, CMTime)

Returns the sum of two CMTimes.

func CMTimeCompare(CMTime, CMTime)

Returns the numerical relationship of two CMTimes.

func CMTimeConvertScale(CMTime, Int32, CMTimeRoundingMethod)

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

func CMTimeCopyAsDictionary(CMTime, CFAllocator?)

Returns a CFDictionary version of a CMTime.

func CMTimeCopyDescription(CFAllocator?, CMTime)

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

func CMTimeGetSeconds(CMTime)

Converts a CMTime to seconds.

func CMTimeMaximum(CMTime, CMTime)

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

func CMTimeMinimum(CMTime, CMTime)

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

func CMTimeMultiply(CMTime, Int32)

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

func CMTimeMultiplyByFloat64(CMTime, Float64)

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

func CMTimeShow(CMTime)

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

func CMTimeSubtract(CMTime, CMTime)

Returns the difference of two CMTimes.

Data Types


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


Numerator of rational CMTime.


Denominator of rational CMTime.


The epoch to which a CMTime refers.


A type to specify the flag bits for a CMTime.


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


Time Constants

Constants to initialize CMTime structures.

CMTime Flags

Constants to specify flags for CMTime.

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.