# Adding parameters to plug-ins Create standard and custom user-facing parameters for your plug-in that will appear in the inspector. ## Discussion Once a plug-in is invoked by a host application, the host application asks for the plug-in’s parameter list by calling the [`addParameters()`](/documentation/professional_video_applications/FxTileableEffect/addParameters()) method. This method is declared in the `FxBaseEffect` protocol, which is inherited by the [`FxTileableEffect`](/documentation/professional_video_applications/FxTileableEffect) protocol. The host application then displays the parameters in its inspector. ### Add a parameter The FxPlug SDK includes methods for adding these standard types of parameters: - Floating-point, integer, and percent sliders - Angle slider - Toggle button (checkbox) - RGB or RGBA color - Point - Popup menu - String - Histogram - Gradient - Path picker - Font menu - Help button - Push button - Image Reference - Group  In the [`addParameters()`](/documentation/professional_video_applications/FxTileableEffect/addParameters()) method, a plug-in first calls the [`api(for:)`](/documentation/professional_video_applications/PROAPIAccessing/api(for:)) method (defined by the `PluginManager` framework) to get the host API object that implements the protocol. It then adds parameters, one by one, using methods in the [`FxParameterCreationAPI_v5`](/documentation/professional_video_applications/FxParameterCreationAPI_v5) protocol. For example, the following code shows an `-addParametersWithError:` method from a simple opacity filter: > Important: Parameter IDs must be in the range of `[1, 9998]`. IDs outside of this range are invalid. ```swift func addParameters() throws { let paramAPI = _apiManager!.api(for: FxParameterCreationAPI_v5.self) as! FxParameterCreationAPI_v5 paramAPI.addFloatSlider(withName: "Opacity", parameterID: 1, defaultValue: 1.0, parameterMin: 0.0, parameterMax: 100.0, sliderMin: 0.0, sliderMax: 10.0, delta: 0.1, parameterFlags: FxParameterFlags(kFxParameterFlag_DEFAULT)) } ``` > Note: > A Mix slider parameter is automatically added filter plug-ins, and a Publish OSC toggle parameter is automatically added in Motion to any plug-in that contains onscreen controls. The Publish OSC toggle parameter is never visible in Final Cut Pro. ### Create a custom parameter In addition to the standard parameter types, you can use the following method to create a custom parameter with an opaque data type: ```swift addCustomParameter(withName:parameterID:defaultValue:parameterFlags:) ``` Each custom parameter must be associated with a custom parameter view, which is defined by the methods in [`FxCustomParameterViewHost_v2`](/documentation/professional_video_applications/FxCustomParameterViewHost_v2). ### Interact with parameters When a user changes a parameter control for an FxPlug plug-in, the host application calls the [`parameterChanged(_:at:)`](/documentation/professional_video_applications/FxTileableEffect/parameterChanged(_:at:)) plug-in method. This is useful for a plug-in that changes the state of other parameters. For example, if the user changes a toggle button, the plug-in can hide or reveal other parameters during [`parameterChanged(_:at:)`](/documentation/professional_video_applications/FxTileableEffect/parameterChanged(_:at:)). ### Handle user interaction for custom UI parameters Custom UI parameters let developers draw directly to a custom UI and create their own controls in a space that the host application makes for them in the inspector. The host application handles user interaction for custom parameters in a different way than standard UI parameters. For example, when you develop custom parameters, they must conform to the [`FxCustomParameterViewHost_v2`](/documentation/professional_video_applications/FxCustomParameterViewHost_v2) protocol. An example of this can be found in the `FxSimpleColorCorrector` sample plug-in. In your plug-in, custom parameters conform to the `FxParameterViewHost` protocol by implementing a [`createView(forParameterID:)`](/documentation/professional_video_applications/FxCustomParameterViewHost_v2/createView(forParameterID:)) method that provides an subclass to the host app. Like any other `NSView` subclass, this custom view draws itself in a window and receives notification of any user actions such as mouse, key, and tablet events. In response to user events, the custom view sets parameter values. Usually it sets the value of a custom parameter. The host application notices that a parameter value has changed and calls the plug-in to render with the new parameter values. The plug-in can create a custom view object programmatically or retrieve it from a `XIB` file (created in Xcode’s Interface Builder and placed in your plug-in’s `Resources` folder). Your plug-in’s custom view methods must call the [`FxCustomParameterActionAPI_v4`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4) host API [`startAction(_:)`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4/startAction(_:)) method before your plug-in accesses any parameter values, and then call the [`endAction(_:)`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4/endAction(_:)) method after it has finished accessing the parameter values. This lets the host application set up and restore the internal state. ### Update versioning for your plug-in’s parameters As you develop plug-ins over time, you may need to deprecate, add, or update your parameters, like changing a default value or range. To ensure that projects using your older plug-ins still function correctly, use [`FxVersioningAPI`](/documentation/professional_video_applications/FxVersioningAPI) to find out the version of the plug-in that’s used with a project. With this information, you can branch your parameter code, update your project, and handle special cases as needed. For example, if you create a version 1 brightness filter with a floating point slider and apply it to a project, the project saves the plug-in’s version number along with the slider value. On subsequent launches of the project, you can query [`versionAtCreation()`](/documentation/professional_video_applications/FxVersioningAPI/versionAtCreation()) and check for a version number of `1`. See [Versioning and obsoleting old plug-ins](/documentation/Professional-Video-Applications/versioning-and-obsoleting-old-plug-ins) for more information. > Tip: If you later update the brightness filter to use a second parameter, update the version of your plug-in. Then, on subsequent launches, do a version check and add a second path for a version number of `2`. ## Topics ### Parameter APIs [`protocol FxParameterCreationAPI_v5`](/documentation/professional_video_applications/FxParameterCreationAPI_v5) Defines the methods provided by the host application to create parameters. [`protocol FxParameterRetrievalAPI_v6`](/documentation/professional_video_applications/FxParameterRetrievalAPI_v6) Defines the functions the application provides to retrieve parameter values. [`protocol FxParameterRetrievalAPI_v7`](/documentation/professional_video_applications/FxParameterRetrievalAPI_v7) Adds a method to retrieve the image information about an image parameter. [`protocol FxParameterSettingAPI_v5`](/documentation/professional_video_applications/FxParameterSettingAPI_v5) Defines the functions the application provides to set parameter values. [`protocol FxParameterSettingAPI_v6`](/documentation/professional_video_applications/FxParameterSettingAPI_v6) Defines the functions the application provides to set parameter flags. [`protocol FxDynamicParameterAPI_v3`](/documentation/professional_video_applications/FxDynamicParameterAPI_v3) Allows your plugin to create parameters on-the-fly. ### Custom Parameter APIs [`protocol FxCustomParameterViewHost_v2`](/documentation/professional_video_applications/FxCustomParameterViewHost_v2) Defines the methods a plug-in needs to implement to associate a custom NSView with one of its parameters. [`protocol FxCustomParameterActionAPI_v4`](/documentation/professional_video_applications/FxCustomParameterActionAPI_v4) Defines the methods the host application provides to support a custom parameter view. [`protocol FxCustomParameterInterpolation_v2`](/documentation/professional_video_applications/FxCustomParameterInterpolation_v2) Defines the methods a plug-in needs to implement to support keyframing custom parameters. ### Constants [`typealias FxParameterFlags`](/documentation/professional_video_applications/FxParameterFlags) These constants specify the characteristics of parameters display. [`typealias FxHistogramChannel`](/documentation/professional_video_applications/FxHistogramChannel) Constants used to identify which channel a histogram operation should apply to. --- 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)