ReaLearn Audio Hook - helgoboss/helgobox GitHub Wiki

Introduction

This page describes the technique that allows ReaLearn to capture MIDI events directly from the MIDI input ports enabled in the REAPER preferences.

ReaLearn is programmed in Rust, but on this page I describe how it would be done using the REAPER C++ SDK functions (on which the reaper-rs Rust bindings build as well).

Procedure

The general idea is to register an audio hook (that REAPER then calls on each audio cycle) and to read the buffer of each already open MIDI device in that hook.

1. Create audio hook

Create a value of type audio_hook_register_t
The most important field of this struct is OnAudioBuffer, to which you should pass your own callback function that REAPER will invoke on each audio cycle.
userdata1 and userdata2 can be used to pass some context that you can then access in the callback function. If you don’t need it, set it to nullptr.
When dealing with MIDI only, input_nch, output_nch and GetBuffer can be set to 0 or nullptr, respectively.

2. Register audio hook

Use Audio_RegHardwareHook(true, my_audio_hook) to let REAPER know about your hook
As soon as you have registered it, REAPER should call your hook callback function very frequently.
REAPER will call it twice for each audio cycle: One time at the beginning of the audio cycle (isPost == false) and one time at the end of it (isPost == true). For details see REAPER Internals.
You probably want to capture the MIDI events before they reach the REAPER tracks. That means you should execute the following logic only if isPost == false.

3. In callback: Get reference to MIDI input device

To capture MIDI events from an already open MIDI device, you first need to get a reference to it (a value of type midi_Input).
You can get such a reference by calling GetMidiInput(some_device_id). This function is an undocumented part of the REAPER API. Justin told me it will stay, so it should be safe to rely on it. The signature can be found here.
It returns nullptr if the given MIDI input device is not enabled in REAPER’s MIDI input preferences.

4. In callback: Read buffer of MIDI input device

Now call midi_Input→GetReadBuf. This gives you a reference to all MIDI events that arrived since the last audio cycle as MIDI_eventlist.
This buffer is mutable! That means you can filter or transform MIDI messages before they reach the tracks. ReaLearn uses this for its Global MIDI Transformation feature.