How to Learn ReaScript for REAPER

reaLuaCode

It is frustrating when using a software to find that there is some functions you need that don’t exist.

In Audio production, some small code snippets can go a loooong way.

If only you could write custom actions, custom scripts for your DAW…

This one of numerous reasons why REAPER is so powerful : it lets you write scripts in a large variety of formats !

NICE ! But where we start ?

I have to admit it took me a bit of time to find the infos… but when we find it, all become clear 😛 So here I will share all you need to know for a good start in scripting for REAPER, in other terms, in using ReaScript !

Basic Knowledge Requirements

Let’s face it : you can do any ReaScript if you know nothing about code. You will have to know a bit of basic programming to be able do you what you want, even simple scripts.

For people who are totally new to programming, I strongly advice you to learn some basics methods on Codecademy or Code Avengers, with java and javascript.

With basic knowledge of variable, loops, semantic, function, parameters, table, and things like that, you will be able to transpose your new skills for any other language, including the one that are part from the ReaScript scope.

Documentation

So, the first and ultimate place to look, it is within REAPER itself, which is able to generate an HTML file with all the function you can use.

Use the last REAPER version and the last SWS/S&M beta : you will have more functions !

Here is how to do it :

  1. Open the action window
  2. Run ReaScript: Open ReaScript documentation (html)…
  3. A reascripthelp.html page will be displayed in your browser : this is where you will pass most of the time

I strongly recommend the FindBar Tweak Firefox plugin, which will make all you search in page more friendly !

Because It is raw HTML, you can add some custom CSS for ease of reading.

My custom style for Reascript Help page !
My custom style for Reascript Help page !

As reference, I put my http://bit.ly/reascript file with custom style on my GitHub account. You can download it by clicking on the raw button and by pressing CTRL+S, but note that REAPER is able to generate this file, depending on what version you have and what extensions you use. I generated this file from one on the last pre-release with last SWS pre-release to be sure to not write feature request for things that are already in place.

You can also find infos on the REAPER wiki => REAPER API.

It is less complete, but it has often example of use, which is very nice.

There is also some actions listed on reaper.fm, here for ReaScript and here for JSFX.

This post about New updated REAPER/JS programming documentation on the Reaper forum can also help you.

Create a Script

To create a new script :

  1. Open the action window
  2. Reascript => New
  3. Save a test.eel file (or any other name / script language)

You would write your script in REAPER v5 build in editor directly, which is pretty nice, or you can use external editor.

There is several language at your disposition for programming actions : C++, Python, EEL and LUA (for REAPER v5). The first one is very powerful and you can do advanced stuff with it, in a deeper level and with a high-level performance, but it is a bit hard to code, the second is non natively interpreted (you will have to install Python libraries on your computer) but simpler than C++ and powerful, and the last two are my favorites : with them, you will be able to write custom actions that can be natively interpreted. They can also have some user inputs, and call some GUI. It is the new era of scripting for Reaper ! 😛

You can use Sublime Text with the powerful ReaSynthax package by Breeder, or Notepad ++ with EEL language file for Notepad++ (syntax highlighting) by spk77.

Then, you can start from small already existing script that some behavior that interest you. spk77 or planetnine scripts are good examples, or you can go on my GitHUB directory for this. I created a Template script, that can be a good start, and that you can use my Console debug message.eel for debugging. Documentation here !

If you become good at it, you will be able to write some advanced extensions, just like SWS or Playtime, and audio effects, in Jesusonic, (search for JS Effects) !

Sharing your Scripts

So you work hard, for hours and days, and you finally succeed what you wanted. Great ! Are you ready to share it with the world and contribute to REAPER’s development ? 😀

Name Your Scripts with Explicit Names

This is one of the majors flaws we can see with a lot of scripts posted online. They are poorly named. Worse, they are sometimes not named at all and paste as plain text in forum posts.

A good name for your script is an explicit name. In most of the case, your script will execute one action only. So, start with a verb, and adds as many words as required so that we can clearly understand what it is all about. Think of your script name as an action in the action window : it is essentially what it will become ! So just as action name, including some good keywords will allow nice filtering.

