# CMTimebase A model of a timeline under application control. ## Discussion A timebase represents a timeline that clients can control by setting the rate and time. Each timebase has either a host clock or a host timebase, and its rate is expressed relative to its host: - When a timebase has rate 0.0, its time is fixed and doesn’t change as its host’s time changes. - When a timebase has rate 1.0, its time increases one second as its host’s time increases by one second. - When a timebase has rate 2.0, its time increases two seconds as its host’s time increases by one second. - When a timebase has rate -1.0, its time decreases one second as its host’s time increases by one second. If a timebase has a host timebase, the host timebase’s rate is a factor in determining the timebase’s effective rate. In fact, a timebase’s effective rate is defined as the product of its rate, its host timebase’s rate, its host timebase’s host timebase’s rate, and so on up to the ultimate host clock. This is the rate at which the timebase’s time changes relative to the ultimate host clock. ## Topics ### Creating Timebases [`func CMTimebaseCreateWithSourceClock(allocator: CFAllocator?, sourceClock: CMClock, timebaseOut: UnsafeMutablePointer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseCreateWithSourceClock(allocator:sourceClock:timebaseOut:)) Creates a timebase by using a source clock. [`func CMTimebaseCreateWithSourceTimebase(allocator: CFAllocator?, sourceTimebase: CMTimebase, timebaseOut: UnsafeMutablePointer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseCreateWithSourceTimebase(allocator:sourceTimebase:timebaseOut:)) Creates a timebase by using a source timebase. ### Copying Timebases [`func CMTimebaseCopySource(CMTimebase) -> CMClockOrTimebase`](/documentation/CoreMedia/CMTimebaseCopySource(_:)) Returns the immediate source — either a clock or timebase — of a timebase. [`func CMTimebaseCopySourceClock(CMTimebase) -> CMClock?`](/documentation/CoreMedia/CMTimebaseCopySourceClock(_:)) Returns the immediate source clock of a timebase. [`func CMTimebaseCopySourceTimebase(CMTimebase) -> CMTimebase?`](/documentation/CoreMedia/CMTimebaseCopySourceTimebase(_:)) Returns the immediate source timebase of a timebase. [`func CMTimebaseCopyUltimateSourceClock(CMTimebase) -> CMClock`](/documentation/CoreMedia/CMTimebaseCopyUltimateSourceClock(_:)) Returns the source clock that’s the source of all of a timebase’s source timebases. ### Getting and Setting Time [`func CMTimebaseGetTime(CMTimebase) -> CMTime`](/documentation/CoreMedia/CMTimebaseGetTime(_:)) Returns the current time from a timebase. [`func CMTimebaseGetTimeWithTimeScale(CMTimebase, timescale: CMTimeScale, method: CMTimeRoundingMethod) -> CMTime`](/documentation/CoreMedia/CMTimebaseGetTimeWithTimeScale(_:timescale:method:)) Returns the current time from a timebase in the specified timescale. [`func CMTimebaseGetTimeAndRate(CMTimebase, timeOut: UnsafeMutablePointer?, rateOut: UnsafeMutablePointer?) -> OSStatus`](/documentation/CoreMedia/CMTimebaseGetTimeAndRate(_:timeOut:rateOut:)) Returns the current time and rate of a timebase. [`func CMTimebaseSetTime(CMTimebase, time: CMTime) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetTime(_:time:)) Sets the current time of a timebase. [`func CMTimebaseSetSourceClock(CMTimebase, CMClock) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetSourceClock(_:_:)) Sets the source clock of a timebase. [`func CMTimebaseSetSourceTimebase(CMTimebase, CMTimebase) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetSourceTimebase(_:_:)) Sets the source timebase of a timebase. [`func CMTimebaseSetAnchorTime(CMTimebase, timebaseTime: CMTime, immediateSourceTime: CMTime) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetAnchorTime(_:timebaseTime:immediateSourceTime:)) Sets the time of a timebase at a particular host time. ### Getting and Setting the Time Rate [`func CMTimebaseGetRate(CMTimebase) -> Float64`](/documentation/CoreMedia/CMTimebaseGetRate(_:)) Returns the current rate of a timebase. [`func CMTimebaseGetEffectiveRate(CMTimebase) -> Float64`](/documentation/CoreMedia/CMTimebaseGetEffectiveRate(_:)) Returns the effective rate of a timebase, which combines its rate with the rates of all its host timebases. [`func CMTimebaseSetRate(CMTimebase, rate: Float64) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetRate(_:rate:)) Sets the rate of a timebase. [`func CMTimebaseSetRateAndAnchorTime(CMTimebase, rate: Float64, anchorTime: CMTime, immediateSourceTime: CMTime) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetRateAndAnchorTime(_:rate:anchorTime:immediateSourceTime:)) Sets the time of a timebase at a particular host time, and changes the rate at exactly that time. ### Interacting with Timers [`func CMTimebaseAddTimer(CMTimebase, timer: CFRunLoopTimer, runloop: CFRunLoop) -> OSStatus`](/documentation/CoreMedia/CMTimebaseAddTimer(_:timer:runloop:)) Adds the timer to the list of timers the timebase manages. [`func CMTimebaseAddTimerDispatchSource(CMTimebase, timerSource: dispatch_source_t) -> OSStatus`](/documentation/CoreMedia/CMTimebaseAddTimerDispatchSource(_:timerSource:)) Adds the timer dispatch source to the list of timers the timebase manages. [`func CMTimebaseRemoveTimer(CMTimebase, timer: CFRunLoopTimer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseRemoveTimer(_:timer:)) Removes the timer from the list of timers the timebase manages. [`func CMTimebaseRemoveTimerDispatchSource(CMTimebase, timerSource: dispatch_source_t) -> OSStatus`](/documentation/CoreMedia/CMTimebaseRemoveTimerDispatchSource(_:timerSource:)) Removes the timer dispatch source from the list of timers the timebase manages. [`func CMTimebaseSetTimerNextFireTime(CMTimebase, timer: CFRunLoopTimer, fireTime: CMTime, flags: UInt32) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetTimerNextFireTime(_:timer:fireTime:flags:)) Sets the time on the timebase’s timeline at which the timer should fire next. [`func CMTimebaseSetTimerToFireImmediately(CMTimebase, timer: CFRunLoopTimer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetTimerToFireImmediately(_:timer:)) Sets the timer to fire immediately once, overriding any previous timer calls. [`func CMTimebaseSetTimerDispatchSourceNextFireTime(CMTimebase, timerSource: dispatch_source_t, fireTime: CMTime, flags: UInt32) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetTimerDispatchSourceNextFireTime(_:timerSource:fireTime:flags:)) Sets the time on the timebase’s timeline at which the timer dispatch source should fire next. [`func CMTimebaseSetTimerDispatchSourceToFireImmediately(CMTimebase, timerSource: dispatch_source_t) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetTimerDispatchSourceToFireImmediately(_:timerSource:)) Sets the timer dispatch source to fire immediately once, overriding any previous timer call. ### Pausing Time Notifications [`func CMTimebaseNotificationBarrier(CMTimebase) -> OSStatus`](/documentation/CoreMedia/CMTimebaseNotificationBarrier(_:)) Requests that the timebase wait until it isn’t posting notifications. ### Data Types [`class CMTimebase`](/documentation/CoreMedia/CMTimebase) A model of a timeline under application control. [`struct CMSync`](/documentation/CoreMedia/CMSync) A type that represents time syncing. [`protocol CMSyncProtocol`](/documentation/CoreMedia/CMSyncProtocol) A type that provides behavior for syncing time. ### Timebase Errors [`var kCMTimebaseError_MissingRequiredParameter: OSStatus`](/documentation/CoreMedia/kCMTimebaseError_MissingRequiredParameter) A timebase error that indicates a parameter is missing. [`var kCMTimebaseError_InvalidParameter: OSStatus`](/documentation/CoreMedia/kCMTimebaseError_InvalidParameter) A timebase error that indicates a parameter isn’t valid. [`var kCMTimebaseError_AllocationFailed: OSStatus`](/documentation/CoreMedia/kCMTimebaseError_AllocationFailed) A timebase error that indicates the memory allocation fails. [`var kCMTimebaseError_TimerIntervalTooShort: OSStatus`](/documentation/CoreMedia/kCMTimebaseError_TimerIntervalTooShort) A timebase error that indicates the time interval is too short. [`var kCMTimebaseError_ReadOnly: OSStatus`](/documentation/CoreMedia/kCMTimebaseError_ReadOnly) A timebase error that indicates the system attempts to modify a read-only timebase. ### Constants [`#define kCMTimebaseVeryLongCFTimeInterval`](/documentation/CoreMedia/kCMTimebaseVeryLongCFTimeInterval) A constant that defines a very long elapsed time in seconds. [`#define kCMTimebaseFarFutureCFAbsoluteTime`](/documentation/CoreMedia/kCMTimebaseFarFutureCFAbsoluteTime) A constant that defines a point of time in the far, far future. [`func CMTimebaseGetTypeID() -> CFTypeID`](/documentation/CoreMedia/CMTimebaseGetTypeID()) Returns the Core Foundation type identifier that identifies a timebase object. ### Notifications [`let kCMTimebaseNotificationKey_EventTime: CFString`](/documentation/CoreMedia/kCMTimebaseNotificationKey_EventTime) A notification that a timebase posts after a discontinuous time jump. ### Deprecations [`func CMTimebaseSetRateAndAnchorTime(CMTimebase, rate: Double, anchorTime: CMTime, immediateMasterTime: CMTime)`](/documentation/CoreMedia/CMTimebaseSetRateAndAnchorTime(_:rate:anchorTime:immediateMasterTime:)) [`func CMTimebaseGetMasterTimebase(CMTimebase) -> CMTimebase?`](/documentation/CoreMedia/CMTimebaseGetMasterTimebase(_:)) Returns the immediate host timebase of a timebase. [`func CMTimebaseGetMasterClock(CMTimebase) -> CMClock?`](/documentation/CoreMedia/CMTimebaseGetMasterClock(_:)) Returns the immediate host clock of a timebase. [`func CMTimebaseGetMaster(CMTimebase) -> CMClockOrTimebase?`](/documentation/CoreMedia/CMTimebaseGetMaster(_:)) Returns the immediate host (either timebase or clock) of a timebase. [`func CMTimebaseGetUltimateMasterClock(CMTimebase) -> CMClock?`](/documentation/CoreMedia/CMTimebaseGetUltimateMasterClock(_:)) Returns the host clock that is the host of all of a timebase’s host timebases. [`func CMTimebaseSetMasterClock(CMTimebase, CMClock) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetMasterClock(_:_:)) Sets the time of a timebase at a particular source time. [`func CMTimebaseSetMasterTimebase(CMTimebase, CMTimebase) -> OSStatus`](/documentation/CoreMedia/CMTimebaseSetMasterTimebase(_:_:)) [`func CMTimebaseSetAnchorTime(CMTimebase, timebaseTime: CMTime, immediateMasterTime: CMTime)`](/documentation/CoreMedia/CMTimebaseSetAnchorTime(_:timebaseTime:immediateMasterTime:)) Sets the time of a timebase at a particular source time. [`func CMTimebaseCopyMaster(CMTimebase) -> CMClockOrTimebase`](/documentation/CoreMedia/CMTimebaseCopyMaster(_:)) Returns the immediate host timebase of a timebase. [`func CMTimebaseCopyMasterClock(CMTimebase) -> CMClock?`](/documentation/CoreMedia/CMTimebaseCopyMasterClock(_:)) Returns the immediate host clock of a timebase. [`func CMTimebaseCopyMasterTimebase(CMTimebase) -> CMTimebase?`](/documentation/CoreMedia/CMTimebaseCopyMasterTimebase(_:)) Returns the immediate host timebase of a timebase. [`func CMTimebaseCopyUltimateMasterClock(CMTimebase) -> CMClock`](/documentation/CoreMedia/CMTimebaseCopyUltimateMasterClock(_:)) Returns the host clock that is the host of all of a timebase’s host timebases. [`func CMTimebaseCreateWithMasterClock(allocator: CFAllocator?, masterClock: CMClock, timebaseOut: UnsafeMutablePointer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseCreateWithMasterClock(allocator:masterClock:timebaseOut:)) Creates a timebase by using a primary clock. [`func CMTimebaseCreateWithMasterTimebase(allocator: CFAllocator?, masterTimebase: CMTimebase, timebaseOut: UnsafeMutablePointer) -> OSStatus`](/documentation/CoreMedia/CMTimebaseCreateWithMasterTimebase(allocator:masterTimebase:timebaseOut:)) Creates a timebase by using a host timebase. --- Copyright © 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)