ReaScript API

REAPER provides an API (advanced programming interface) for users and third parties to create extended functionality. API functions can be called from a compiled C/C++ dynamic library that is loaded by REAPER, or at run-time by user-created ReaScripts that can be written using REAPER's own editor.

ReaScripts can be written in EEL2, a specialized language that is also used to write JSFX; Lua, a popular scripting language; or Python, another scripting language. EEL and Lua are embedded within REAPER and require no additional downloads or settings. Python must be downloaded and installed separately, and enabled in REAPER preferences.

A script named "__startup.lua|.eel" will be started automatically by Reaper at startup. You can have both; Reaper will run __startup.eel first, __startup.lua second. This __startup-script doesn't need to be registered into the actionlist of Reaper; it's pure existence in the scripts-folder of the resources-folder of Reaper is sufficient for it to be run.

Learn more about ReaScript: http://www.cockos.com/reaper/sdk/reascript/reascript.php.

This documentation includes the functions provided by SWS: sws-extension.org as well as Julian Sader's plugin, that can be installed via ReaPack.

The IDE in Reaper has some limitations, as every line must not exceed 4095 characters, or they will be split when the script is loaded the next time. It also tries to obey the script's chose character for indentation. So if every line begins with a tab, hitting tab will insert 4 spaces, if every line begins with spaces, hitting tab will insert 2 spaces. The IDE has known issues with Unicode-characters, especially when inserted via Alt+GR. So sometimes it's easier to use an external IDE/editor instead.

The base-directory for files created from ReaScript can be read from the reaper.ini -> [REAPER] -> lastcwd= That means, if you create a new file without giving it a path, it will be created in the path set in lastcwd.

Note: a lot of the functions in this document require 3rd-party-extensions. You can find and install them from here:
SWS: https://www.sws-extension.org
JS-extension: https://forum.cockos.com/showthread.php?t=212174
ReaPack: https://reapack.com/
ReaImGui: https://forum.cockos.com/showthread.php?t=250419
Osara: https://osara.reaperaccessibility.com/
ReaBlink: https://github.com/ak5k/reablink/releases/
ReaLlm: https://github.com/ak5k/reallm
ReaFab: https://github.com/ak5k/reafab
ReaMCULive: https://github.com/ak5k/reamculive/releases/
PeloReaper: https://github.com/pelori/PeloReaper

Usage of the Reaper Api in C++

Note: the C++ pure virtual interfaces used require the MSVC-compatible C++ ABI on Win32. Sorry, mingw users.

Reaper extensions: see http://www.cockos.com/reaper/sdk/plugin/plugin.php and reaper_plugin.h. The API functions in this header can be retrieved using reaper_plugin_info_t.GetFunc() or by using the Action "[developer] Write C++ API functions header" directly in Reaper.

VST plugins: see http://www.cockos.com/reaper/sdk/vst/vst_ext.php The API functions in this header can be retrieved using audioMasterCallback.

Because the API is dynamic, callers should never assume a function exists. Check that a non-NULL function pointer was returned before using it (unless loaded functions are verified using REAPERAPI_LoadAPI(), see note below).

New (4.76+) usage of this file: - 1) most source files should just #include "reaper_plugin_functions.h" as is. - 2) one file should #define REAPERAPI_IMPLEMENT before including this file. - 3) the plug-in should call REAPERAPI_LoadAPI(rec->GetFunc) from REAPER_PLUGIN_ENTRYPOINT - and check the return value for errors (REAPERAPI_LoadAPI will return 0 on success).

By default, all functions listed in this file are loaded. This means that an older version of REAPER may not succeed in loading, and also it may bloat your plug-in. If you wish to only load needed functions, #define REAPERAPI_MINIMAL and various #define REAPERAPI_WANT_ lines before including this file. You must put these definitions where REAPERAPI_IMPLEMENT is defined and you can optionally put them elsewhere (to detect needed REAPERAPI_WANT_xxx lines at compile- time rather than link-time).

ReaScript/EEL API

For information on the EEL2 language, please see the EEL2 User Guide

ReaScript/EEL scripts can call API functions using functionname().

Parameters that return information are effectively passed by reference, not value. If an API returns a string value, it will usually be as the first parameter.

Examples:

// function returning a single (scalar) value:
sec = parse_timestr("1:12");

