Building REAPER Extensions

Overview

REAPER extensions are DLLs/dylibs that extend REAPER’s functionality. Unlike plugins, extensions:

Run in REAPER’s main process
Can register custom actions and menus
Have full access to REAPER’s API
Can show dockable windows
Don’t process audio in a plugin chain

REAPER extensions are not audio plugins. They’re for adding features to REAPER itself, like custom tools, utilities, or workflow enhancements.

IPlugReaperExtension Template

The IPlugReaperExtension example demonstrates:

Registering actions in REAPER’s action list
Creating a dockable UI window
Using REAPER API functions
Responding to REAPER state changes
Adding menu items

Project Structure

Unlike plugins, extensions don’t have config.h with plugin metadata:

config.h

#define PLUG_CLASS_NAME IPlugReaperExtension
#define PLUG_WIDTH 300
#define PLUG_HEIGHT 300
#define PLUG_FPS 60
#define PLUG_SHARED_RESOURCES 0

#define ROBOTO_FN "Roboto-Regular.ttf"
#define SHARED_RESOURCES_SUBPATH "IPlugReaperExtension"

No PLUG_TYPE, PLUG_CHANNEL_IO, or plugin format defines. Extensions aren’t loaded as plugins.

Basic Structure

Header
Initialization
UI Setup
State Monitoring

IPlugReaperExtension.h

#pragma once

#include "ReaperExt_include_in_plug_hdr.h"

enum EControlTags
{
  kCtrlTagText = 0,
  kNumCtrlTags
};

using namespace iplug;
using namespace igraphics;

class IPlugReaperExtension : public ReaperExtBase
{
public:
  IPlugReaperExtension(reaper_plugin_info_t* pRec);
  
  void OnIdle() override;
  void OnUIClose() override { mGUIToggle = 0; }
  
private:
  int mPrevTrackCount = 0;
  int mGUIToggle = 0;
};

Key Differences:

Inherit from ReaperExtBase (not Plugin)
Constructor takes reaper_plugin_info_t*
No ProcessBlock or audio processing

IPlugReaperExtension.cpp

IPlugReaperExtension::IPlugReaperExtension(reaper_plugin_info_t* pRec)
: ReaperExtBase(pRec)
{
  // Import REAPER API functions
  IMPAPI(GetNumTracks);
  IMPAPI(CountTracks);
  IMPAPI(InsertTrackAtIndex);
  
  // Define actions as lambdas
  auto action1 = []() {
    MessageBox(gParent, "Action 1!", "Reaper extension test", MB_OK);
  };
  
  auto action2 = []() {
    InsertTrackAtIndex(GetNumTracks(), false);
  };
  
  // Register actions with REAPER
  RegisterAction("IPlugReaperExtension: Action 1 - MsgBox", action1, true);
  RegisterAction("IPlugReaperExtension: Action 2 - AddTrack", action2);
  RegisterAction("IPlugReaperExtension: Action 3 - Show/Hide UI", 
                 [&]() { ShowHideMainWindow(); mGUIToggle = !mGUIToggle; }, 
                 true, &mGUIToggle);
  
  // ... UI setup
}

IMPAPI Macro: Imports REAPER API functions so you can call them by name.RegisterAction: Adds custom actions to REAPER’s action list (Actions → Show action list).

mMakeGraphicsFunc = [&]() {
  return MakeGraphics(*this, PLUG_WIDTH, PLUG_HEIGHT, PLUG_FPS);
};

