Joe Maller: FXScript Reference

FXScript is the native effects language used by Apple's Final Cut Pro for creating or modifying generators, filters and transitions. It's one of the most powerful elements of the program but almost no one knows it exists.

When I first started exploring FXScript, I found a web posting by Michael Horton of the Los Angeles Final Cut Pro User Group where he half-jokingly commented:

"...if you can use the FX builder then you will be one of 5 people in the world who know how to use that dang thing."

It's been a while since I first posted this, and there have to be more than five of us now.

One reason for the lack of FXScripting is how spare available documentation is. Apple used to have a FXScripting web page which offered nine addon FXScripts for download with no reference materials of any kind. The site disappeared when Final Cut Pro 2.0 was released. Since first publishing this, many new Final Cut Pro books have been published, many with FXScripting chapters.

My goal in writing this down is to help others get started making effects for Final Cut Pro. However, I've found many similarities to other programming languages while researching this, so this site might be helpful to more then just Final Cut Pro users.

About the FXScript Reference

These pages grew out of notes I made while developing Joe's Filters. A lot of what is covered on these pages resulted from experimenting and dissecting the scripts included with Final Cut Pro.

The reference into the following sections:

• FXScript Reference

  This page.

• FXScript Basics

  Introduces FXScript and FXBuilder, discusses basic formatting and syntax.

• FXScript Constants

  Lists and describes many of FXScript's predefined variables.

• FXScript Variables

  Discusses different data types and how to define and store information in variables, arrays and image buffers

• FXScript Functions

  Covers the basic idea and workings behind FXScript's functions, as well as specifics behind several of the functions I've used.

• FXScript Input Variables

  Shows and explains the different kinds of variables in FXScript, how to use them and what their various attributes represent.

• FXScript RGB and YUV Color

  Talks about specific issues when dealing with RGB and YUV color spaces, how to change color spaces and some symptoms of using the wrong color space.

• FXScript FAQ

  A place for questions and answers about FXScript and Joe's Filters.

Things you should probably know

I've tried to start slow, but there are some assumptions I make to keep things flowing. If you've been working with computer graphics for a little while most of this should probably be second nature. Basic programming ideas like variables and functions will be covered, but I try to explain these when discussing how FXScript deals with them.

• RGB and Alpha channels

  Images are constructed from a mix of red, green and blue light channels plus one alpha channel to define transparency. Channels are easiest to think of as grayscale files, each pixel's brightness value translates to the intensity of the corresponding color. For Alpha Channels, each pixel's brightness indicates the opacity of the corresponding pixels. Each channel is made up of 256 levels of gray (8 bits), when all four channels are combined they can create over 4 billion combinations of color and transparency (32 bit color). The range of numbers between 0-255 appear frequently referring to pixel values in channels and averaged pixel values of whole images. Remember that computers usually start counting from zero instead of one.

• If-Then-Else Statements and Basic Flow Controls

  If/then statements control the direction of a script. These basically check whether something is true or false and then do one thing or another. These are really very simple abstraction of everyday life. Either something happens or it doesn't; either way, new choices become available. There is a reason these structures are referred to as logic.

• Basic Memory Management

  If you've used the clipboard, you've already managed your computer's memory. Managing memory is a lot like putting stuff in your pockets. Pockets free our hands to do or hold other things, memory works the same way.

About Image Processing

The Hypermedia Image Processing Reference is an amazing reference on image processing from a math-intensive computer science perspective. The site was published by the Department of Artificial Intelligence at the University of Edinburgh. It's huge and somewhat overwhelming considering I'm used to using these tools, not building them. However, it's interesting to explore the space between conventional right-brain creativity and the left-brain technology that makes all this stuff work.

Here are some additional sites which might be helpful:

Matrix Operations by Paul Haeberli (a part of SGI's Graphica Obscura)

Lecture notes from Prof. Frederic I. Parke (Texas A&M)

• Digital Images
• Color Spaces
• Image Statistics (histograms)
• Operations or Functions on Images
• Neighborhood Operations
• Morphological Operations

Professor Parke's notes refer to this book, which is unfortunately out of print:

Digital Imaging : Theory and Applications by Howard E. Burdick

Also see The C Terrain by Nitin Gupta, a fantastic, funny and lengthly introduction to programming in C. (remember that FXScript syntax is very similar to C)

Other FXScript Resources

Unfortunately, this list isn't very long. However, that shortage or resources was a major factor in my sitting down to write out these pages. I've been searching the web extensively and nothing much comes up. Here's all I found:

2-Pop's FXScript page

If you know of any other FXScript resources, please send me a note and I will add them to the list.

Final Cut Versions

This reference was mostly written and tested on Final Cut Pro 1.2.5, then updated for Final Cut Pro 2.0. All of Joe's Filters have been tested on Final Cut Pro 2.0, and needed no modification. FXScript was revised between version 1.2.1 and 1.2.5, when YUV functions were added and clarified. FXScript changed very little between versions 1.2.5 and 2.0, most all of the included Final Cut Pro filters were unchanged.

Improvements in Final Cut Pro 3.0

Not much changed for FXScript with the new version. On OS X, the FXBuilder editor seems to have been carbonized, so type is anti-aliased, drap and drop editing works, and the save dialogs are OS X clean. Most noticably, the plugin controls have been reworked and now take up less space. Aquafied radio buttons and checkboxes were also added.

So far, Apple hasn't documented the workings of the three-way color corrector or other visual controls. These effects do have FXScript attached to them, but very few of their commands are documented and I haven't been able to get any changes to work.

Is this free? Are you crazy? Why not a book?

Yes. My FXScript Reference is free, but my filters are shareware. If you find this helpful, please consider buying the filters as a show of suppor, they're fairly useful too. Several people suggested some sort of donation mechanism, so I added PayPal and a checkbox to the Kagi purchasing page.

I am open to any discussions of expanding this site into a book. As it stands now though, FXScript isn't popular enough for most publishers. I doubt that will change any time soon.

Most of the time, I do not think I am crazy. There is some evidence to the contrary however.

Instructional Use

If the information contained on these web pages will be used in a paid instructional environment please consider purchasing a set of my filters for each student. The price is very reasonable and could be built into the tuition or administrative costs of the course. Thank you in advance for helping me to help you.

Some of my other online tutorials have been used in classes where students pay tuition to attend. I like knowing that my work is helping people learn, but I'm slightly disturbed that someone could be getting paid as a teacher while passing out my work then sitting back and drinking a coffee. Hopefully this isn't the case, but in at least one instance, I have reason to believe that is the situation.

Disclaimer

All explanations provided in my FXScript Reference are based on research and conclusions made while writing Joe's Filters. I am not a trained programmer, and the contents of this site are provided as is.

If I got something wrong, please let me know: