# 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.
```bash
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
1.  **Initialize:** Open the MeowTab extension and click **"Create Tab Track"**.
2.  **Configure:** Set your string count and tuning in the **Settings** tab.
3.  **Edit:** Select a note length and modifier (e.g., Palm Mute), then click on the fretboard to place a note.
4.  **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:
```bash
busted
```

## 📈 Development Roadmap
- [x] **Phase 1:** Pivot Architecture to Visual Tab Editor.
- [x] **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](./architecture_and_tools.md) - Detailed breakdown of MIDI encoding and external libraries.
*   [Implementation Plan](./implementation_plan.md) - The master roadmap and user stories.
*   [Prompt Log](./prompt_log.md) - 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"]