Reaper keys

Reaper keys is an extension for the REAPER DAW that provides a new action mapping system based on key sequences instead of key chords. The system is similar to Vim, a modal text editor, and by default comes with vim-like bindings.

Click here for a very outdated and low quality demo for v1 or jump to examples.

Pros

Save a couple minutes per hour
Develop arthritis at 60 instead of 40
Reduce mouse usage
Increase maximum bandwidth between your brain and your project
A structure for Reaper's giant bag of actions

Installation

Add https://raw.githubusercontent.com/gwatcha/reaper-keys/master/index.xml to Reapack.
Optionally, install SWS (by hand or from ReaTeam Extensions). Although this extension may work without SWS, the experience will be worse.

Features

Bind key sequences

With Reaper keys you may bind key sequences to actions rather then singular key presses. This allows one to hierarchically organize many keybindings. A completion/feedback window is provided to assist with command completion.

Compose actions

Reaper keys lets one compose actions of different types to create new commands. For example, in normal mode, any action with timeline motion type can follow any one with timeline operator type. So if one enters tL, it would compose into (t -> "PlayAndLoop", L -> "NextMeasure"), and play and loop the next measure.

Other examples of timeline operator bindings are s -> "SelectItemsAndSplit" , or z -> "ZoomTimeSelection", so you could also enter sL or zL.

This grows the number of available actions exponentially but still preserves your brain, as you only need to know the timeline_motions, timeline_operators, and the fact that you can compose them.

Multi-modal

Changing modes changes the way keys compose. By default, it is in normal mode, but you could for example go into visual timeline mode by pressing v.

In this mode, timeline motions extend the current time selection, and timeline actions operate immediately and return one to normal mode. Useful if you want visual feedback before executing a timeline action, or just want to extend the time selection using motion commands.

Macros

Macros are a way to save a sequence of commands, and play them back later.

To record a macro, enter q and an arbitrary character to specify the register that the macro will save into. Then, perform a series of actions, and finish recording by pressing q.

You may play it back by entering @ and the character you specified earlier. Optionally, prefix it with a number to indicate the number of repetitions.

Some ideas to start with

o         # insert track
<Space>fc # show fx chain
a         # add fx
# add ReaSynth
<ESC>     # close fx window
im        # insert midi item
<Space>so # open in midi editor
0         # get to item start
a         # add note and select it
5p        # paste 5 more notes (last one is selected)
NN        # select two more previous notes
<M+k>     # move 3 notes up semitone
Z         # close midi editor
5+        # zoom horizonally 5 times

An alternative way if you wish to start recording straight ahead:

iv      # insert virtual instrument track
# Select ReaSynth. Track gets created and armed
<ESC>   # close fx window
R       # toggle record
# play some notes
<Enter> # stop recording

If you want to manipulate the item:

v # set mode visual
3l # jump right 3 grid divisions
o  # change time selection bound (to left one)
l  # jump right
!  # play and loop

If you want to adjust item volume:

<C+<Space>> # show mixer (for visual feedback)
10<C-J>     # -10db volume for track

Help

Enter <CM-x> (Ctrl + Alt + x) to show a list of available bindings you can search and filter.

If you're stuck in a state you don't know how to get out of, you can press <ESC> to reset back to normal.

Also, if your key press is not being detected, try unfocusing the feedback window.

Tweaking

internal/definitions/actions.lua -> add actions
internal/definitions/bindings.lua -> add or customise key bindings
internal/definitions/config.lua -> change GUI settings

Contributing

Running tests

For running tests locally you'd need some Linux distribution with X11 and xdotool.

cd tests;
chmod +x prepare copy-configs patch-settings test

./prepare # This will create a local Reaper installation
./copy-configs # This will make current instance of reaper-keys testable
./patch-settings # Or change test to true in internal/definitions/config.lua
./test # This will run every test and compare with reference projects

If you don't use X11 you can have a look at .github/workflows/wf.yml to see how x11 is emulated with Xvfb.

Writing tests

Each test is just a sequence of keys you press to achieve some result. One notable exception is a hotkey or a special key like "Return" (Enter) or "Backspace". In that case, prefix line with & and enter the key combination after, like &Return.

Reporting performance issues

Download "Lua profiler" from ReaTeam Scripts and "ReaImGui" from ReaTeam Extensions via ReaPack.
Change "profile" to "true" in internal/definitions/config.lua
In Reaper, click Actions > Running script > rk.lua > Terminate instances. There may be no "Running script", then just skip this step.
Press any key. A profiler window will open.
Click "Acquisition > Stop" in the profiler window after you're done
Click "Copy to clipboard". Paste in a GitHub issue.
When you're done, change "profile" back to false and repeat (3)

Further Information

Check out the documentation to learn more.

gwatcha/reaper-keys