midi-cli 0.3.0__tar.gz → 0.4.0__tar.gz

midi_cli-0.4.0/ARCHITECTURE.md

@@ -0,0 +1,189 @@
+# Architecture
+
+Developer reference for midi-cli: instruments, focus traversal, audio flow, and persistence.
+
+## Module Overview
+
+| File | Responsibility |
+|------|---------------|
+| `app.py` | Entry point, main loop, raw key input, focus traversal |
+| `state.py` | All global state; instruments, focus, edit workflow state |
+| `audio.py` | `sd.OutputStream` callback; synth + sample mixing; loop mixing; metronome |
+| `midi.py` | MIDI input callback; keyboard-mock trigger; routes note-ons through the active instrument |
+| `sampler.py` | Per-instrument sample I/O, pitch/volume offsets, chromatic pre-compute, copy |
+| `loop.py` | Loop state machine (`cycle_loop_state`, `reset_loop_state`) |
+| `ui.py` | Terminal rendering: submenu strip, header strip, waveform block, tune panel |
+| `config.py` | Config load/save, device enumeration, instrument persistence |
+
+## Startup Flow
+
+1. `load_defaults()` reads `config.json` (devices, MIDI port, synesthesia, instruments, current instrument)
+2. `migrate_legacy_samples()` moves any flat `samples/note_*.wav` into `samples/sampler-a/`
+3. `init_instruments(cfg["instruments"])` builds the in-memory instrument list
+4. `load_all_instruments()` loads each sampler's wav/pitch/volume files and (if chromatic was on) recomputes its chromatic set
+5. `activate_instrument(idx)` rebinds `st.samples`, `st.pitch_offsets`, `st.volume_offsets`, `st.pitched_samples`, `st.chromatic_samples` to the live instrument's dicts
+6. MIDI input opened; if unavailable, falls back to keyboard mock
+7. `sd.OutputStream` started; main loop runs
+
+## Three-Layer Model
+
+The UI is organized in three layers:
+
+- **Modes** (focus ring, ←→/Tab cycles): `instrument │ edit │ loop │ config`
+  - `st.focus` holds the active mode. `edit` is skipped when the current instrument is a synth.
+  - `←` / `→` (and `Tab` / `Shift-Tab`) change mode. If a submenu is open, it closes first.
+
+- **Submodes** (submenu strip — the line above the header, ↑↓ navigate, Enter select):
+  - `instrument` → `synth / sampler-a / sampler-b`
+  - `edit` → `tune / trim / copy / split / record / chromatic: off/on` (Enter opens workflow)
+  - `loop` → `○ idle │ ● rec │ ▶ play │ ⊕ dub │ metro: on/off ♩bpm` (↑↓ navigate, Enter select/activate)
+  - `config` → device/port/synesthesia/volume fields (↑↓ navigate, Enter cycles value)
+
+- **Toggles / sub-modes**:
+  - Metro+BPM row (row 4 in loop submenu): Enter toggles metronome on/off. While metro is on and row 4 is focused: ↑↓ adjust BPM ±1, ←→ adjust BPM ±5. Turning metro off closes the submenu; Escape closes submenu with metro state preserved.
+  - Chromatic on/off: Enter when `chromatic` row is focused in edit submenu.
+
+## UI Layout
+
+```
+[submenu strip]     ← submode options for the focused mode
+[header strip]      ← instrument │ edit │ loop │ config
+[status line]       ← note, sustain, loop position, chromatic state, etc.
+[MIDI/keyboard hint]
+[help line]
+[blank]
+[waveform block — 6 rows]   ← pad strip / loop waveform / trim / split / config
+```
+
+`NUM_UI_LINES = 5` (submenu + header + status + MIDI + help). `waveform_block = TRIM_WAVEFORM_HEIGHT + 1 = 7`.
+
+## Key Map
+
+| Key | Action |
+|-----|--------|
+| `←` `→` | **Always** cycle focus ring (close submenu if open). Exception: edit actions (tune/trim/split) retain fine-control behavior. Exception: when metro is on and loop row 4 is focused, adjust BPM ±5. |
+| `↑` `↓` | Navigate submenu rows when a submenu is open. Exception: when metro is on and loop row 4 is focused, adjust BPM ±1 (navigation blocked). Inert at top level. |
+| `Tab` / `Shift-Tab` | Equivalent to `→` / `←` (cycle focus ring, close submenu if open). Exception: swap tune param / switch board in copy. |
+| `Space` | Cycle loop state (`idle → recording → playing → overdub`) globally, from any focus. |
+| `Enter` | Open submenu / confirm step. In config submenu: cycle the focused field's value. In loop submenu on metro row: toggle metro on/off (turning off also closes submenu). |
+| `Escape` | Back out / close overlay / clear loop. |
+| `F1`–`F10` | Switch to instrument at index 0–9 (global, any focus). |
+| `Ctrl-A` | Advance split-marker → assign phase |
+| `Ctrl-C` | Quit |
+| MIDI / `1`–`0` | Play notes (`1`=C4 … `0`=A4 in keyboard-mock mode) |
+| `` ` `` | Toggle sustain (keyboard-mock mode) |
+
+Single-letter verbs (`m`, `v`, `l`, `z`, `r`, `c`) have been removed — everything goes through focus traversal.
+
+## Edit Submenu
+
+Auto-opened when Tab moves focus to `edit`. Rows (all lowercase):
+
+```
+tune        pitch + volume editor
+trim        start/end selection
+copy        source → dest (cross-board capable)
+split       markers → slice-assign
+record      arm/disarm recording
+chromatic   toggle + root (per-instrument)
+```
+
+Navigation inside the submenu:
+
+- `←` / `→` / `↑` / `↓` all step the focused row (wrapping)
+- `Enter` on a non-toggle row enters its workflow (sets `st.edit_action`)
+- `Enter` on `chromatic` toggles it
+
+## Edit Actions
+
+Each edit action sets `st.edit_action` and hijacks key handling until `Escape` backs out.
+
+### tune
+
+- `pitch_selected_note` tracks the currently selected note.
+- Play a key to select it (and preview its sound).
+- `Tab` toggles `st.tune_edit_param` between `"pitch"` and `"volume"`.
+- Arrows adjust whichever param is focused:
+  - pitch: `↑↓` ±1 semitone, `←→` ±10 cents
+  - volume: `↑↓` ±1 dB, `←→` ±0.5 dB (clamped to [-40, +12] dB)
+- Changes persist to `samples/<inst_id>/pitch_offsets.json` and `volume_offsets.json`.
+
+### trim
+
+- Play a key with an existing sample to select.
+- Step 0: adjust start (fine=0.1%, coarse=1%), `Enter` confirms.
+- Step 1: adjust end, `Enter` saves the slice.
+- `Escape` in step 1 returns to step 0; in step 0 deselects.
+
+### copy
+
+- Source: play any key on any instrument with an existing sample.
+- `Tab` / `Shift-Tab` while in copy switches the *active instrument* so you can paste to a different board.
+- Destination: play the target key. If it already has a sample, confirm with `Enter` or cancel with `Escape`.
+
+### split
+
+- Play a key with an existing sample to select.
+- Markers phase: cursor arrow keys + `Enter` to place markers; `Ctrl-A` advances to assign.
+- Assign phase: each note-on saves the current slice to that key and advances to the next.
+- `Escape` steps back (slice → prior slice → markers phase → deselect).
+
+### record
+
+- All note-ons start recording on that key (via `start_recording`).
+- All note-offs stop (via `stop_recording`).
+- Escape stops any in-flight recording and exits the action.
+
+### Chromatic (toggle)
+
+- Toggles `inst["chromatic_on"]`.
+- If the instrument has no `chromatic_root`, the next note-on with an existing sample sets the root and kicks off background pre-computation (`compute_chromatic_samples_async`).
+- When on, `_audio_for_note` in `midi.py` returns the pre-computed chromatic sample for the played note.
+
+## Audio Callback
+
+`audio_callback` runs on a real-time thread (sounddevice); it holds `voices_lock` for the entire block.
+
+Priority order:
+
+1. **trim preview** — if `st.edit_action == "trim"` and `trim_looping`, render trim loop only
+2. **split preview** — if `st.edit_action == "split"` and `split_looping`, render split loop only
+3. **sample voices + synth voices** — mixed together; synth voices exist when playing on Synth, sample voices for samplers
+4. **loop capture / playback / overdub** — loop_state machine
+5. **metronome** — always mixed when `metronome_enabled`
+
+### Voice-level audio reference
+
+Each entry in `st.sample_voices` stores its own `audio` buffer and `vol`, not just an instrument/note id. This means that if the user switches instruments mid-ring-out, notes already sounding finish with their original buffers and volumes — the switch only affects *new* note-ons. This is what makes "switch instrument mid-loop" safe.
+
+## Loop Overlay
+
+Global buffer (`st.loop_buffer`). Same state machine as before:
+
+- `idle → recording`: clears `loop_record_chunks`
+- `recording → playing`: concatenates chunks (quantizing to a bar boundary when the metronome is on), starts playback
+- `playing → overdub`: incoming mix summed into `loop_buffer` in real time
+- `overdub → playing`: increments `loop_layer_count`
+
+Triggered by `Space` (global, any focus) — advances the loop state machine. `Escape` on Loop focus clears. The loop submenu (Enter on loop focus) lets you select a specific state or toggle the metronome; while metro is on and row 4 is focused, arrows adjust BPM. Because the loop buffer is global and voice-level audio refs are independent, switching instruments mid-loop does not disturb audio already in the buffer; new overdubbed notes come out of the freshly selected instrument.
+
+## State Locking
+
+`st.voices_lock` is shared between:
+- `audio_callback` (audio thread) — holds lock for entire block
+- `midi_callback` (MIDI thread) — holds lock briefly for voice mutations
+- `app.py` main loop — holds lock for loop transitions, some edit-action resets
+
+All mutations to `voices`, `sample_voices`, `loop_buffer`, `loop_state`, and related fields must happen under this lock.
+
+## Persistence
+
+| Data | Location |
+|------|----------|
+| Samples | `samples/<inst_id>/note_<midi>.wav` (16-bit mono, 48kHz) |
+| Pitch offsets | `samples/<inst_id>/pitch_offsets.json` |
+| Volume offsets | `samples/<inst_id>/volume_offsets.json` |
+| Config (devices, synesthesia, volume, instruments, current instrument, per-instrument chromatic state) | `config.json` |
+
+Legacy `samples/note_*.wav` (pre-redesign) are migrated to `samples/sampler-a/` on first boot.
+

{midi_cli-0.3.0 → midi_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: midi-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: A MIDI sampler and looper in your terminal
 Project-URL: Homepage, https://github.com/mnbpdx/midi-cli
 Project-URL: Repository, https://github.com/mnbpdx/midi-cli