back to main reference page
ReaScript
top Introduction
ReaScript is a feature that allows you to run Perl or Python scripts within REAPER. From within the script, you can call any REAPER action, and also call back into most of the REAPER Extensions SDK functions. ReaScript can be used to create anything from advanced macros to full-featured REAPER Extensions.
top Requirements
To use ReaScript, you must have either Python or Perl installed on your computer. Both are freely available in several free distributions. OSX comes with both Python and Perl already installed, though older OSX installs may not have the most recent versions of Python or Perl.
Installing either Python or Perl is usually a simple, straightforward process. Although both are open-source projects, meaning the source code is available for anyone to build, most users will simply run a binary installer just like installing any other program (such as REAPER).
Python: ReaScript requires Python 3.1. A list of Python distributions is here.
Perl: ReaScript requires Perl 5.10, and a standard Perl module called FFI. A list of Perl distributions is here. The FFI module is here: Win32, OSX. FFI.pm and FFI.dll (or FFI.dylib on OSX) should both be placed in the Perl/lib directory of your Perl installation.
top Running ReaScripts
To run a ReaScript, first you will need to either write a script, or copy a script from another user. Scripts can be placed anywhere on your disk, but it's convenient to keep them all in the REAPER/Scripts application data directory.
To write a new script, show the Actions list (bound to the ? key by default), and click ReaScript: Load. You will be prompted for the location to save your new script, the default location is recommended. Name your script something like test.py or test.pl, then click ReaScript: Edit. A text editor will open.
The simplest possible ReaScript in Python is:
or in Perl:
Save the ReaScript, and then click Run. You should see a window that says "Test OK". Common reasons for the script failing are:
top Calling REAPER Actions
You can call any REAPER action from ReaScript by using the API function
Find the action number for a given action by opening the Actions list, and scrolling the window right to reveal an extra column. For example, from ReaScript you would call the REAPER action "Item: Split item under mouse cursor" like this, in Python:
If you use ReaScript as an advanced macro language, this is the only API function you need to know.
top ReaScript API
ReaScripts also have access to most of the REAPER Extensions SDK functions. For a list of all API functions available to ReaScripts, run the REAPER action "ReaScript: open ReaScript help (html)". The help page will explain the basics of how to call API functions, which may require idiosyncratic syntax, because API functions can return information in the parameter list as well as the function return value. For convenience, there are also basic API functions for getting information from, and showing information to, the user.
For more help on ReaScript, to report bugs, to request additional API functions, to share ReaScripts, or just to discuss the possibilities, please use the REAPER Developer Forum.
ReaScript
top Introduction
ReaScript is a feature that allows you to run Perl or Python scripts within REAPER. From within the script, you can call any REAPER action, and also call back into most of the REAPER Extensions SDK functions. ReaScript can be used to create anything from advanced macros to full-featured REAPER Extensions.
top Requirements
To use ReaScript, you must have either Python or Perl installed on your computer. Both are freely available in several free distributions. OSX comes with both Python and Perl already installed, though older OSX installs may not have the most recent versions of Python or Perl.
Installing either Python or Perl is usually a simple, straightforward process. Although both are open-source projects, meaning the source code is available for anyone to build, most users will simply run a binary installer just like installing any other program (such as REAPER).
Python: ReaScript requires Python 3.1. A list of Python distributions is here.
Perl: ReaScript requires Perl 5.10, and a standard Perl module called FFI. A list of Perl distributions is here. The FFI module is here: Win32, OSX. FFI.pm and FFI.dll (or FFI.dylib on OSX) should both be placed in the Perl/lib directory of your Perl installation.
top Running ReaScripts
To run a ReaScript, first you will need to either write a script, or copy a script from another user. Scripts can be placed anywhere on your disk, but it's convenient to keep them all in the REAPER/Scripts application data directory.
To write a new script, show the Actions list (bound to the ? key by default), and click ReaScript: Load. You will be prompted for the location to save your new script, the default location is recommended. Name your script something like test.py or test.pl, then click ReaScript: Edit. A text editor will open.
The simplest possible ReaScript in Python is:
RPR_APITest()or in Perl:
RPR_APITest();Save the ReaScript, and then click Run. You should see a window that says "Test OK". Common reasons for the script failing are:
- Python or Perl not installed
- Wrong version of Python or Perl installed
- Multiple versions of Python or Perl installed, and the system picks up the wrong version
- Syntax error (typo, missing newline, incorrect indentation in Python)
top Calling REAPER Actions
You can call any REAPER action from ReaScript by using the API function
RPR_Main_OnCommand(actionnumber, 0)Find the action number for a given action by opening the Actions list, and scrolling the window right to reveal an extra column. For example, from ReaScript you would call the REAPER action "Item: Split item under mouse cursor" like this, in Python:
RPR_Main_OnCommand(40746, 0)If you use ReaScript as an advanced macro language, this is the only API function you need to know.
top ReaScript API
ReaScripts also have access to most of the REAPER Extensions SDK functions. For a list of all API functions available to ReaScripts, run the REAPER action "ReaScript: open ReaScript help (html)". The help page will explain the basics of how to call API functions, which may require idiosyncratic syntax, because API functions can return information in the parameter list as well as the function return value. For convenience, there are also basic API functions for getting information from, and showing information to, the user.
For more help on ReaScript, to report bugs, to request additional API functions, to share ReaScripts, or just to discuss the possibilities, please use the REAPER Developer Forum.
ReaScript