ModalGrid

ModalGrid breathes new life into the classic Novation Launchpad MK1 by transforming it from a simple clip launcher into a smart melodic instrument. Built for Linux, it maps musical scales and modes directly to the grid—ensuring you never hit a wrong note. With native ALSA MIDI integration and on-device configuration, it turns your hardware into a powerful, expressive surface for your DAW.

Core Philosophy

• Hardware Awareness: Respects the limitations of the MK1 (Red/Green/Amber LEDs only), using color meaningfully (e.g., Amber = Root Note, Green = In-Key, Red = Out-of-Key).
• Musicality: Actively helps the user play in key, acting as a filter and a guide.
• Connectivity: Native integration using virtual ALSA MIDI ports, easily bridged to JACK.

Features

Smart Note Mapping (The "Engine")

• Root & Scale Selection: Extensive library of scales including Major, Minor, Modes, Pentatonics, and exotic scales (Bhairav, Pelog, etc.).
• Tuning: Exotic and non-Western scales are approximated to 12-Tone Equal Temperament (12-TET) to ensure compatibility with standard MIDI synthesizers.
• Layout Modes:
  • Diatonic 4th (Default): Standard "Keyboard" feel where moving up a row moves a 4th degree in the scale.
  • Diatonic 3rd: Layout where moving up a row moves a 3rd degree.
  • Sequent: Continuous diatonic layout.
  • Chromatic: All semitones are mapped, with scale notes highlighted.
  • Chromatic Guitar: Layout mimicking guitar tuning (bottom rows).
  • Drum Rack: 4x4 quadrants for standard drum rack mapping (chromatic, no scale filtering).
• Visual Feedback:
  • Root Notes: Amber.
  • In-Scale Notes: Green.
  • Out-of-Scale: Off (in Diatonic modes) or Dim (in Chromatic modes).

Quick Scale Mode

• Activation: In Config Mode, press the button at Row 1, Column 7 (Green). This activates the Quick Scale overlay.
• Usage: In Play Mode, the top 2 rows are replaced by Quick Scale controls.
• Sub-Pages: Press the Top-Right Button (Row 0, Col 7) of the overlay to cycle between:
  1. Root Note: Select Root Note, Relative Scale, Circle of Fifths.
  2. Modus: Select Scale Mode (Major, Minor, Dorian, etc.).
  3. Note Repeat: (Placeholder) Configuration for note repeat.

Configuration Interface

• Enter Config Mode: Press the Top-Right Side Button (Session/Vol).
• Config Grid Layout:
  • Row 0 (Top): Layout Selection (Diatonic 4th, Chromatic, Guitar, etc.).
  • Row 1-2: Root Note Selection & Helpers (Relative Scale, Circle of Fifths, Quick Scale).
  • Row 3: Octave Selection (-2 to +5).
  • Row 4-7: Scale Selection (Major, Minor, Modes, Exotic Scales).

Connectivity

• Auto-detection of connected Launchpad MK1 devices.
• Creates a virtual ALSA MIDI output port (ModalGrid).
• Routes notes from the Launchpad to the virtual port.

Installation

1. Clone the repository:

   git clone https://github.com/dtk1985/ModalGrid.git
   cd ModalGrid

2. Set up a virtual environment (recommended):

   python -m venv .venv
   
   # Bash / Zsh
   source .venv/bin/activate
   
   # Fish
   source .venv/bin/activate.fish

3. Install dependencies:

   python -m pip install -r requirements.txt

Usage

Running the Controller

python src/main.py

JACK/ALSA Setup

1. Start your JACK audio server (or PipeWire).
2. Run the script.
3. Use a patchbay like qpwgraph or Catia to connect the ModalGrid ALSA MIDI port to your DAW or synth.
   • Note: If using pure JACK, you may need an ALSA-to-JACK bridge (like a2jmidid). PipeWire handles this automatically.

Technical Architecture

Tech Stack

• Language: Python 3.10+
• Libraries: mido, python-rtmidi

Component Design

1. LaunchpadDriver: Handles raw MIDI communication and abstracts LED color codes.
2. TheoryEngine: Pure logic class that calculates MIDI note numbers based on Root + Scale + Interval.
3. ModalGridApp (Main Controller): Handles state (Current Key, Current Mode), renders the UI, and routes input events.

Hardware Notes (Launchpad MK1)

• Grid: 8x8 (Notes) + Top Row (CC) + Right Column (Notes).
• Colors: Limited to Red, Green, and Amber (Mix) with low/high brightness levels.