How to read the Reascript API

Next week I’ll begin walking you through how to write real, functioning Reascripts. My plan with that is to dive in head-first – even if you have zero knowledge – and walk you through it step-by-step.

But before we do that, I have to introduce you to a concept that’s going to confuse the crap out of you if you’ve never programmed a line of code before.

Don’t worry if you don’t understand anything in this post, just continue on with the examples that I write up in future posts. Once you start learning the basics and seeing patterns, you’ll be coming back to this page for reference.

So today I’m going to introduce you to…

The Reascript API

API is an acronym for Application Program Interface. In layman’s terms, an API is a set of pre-written code provided by a software’s developer to allow other people to extend their software’s native capabilities.

An audio-related example: think of an API as the presets that come with a keyboard or a guitar pedal. They come prepackaged, and sometimes you use a lot of them to build a brand new sound. While this isn’t an ideal analogy (some presets suck and you never use them, and they’re not always building blocks) – hopefully it’ll serve as a basis for understanding the concept.

As a more specific example, to find out if a track is muted you’ll use code that looks like reaper.GetMediaTrackInfo_Value(track_name, “B_MUTE”, 0). Or to get the number of tracks that are currently selected the code looks like reaper.CountSelectedTracks(0).

Where do you find the Reaper API?

The Reaper API is pretty easy to find. When all else fails you can quickly stick “Reaper API” in your Google machine.

Otherwise, ~~click here to go directly to it.~~
Note: the above link is a depreciated version of the API. The proper way to access it is within Reaper itself. Go to the Help menu and click “Reascript Documentation”.

Also Raymond Radet (X-Raym) has created a great page that allows you to quickly search the API for a given function. While he warns it’s not always 100% up-to-date, I haven’t found an issue with it thus far.

How in the world do you read the Reascript API?

So once you’re at the API, first allow your eyeballs to be seared with pain at the white background with Times New Roman font. Consider this the only hazing ritual – welcome to the club (or run to X-Raym’s page)

Before I go further, for this series I’ll only be covering how to read the API for Lua. From there you should be able to see similar patterns in C++/Python, but I won’t be walking through them specifically.

Your first job is to scroll down the page until you see the API Functions List. These are all of your pre-written codes (called functions from here on out) that will help you make cool new actions in Reaper! Most of these are fairly straightforward and are named by what they do. For example

AnyTrackSolo – this will return a true variable if there is any track solo’ed in your project, it will return a false variable if there are no tracks solo’ed.
CountProjectMarkers – this will return a variable with the total number of markers in your project

You can click on each of these functions to get more detail about exactly how to use them. Let’s look at that now…

Detailed function examples

First we’ll look at CountSelectedMediaItems. For those of you unfamiliar, a Media Item in Reaper is a segment of audio (or images & video, but ignore that for this example) on the timeline. Pro Tools calls these “clips” if you’re more familiar with that.

Below is the API reference for CountSelectedMediaItems:

C: int CountSelectedMediaItems(ReaProject* proj)

EEL: int CountSelectedMediaItems(ReaProject proj)

Lua: integer reaper.CountSelectedMediaItems(ReaProject proj)

Python: Int RPR_CountSelectedMediaItems(ReaProject proj)

count the number of selected items in the project (proj=0 for active project)

The first thing you see is that the same function is written a little differently for each language. There is also a description of what the function does at the bottom, as well as a bit of info on how to get access the project you’re currently working on.

Let’s dig into the Lua version a bit deeper:

Lua: integer reaper.CountSelectedMediaItems(ReaProject proj)

Going left to right, let’s explain everything in detail…

integer is describing what kind of information this function will give back to you after the code runs. In this case, it will return a number. More specifically, the number of selected items. So you’ll have to provide a variable for this go to into. Your code will end up looking like this for your current project:
number_of_media_items = reaper.CountSelectedMediaItems(0)
reaper.CountSelectedMediaItems is the name of the function. In Lua, all functions have the prefix “reaper.”, and then finish with the function name.
(ReaProject proj) is the parameter you need to provide the function. That’s a fancy way of saying the information you hand off to the function. In this case, it’s looking for a “ReaProject” (aka Reaper Project) which is represented by a number (shown as “proj” in the example). As they told you earlier in the API – “0” is the active project.

So our code number_of_media_items = reaper.CountSelectedMediaItems(0) means “hey Reaper, give me the number of Media Items in my active project that are selected and dump it in the variable number_of_media_items“. If we have a variable that equals zero the code can also look like number_of_media_items = reaper.CountSelectedMediaItems(variable)

A little less difficult than you thought, right?!

Let’s do one more…

Lua: number reaper.GetMediaTrackInfo_Value(MediaTrack tr, string parmname)

Going left to right again…

number this time instead of getting back specifically an integer (aka a whole number with no decimals), we’re going to get back a number. In Lua, an integer is a sub-type of number variables. The other number subtype is called a float (essentially a number that can have decimal places). Since running this function will give you back a number, said number can be an integer or decimal. Mostly what matters is this variable is going to be the information we want to get from the function.
reaper.GetMediaTrackInfo_Value is again the name of the function. You see the prefix “reaper.” again, and the function name is GetMediaTrackInfo_Value. Clearly, we’re trying to get information in number form (aka “Value”) from a Media Track
(MediaTrack tr, string paramname) just like before, these are the parameters we’re giving the function. In this case, for the function to work we need to give it two parameters. The first is a Media Track, aka a track from the timeline. The second is a string (in programming a string is essentially a word or set of words) “paramname”. If you go check out the specific reference to this function you’ll see a TON of options you can get information on such as mute, phase, solo, record arm, record input, volume, pan, etc. In our case, we want to know if the track is muted. So our paramname string is “B_MUTE”.

So our finished code for finding the mute status of a track would look like track_mute_status = reaper.GetMediaTrackInfo_Value(track, “B_MUTE”).

Keep in mind, if you just write this code straight away and run it in Reaper, you’ll get an error. You need to use another function (reaper.GetTrack) to store a track variable and actually make this work.

Wrapping up

So that’s pretty much all there is to reading the API! Certainly things can get a little more complicated, but this basic reference should start you off on the right foot. If you have any questions – I’m on twitter @adamtcroft – don’t be a stranger!