66 lines
3.5 KiB
Markdown
66 lines
3.5 KiB
Markdown
# 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"]
|