REAPER OSC commands are defined in a plain-text file with an unusual extension and no GUI, which is why most people assume the OSC vocabulary is fixed. It is not. Every address REAPER listens on is declared in a .ReaperOSC pattern file you can read, copy and rewrite — and on top of that vocabulary there is a second, open-ended mechanism that lets you fire any of REAPER's several thousand actions by command ID. This is the reference for both, written for someone building a controller rig rather than reading a spec.
- What you get: where the config file lives, what its syntax means, how to fire actions by ID, and how the
@wildcard works. - What you need: REAPER 6 or 7 with an OSC device already added under Preferences → Control/OSC/web.
- Time: 10 minutes to read, a lifetime of not guessing at addresses.
- Cost: free in REAPER. OSC output from a gamepad is a Pro bridge feature,
$89one-time.
Where is the REAPER OSC config file?
In the OSC subfolder of the REAPER resource path, and the quickest way there is Options → Show REAPER resource path in explorer/finder.
By platform, that resolves to:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/REAPER/OSC/ |
| Windows | %APPDATA%\REAPER\OSC\ |
| Linux | ~/.config/REAPER/OSC/ |
| Portable install | <REAPER folder>/OSC/ |
Inside you will find Default.ReaperOSC. Any .ReaperOSC file you drop into that folder appears in the Pattern config dropdown of the OSC device dialog after a restart of the device — so the workflow is always copy, rename, edit, select, never edit the default in place. A REAPER update can replace the shipped file and take your edits with it.
What does the file format actually look like?
One command per line: a REAPER command token, then one or more address patterns, each prefixed with a letter declaring the value type.
Conceptually, a line reads as "when a message of this shape arrives, do this REAPER thing". A transport line and a track line have the same structure:
# A command token, then typed address patterns.
PLAY t/play
STOP t/stop
RECORD t/record
TRACK_VOLUME n/track/@/volume f/track/@/volume/db
TRACK_MUTE b/track/@/mute t/track/@/mute/toggleThe leading letter is the important part. It tells REAPER how to interpret the payload — whether it is a trigger with no meaningful value, a boolean, a raw float, a normalised float in the 0–1 range, an integer, or a string. The same command can be declared with several patterns at once, which is how one REAPER function ends up reachable at both a normalised address and a real-units address.
Do not take the letter legend from a blog post, including this one. The authoritative list for your exact build is in the comment block at the top of Default.ReaperOSC, and it is a few hundred words long. Open it once, read the header, and you will never need to guess. That header is also the complete list of command tokens — far longer than any article would reproduce.
What does @ mean in a ReaperOSC pattern?
It is an index wildcard, almost always a track number.
A pattern containing @ expands across the indexed set, so a single declared pattern covers every track:
/track/1/volume → track 1
/track/2/volume → track 2
/track/24/volume → track 24Some patterns use two wildcards for nested indexes, such as a send on a track. The number of tracks REAPER exposes to a surface is itself configurable at the top of the file via a device-size declaration, which is what makes banked surfaces possible: tell REAPER the device has eight tracks and the addresses refer to a window of eight, which you then scroll with a bank action.
For a gamepad you usually want the opposite of banking — one control that follows the selected track. That is easier through the Learn dialog's Enable only when track is selected checkbox than through pattern files, and the approach is covered in the mapping and scoping guide.
Firing any REAPER action over OSC
The pattern file covers mixer-style control. Everything else — four thousand-odd actions — is reachable through /action.
Requirements, in order:
- The OSC device must have Allow binding messages to REAPER actions and FX learn ticked in its dialog. Without it, action messages are silently dropped.
- You need the real command ID. Get it from
Actions → Show action list, right-click the action, Copy selected action command ID.
Then send the ID as part of the address:
/action/1007 # Transport: Play
/action/1016 # Transport: Stop
/action/1013 # Transport: Record
/action/40044 # Transport: Play/stop
/action/1068 # Transport: Toggle repeat
/action/40364 # Options: Toggle metronomeVerify each of these in your own Actions list before building a rig on them. Command IDs are stable across REAPER versions for built-in actions, but typos are not detectable at runtime — a wrong ID fires a different action, or nothing, with no error.
ReaScripts and extension actions get string IDs beginning with an underscore, like _RS7d3f… or _SWS_…. Those work the same way, with the string in place of the number. That is the mechanism that makes OSC genuinely powerful: a gamepad button fires a ReaScript which does arbitrary work, and you never touch a MIDI port.
Driving the addresses from a gamepad
On the bridge side, every binding has an editable OSC address, so the job is simply writing REAPER's addresses into the mapping editor instead of the defaults.
Targets are configured as host:port pairs in Settings → OSC — 127.0.0.1:8000 for the local machine, or a LAN IP for a REAPER box across the room. A practical gamepad-to-REAPER address set:
| Input | OSC address | Payload | Result in REAPER |
|---|---|---|---|
| Cross / A | /action/40044 | trigger | Play / stop |
| Circle / B | /action/1013 | trigger | Record |
| Square / X | /action/40364 | trigger | Toggle metronome |
| Left stick Y | /track/1/volume | float 0.0–1.0 | Track 1 fader, float precision |
| Right stick X | /track/2/pan | float | Track 2 pan |
| L2 trigger | /track/1/send/1/volume | float 0.0–1.0 | Send 1 level ride |
| Touchpad X/Y | learned onto FX params | float | Two-axis plugin morph |
Note what the float columns buy you. A trigger pull sending a 32-bit float across a six-second send ride has no audible quantisation. The same gesture as a 7-bit CC has 128 steps, and on a long slow sweep you can hear every one of them. That resolution difference is the main reason to pick OSC over MIDI here, and it is argued out in OSC versus MIDI for gamepad control.
OSC is only one of REAPER's five control-surface routes. If you are not sure this is the right one, the control surfaces compared puts it next to MIDI Learn, Mackie Control, HUI and the web interface, and the MIDI Learn guide covers the route most people should start with.
OSC output is a Pro feature — the free build is MIDI-only with three saved presets. Download the free build to test the MIDI path, or get Pro for $89 one-time for OSC targets, unlimited presets and the full mapping editor.
Editing the pattern file safely
Three habits that prevent a weekend of confusion:
- Copy first.
cp Default.ReaperOSC MyRig.ReaperOSC, then selectMyRigin the Pattern config dropdown. - Change paths, not prefixes. The letter prefix declares the value type REAPER expects. Changing
/track/@/volumeto/ch/@/faderis fine; changing the prefix letter changes how the payload is interpreted and usually breaks the line. - Reload after editing. REAPER reads the file when the OSC device is created. Open the device dialog and click OK, or restart REAPER, after an edit.
The main reason to edit at all is interoperability — when another application in your chain already speaks a fixed address shape and you would rather change REAPER than rewrite that app. If you are building the sender yourself, leave the default file alone and write REAPER's addresses on the sender side instead.
FAQ
Where is the REAPER OSC config file?
In the OSC subfolder of the REAPER resource path. Use Options → Show REAPER resource path in explorer/finder, then open OSC. The shipped file is Default.ReaperOSC.
What is the format of a .ReaperOSC file?
Plain text, one command per line. Each line names a REAPER command token such as PLAY or TRACK_VOLUME, followed by one or more address patterns prefixed by a letter that declares the value type.
How do I trigger a REAPER action over OSC?
Send /action/<command id>, where the command ID comes from right-clicking the action in the Actions list and choosing Copy selected action command ID. The OSC device must have action binding enabled.
What does the @ symbol mean in a ReaperOSC pattern?
It is a wildcard that stands in for an index, most often a track number. A pattern written with /track/@/volume matches /track/1/volume, /track/2/volume and so on.
Can I run a ReaScript over OSC?
Yes. Scripts get a command ID beginning with an underscore, such as _RS1a2b3c. Send that string as the action identifier and REAPER runs the script.
Do I need to edit the config file at all?
Not for most setups. The default vocabulary plus /action messages plus OSC Learn covers almost everything. Edit the file when you need a specific address shape that another application already speaks.
Wrap-up
REAPER's OSC vocabulary is a text file you own, plus an action escape hatch that reaches everything the text file does not. Read the header of Default.ReaperOSC once, copy your own IDs out of the Actions list, and you can address any part of REAPER from any device on the network. If you have not added the OSC surface yet, start with the OSC setup guide.
Download Universal Controller MIDI and point a gamepad at those addresses.