// function returning information in the first parameter (function returns void):
GetProjectPath(#string);

// lower volume of track 3 by half:
tr = GetTrack(0, 2);
GetTrackUIVolPan(tr, vol, pan);
SetMediaTrackInfo_Value(tr, "D_VOL", vol*0.5);

ReaScript/EEL can import functions from other reascripts using @import filename.eel -- note that only the file's functions will be imported, normal code in that file will not be executed.

ReaScript/Python API

ReaScript/Python requires a recent version of Python installed on this machine. Python is available from multiple sources as a free download. After installing Python, REAPER may detect the Python dynamic library automatically. If not, you can enter the path in the ReaScript preferences page, at Options/Preferences/Plug-Ins/ReaScript.

ReaScript/Python scripts can call API functions using RPR_functionname().

All parameters are passed by value, not reference. API functions that cannot return information in the parameter list will return a single value. API functions that can return any information in the parameter list will return a list of values; The first value in the list will be the function return value (unless the function is declared to return void).

Examples:

# function returning a single (scalar) value:  
sec = RPR_parse_timestr("1:12")  

# function returning information in the first parameter (function returns void):  
(str) = RPR_GetProjectPath("", 512)  

# lower volume of track 3 by half (RPR_GetTrackUIVolPan returns Bool):  
tr = RPR_GetTrack(0, 2)  
(ok, tr, vol, pan) = RPR_GetTrackUIVolPan(tr, 0, 0)  
# this also works, if you only care about one of the returned values:  
vol = RPR_GetTrackUIVolPan(tr, 0, 0)[2]  
RPR_SetMediaTrackInfo_Value(tr, "D_VOL", vol*0.5)  

You can create and save modules of useful functions that you can import into other ReaScripts. For example, if you create a file called reascript_utility.py that contains the function helpful_function(), you can import that file into any Python ReaScript with the line:

import reascript_utility

and call the function by using:

reascript_utility.helpful_function()

Note that ReaScripts must explicitly import the REAPER python module, even if the script is imported into another ReaScript:

from reaper_python import *

ReaScript/Lua API

ReaScript/Lua scripts can call API functions using reaper.functionname().

Some functions return multiple values. In many cases, some function parameters are ignored, especially when similarly named parameters are present in the returned values.

Examples:

-- function returning a single (scalar) value:
sec = reaper.parse_timestr("1:12")

-- function with an ignored (dummy) parameter:
path = reaper.GetProjectPath("")

-- lower volume of track 3 by half:
tr = reaper.GetTrack(0, 2)
ok, vol, pan = reaper.GetTrackUIVolPan(tr, 0, 0)
reaper.SetMediaTrackInfo_Value(tr, "D_VOL", vol*0.5)

ReaScript/Lua can import functions from other ReaScripts using require. If the files are not being found, it is probably a path problem (remember that lua paths are wildcard patterns, not just directory listings, see details here).

Datatypes used in this document

boolean - accepts only true or false as values
optional boolean - a boolean, that can be given, but is not required
number - can be integer, double or a floating-point-number
optional number - a number, that can be given, but is not required
integer - only integer numbers allowed
reaper.array - a special array, that Reaper provides
string - a string of characters/text
optional string - a string, that can be given, but is not required

AudioAccessor - Audio Accessor object for a track or a media-item
BR_Envelope (BR) - an envelope-object, created from a track or take-envelope
HWND - a window
IReaperControlSurface - a ControlSurface, e.g. OSC-devices
joystick_device - a joystick-device
KbdSectionInfo - Keyboard Section Info, - 0, Main
- 100, Main (alt recording)
- 32060, MIDI Editor
- 32061, MIDI Event List Editor
- 32062, MIDI Inline Editor
- 32063, Media Explorer
PCM_source - the audiosource of a MediaItem
ReaProject - a project within Reaper; 0 for current open project(-tab); in EnumProjects, it is an object, not a number!
RprMidiTake (FNG) - ReaperMidiTake as object
RprMidiNote (FNG) - RprMidiNote as object
MediaTrack - a Reaper-Track as object
MediaItem - a Reaper-MediaItem like audio,video, Midi, etc as object
MediaItem_Take - a take within a MediaItem as object
TrackEnvelope - an envelope of a track as object
WDL_FastString(S&M) - a different kind of a string, made into a Reaper-object

deviceHDC - get it using function JS_GDI_GetWindowDC

Returns the description of an action.

Adds a ReaScript (returns the new command ID, or 0 if failed) or removes a ReaScript
Returns >0 on success.
Use commit==true when adding/removing a single script.
Committing means, that Reaper stores the Reascript-information into the reaper-kb.ini for permanent use.
It will be committed at Reaper's exit as well, but if Reaper crashes before exiting properly, your added
script might get lost. When adding many Reascripts to Reaper, setting commit to false might help prevail
ressources, as you don't rewrite the reaper-kb.ini file over and over again. However, if you only add a
few scripts, this might not be of importance to you.
So when bulk adding/removing multiple scripts, you can optimize the n-1 first calls with commit==false and commit==true for the last call.

The commandID returned, might change, when adding this script into another Reaper-installation.
To be sure to use the right command-id, use ReverseNamedCommandLookup() to get the ActionCommandID, which will never change, until you remove the script.

If you want to add a script to several sections, you need to add them individually, by calling the function again with the changed section-number.

arms a command (or disarms if 0 passed) in section sectionname (empty string for main)

Deprecated, see kbd_enumerateActions (v6.71+).

Wrapper for the unexposed kbd_enumerateActions API function.
Main=0, Main (alt recording)=100, MIDI Editor=32060, MIDI Event List Editor=32061, MIDI Inline Editor=32062, Media Explorer=32063

Deprecated, see kbd_getTextFromCmd (v6.71+).

Wrapper for the unexposed kbd_getTextFromCmd API function.

See CF_EnumerateActions for common section IDs.

gets the currently armed command and section name (returns 0 if nothing armed). section name is empty-string for main section.

Return toggle-state of an action. See GetToggleCommandStateEx.
See NamedCommandLookup() for the correct command_id.

Return toggle-state of an action.

For the main action context, the MIDI editor, or the media explorer, returns the toggle state of the action. For the MIDI editor, the action state for the most recently focused window will be returned.
See NamedCommandLookup() for the correct command_id.

Send an action command to the last focused MIDI editor.

Returns false if there is no MIDI editor open, or if the view mode (piano roll or event list) does not match the input.

see MIDIEditor_OnCommand

Send an action command to a MIDI editor.

Returns false if the supplied MIDI editor pointer is not valid (not an open MIDI editor).

see MIDIEditor_GetActive, MIDIEditor_LastFocused_OnCommand

Performs an action belonging to the main action section.
To perform non-native actions (ReaScripts, custom or extension plugins' actions) safely, see NamedCommandLookup().
See Main_OnCommandEx.

Performs an action belonging to the main action section. To perform non-native actions (ReaScripts, custom or extension plugins' actions) safely, see NamedCommandLookup().