Adding Custom UI to Motion Templates through Native Plug-Ins

This tutorial guides you through the process of adding certain UI elements to a Motion Template that are not, by default, available in Motion.

You may be looking to add a banner graphic at the top of the parameter inspector to improve brand recognition and provide access to product documentation. You may be looking to divide a long list of parameters into sections through the use of dividers (textual labels) as a substitute for the fact that Motion does not let developers create and publish parameter groups.

Banner graphics and section dividers can be added to any Motion Template hosted in a FxTemplates project by borrowing functionality from FxPacks, the project file format used to implement native plug-ins.

Phase 1: Create an FxPack

Let us assume that your current FxTemplates project is called “Goodies” and the author is “ACME”. In the FxFactory app, select FileNewPlug-Ins to create a new project to host your native plug-ins:

Click Continue to create the first plug-in in the FxPack.

Leave the plugin type as Generator if you are only interested in using the native plug-in for custom UI. If you need to use this plug-in to host an Object Tracker too, set the effect type to Filter.

Since the product name is “Goodies” call the plug-in “Goodies UI” as a reminded that the plugin will be used solely for the purpose of adding UI to your Motion Templates. In following other FxFactory conventions, set the plugin to appear under a category that is formed by author, or author + product name, e.g. “ACME Goodies”:

The plugin will only be used inside Final Cut Pro and Motion and it will not require a watermark, so the next step is to turn off the corresponding options inside the Info section:

Disable Rendering for Better Performance and eGPU Compatibility

Switch to the Renderer section and turn on the option named Do not render any output through the composition:

That option is new in FxFactory 7.1.7 and it instructs your plug-in to forego any rendering operations, so that while its UI remains functional in the parameter inspector, it will not produce any output through its composition. Please note the following side effects:

  1. Disabling rendering allows plug-ins to avoid errors on systems connected to an eGPU, when the underlying composition is based on Quartz Composer1).
  2. Disabling rendering provides a performance benefit, since the plug-in skips any work involved in rendering your composition, no matter how simple it may be. This is equally true if your plugin is based on Quartz Composer or FxCore.
  3. Disabling rendering does not mean that your generator produces a transparent output, or that your filter acts as a passthrough. Instead, your plugin will produce a solid black output2). You obviously need to account for this in your Motion Template, as described below.

Since your plug-in can potentially generate a solid black output, you should plan to modify all your Motion templates accordingly. If your custom UI plugin is a Generator, make sure its layer opacity is set to 0%:

When the layer opacity is set to 0%, it does not matter what the output of your plugin is. The host app will simply ignore it.

If the plugin is a filter (perhaps because you are planning to use it for object tracking as well) set its Mix value at the end of its parameters list to 0%:

When you set the mix slider to 0%, the host app will ignore any modifications made by your plugin to its layer, thus guaranteeing that the original media will render as is.

Back to the plug-in

Assuming that you have completed any modifications to your Motion Templates, or that you plan on making those changes at a later time, switch back to the FxPack.

Assign the same icon to the FxPack that you are already using for the FxTemplates project 3). To do that, add the same graphic file to the product’s Assets section in the FxPack and switch to the Product section:

There are a few things to do under the Product section:

  1. Assign the icon graphic you just added to the Assets section.
  2. Provide a product’s description, since the one found in the FxPack project will now become the one used for the product as a whole.
  3. Make sure the author, product ID and vendor ID match those you had supplied in the FxTemplates product.
  4. Switch the Visibility option to Hide Product and Plug-Ins. Since your FxPack is only useful in a supporting role to your Motion Templates, there is no reason users should be able to see the product or the custom UI plug-in when the commercial version is installed.
  5. Update the product Requirements section to reflect similar values in the FxTemplates project. If your FxTemplates product targets Final Cut Pro 10.4 you should enter a minimum macOS version of 10.12.4. If the current FxFactory release is 7.0.6, you might want to use “7.0” as the minimum version required.
  6. Disable the “After Effects” and “Premiere Pro” options under the Requirements section, since this plugin will have no reason to be available inside those apps.
  7. Leave the Requires Watermark option on. This is very important: even though your custom UI plug-in does not require a watermark, the product as a whole (including your Motion Templates) do.

Phase 2: Adding Your Custom UI to the FxPack

Switch to the Parameters section of the plugin to begin building your custom UI:

Notice that the default generator created by FxFactory comes with a few parameters. You will not need these parameters or the output of the generator, so your first step is to select and delete them:


As an exercise to the reader, you can also edit the composition and delete its entire rendering logic (i.e. all patches in the composition). This step is optional, and it makes sense only if you are in fact developing a generator whose only purpose is to provide custom UI for your templates. In this very specific case, the layer that hosts this plugin can be disabled in the Motion project to avoid paying any performance penalty. Why bother removing all patches from a composition then? An empty composition uses less disk space than one with any content at all, so it will load faster and make the resulting product leaner. It does not make sense to delete all patches in the composition if you are developing a filter plugin that is used both for custom UI and to provide an object tracker. FxFactory considers a filter to be valid only if it has certain required inputs mapped. In particular, a filter is supposed to have a main image input. If said input is not mapped, the plugin will not be loaded by Motion or Final Cut Pro.


