<!--
{
  "documentType" : "article",
  "framework" : "professional_video_applications",
  "identifier" : "/documentation/Professional-Video-Applications/understanding-time-in-fxplug",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Understanding time in FxPlug"
}
-->

# Understanding time in FxPlug

Learn about time handling in host apps and plug-ins.

## Discussion

FxPlug 4 uses rational time of <doc://com.apple.documentation/documentation/CoreMedia/CMTime> type to handle all timing in the host apps and plug-ins. Time can be in the form of a specific time or duration in an effect, object, or timeline (project). When FxPlug methods use `time` or `renderTime`, that time generally refers to the current time that the host is providing or requesting. [`FxTimingAPI_v4`](/documentation/professional_video_applications/FxTimingAPI_v4) provides methods to access other time values available in the host app. For FxPlug methods that don’t provide time, you can use [`FxCustomParameterActionAPI_v4`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4)’s  [`currentTime()`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4/currentTime()) to determine current playhead time in the project.

### Time in Motion

In Motion projects, timelines always start at zero, regardless of the custom timecode the user may set in the project’s properties. Input time is also always relative to the timeline start time. Other times of significance are indicated in the following figure.

![Screenshot of a Motion timeline showing a variety of times, ranging from Zero Timeline time on the left to Maximum Timline Time on the right.](images/com.apple.professionalvideoapplications/media-3695370@2x.png)

### Time in Final Cut Pro

In Final Cut Pro, projects can start at any timecode set by the user, and their timeline time will be continuous from that start time. Timeline time is independent of Input Time in Final Cut Pro, so [`FxTimingAPI_v4`](/documentation/professional_video_applications/FxTimingAPI_v4) provides two convenience methods to convert between them: [`timelineTime(_:fromInputTime:)`](/documentation/professional_video_applications/FxTimingAPI_v4/timelineTime(_:fromInputTime:)) and [`inputTime(_:fromTimelineTime:)`](/documentation/professional_video_applications/FxTimingAPI_v4/inputTime(_:fromTimelineTime:)). The following figure shows various times in the FxTiming API.

![Screenshot showing the Final Cut Pro timeline with a variety of times labeled, from Timeline Start Set by User on the left to Current Input Time on the right.](images/com.apple.professionalvideoapplications/media-3695369@2x.png)

> Note:
> Although the timeline’s start time is set by the user, the timecode of the timeline will not necessarily correspond to the rational time your plug-in uses. This difference may be due to drop-frame timecode, or because the timecode resets to `00:00:00:00`. For example, if the user sets the project start timecode to `23:59:50:00`, the rational start time of the timeline when converted to seconds may be `86476.39` seconds, but will NOT reset to `0` seconds when the timeline’s timecode reaches `00:00:00:00`.

### Motion effect templates

You must [apply FxPlug plug-ins to a Motion template](https://support.apple.com/guide/motion/intro-to-final-cut-pro-templates-motn17691fe6/mac) to use it in a Final Cut Pro project. You may notice significant differences in how [`startTime(forEffect:)`](/documentation/professional_video_applications/FxTimingAPI_v4/startTime(forEffect:)), [`durationTime(forEffect:)`](/documentation/professional_video_applications/FxTimingAPI_v4/durationTime(forEffect:)), and [`startTimeOfInput(toFilter:)`](/documentation/professional_video_applications/FxTimingAPI_v4/startTimeOfInput(toFilter:)) return time values. To understand these differences, imagine that an effect template added to a clip in Final Cut Pro is equivalent to a complete timeline in Motion. For example, in Motion, [`startTime(forEffect:)`](/documentation/professional_video_applications/FxTimingAPI_v4/startTime(forEffect:)) will return the plug-in effect’s start time relative to the Motion timeline. In Final Cut Pro, the same method will return the start time of the plug-in effect, relative to the native start time of the clip to which the user applies the template, regardless of the how much of the clip’s head has been trimmed by the user.

### Retiming and frame duration

Effect templates that you apply to clips or other objects in Final Cut Pro may stretch to match the duration of the clip. When clips with effect templates are retimed by the user in Final Cut Pro, the effect template will adjust proportionally.

Unlike in Motion, [`frameDuration(_:)`](/documentation/professional_video_applications/FxTimingAPI_v4/frameDuration(_:)) and [`sampleDuration(_:)`](/documentation/professional_video_applications/FxTimingAPI_v4/sampleDuration(_:)) always return the native frame or sample durations of the clip, regardless of how fast or slow you retime it. If your plug-in attempts to determine the frame duration or frames per second of the timeline, then use [`timelineFpsNumerator(for:)`](/documentation/professional_video_applications/FxTimingAPI_v4/timelineFpsNumerator(for:)) and [`timelineFpsDenominator(for:)`](/documentation/professional_video_applications/FxTimingAPI_v4/timelineFpsDenominator(for:)) to make that calculation, as shown in the example below.

```swift
let timingAPI = _apiManager!.api(for: FxTimingAPI_v4.self) as! FxTimingAPI_v4
var timelineFrameDuration = CMTimeMake(value: Int64(timingAPI.timelineFpsDenominator(for: self)),
                                           timescale: Int32(timingAPI.timelineFpsNumerator(for: self)))
```

---

Copyright &copy; 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)