RGP Lua is a powerful plug-in for Finale

Finale has long been at its most powerful when combined with the third-party tools that hook into it and extend its capabilities. If you’re a Finale user with some basic coding skills and you’ve ever wished you could automate certain tasks or add new features to Finale, you’ll want to know about RGP Lua, a free plug-in for Finale that uses Lua scripts to interact with Finale documents.

Editor’s note: Robert Patterson contributed content for this article; Aaron Sherber and Jason Loffredo contributed images.

What is RGP Lua?

RGP Lua is a follow-on plugin to JW Lua, a Lua interpreter for Finale. JW Lua was created by Jari Williamsson in the mid-2000s, and it quickly fostered a community of contributors through the JW Lua email list. In 2017 Jari had other responsibilities that prevented him from continuing to support the plug-in, but the seed had been planted.

Robert Patterson, another third-party developer of plug-ins for Finale, introduced RGP Lua in 2021. One of RGP Lua’s design goals is compatibility with scripts written for JW Lua.

The plug-in accesses Finale documents through a PDK Framework that Jari developed. Jari graciously shared the source code of the PDK Framework with MakeMusic, the creators of Finale, with permission to share it with Robert. The PDK Framework provides a set of classes and functions that allow Lua scripts directly to process a Finale document.

Finale itself offers FinaleScript, and there are external scripting frameworks such as AutoHotKey (Windows) and Keyboard Maestro or AppleScript (Mac). These frameworks primarily provide scripted automation of Finale’s user interface. By comparison, RGP Lua allows you to create custom dialogs, manipulate text and graphics, create new expressions or articulations, and much more. Because it has direct access to the data, it is very fast.

You do not need any programming skills to use RGP Lua. There is a wealth of scripts already written to address a vast array of needs. Visit the Finale Lua web site for a complete rundown on available scripts and how to install them, as well as how to install the RGP Lua plug-in itself.

Example Lua scripts

If you wish to learn more about how to create your own Lua scripts, here are some simple examples.

Example 1: Hide articulations

This script hides all articulations in the selected region of the score. It loops through all the entries in the selected region. For each entry it finds all articulations attached to that entry and hides them one-by-one.

for entry in eachentry(finenv.Region()) do
    local articulations = entry:CreateArticulations()
    for articulation in each(articulations) do
        articulation.Visible = false
        articulation:Save()
    end
end

Example 2: Remove page breaks

This script loads all measures in a selected region and removes any page breaks on them.

local measures = finale.FCMeasures()
measures:LoadRegion(finenv.Region())
for measure in each(measures) do
    if measure.PageBreak then
        measure.PageBreak = false
        measure:Save()
    end
end

How to access the scripts

Accessing RGP Lua scripts is the same as any other third-party plug-in in Finale. The instructions are provided on the Finale Lua site.

As ever, Jason Loffredo of Conquering Finale fame has made a video to help you through the process:

Once installed, restart Finale, and you’ll see RGP Lua in your Plug-ins folder:

Any scripts loaded in RGP Lua will appear within that subfolder:

Create your own scripts

To start creating your own scripts, you’ll need some basic knowledge of Lua programming. Lua is a simple and flexible language that is easy to learn, especially if you have experience with other programming languages. You’ll also need a text editor to write your scripts, and of course, Finale installed on your computer.

There are many resources available to help you get started with RGP Lua:

• The RGP Lua documentation is the best place to start.
• You can supplement that with Jari’s original JW Lua documentation, most of which is still relevant. (However, RGP Lua does not support UserValueInput.)
• The PDK Framework documentation is very valuable.
• You should also install the RGP Lua Class Browser script which provides direct links to the documentation pages of the PDK Framework.
• There are many working scripts on the Finale Lua Scripts GitHub repository which demonstrate a variety of techniques for using Lua to edit your documents.

If you’re interested in contributing to the Finale Lua project, you can fork any of the repositories on GitHub and submit pull requests with your changes. The Finale Lua project is open source (to the extent permitted by MakeMusic), and contributions are always welcome.

What’s next for RGP Lua?

Robert is preparing a new release that will allow a script to run when Finale starts up. It also adds new classes and functions to the PDK Framework, and it will embed version 2.1.0 of the luaosutils library for easy access to a number of operating system functions.

A primary goal for the future is to provide access to Finale’s new features as they are added to Finale. and to maintain compatibility with future versions of macOS and Windows.

From there, the plug-in will do whatever Lua programmers dream up for it to do.