In this article, we will be taking an in-depth look into the way REAPER implements OSC (Open Sound Control) through the pattern configuration file, and build our own optimized version. The examples provided here will use TouchOSC ; however, they could be applied to any other control surface or program using OSC.
While I'm aware that there are other tools that also take advantage of OSC in Reaper, such as DrivenByMoss 4, ReaLearn 2 or CSI V3, I made a conscious decision to focus solely on the native REAPER implementation of OSC.
Getting started with the pattern configuration file
The best way to get started is to make a copy of the Default.ReaperOSC file and rename it to something else before using it. The file is located here :
- On Mac :
/Users/your-username/Library/Application Support/REAPER/OSC/Default.ReaperOSC
- On Windows :
C:\Users*your-username*\AppData\Roaming\REAPER\OSC\Default.ReaperOSC
Open the file in your text editor of choice and let's take a look. You should see something like this :
# Default.ReaperOSC
# OSC pattern config file.
DEVICE_TRACK_COUNT 8
DEVICE_SEND_COUNT 4
DEVICE_RECEIVE_COUNT 4
DEVICE_FX_COUNT 8
DEVICE_FX_PARAM_COUNT 16
DEVICE_FX_INST_PARAM_COUNT 16
DEVICE_MARKER_COUNT 0
DEVICE_REGION_COUNT 0
What am I looking at?
The first few settings (DEVICE_TRACK_COUNT to DEVICE_REGION_COUNT) will determine how many tracks REAPER sends to the DEVICE connected. By default this means REAPER sends the information of the first 8 tracks, for each track it sends information of the first 4 sends, 4 receives, 8 fx slot and for each fx slot, 16 fx or instrument parameters.
Each lines represents an action message to be sent to the device and / or interpreted by REAPER, it can include an argument defined with a flag immediately before the pattern.
Action message pattern example
TRACK_NAME s/track/name s/track/@/name
^ ^ ^ ^
# action arg pattern wildcard
Action
The action description is written in uppercase at the start of the message.
Argument
Before each pattern, you can include an argument that determines how the device or REAPER interprets the message. The argument is not included in the message received by the device. Here are the artument types:
- n - normalized floating-point
TRACK_VOLUME n/track/volume
# Sends a value from 0 to 1
- f - raw floating-point argument
TEMPO f/tempo/raw
# Sends the floating point value, for example 120.00 for the tempo
- b - binary argument
TRACK_MUTE b/track/mute
# Sends either 0 or 1. The device sets or clears the state
# when sending the message. Can be used to emulate switches or momentary controls.
- t - trigger or toggle message
METRONOME t/click
# The device sends /click or /click 1 to toggle the metronome on or off. REAPER
# sends /click 1 when the metronome is enabled, and /click 0 when the metronome
# is disabled.
- r - rotary
SCRUB r/scrub
# The device sends /scrub 1 to scrub forward, and /scrub -1 to scrub in reverse
# (if ROTARY_CENTER is 0).
- s - string
TRACK_NAME s/track/name s/track/@/name
# The device sends /track/3/name "vox" to rename track 3 in REAPER, or /track/name
# "vox" to rename the track that is currently selected in the device. REAPER sends
# /track/3/name "vox" to report that name of track 3 is "vox". If track 3 is
# currently selected in the device, REAPER will also send /track/name "vox".
- i - integer
ACTION i/action t/action/@
# The device sends /action 40757 or /action/40757 to trigger the REAPER action
# "split items at edit cursor".
Pattern
The pattern that follows the argument flag is arbitrary - this means you can decide on the naming convention for your controller and its configuration file.
For the TRACK_NAME action s/track/name and s/track/@/name are two different messages for the same action.
Wildcard
The wild card @ is REAPER-only and is a way to target a specific action pattern. For example, if REAPER is sending to device a count of 4 tracks, you can expect that the following addresses /track/1/name, /track/2/name, /track/3/name and /track/4/name to receive values. Again, the argument s is not included in the message.
LogicPad Track Name Example
Let's look at how the TRACK_NAME pattern is implemented in the LogicPad template included with TouchOSC (You can find it under Help > Examples > LogicPad). The config file LogicPad.ReaperOSC is in the same folder as the Default.ReaperOSC and is also included with REAPER.
# LogicPad.ReaperOSC
TRACK_NAME s/1/trackname@ s/2/trackname@ s/3/trackname s/4/trackname s/5/trackname
Looking at the configuration file we can see that for this interface, 5 messages are being sent to the device from REAPER. Two of them are using a wildcard and the three others are not.
On the interface we can see 8 track labels named "One" to "Eight"
In the Document Tree we can find their respective labels under page1 in each subfolder.
Each label address uses a dyanmics placeholders in TouchOSC (We'll look at dynamic placeholders in the upcoming TouchOSC deep dive article)
Conclusion and consideration
Hopefully this deep dive introduction will help you explore OSC in REAPER and demystify the pattern configuration file.
In the next article we will start building our own template. As we build it from scratch we will consider optimization from the start. This is because the Default.ReaperOSC configuration file includes a lot of feedback messages and it will flood the device with thousand and thousand of messages that can impact performance and makes it difficult to debug incoming messages.
In the meantime you can join the TouchOSC Discord.
Stay tuned!