MeowTab: Simplicity-First MIDI Tablature Editor for REAPER 🐱🎸

MeowTab is a lightweight, low-latency REAPER extension designed to act as a visual guitar tablature editor. It provides a simplified interface for editing MIDI notes directly on a fretboard, acting as a streamlined alternative to the standard Piano Roll.

✨ Features

Visual Fretboard Editor: Insert and modify MIDI notes by clicking directly on a customizable fretboard.
Dual-Layer MIDI Encoding: Uses REAPER Text Events for 100% visual accuracy and General MIDI hacks (velocity/legato) for immediate audible feedback and compatibility with tools like Guitar Pro.
Real-Time Sync: The fretboard visualizer scrolls in real-time with REAPER's transport, showing notes passing a neon-green playback cursor.
Piano Roll Integration: Highlight notes in the native REAPER Piano Roll and update their string/fret position via the MeowTab UI.
Customizable Instrument Setup: Configure any number of strings and per-string tunings to match your guitar, bass, or other fretted instrument.
Built-in Preview: Hear what you're writing immediately with a default synth tone preview on click.
Interaction Logging: Dedicated log tab for tracking tool actions and troubleshooting.

🛠 Architecture

UI Layer (src/main_ui.lua): Hardware-accelerated interface using ReaImGui.
Logic Module (src/tuning_logic.lua): Advanced MIDI-to-Fret mapping and TDD-validated tuning matrices.
MIDI Engine: Custom Lua logic for inserting dual-layer MIDI data (Text Events + Note properties).

🚀 Development & Testing

1. Test-Driven Development (TDD)

MeowTab is developed using strict TDD. All core logic must have a passing test in the spec/ directory.

Local Docker Testing

We use a headless REAPER environment for testing.

docker build -t meowtab-test -f Dockerfile.test .
docker run --rm -v $(pwd):/app meowtab-test

2. REAPER Dependencies

MeowTab relies on several community extensions:

ReaImGui: Essential for the visual tablature interface.
SWS Extension: Recommended for advanced track/item management.
js_ReaScriptAPI: Required for advanced window and mouse handling.

🎸 Usage Workflow

Initialize: Open the MeowTab extension and click "Create Tab Track".
Configure: Set your string count and tuning in the Settings tab.
Edit: Select a note length and modifier (e.g., Palm Mute), then click on the fretboard to place a note.
Visualize: Hit play in REAPER; the fretboard will automatically scroll and highlight notes as they are played.

🧪 Running Unit Tests

Once Lua and Busted are installed, you can verify the core logic:

busted

📈 Development Roadmap

Phase 1: Pivot Architecture to Visual Tab Editor.
Phase 2: Dockerized Headless Testing Environment.
Phase 3: ReaImGui UI Skeleton (Settings, Editor, Log).
Phase 4: TDD Implementation of Dual-Layer MIDI Engine.
Phase 5: Real-Time Visualizer Scrolling.
Phase 6: ReaPack Distribution.

📝 Documentation

Architecture & Tools - Detailed breakdown of MIDI encoding and external libraries.
Implementation Plan - The master roadmap and user stories.
Prompt Log - History of project decisions and development steps.

author: wompmacho date: '2024-05-24T12:05:00-04:00' lastmod: '2024-05-24' tags: ["guitar", "tabs", "reaper", "midi", "tdd"]