Joe Maller: FXScript Reference: FXScript Basics

Final Cut pro uses FXScripts in three ways; as Filters, Transitions or Generators. There isn't much difference between these scripts, mostly it's just the first word of a script determines how Final Cut Pro will handle the script. From a functional point of view, the most basic differences between the three kinds of FXScripts are:

• Generators do not need a source clip
• Filters use only one source clip
• Transitions use two source clips

Writing FXScripts with FXBuilder

FXBuilder is the tool included with Final Cut Pro for building filters. Use FXBuilder to create new scripts or modify existing filters. To access FXBuilder, choose it from the top of the Tools menu or select a filter from from the Effects browser tab and choose "Effect Editor" from the View menu.

There are three main components of FXBuilder:

• FXBuilder Text Entry tab

  The main source code tab. This is where scripts can be built and tested before saving them as text files or compiling them as filters.

• FXBuilder Input Controls tab

  These update when you run a script.Together with the FXBuilder preview window this allows for real-time testing of scripts in progress.

• FXBuilder Preview Window

  The small window that pops up when running a script from FXBuilder. It shows the effect of a script in real-time on a thumbnail image.

To test a script, choose RUN from the FXBuilder menu or press Command-K. Clips dragged into the Source 1 box of FXBuilder Input Controls will appear in the preview window.

When I'm working on scripts, I usually rearrange the FXBuilder windows to make working easier. My usual FXBuilder setup looks something like this (only much sloppier):

Other Tools

If you are going to be working with FXScript, BBEdit or BBEdit Lite (free) can not be recommended highly enough. These incredibly powerful text editors with programmer's tools make writing FXScript code much easier. I tend to develop my code in BBEdit and paste it into FXBuilder for testing.

One of the best functions of either BBEdit is the multi-file searching. Point BBEdit at your Final Cut Pro plugins folder and search for a function name and immediately preview every usage of that function. Sherlock could also be used to search for function names within files by checking the Contents option in the search bar, but BBEdit Lite is free, so there's no reason not to try it.