mLayoutFunc = [&](IGraphics* pGraphics) {
  pGraphics->SetLayoutOnResize(true);
  pGraphics->LoadFont("Roboto-Regular", (void*) ROBOTO_REGULAR, ROBOTO_REGULAR_length);
  pGraphics->AttachPanelBackground(COLOR_GRAY);
  
  const IRECT bounds = pGraphics->GetBounds();
  
  // Button to trigger action
  pGraphics->AttachControl(
    new IVButtonControl(bounds.GetGridCell(0, 3, 1).GetPadded(-20),
                        [&](IControl* pCaller) {
                          SplashClickActionFunc(pCaller);
                          action2();  // Call action directly
                        }, "Action 2 - Add Track"));
  
  // Button to dock/undock window
  pGraphics->AttachControl(
    new IVButtonControl(bounds.GetGridCell(1, 3, 1).GetPadded(-20),
                        [&](IControl* pCaller) {
                          SplashClickActionFunc(pCaller);
                          ToggleDocking();
                        }, "Dock"));
  
  // Text display
  WDL_String str;
  mPrevTrackCount = CountTracks(0);
  str.SetFormatted(64, "NumTracks: %i", mPrevTrackCount);
  pGraphics->AttachControl(
    new ITextControl(bounds.GetGridCell(2, 3, 1), str.Get(), IText(24, EAlign::Center)), 
    kCtrlTagText);
};

void IPlugReaperExtension::OnIdle()
{
  int tracks = CountTracks(0);
  
  if (tracks != mPrevTrackCount) {
    mPrevTrackCount = tracks;
    
    if (GetUI()) {
      GetUI()->GetControlWithTag(kCtrlTagText)
            ->As<ITextControl>()
            ->SetStrFmt(64, "NumTracks: %i", tracks);
    }
  }
}

OnIdle: Called periodically. Use to monitor REAPER state and update UI.

Creating an Extension

Duplicate Template

cd iPlug2/Examples
python duplicate.py IPlugReaperExtension MyReaperTool MyCompany
cd MyReaperTool

The duplicate script will show a warning about not being able to parse plugin config. This is expected for REAPER extensions.

Define Actions

Create lambdas for your custom actions:

MyReaperTool::MyReaperTool(reaper_plugin_info_t* pRec)
: ReaperExtBase(pRec)
{
  // Import needed API functions
  IMPAPI(GetSelectedTrack);
  IMPAPI(GetSetMediaTrackInfo);
  IMPAPI(SetTrackSelected);
  IMPAPI(UpdateArrange);
  
  // Action: Color selected tracks red
  auto colorRed = [&]() {
    MediaTrack* track = GetSelectedTrack(0, 0);
    if (track) {
      int color = RGB(255, 0, 0) | 0x1000000;  // Custom color flag
      GetSetMediaTrackInfo(track, "I_CUSTOMCOLOR", &color);
      UpdateArrange();
    }
  };
  
  // Action: Show track count
  auto showTrackCount = [&]() {
    int count = CountTracks(0);
    char msg[64];
    snprintf(msg, sizeof(msg), "Track count: %d", count);
    MessageBox(gParent, msg, "Track Info", MB_OK);
  };
  
  // Register actions
  RegisterAction("MyReaperTool: Color Selected Track Red", colorRed, true);
  RegisterAction("MyReaperTool: Show Track Count", showTrackCount, true);
}

Import REAPER APIs

Use IMPAPI to import functions from REAPER’s API:

// Track functions
IMPAPI(GetTrack);
IMPAPI(GetSelectedTrack);
IMPAPI(InsertTrackAtIndex);
IMPAPI(DeleteTrack);
IMPAPI(SetTrackSelected);
IMPAPI(GetSetMediaTrackInfo);

// Item functions
IMPAPI(GetSelectedMediaItem);
IMPAPI(GetMediaItem);
IMPAPI(GetSetMediaItemInfo);

// Project functions
IMPAPI(GetCurrentProjectInLoadSave);
IMPAPI(EnumProjects);

// UI functions
IMPAPI(UpdateArrange);
IMPAPI(UpdateTimeline);

You must import every REAPER API function you want to use. If you forget IMPAPI, you’ll get linker errors.

Build UI

mLayoutFunc = [&](IGraphics* pGraphics) {
  pGraphics->SetLayoutOnResize(true);
  pGraphics->AttachPanelBackground(COLOR_DARK_GRAY);
  
  const IRECT bounds = pGraphics->GetBounds().GetPadded(-10);
  
  // Add controls
  pGraphics->AttachControl(
    new IVButtonControl(bounds.GetGridCell(0, 4, 1).GetMidVPadded(30),
                        [&](IControl* pCaller) {
                          SplashClickActionFunc(pCaller);
                          colorRed();
                        }, "Color Red"));
  
  pGraphics->AttachControl(
    new IVButtonControl(bounds.GetGridCell(1, 4, 1).GetMidVPadded(30),
                        [&](IControl* pCaller) {
                          SplashClickActionFunc(pCaller);
                          ToggleDocking();
                        }, "Dock/Undock"));
};

