renardo-reapy 0.11.0.dev2

A fork of Reapy, the pythonic wrapper for REAPER's ReaScript Python API. Intended to be refactored and simplifyed for maintenance and usage as base for renardo Reaper integration

renardo_reapy

renardo_reapy is a nice pythonic wrapper around the quite unpythonic ReaScript Python API for REAPER.

This is a fork of python-reapy.

Contents

1. Installation
2. Usage
   • ReaScript API
   • reapy API
   • Performance
   • Documentation
3. Contributing
4. Author
5. License

Installation

If you feel you need more explanation than the straightforward instructions below, head to the detailed installation guide.

renardo_reapy is available via pip:

$ pip install renardo-reapy

One additional step is required to let REAPER know renardo_reapy is available. First, open REAPER. Then in a terminal, run:

$ python -c "import renardo_reapy; renardo_reapy.configure_reaper()"

Restart REAPER, and you're all set! You can now import renardo_reapy from inside or outside REAPER as any standard Python module.

Instead of creating a new ReaScript containing:

from reaper_python import *
RPR_ShowConsoleMsg("Hello world!")

you can open your usual Python shell and type:

>>> import renardo_reapy
>>> renardo_reapy.print("Hello world!")

Usage

ReaScript API

All ReaScript API functions are available in renardo_reapy in the sub-module renardo_reapy.reascript_api. Note that in ReaScript Python API, all function names start with "RPR_". That unnecessary pseudo-namespace has been removed in renardo_reapy. Thus, you shall call renardo_reapy.reascript_api.GetCursorPosition in order to trigger reaper_python.RPR_GetCursorPosition. See example below.

>>> from renardo_reapy import reascript_api as RPR
>>> RPR.GetCursorPosition()
0.0
>>> RPR.SetEditCurPos(1, True, True)
>>> RPR.GetCursorPosition()
1.0

Note that if you have the SWS extension installed, the additional ReaScript functions it provides will be available in renardo_reapy.reascript_api and usable inside and outside REAPER as well.

renardo_reapy API

The purpose of renardo_reapy is to provide a more pythonic API as a substitute for ReaScript API. Below is the renardo_reapy way of executing the example above.

>>> import renardo_reapy
>>> project = renardo_reapy.Project() # Current project
>>> project.cursor_position
0.0
>>> project.cursor_position = 1
>>> project.cursor_position
1.0

The translation table matches ReaScript functions with their renardo_reapy counterparts.

Performance

When used from inside REAPER, renardo_reapy has almost identical performance than native ReaScript API. Yet when it is used from the outside, the performance is quite worse. More precisely, since external API calls are processed in a defer loop inside REAPER, there can only be around 30 to 60 of them per second. In a time-critical context, you should make use of the renardo_reapy.inside_reaper context manager.

>>> import renardo_reapy
>>> project = renardo_reapy.Project() # Current project
>>> # Unefficient (and useless) call
>>> bpms = [project.bpm for _ in range(1000)] # Takes at least 30 seconds...
>>> # Efficient call
>>> with renardo_reapy.inside_reaper():
...     bpms = [project.bpm for _ in range(1000)]
...
>>> # Takes only 0.1 second!

A small overhead due to sending function and arguments over the network will still occur each time a renardo_reapy function is called from outside REAPER. When running the same function many times in a row (e.g. over a thousand times), using renardo_reapy.map may significantly increase performance. See its documentation for more details.

Documentation

Check the documentation and especially the API guide and Translation Table for more information.

Contributing

For now, about a half of ReaScript API has a renardo_reapy counterpart, the docs are far from great, and many bugs are waiting to be found. Feel free to improve the project by checking the contribution guide!

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.