For scripts that are just coded to be called from other scripts, you can make it start by “Functions”, and don’t use verbs in its name, so we know that it is not aimed to be imported in REAPER.

If your script can do advanced functions, you can have a more original name. A good example for this is the Item Marker Tool. from planetnine. But once again, try to be explicit. Originality is not often the good solution in naming scripts. This is the lesson we can learn from one of the most powerful script I saw, which is able to unglue items, recalling their source files, even if it was merged with several different item sources. It was call superglue… and just get one answer in 3 years, until I bump its thread few days ago !

So, think as action, think with Search Engine Optimization in mind…

You can prefix your script with your nickname. It will allow you to quickly find your scripts in the action panel, and it is a nice way to have a little credit for your what you have done ! 🙂

Here is example of scripts name I wrote :

  • X-Raym_Glue selected items independently.eel
  • X-Raym_Create regions from selected takes and from track name.eel

Well, you get the idea !

Coding Conventions

Your script can be the source of other powerful scripts. Users can create a fork for their own needs, or they can optimize it, and even write totally new scripts based on yours. That’s why coding conventions will not only save your time while coding, but also help users to take full advantage of your script. There more user-friendly the scripts will be coded, the more users will feel they can code by them-self !

Comments

Please, add as many comment lines as you can ! I did some scripts conversion from python without any comment to EEL, without any python knowledge, and… I didn’t have the feeling to convert a script, I really have the impression to do some advance reverse engineering, every line was a new challenge… I add to add plain text comment at almost every line. I finally succeed after two days, rebuilding the script in reading my comment only, because the variable names was so hard to read (see next section of this article).

It would have been much easier if the source code had comments, to explain in plain text what it is all about, and what subtleties have to be known if the script would be modified.

You can basically add three type of comment.

  • Credits comment, to let the user know who did the script, when, what version, and where it is shared, and from what scripts it came if it is a fork.
  • Block of code title comment, to let the user know that a group of following lines is all about. Divided your code in sections will make it way simpler to understand.
  • Inline comment, to explicit some tricky lines code, or give explanation.

Sure, you don’t have to overflow your script with comment lines, but some basic comments can be very helpful. Think that you are writing the source code for someone else that would be a beginner, just as you were few times ago. Everyone will thank you for that !

Variables and Function Names

The way you name your function and your variables is an other way to extend your script readability, and “forkability”. Renaming variables and functions are usually the first thing I do when I start from an other script…

We can code with common conventions in mind, but the tricky part is that a lot of REAPER scripters came from an other language, and so, have different conventions. I came from WordPress PHP, where functions are usually named_like_that, and variables in semiCamelCase. It is the opposite in ReaScript documentation !

