ReaScript Basics with Raymond Radet Part-1

When I started researching for an article on making scripts for REAPER I quickly realized I knew nothing and would need some expert help. I contacted Raymond Radet, one of the most active ReaScript writers on the REAPER forum to answer some of my questions.
He did more than answer my questions, during our conversation he wrote a few scripts that solved one of my own feature requests.
At this point you may still not know what a ReaScript is so let’s start at the beginning.

reaperblog: Can you summarize the difference between programming and scripting?

Raymond: In appearance, both disciplines look the same: it is about code writing. In details, they are very different.

Programming is writing code that will be compiled, in order to create executable programs. These programs can be executed and interpreted by the Operating System.

Scripts are text files writing in code that can be interpreted by a program into instructions, without compilation. You cannot execute a script alone. It is just text.

In practice, this leads to critical differences: when writing a program, you will have to think about OS-compatibility, display, sometimes even hardware compatibility, compilation debugging, memory allocation and other “low level” stuffs.

Scripts can have OS-dependent features (such as paths to libraries), but usually, the only compatibility that you will have to take care of is the compatibility with the destination program.

Once we’ve downloaded a script, or written our own, how can they be activated?

First advice, put the scripts in the Scripts resource folder, so that you will be sure that they are exported with your configZip, if you made one. To get to this place, simply click on Options, Show REAPER resource path in explorer/finder… You will see a Scripts folder.

After this optional step, you just have to load it/them with the Actions List Window.

1. Open the Action List with Action, Show action list…
2. There is a small button on the bottom right: ReaScript: New/Load.
3. You can select multiple files at once. If you want to load scripts from different subfolder at once, you can use your explorer/finder find bar and look for every files in the parent folder and its childs (*.* on Windows).
4. Now, your scripts are imported. It works as every other actions. You can assign keyboard shortcuts or toolbar buttons to it, use it in custom actions etc… The party can begin!

If your scripts are in Python, you will have to install Python libraries on your computer. Take a look on the REAPER Wiki to know how to install them.

REAPER scripters can use EEL, LUA and Python to create things, does each have an advantage, are they interchangeable?

Every language is different. Here is what sets each apart.

EEL:
+ native interpretation
+ high performance
– proprietary language (not a lot of documentation online)

Lua:
+ native interpretation
+ very simple syntax
+ a lot of nice native functions
+ very common language (resources available online)
+ ability to call external libraries (you may use other functions than those provided by the REAPER API)
– don’t work with REAPER v4 (need REAPER v5 pre-releases).

Python:
+ very common language (resources available online)
+ ability to call external libraries (you may use other functions than those provided by the REAPER API)
– need external libraries and a bit of configuration to make it work
– harder syntax

If you want my opinion about it… use Lua! 😀 But a professional respected master veteran of code’s opinion will be better. Here is what schwa, one of Cockos genius developer team members, thinks about it:

I find Lua to be a a real pleasure to use, honestly more fun than any other scripting language I’ve had experience with. Within a few minutes of using the language for the first time I was working on a script that will represent a significant new feature, which will be released as part of 5.0, and be indistinguishable from functionality coded natively in REAPER. Because, really, it is functionality coded natively in REAPER, with identical access to the internals of REAPER, including access to track audio and MIDI.

I really think that the combination of Lua’s ease of use, and improvements to REAPER’s API, will open up an almost unlimited world of creative possibilities

Do you know what it was? No less than a notation editor! Yes, a music style sheet MIDI editor! It was a bit raw, and has been removed from current pre-releases, but you get the idea.

A lot of impressive demos of what is possible with Lua is available in REAPER JFX/ReaScript subforum and REAPER Pre-Releases subforum, such has the Lua and automation envelopes generation by Xenakios. And it is not just about what we can do, it is about how easily we can make it! After two months of EEL, I switched (very easily) to Lua, and I succeeded to finish some “old” scripts, thanks to Lua code snippets I found online. That’s what is nice when using a popular scripting language.

In practice, I still continue to code in EEL for a simple reason: Lua is only available for actual pre-releases of REAPER v5, which make it not so accessible for the casual user. Compatibility with REAPER version may be the most determinant factor when choosing a language for coding. I usually code in Lua if I need functions that exist only in v5 pre.