Build and Install

Windows

Open .sln in Visual Studio
Build “REAPER Extension” configuration
Output: build-win/MyReaperTool.dll
Copy to C:\Users\[You]\AppData\Roaming\REAPER\UserPlugins\
Restart REAPER

macOS

Open .xcworkspace in Xcode
Build “REAPER Extension” scheme
Output: build-mac/MyReaperTool.dylib
Copy to ~/Library/Application Support/REAPER/UserPlugins/
Restart REAPER

Test Actions

In REAPER: Actions → Show action list

Search for “MyReaperTool”

Your actions should appear in the list

Assign keyboard shortcuts if desired

Test Show/Hide UI action

REAPER API Access

Common API Functions

Tracks
Items
Project
UI Updates

// Get track count
int count = CountTracks(0);

// Get track by index
MediaTrack* track = GetTrack(0, 0);  // Project 0, track 0

// Get selected track
MediaTrack* selected = GetSelectedTrack(0, 0);

// Get/set track name
char name[256];
GetSetMediaTrackInfo_String(track, "P_NAME", name, false);  // Get
GetSetMediaTrackInfo_String(track, "P_NAME", "New Name", true);  // Set

// Get/set track volume (0.0-4.0, 1.0=0dB)
double volume;
GetSetMediaTrackInfo(track, "D_VOL", &volume);  // Get
volume = 0.5;  // -6dB
GetSetMediaTrackInfo(track, "D_VOL", &volume);  // Set

// Get/set track pan (-1.0 to 1.0)
double pan = 0.0;
GetSetMediaTrackInfo(track, "D_PAN", &pan);

// Select/deselect track
SetTrackSelected(track, true);

// Get item count on track
int itemCount = CountTrackMediaItems(track);

// Get item by index
MediaItem* item = GetTrackMediaItem(track, 0);

// Get selected item
MediaItem* selected = GetSelectedMediaItem(0, 0);

// Get/set item position
double position;
GetSetMediaItemInfo(item, "D_POSITION", &position);  // Get
position = 10.0;  // 10 seconds
GetSetMediaItemInfo(item, "D_POSITION", &position);  // Set

// Get/set item length
double length;
GetSetMediaItemInfo(item, "D_LENGTH", &length);

// Get active take
MediaItem_Take* take = GetActiveTake(item);

// Get current project
ReaProject* proj = EnumProjects(-1, nullptr, 0);

// Get project sample rate
double sampleRate = 0;
GetSetProjectInfo(proj, "PROJECT_SRATE", &sampleRate, false);

// Get play state
int state = GetPlayState();
// 0=stopped, 1=playing, 2=paused, 4=recording

if (state & 1) {
  // Currently playing
}

// Get play position
double pos = GetPlayPosition();

// Get/set tempo
double tempo = 120.0;
SetCurrentBPM(proj, tempo, false);

// Redraw arrange view
UpdateArrange();

// Redraw timeline
UpdateTimeline();

// Show console message
ShowConsoleMsg("Hello from extension!\n");

// Show message box
int result = MessageBox(gParent, "Message", "Title", MB_YESNO);
if (result == IDYES) {
  // User clicked Yes
}

API Documentation

Full REAPER API reference:

https://www.reaper.fm/sdk/reaper_plugin_functions.h
Search “REAPER API” in REAPER’s help

Action Registration

Action Types

// Simple action (no state)
RegisterAction("MyTool: Do Something", doSomething);

// Action with menu item (checkmark in menu)
RegisterAction("MyTool: Toggle Feature", toggleFeature, true);

// Action with toggle state
int state = 0;
RegisterAction("MyTool: Show Window", showWindow, true, &state);
// state will be read to show checkmark in menu