Next, add a banner and a section divider. Both parameter types are available under the + button below the parameter list:

First, let’s configure the Banner parameter according to the most common scenario:

The most unintuitive aspect of a banner is its graphic. You can supply a colorful graphic if you wish, but the option that works best is to supply a black-only graphic with alpha and enable the Invert over dark background option below. This tells FxFactory to treat the image as a reference graphic, to be inverted when displayed in a dark UI 4) This particular feature has allowed FxFactory to always display your banner graphics correctly no matter how the host application is configured. Video apps have recently settled on dark UIs, but not long ago it was possible to alter the appearance and future versions may again give users that option.

Your banner graphic should look great on Retina (HiDPI) displays. Create the graphic as a PNG file at 144dpi resolution, and ensure its dimensions in pixels are twice the intended display dimensions in points. Banners should not be wider than 148 points, equivalent to 296 pixels at 144dpi, if you wish the graphic to be fully visible when users have resized the parameter inspector to its minimum width. If your banner graphic is wider than 148 points, it may get cropped.

The second unintuitive truth about the banner parameter is that you do not need to supply a second graphic for the “click” state. By default, FxFactory will lighten or darken your graphic to indicate the pressed (clicked) state. You can supply a different graphic only if you wish to customize this behavior.

Lastly, if you wish to link your banner to the product’s website or documentation, make it clickable and enable the Add button to perform the same action option. This tells FxFactory to display a “Help” button to the side of the graphic. The button makes it obvious to users that the banner is more than cosmetic. Users can click either the graphic or the button to access the product’s website or documentation.

You can certainly create more than one banner graphic, but if you are looking for a way to help organize parameters in the inspector, Section Title parameters are a better choice.

Select the lone Section Title parameter you created earlier to view its options:

Strictly speaking, there is a single option to configure: the text displayed in the inspector. You can customize font, size and alignment of the title with a few caveats:

  • The system font is usually the better choice as it matches the UI in most host apps. This is especially true of Final Cut Pro.
  • If you select a different font, do not use a font that may not be installed on all macOS systems.
  • You can simply enter a space to create a section title that renders no text, i.e. a spacer. You can tweak the font size to increase the vertical size of this spacer.
Create as many Section Title parameters as you need in all your Motion Templates. For example, if your templates contain parameters that affect Geometry and Background, create two Section Title parameters with those titles to be used in the effect UI.

When you are satisfied with the parameters created in the native plugin, save the product. You may – if you wish – launch Motion to test this generator. If you add it to your timeline and switch to the parameter inspector, you will notice the banner and section title parameters you just created. These are now available to your Motion Templates for publishing, but there are a few more steps to make that happen.

Phase 3: Bundling the FxPack and FxTemplates Projects Together

FxFactory must be told that the FxPack we just created is linked to the FxTemplates project that contains your Motion Templates. Ultimately, these two are components of a single product.

Open the FxTemplates project and switch to the Product section. Under the Bundled with popup menu, select the “ACME Goodies” product (the FxPack created in Phase 2). Notice that certain options in the UI will become grayed out as a result:

The reason you will no longer be able to edit certain values is that they are now inherited from the parent product, the FxPack. If you wish to change these values, you will now have to edit them inside the FxPack instead.

The FxPack and FxTemplates for your product must always be installed at the same time. If you install one without the other, or if you mix and match editable and commercial versions, you risk losing configuration data.

After the FxTemplates project has been bundled with an FxPack, it will behave slightly differently. If you make changes under the Product section in the FxPack, you will be asked to migrate those changes when you open its FxTemplates counterpart. It is a good idea to immediately save these migrated changes to disk.

Phase 4: Adding Your Custom UI to the FxTemplates

It is finally time to add your custom UI to the Motion Templates. With both editable versions of your FxPack and the FxTemplates installed, Edit one of the Motion Templates in the FxTemplates project with Motion.

Your new generator is available under ACME GoodiesGoodies UI:

Add it to your timeline and switch to the parameter inspector. Notice that you can publish the banner and section title parameters you created earlier:

You can now improve the UI of your Motion Template with banners and dividers as you please, but one last step is required to wrap things up: there is no reason the custom UI plug-in should rendering anything. Disable the plug-in’s layer:

Even when its layer is disabled, the published parameters are still available and functional. On the plus side, no performance penalty is incurred by having Motion load and render the composition. Win-win!

If you wish to make changes to the custom UI, such as adding new banners or section titles:

  • Quit Motion.
  • Edit the FxPack, and its custom UI plugin, in order to modify its parameters.
  • Save the FxPack.
  • Edit the FxTemplates.
  • Edit any Motion Templates that should adopt the changes.

If you forget to quit Motion, you do not give FxFactory a chance to load the changes you have made to the native plugin.

This concludes the portion of the process that developers can complete on their own. We perform additional steps when turning your editable product into a commercial one.
1)
Plug-ins based on FxCore do not encounter the same problem with eGPUs, but disabling rendering will still improve performance of your templates.
2)
This part is up to the host, and the behavior thus described applies to the latest version of Final Cut Pro and Motion.
3)
It makes the products easier to spot in the UI.
4)
A similar concept and behavior can be observed with Cocoa’s NSImage class, when instances are marked as a template.