Are the SWS/S&M extensions actually ReaScripts?

Extensions and scripts can use the same API functions provided by REAPER, and both cannot be executed without REAPER, but there is one major difference: extensions source code is compiled (just as programs), scripts code is not. This single difference has a lot of consequences, especially in performance, but also in other things I talked about in the previous question.

On Windows x64, the SWS/S&M extensions file is a simple package of three files: a DLL, called reaper_sws64.dll, sws_python.py and the changelog file. This DLL file is generated from more than one thousand files written by its developers in C++ (you can find all the files on the Jeff0S/sws GitHub repository). All the two thousands SWS actions are compiled in binary in one single OS-dependent file. Every operating system has its own build.

If you want to modify the source code of one action, you can’t edit the binary file. You will have to download the source files on the online repository, and create a development environment, as described on the Building the SWS Extensions GitHub Wiki page.

On the other side, scripts are singles files, with source in plain text (easily editable). REAPER is able to transcribe them into instructions, which could be less efficient than extensions which could be better for critical real-time behavior, due to their low level language origin. Scripts are not OS-dependent and doesn’t require any installation by itself. But, if the scripts need to call external libraries in order to work, such as with Python, these libraries would required an OS-dependent installation as every other program. In REAPER, it is not required with EEL and Lua.

The other major difference is that extensions are really integrated into REAPER. Extensions can create menus, complex windows (with tabs, search fields, multi-line text-fields…), integrate file format, provide API functions and a lot of other things that couldn’t be done with scripts. Think about all the SWS windows from the Extensions menu: few of them (if any) could have any equivalent via scripting, even with GFX windows (which is a way to create simple User Interface for scripts).

Do scripts ever break REAPER?

They can make it crash, they can make it bug, they can make it do strange things, but they can’t break it, because they don’t touch its core files.

Even functions that can write XML directly in the project have some securities. They don’t work if the code is not valid.

When should a user turn to scripting vs custom actions?

Custom actions are very nice for a simple set of actions, executed one after the other.

For more advanced stuffs, you can use the SWS Cycle Action Editor, which allows to make custom actions, with conditionals, repetition and other cool features.

But if you need to modify or display values in a window, to do things based on those values, to have a script than can control these value in a window with sliders or knobs, or to have something running in background, use scripts. Values can be color, pan value, item position, notes, midi events, name of an FX, envelope point number or anything you can think off related to your project. You will be able to get these values and modify it to your needs, or just displaying them in a GFX window, just like with the brilliant HeDa’s Notes Window:

The cool thing is that scripts have the ability to call REAPER actions, in a very simple way! So, for example, instead of using 10 lines of code to select all tracks, you just use one, calling the dedicated REAPER action.

Finally, you can also include your script inside… a custom action, with other REAPER actions, or other scripts!

What can’t be done with scripting?

You can’t do anything that touches the REAPER core. You can add actions, not modify or delete things from the host, or make REAPER loads faster, or support thumbnails in video items, or create a new kind of envelopes, or any other fancy things like that which determines the REAPER core. This is up to Cockos.

It may be more clarifying to consider what we can do. As my work involves a lot of different fields (audio story editing, subtitling, acoustical music, electronic music…), I made a large variety of scripts in the following categories:

• Color
• Envelopes
• FX
• Item Editing
• Item Properties (Pan values, pitch etc…)
• MIDI editing
• Regions
• Tempo / Time Signature
• Text Items / Subtitling
• Track Properties

There is still a lot of fields I could explore, I’m pretty sure there is some nice functions I haven’t discover yet in the API. I may find them when the need will come.

What is nice is when someone uses standards functions for completely innovative things. This is how HeDa, who started learning code few weeks after me, succeeds to do one of the most impressive script out there, answering an old feature request: having regions and markers sets, and be able to select multiple regions. This is done by considering them items on certain tracks representing regions.

Note that this script is one of those which are not just “simple actions”, but that runs in background, still active until you deactivate it.

====
That’s it for part 1. The next half will be up next week.