Action Descriptions

Action Naming Convention:

Start with extension name: "MyTool: ..."
Use descriptive verbs: Show, Hide, Toggle, Add, Remove
Keep under 80 characters
Use title case

Window Docking

// Toggle docking state
ToggleDocking();

// Check if docked
if (IsDocked()) {
  // Window is docked
}

Users can:

Dock to left/right/bottom of REAPER window
Float as separate window
Save dock state with REAPER project

Example Extensions

Track Organizer

class TrackOrganizer : public ReaperExtBase
{
public:
  TrackOrganizer(reaper_plugin_info_t* pRec) : ReaperExtBase(pRec)
  {
    IMPAPI(CountTracks);
    IMPAPI(GetTrack);
    IMPAPI(GetSetMediaTrackInfo_String);
    
    auto sortByName = [&]() {
      int count = CountTracks(0);
      std::vector<std::pair<std::string, MediaTrack*>> tracks;
      
      for (int i = 0; i < count; i++) {
        MediaTrack* track = GetTrack(0, i);
        char name[256];
        GetSetMediaTrackInfo_String(track, "P_NAME", name, false);
        tracks.push_back({name, track});
      }
      
      std::sort(tracks.begin(), tracks.end());
      
      // Reorder tracks (would need more API calls)
      ShowConsoleMsg("Sorted tracks by name\n");
    };
    
    RegisterAction("TrackOrganizer: Sort Tracks by Name", sortByName, true);
  }
};

Batch Processor

auto batchNormalize = [&]() {
  int count = CountTracks(0);
  
  for (int i = 0; i < count; i++) {
    MediaTrack* track = GetTrack(0, i);
    
    // Analyze peak
    double peak = AnalyzeTrackPeak(track);
    
    // Set volume for normalization
    if (peak > 0.0) {
      double volume = 1.0 / peak;
      GetSetMediaTrackInfo(track, "D_VOL", &volume);
    }
  }
  
  UpdateArrange();
  ShowConsoleMsg("Normalized all tracks\n");
};

Building

Visual Studio (Windows)

Configuration: REAPER Extension
Platform: x64
Output: build-win/MyReaperTool.dll

Xcode (macOS)

Scheme: MyReaperTool - REAPER Extension
Architecture: Universal (Intel + Apple Silicon)
Output: build-mac/MyReaperTool.dylib

Troubleshooting

Extension doesn't load in REAPER

Check file is in correct UserPlugins folder
Restart REAPER
Check REAPER console (View → Show REAPER console) for errors
Verify correct architecture (x64 for Windows, Universal for macOS)

Actions don't appear in action list

Verify RegisterAction was called in constructor
Check REAPER console for registration errors
Search for exact extension name in action list

REAPER API function returns null

Did you call IMPAPI(FunctionName) to import it?
Check function signature matches REAPER docs
Verify REAPER version supports that API

Window doesn't dock properly

Use SetLayoutOnResize(true) in layout function
Implement proper bounds handling for resize
Test dock/undock with ToggleDocking()

Next Steps

REAPER API Docs

reaper_plugin_functions.hComplete API reference

REAPER Plugins

Build audio plugins that integrate with REAPER API

IGraphics

Customize extension UI

Examples

Browse more REAPER extensions

​Overview

​IPlugReaperExtension Template

​Project Structure

​Basic Structure

​Creating an Extension

​REAPER API Access

​Common API Functions

​API Documentation

​Action Registration

​Action Types

​Action Descriptions

​Window Docking

​Example Extensions

​Track Organizer

​Batch Processor

​Building

​Visual Studio (Windows)

​Xcode (macOS)

​Troubleshooting

​Next Steps

REAPER API Docs

REAPER Plugins

IGraphics

Examples

Overview

IPlugReaperExtension Template

Project Structure

Basic Structure

Creating an Extension

REAPER API Access

Common API Functions

API Documentation

Action Registration

Action Types

Action Descriptions

Window Docking

Example Extensions

Track Organizer

Batch Processor

Building

Visual Studio (Windows)

Xcode (macOS)

Troubleshooting

Next Steps