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

Topics

Creating Times

init()

Initializes a new CMTime equal to kCMTimeInvalid.

init(seconds: Double, preferredTimescale: CMTimeScale)

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

init(value: CMTimeValue, timescale: CMTimeScale)

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

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.

Performing Common Operations

func CMTimeAdd(CMTime, CMTime)

Returns the sum of two CMTimes.

func CMTimeSubtract(CMTime, CMTime)

Returns the difference of two CMTimes.

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 CMTimeMultiplyByRatio(CMTime, Int32, Int32)

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

func CMTimeConvertScale(CMTime, Int32, CMTimeRoundingMethod)

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

Inspecting and Evaluating Times

func CMTimeCompare(CMTime, CMTime)

Returns the numerical relationship of two CMTimes.

func CMTimeAbsoluteValue(CMTime)

Returns the absolute value of a CMTime.

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 CMTIME_IS_VALID(CMTime)

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

func CMTIME_IS_INVALID(CMTime)

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

func CMTIME_IS_POSITIVEINFINITY(CMTime)

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

func CMTIME_IS_NEGATIVEINFINITY(CMTime)

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

func CMTIME_IS_INDEFINITE(CMTime)

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

func CMTIME_IS_NUMERIC(CMTime)

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

func CMTIME_HAS_BEEN_ROUNDED(CMTime)

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

Utility Functions

func CMTimeShow(CMTime)

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

func CMTimeCopyDescription(CFAllocator?, CMTime)

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

func CMTimeCopyAsDictionary(CMTime, CFAllocator?)

Returns a CFDictionary version of a CMTime.

Data Types

struct CMTime

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

typealias CMTimeValue

Numerator of rational CMTime.

typealias CMTimeScale

Denominator of rational CMTime.

typealias CMTimeEpoch

The epoch to which a CMTime refers.

struct CMTimeFlags

A type to specify the flag bits for a CMTime.

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