81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
# CLAUDE.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## What this is
|
|
|
|
A REAPER MIDI-editor grid/step-entry mode written in Lua, built for
|
|
keyboard-and-speech use with OSARA. Pure ReaScript — no ReaPack, no
|
|
js_ReaScriptAPI, no ReaImGui. `README.md` is the user manual and is unusually
|
|
detailed; read the relevant section before changing behaviour, and update it
|
|
when behaviour changes.
|
|
|
|
## Commands
|
|
|
|
```
|
|
lua test_lib.lua # run the tests
|
|
powershell -ExecutionPolicy Bypass -File install.ps1 # install (REAPER must be CLOSED)
|
|
powershell -ExecutionPolicy Bypass -File install.ps1 -Uninstall
|
|
```
|
|
|
|
There is no build, no lint, no package manager, no test framework. `test_lib.lua`
|
|
is a single script of `eq(got, want, label)` assertions printing `ALL PASS` or a
|
|
failure count; to run one case, comment out the others. It stubs a global
|
|
`reaper` table, so it only covers the pure logic (scale stepping, note naming,
|
|
grid labels, chord construction). Anything touching MIDI data or the REAPER API
|
|
can only be exercised inside REAPER. Note it `dofile`s an **absolute** path to
|
|
`midigrid_lib.lua`.
|
|
|
|
## Architecture
|
|
|
|
**`midigrid_lib.lua`** holds essentially all the logic as module `M`. Every
|
|
action script is a thin adapter: resolve its own directory from
|
|
`reaper.get_action_context()`, `dofile` the lib, check `G.isActive()`, and either
|
|
`G.passThrough(...)` or call a couple of lib functions. New behaviour belongs in
|
|
the lib; new action scripts should stay ~10 lines.
|
|
|
|
**No private cursor state.** Time is REAPER's edit cursor; pitch is the MIDI
|
|
editor's `active_note_row`; cell size is `MIDI_GetGrid()`. This is what lets grid
|
|
mode and plain OSARA editing interleave without drifting, and why the user's
|
|
existing grid-size keybindings just work. Do not introduce a cursor of your own.
|
|
|
|
**Action scripts must never call `reaper.defer`.** A still-running script makes
|
|
REAPER show its "already running — terminate or launch new instance?" prompt on
|
|
the next keypress, which destroys key repeat. All timing lives in
|
|
`MidiGrid_Daemon.lua`, one background loop that auto-starts (`G.ensureDaemon()`),
|
|
heartbeats via ExtState, refuses to start a second copy, and releases notes on
|
|
`atexit`. Actions post a request to ExtState and exit immediately. If you need
|
|
something to happen later — note release, stop-at-bar-end, restoring borrowed
|
|
loop/repeat state — add it to the daemon loop, not to an action.
|
|
|
|
**ExtState section `midigrid`** is the only state. Persisted (`M.set`/`M.get`):
|
|
`active`, `hold`, `root`, `scale`, `vel`, `velstep`, `chan`, `previewdur`,
|
|
`stoplead`. Transient (`M.setTemp`/`M.getTemp`, persist flag false): `seq`,
|
|
`pitches`, `dur`, `hb`, `stopat`, `stoparm`, `savedloop`, `savedrep`. Preview
|
|
traffic must stay transient — persisting it would write `reaper.ini` on every
|
|
keypress.
|
|
|
|
**Every grid key falls back.** When grid mode is off, each bound key forwards to
|
|
what it did before via `G.passThrough` (e.g. `_OSARA_PREVCHORD`, or a numeric
|
|
command id), so nothing is permanently taken away.
|
|
|
|
**All feedback is speech**, via `G.say` → `osara_outputMessage`, falling back to
|
|
the console when OSARA is absent. There is no window and no `gfx`.
|
|
|
|
Musical positions are converted through quarter-notes (`MIDI_GetPPQPosFromProjQN`
|
|
and friends), not raw ticks, so edits stay correct across tempo changes.
|
|
|
|
## Installation model
|
|
|
|
`install.ps1` edits `reaper-kb.ini` directly and is idempotent (it strips all
|
|
`RSmidigrid` lines first, and backs up to `reaper-kb.ini.midigrid-backup`).
|
|
REAPER rewrites that file on exit, so it must be closed or changes are lost.
|
|
|
|
Adding a new action means adding a row to **both** tables in `install.ps1`: the
|
|
`$actions` table (`SCR 4 <section> <id> "<description>" <path>`) and, if it needs
|
|
a key, `$keys` (flags: 1 base, +4 Shift, +8 Ctrl, +16 Alt; section 0 = Main,
|
|
32060 = MIDI Editor). `KEY` lines must reference the named command — the SCR id
|
|
with a **leading underscore** (`_RSmidigrid_open`). Without the underscore REAPER
|
|
silently converts the binding to a no-op; this is exactly why importing
|
|
`MidiGrid.ReaperKeyMap` does not work and the file is kept for reference only.
|