Joe Maller: FXScript Reference: FXScript BasicsDescribes some basics information about creating FXScripts for Final Cut Pro.
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:
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:
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):
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
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.
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.
The definition section is everything before the
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:
The above lines would create a filter named
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.
Definition Flags not covered:
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.