01 ‐ CSI Overview - FunkybotsEvilTwin/CSIUserGuide GitHub Wiki

Control Surface Integrator (CSI)

The Control Surface Integrator (CSI) is a powerful Reaper plugin designed to provide unparalleled flexibility in integrating your hardware control surfaces. Whether you're working with a single MIDI, MCU, or OSC device or creating a fully integrated multi-surface setup, CSI allows you to customize your configuration to suit your workflow. By tailoring the plugin to your needs, you can achieve levels of control far beyond Reaper's default capabilities, enabling seamless collaboration between multiple surfaces in a unified virtual control system.

Note:
CSI requires access to the MIDI Devices, which must be disabled in Reaper's Preferences > Audio > MIDI Devices. For this reason, CSI may not be ideal for use with MIDI controller keyboards that need to pass note data to Reaper alongside control functions. However, users have successfully implemented workarounds by using BOME MIDI Translator to split note and control data, then routing the control data to CSI via a virtual MIDI port.

Benefits of CSI

  • Works with any MIDI, MCU, or OSC device
  • Supports multiple surfaces working together as an integrated system
  • Provides control over Reaper and plugins
  • Includes starting configuration files for many common surfaces and example FX mappings
  • Highly customizable (text-based surface files are easy to learn and modify)
  • Offers color support on devices such as X-Touch, FaderPort8/16, MIDI Fighter Twister, and OSC surfaces
  • Allows creation of custom encoder response curves
  • Supports Mac, PC, and Linux
  • Open-source project (contributions welcomed)

High-Level Concepts

Pages

In CSI, you can define one or more Pages, each containing the configuration for specific surfaces and actions.

  • Only one Page is active in Reaper at a time, but switching between Pages is simple using Navigation Actions.
  • For example, you could create a "Recording Page" and a "Mixing Page," with the physical controls (buttons, faders, etc.) mapped to different actions on each.
  • Pages allow you to completely reconfigure surface behavior, as well as include or exclude surfaces as needed

Surfaces

Each surface within a Page is defined by two key components:

1. Surface Configuration File: surface.txt

  • Describes the capabilities of the control surface.
  • Each control or display (referred to as a Widget) is defined in this file.
  • Widgets specify:
    • Messages CSI expects to receive (e.g., button presses or fader movements).
    • Feedback Processors to define messages CSI sends to the surface (e.g., lighting up a button or updating a display).

2. Zone Files: Zones

  • Dictate how the control surface maps to Reaper elements and/or plugins.
  • Controlling Reaper: Maps surface elements (defined in surface.txt) to Reaper actions.
  • Controlling Plugins: Maps surface elements to parameters in FX plugins (e.g., VST, VST3, AU, CLAP, JSFX to some extent).