That said, you can still write explicit functions name starting with a verb, and explicit variables name, without any abbreviations, except for the variable type if needed, as suffix or prefix (such as variableName_str for a string variable.

You can read more about general coding conventions on Coding conventions – Wikipedia.

Platforms

The place where your share your script is very important. It will allow user to find your script less or more easily, keeping them from reinventing something that already exist. How many times I saw on the forum something like “Why did you code this, it was already made by X in post N page Z of this thread”.

I will list you places where scripts are actually shared, from the less recommended to the more.

  1. In a forum comment. This is the warranty that your code will be forget in the forum abysses with time. It is not handy for you, cause you can’t updated it easily, you can’t have access to it easily, and it is not handy for its users, that will probably never know if you write a new version. Writing code in post forum is for sharing some quick infos, not for posting entirely working scripts. Even you simplest code snippet, as long as it is working, can be useful for someone. Please, never do that ! Post links to your scripts or your code snippets instead !
  2. On the REAPER Stash, which is the biggest platforms where REAPER community resources are shared. Unfortunately, it is not really adapted for code sharing. Scripts evolve, can be modify and share by others, can be optimized etc… Stash will let put a file online and update it if needed, but people cannot be warned of this update. It is a good start, but there is better.
  3. You can use your website to promote your scripts, but you will not benefit from the tools that the next solution has to offer if you host the sources on your personal server only.
  4. On a online code sharing repositories such as GitHub or Bitbucket. Because it is dedicated code sharing platforms, you will have a bunch of features very handy for sharing your code ! People will be able to follow your workspace, to report bugs, to forks/optimize your scripts, make pull-requests, and you will be able to update it easily… It is also perfect for code snippets, and for open your scripts to collaborative work !

There is no perfect centralized way to share script at this moment, but from far the best solution is the online code sharing Repositories.

We have an interesting discussion with innuendo ( here : Integrate access to online user script database, automate user scripts management ), about how it could be perfect, for users and developer. I encourage you to read it… and why note, to vote for the feature request ! 🙂

Forum Thread

Once you have published your script, just open a thread on REAPER JSFX/ReaScript discussion, with the name of your script, and why not, with it’s language as prefix, so every know can know at first glance that this post is about an actual working script and not about a simple ReaScript question.

It is the perfect place to document your script, and put some nice animated GIF screenshots, using LICEcap (by Cockos too!) or an explanation video !

Conclusion

It will take you time to do some advanced code, but sometimes, with just 10 lines of script, you will be able to do something you wanted in REAPER since a long time. Or you can tweak an existing script to make it work as you want. That’s why I can promise you that you will never regret the time investing in code learning : you will really discover what REAPER can do for you ! 😀

Rendez-vous on the forum, I can’t wait to see your scripts ! 😛

  • tomotello

    Merveilleux! Very welcome initiative! I’m just joining the Reascript community – comming from other languages C,C++, Perl, Python. Just a spontaneous feedback from a newbe (might be to be addressed to Cockos directly): It’s fine that the API documentation can be generated and is therefore always up-to-date. But the alphabetic order is for a newbie not really useful. A categorization parameter within the source which would allow to have a documentation structured by categories would be speed-up a start much. For my personal use I’ll have to do this manually now, before I even start my first script. When getting in touch with a new programming language the first thing I want to know is what’s available for the different tasks, such as I/O, Audio, MIDI functions. Searching all the time through an alaphabetic list makes me crazy.

  • I am totally agree with you ! I would love to have “items functions”, “midi functions”…
    And in HTML point of view, it could be better too, to allow further styling (and more clarity).
    This long alphabetic tables are not handy…
    I already told it in the pre-release forum but nobody seems really interested for the moment. Maybe be later !
    Thank you for your comment 🙂
    Any scripts idea in mind ?

  • tomotello

    yes, I’ve two areas for scripting in mind:

    1) Test Automation / QA for creation of sample libraries

    MIDI: Dynamically generating scales, arpeggios throughout the entire register and velocity range of an instrument with typical articulations per instrument

    2) improved, ad hoc transport control, e.g. for live performances

    MIDI: For music styles where dynamically changing tempo variations, holds, caesuras, fermatas or theatre productions are core features, there was so far one only software really covering this in an easy way, Midi Maestro (see http://www.midimaestro.com/2.html -Cue to cue performance with support for vamps, caesuras, fermatas, skips and cola voce sections (where the conductor follows a soloist). As Midi Maestro seems to be discontinued I’m after a replacement in first priority to get the fermata feature per se available some how and if possible in second priority I’ll try to reimplement with scripting in Reaper the interpretation of the Midi Maestro approach to manage these hold-on-cue, jump-to-next cue proprietary MIDI extensions (META tags on a dedicated track) to make it possible to read in Midi files with such holds/fermatas to be handled directly in Reaper without modifications.

    Any hints / recommendations for examples in these areas are very welcome…

  • Wow, that is ambitious !
    I have made a lot of scripts fot regions and items, but none fot MIDI. You will surely find help on REAPER forum 🙂
    1. Will be more complicated as it sound because evry bank handle parametrs and key mapping differently. I already see vibratos placed on velocity, on modulation wheel, on CC, on after touch, on footpedal… Some instrument with no dynamic control other that modulation wheel… Every bank has its own logic !
    2. This can be very helpful, indeed 🙂 check pre release v5 of REAPER, there is a tons of tempo enhancements and new tempo related functilns in the API !
    Good luck with your projects !