To use the scripts that are published on this site, merely download the .script file that is listed under Download on the script's description page, and Import the script using the command under "Advanced->RFX Effects, Tools, and Utilities" menu. and then run the "Rebuild all RFX plugins" command in the "Advanced->RFX Effects, Tools, and Utilities" menu.

The new command will appear under the "Effects->Custom Effects" menu for effects, the "Edit->Merge Clipboard with Selection" menu for transitions, and the "Tools" menu for tools and generators.

The rest of this page covers how to write your own RFX-GIMP scripts.

Most scripts will be written using the LiVES RFX Builder utility. To start using RFX Builder, open up the "New Test RFX Script" dialog from the "Advanced->RFX Effects, Tools, and Utilities" menu.

Fill in (at a minimum) the Name, Author, Menu Text, and Action Text fields. For the following example, a simple "Invert" script will be created. The script merely negates the colors of the selected video.

Open the "Pre loop code" editor and paste the code from the default.preloop file. This code runs once before your processing begins and sets up communication with GIMP's Script-fu server (starting GIMP if necessary), defines a Perl subroutine ('&rfx_sendmsg') for sending Script-fu code to GIMP, and defines some utilities in Script-fu that facilitate scripting (currently only the procedure 'rfx-save-frame'). This pre-loop code should typically be identical for any RFX-GIMP scripts that you write (though it does not have to be).

After you've pasted the Pre-loop code, close the editor and open the "Loop code" editor. This is where you will be writing your Script-fu script. Your loop code will typically consist of a single call to the 'rfx_sendmsg' subroutine, passing as its argument a string containing your Scheme script.

The 'qq' quoting provided by Perl's Text::Balanced module makes it easy to build this string while being free to spread you code across several lines and employ Scheme-style indentation. If you use 'qq{ ... }' as your delimiters, ticks (single-quotes) and double quotes will not present a problem; just be careful about using curly braces in your code (it is easy to avoid them in Scheme). Also, avoid using symbols that begin with a dollar ($) sign, as these will be interpreted as Perl variables.

Here is the loop code for the invert colors script.

&rfx_sendmsg (
  qq{
    (let* ((input-file (string-append "$curtmpdir" DIR-SEPARATOR "$in"))
           (image (car (gimp-file-load RUN-NONINTERACTIVE input-file input-file)))
           (layer (car (gimp-image-get-active-layer image))) )
      (gimp-invert layer)
      (rfx-save-frame image "$out") )
    }
  );

The let* bindings merely open the input frame using the Perl variables provided by LiVES and set up the 'image' and 'layer' variables that your script will use. Your script would then process the image just as in "normal" Script-fu (just avoid running any plug-ins in RUN-INTERACTIVE mode).

For the Invert effect, the only thing our script needs to do is call the 'gimp-invert' PDB procedure. However, it is necessary that when you have finished processing the image, there should be only one layer (merge your layers or flatten your image as necessary), and that the image dimensions are unchanged (there are a few exceptions to this, but for now keep all frames their original size).

The last step of your script should invoke the 'rfx-save-frame' procedure as shown. This procedure will save the frame in the appropriate format, and also delete the image. It is important that your looping code removes any temporary channels, paths, buffers, etc. that it may have created, since your script may be called thousands of times in a single session.

For an example of a more complex script, look at the code for the Cartoonize effect. Even though there is a lot of processing of the image, with several layers and masks being created, the "wrapper" code is still the same. This will be true of most of the effects scripts you write.

Once you have finished editing your script, close the editor window and then press OK in the RFX Builder dialog.

The next step is to build the script by running the "Rebuild all RFX plugins" command in the "Advanced->RFX Effects, Tools, and Utilities" menu.

You can then run the script on the selected range of a clip by choosing the "Run Test Rendered Effect/Tool/Generator" command from the "Advanced->RFX Effects, Tools, and Utilities" menu. Start with a fairly short selected range (~100 frames or so), since the process can take some time.

After you've fully tested your plugin, you can add it permanently to LiVES (the details of which I will cover in the future).

For a more complicated example that uses input parameters, see the Motion Blur script.