Moonlighting with Lua – the powerful tool for music notation you never hear of.

I suppose a good place to start is with the question “What exactly is Lua?”

Lua is a lightweight computer programming language (the complete Lua distribution could fit on a floppy disk) designed primarily for use within other applications (think plugins) to increase functionality and productivity of the host software program.

Video games are a good example. In recent years, Lua has risen to become a lingua franca for scripting in video games as diverse as World of Warcraft and Angry Birds. For programmers with an interest in this area, this means that your Lua programming skills are transferable from company to company.

Lua’s construct of simple, flexible meta-features can be extended as needed, rather than supplying a feature-set specific to one software program. This makes Lua an ideal and powerful tool for music notation software.

History & Trivia: Lua was created in 1993 by members of the Computer Graphics Technology Group (Tecgraf) at the Pontifical Catholic University of Rio de Janeiro (PUC-Rio), in Brazil. In 2011, Lua was honored with Game Developer Magazine’s Front Line Award in the programming tool category.

‘Lua’ is the Portuguese word for ‘moon’. In Roman mythology, ‘Lua’ was the Goddess to whom soldiers sacrificed captured weapons. 


Finale already has a robust Lua scripting environment created by programmer Jari Williamsson called “JW Lua”. Officially still in beta, JW Lua is a plug-in for Finale that runs Lua scripts. These scripts behave as fully-featured plug-ins. No additional software is necessary to write them. (Lua scripts are plaintext files.)

If you have been using Finalescript to script various ancillary tasks in Finale, the first thing you will notice is that Lua is FAST.

A great example of Lua’s speed is the “Split Articulations” script from CJ Garcia and Mark Adler of MakeMusic.  This script converts combined articulations such as accent-tenuto, marcato-staccato, and others into separate accent + tenuto, marcato + staccato articulations, to take advantage of the much improved articulation placement of Finale 26.

Scoring Notes recently did a tutorial to help Finale users get up and running with this script.  The blog post includes a helpful tutorial for downloading and installing the JW Lua plugin for Finale. My colleague Philip Rothman, who authored the post, observes: “The script is incredibly fast — I used it on a large orchestral score of more than 1000 bars in length, and it took only a second or two.”

Another example on the JW Freeware Plug-ins Wiki compares a Lua script performing an identical task to one created in Finalescript. The Lua script runs 372 times faster on the same machine. So, yeah.

In Finale, once you install the JW Lua (beta) plugin, you can run scripts written by yourself, or run shared scripts created by others to help you automate various tasks.


Dorico has the beginnings of a framework for Lua scripting support built in. The easiest way to create a  Lua script in Dorico 2.0 is by recording a macro;  record a series of steps within the program using “Start / Stop Recording Macro” then play the script back using “Run Last Script”. It is also possible to edit these commands, and even save a copy of a specific recorded macro for later recall. The resulting output  is a Lua script, saved to a text file.

Go to “Script > Start Recording Macro”. After you have completed recording actions, choose “Script > End Recording Macro”. Your actions were recorded, and can be played back.

Dorico creates a user file called “usermacro.lua” the first time you record some actions. This file will be overwritten every time you start recording a new sequence of events. An enclosing “script plug-ins” folder is also created the first time you record any macro.

However, contents aside, this is  just a text file, and you can save a copy of your recorded “usermacro.lua” macro with a different name more suited for the task sequence, then recall it any time later by choosing “Run Script…” from the menu, and selecting your renamed and saved script when the dialog opens.

In case you come up with a really useful macro you want to save as, rename and reuse, the “usermacro.lua” file can be found here (after you record something, of course):

Mac: ~/Library/Application Support/Steinberg/Dorico/Script plug-ins
Windows: ~\AppData\Roaming\Steinberg\Dorico\Script plug-ins

While other music notation software programs such as LilyPond make use of Lua scripting, the goal of this little corner of Of Note will be to share (over time) some of the small useful, yet functional scripts being written in Lua that you can add to your toolbox for both Dorico and Finale. (As of this writing, Sibelius does not support Lua, but rather, uses its own proprietary scripting language for plugins called Manuscript).

If you are Finale or Dorico user, for what I will post here, you probably won’t need to know anything technical beyond some basic things you likely already know about for your music notation program anyway.

If you are a programmer, and are interested in, or are already writing scripts for Finale or Dorico using the Lua scripting language, I’d love to share your efforts related to these music notation software programs on this blog. – the official site for Lua language development.

JW Lua –  a high-performance script language for Finale.

3 Replies to “Moonlighting with Lua – the powerful tool for music notation you never hear of.”

  1. Cool stuff. For both Finale and Dorico, I believe that a Lua program can make a fairly direct connection to the program internals. (I suspect that MuseScore could do something similar). For Sibelius there is no access to any of the program functions and objects except through ManuScript.

    ManuScript was really designed to be a scripting language itself; it requires no external language support, and provides a mechanism for distributing plugins. It becomes pretty complex to write a workable plugin, though, and there are really no simple “scripts” available. Being able to record a plugin would have been useful, and having access to the same commands that users do (and which can be assigned shortcuts to), wold have made that easier. For this sort of thing people need to get external keystroke recorders, which a lot of people do make extensive use of.

    While a ManuScript plugin could read the text of a Lua Script that made calls to the same Manuscript commands available to a Sibelius plugin, that would probably not make it any easier to a user to write such a script than it would be to write a ManuScript plugin directly.

    ManuScript can also invoke an external application, so in theory it could invoke Lua to run a script, but it would have no access to the Sibelius internals.

    An ambitious programmer could possibly figure out a way to integrate ManuScript and another language through the available ManuScript commands, but it would likely be both complex and slower than the current Sibelius model.

    If Avid/Sibelius were to expose an API that could be called from Lua or C++ or any other external programming language, then it would open up other avenues for scripting.

    Have fun with the Finale scripts. That seems to be the most fruitful field to plow at the moment.

  2. I’m not sure you’re correct when you say that Sibelius Manuscript Language doesn’t rely on external support. Isn’t it still based on the embedded language Haskell?

    Maybe some optimization of the Sibelius plugin authoring process could be made by going outside of Sibelius into the wider Haskell world.

    While I’m “here”, thank you for all of your work on Sib plugins over the years!

  3. ManuScript was (and is) based on the embedded language Simkin. The ManuScript Reference states: “ManuScript is a simple, music-based programming language used to write plug-ins for Sibelius. ManuScript is based on Simkin, an embedded scripting language developed by Simon Whiteside, and has been extended by him and the rest of the Sibelius team ever since. (Simkin is a spooky pet name for Simon sometimes found in Victorian novels.) For more information on Simkin, and additional help on the language and syntax, visit the Simkin website at”

    I have never really gotten much from looking at Simkin, and any language changes need to be done directly by the Sibelius developers anyway. I think ManuScript is a good distance away from the current version of Simkin.

    I had a quick look as Haskell, and it appear that they have importers for several notation file formats, including Sibelius. I am surprised that they don’t use MusicXML import, and that would give access to more formats, and the Sibelius file format is not publicly documented. But it seems that they can import a file into their own format, and then Haskell code can manipulate the data. They can also export to MusicXML, which could be read by Sibelius.

    But I don’t think they are processing a Sibelius score directly. There would be a fair amount of conversion to do a round trip to and from Sibelius.

    ManuScript, the editor, and the plugin runtime system are all built into Sibelius, so you don’t need anything else to write plugins.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.