Other great things about BBEdit are Parentheses flashing (Balancing) so you can see when they are closed and Syntax Coloring (choose C++ or work with the file extension ".cc", Final Cut Pro won't care) for a basic coloring of FXScript source code. It's not perfect, but it's better than all gray.

About the FXScript Language

The syntax of FXScript is similar to JavaScript, which I'm told is similar to C++ and Java. These similarities helped me to discover a basic understanding from sites found around the web, some of the code examples on Paul Haeberli's Graphica Obscura Web site are very similar to FXScript.

FXScript uses a more programmatic syntax than AppleScript. Though it might take a bit longer to learn at first, it's much more efficient and does a lot more with fewer words.

The language is case-insensitive (capitalization doesn't matter) although I do try to at least be consistent about variable names and functions.

Line breaks are indicated with a semicolon (;) or a linebreak (return). Statements must appear on the same line. Semicolons can be used to put shorter commands onto the same line.

Unfortunately, FXScript is only for visual effects. There is no mention of audio effects or controls anywhere in the manual, and the audio filters can't be edited or viewed.

Programming is sort of like learning to read and write music. Once the language's syntax is understood, the flow is very logical and usually easy to understand. After reading through a few scripts, it should start to make some sense. If you are looking for a more general overview of scripting and scripting syntax conventions, you might want to skim the first few chapters of some books about other scripting languages or visit web tutorials about AppleScript or JavaScript.

Script Structure

Every FXScript is has two sections; the Definition section and the Code section. Scripts seem to be linear, so items must be defined before they are used, this includes any subroutines which need to appear above any commands which reference them.

Definition Section

The definition section is everything before the code line. This is where filters are assigned their type and menu position. All user input controls are declared in the Definition section.

Final Cut pro checks the definition section of every text file in the plugins folder at startup. If any syntax errors are encountered in the definition section, Final Cut Pro will ignore that FXScript and it will not appear in the menus.

The first two lines of the definition section assigns a type (filter, generator or transition) and a group:

filter "Joe's Filter";
group "Joe's Filters";

The above lines would create a filter named Joe's Filter in a menu group named Joe's Filters. The filter line sets the title, while group tells Final Cut Pro which which submenu to show the script in. Scripts are not limited to existing submenus, if the submenu named by a filter does not exist, Final Cut Pro will create it.

Next would be the controls for adjusting filter values, see the FXScript User Input Controls page for explanations and examples of FXScript controls.

Additional Definition Items

Besides the Filter, Transition, Generator and Group definitions, there are several other items that can appear in the definition section. Most are somewhat cryptic and their function is not always easy to understand.

• FullFrame

  Several of the included filters contained this definition flag, and it can cause headaches where it is used. Including this flag in an FXScript tells Final Cut Pro to ignore fields (interlacing) and render the effect without fields. This does not mean the image will be de-interlaced, it just means the filter will update 30 times a second instead of 60 (for NTSC).

• InformationFlag("YUVaware")

  This item is discussed more completely on the FXScript RGB and YUV Color page. It tells Final Cut Pro to look out for YUV and RGB pixel data and conversions while executing the script.

• ProducesAlpha

  This item is tells Final Cut Pro that there might be an alpha channel (transparency) created by this file. Including this does not mean your filter will automatically create transparency, it just means the filter is capable of displaying transparency.

• WipeCode(code, accuracy)

  All of Final Cut Pro's built-in transitions include this line immediately following the Definition and Group statements. Code and Accuracy are replaced by numeric values. Every built-in transition sets accuracy to 100, but code varies, most transitions keep it at zero, some go over 100. The Final Cut Pro manual cryptically defines this line as:

  "Defines the transitions's wipe code."

  That doesn't help much.

  I haven't been able to discern much effect from trying different values, FXBuilder didn't choke even on six-digit numbers. What's more confusing is that omitting the line doesn't seem to have any affect on the dozen or so transitions I tested.

  Unless I discover some justification for the numbers, I'm probably going to include WipeCode(0,100) in my transitions. I'm not sure what effect it has, and don't want to be surprised down the road. The line appears in all of Apple's filters, I might as well be better safe than sorry. The values (0,100) are most common.

Definition Flags not covered: KeyType, AlphaType, QTEffect, EffectID, InvalEntireItem and RenderEachFrameWhenStill

Code Section

Code is the magic divider, occurring on it's own line and separating the input/definition section from the active section of the script. Code must be present in all FXScripts or they will return an error. Final Cut Pro scans all filters and text files in the Plugins folder when the application starts up. If Final Cut Pro finds anything wrong in this section the script will not appear in the menus.

Saving FXScripts

To use an FXScript in Final Cut Pro the script must be saved as a text file or exported as a plug-in. Because plain text files work, filters can be written and saved with just about any text editor. I mostly use BBEdit because it probably has the best set of tools available for working with programmatic text on a Mac.

To export a plug-in or encoded plug-in, your script must first be in an FXBuilder window. Get the script into FXBuilder by either pasting the script from a text file, or selecting Effect Editor from the View menu (a script must be selected in the Viewer or Browser windows first). Create Plug-in and Create Encoded Plug-in are choices in the FXBuilder menu. Remember this menu is only visible when an FXBuilder window is selected. There are no formatting choices, just name the file and save it wherever you want it to go.

The Shareware version of Joe's Filters are distributed as encoded plugins. Otherwise it would have been so ridiculously easy to defeat the watermark that only the most scrupulous people would have paid. I know that if I downloaded a set of filters and they were completely unlocked I probably wouldn't pay for a long time, if ever. The truth hurts.

The paid version of my filters are distributed as text files. This way anyone can learn from and improve upon them. It's disappointing that the Eureka filters were only distributed locked, and since the author has more or less vanished, there is no way anyone can improve upon or expand those filters without starting from scratch. Also, no one can take them apart to learn from them.

I hope anyone who buys the filters will take them apart, see how I built them and then go build their own.