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

{midi_cli-0.1.3 → midi_cli-0.3.0}/.gitignore

@@ -8,3 +8,4 @@ build/
 samples/
 samples-*/
 config.json
+.claude/settings.local.json

midi_cli-0.3.0/ARCHITECTURE.md

@@ -0,0 +1,149 @@
+# Architecture
+
+Developer reference for midi-cli: modes, key behavior, and app flow.
+
+## Module Overview
+
+| File | Responsibility |
+|------|---------------|
+| `app.py` | Entry point, main loop, raw key input, mode switching |
+| `state.py` | All global state and constants (single source of truth) |
+| `audio.py` | `sd.OutputStream` callback; synth rendering, sample playback, loop mixing, metronome |
+| `midi.py` | MIDI input callback; keyboard mock input (`trigger_keyboard_note`) |
+| `sampler.py` | Sample I/O (load/save WAV), pitch shifting, chromatic pre-computation, split/copy |
+| `loop.py` | Loop state machine transitions (`cycle_loop_state`) |
+| `ui.py` | Terminal rendering (`draw_ui`); trim/copy/split state resets |
+| `config.py` | Config file load/save, device enumeration |
+
+## Startup Flow
+
+1. `load_defaults()` reads saved config (devices, MIDI port, synesthesia)
+2. MIDI input opened; if unavailable, falls back to keyboard mock mode
+3. `load_samples()` reads `samples/note_*.wav` into `state.samples`
+4. `load_pitch_offsets()` reads `samples/pitch_offsets.json`
+5. `sd.OutputStream` started (runs `audio_callback` on a background thread)
+6. Terminal set to raw mode, alternate screen entered
+7. Main loop: `draw_ui()` → `select()` with 50ms timeout → handle key
+
+## Modes
+
+Modes are stored in `state.mode`. The ordered list is defined in `state.MODES`:
+
+```
+synth → sample → pitch → chromatic → trim → copy → loop → split
+```
+
+- **Tab** advances to the next mode (wraps)
+- **Shift+Tab** goes to the previous mode
+- Switching away from `trim`, `copy`, `split`, or `loop` resets that mode's transient state
+- **`r`** is a global key toggle (arm/disarm recording) — not a mode
+- **`c`** opens the config overlay — not a mode
+
+### synth
+Polyphonic additive synth (5 harmonics, piano-like two-stage decay).  
+Note on → voice added to `state.voices`. Note off → voice set to `releasing`.  
+Sustain pedal (CC 64) holds notes until pedal release.
+
+### sample
+Plays back recorded samples. Note on → sample voice added to `state.sample_voices`, plays from position 0.  
+Note off → voice set to `releasing` (5ms fade out). Sample plays to its natural end before being removed.
+
+### Record armed (`r` key)
+`record_armed` is a boolean flag in state, not a mode. Press **r** to arm (yellow ARM indicator appears); press **r** again to disarm.  
+While armed: note on → `start_recording()`, note off → `stop_recording()`.  
+In keyboard mock mode: key press toggles recording on/off per-note via `keyboard_recording_notes`.  
+Tabbing away while armed automatically disarms and stops any active recording.  
+In chromatic mode, **r** means "reselect root" — it does not arm recording.
+
+### pitch
+Note on → plays the sample and sets `pitch_selected_note`.  
+Arrow keys adjust pitch offset for the selected note (Up/Down: ±1 semitone, Left/Right: ±10 cents).  
+Changes saved to `samples/pitch_offsets.json` and recomputed asynchronously via pyrubberband.
+
+### chromatic
+One sample is pitch-shifted across a two-octave range (±12 semitones from root) and pre-computed in a background thread into `state.chromatic_samples`.  
+On entry: if no root is set, enters "selecting" sub-state — next note-on with a sample sets the root and triggers pre-computation.  
+Press **r** to re-select root.
+
+### trim
+Note on (with an existing sample) → selects that note, begins loop preview of full sample.  
+Two-step workflow:
+1. **Step 0** — adjust start point with arrow keys (fine: 0.1%, coarse: 1%), **Enter** to confirm
+2. **Step 1** — adjust end point with arrow keys, **Enter** to save the trimmed slice
+
+**Escape** in step 1 goes back to step 0. **Escape** in step 0 deselects.
+
+### copy
+Two-step note selection:
+1. Note on → sets `copy_source_note` (must have a sample)
+2. Note on → sets `copy_dest_note`; if dest already has a sample, prompts for confirmation (**Enter** to confirm, **Escape** to cancel)
+
+### loop
+Loop state machine: `idle → recording → playing → overdub → playing → ...`  
+Triggered by **l** key.  
+Sample voices (from note-on) are mixed into the loop buffer during recording and overdub.  
+**Escape** resets to idle.
+
+State transitions (`loop.py:cycle_loop_state`):
+- `idle` → `recording`: clears buffer, starts accumulating audio blocks
+- `recording` → `playing`: concatenates chunks into `loop_buffer`, starts playback
+- `playing` → `overdub`: incoming audio mixed (summed) into `loop_buffer` in real time
+- `overdub` → `playing`: increments `loop_layer_count`, returns to playback
+
+### split
+Splits one sample into multiple slices and assigns each to a MIDI note.  
+Two phases:
+- **markers**: select a source note, use arrow keys to position cursor, **Enter** to place a marker. **a** advances to assign phase.
+- **assign**: each note-on saves the current slice to that key and advances to the next. **Escape** steps back one slice (or back to markers phase).
+
+### Config overlay (`c` key)
+Press **c** from any mode to open the config overlay (rendered in the waveform area). All keys except **q** are swallowed while the overlay is open.  
+Up/Down navigates fields. Left/Right changes values. Fields: input device, output device, MIDI port, synesthesia toggle. Changes saved immediately on each arrow press.  
+Press **c** or **Escape** to close the overlay. Focus always resets to field 0 on open.
+
+## Audio Callback
+
+`audio_callback` runs on a real-time background thread (called by sounddevice). It holds `voices_lock` for the entire block.
+
+Priority order inside the callback:
+1. **trim** loop preview (if `trim_looping`)
+2. **split** loop preview (if `split_looping`)
+3. **loop** mode — sample voices + loop buffer capture/playback/overdub
+4. **sample / pitch / chromatic** — sample voice playback
+5. **synth** — additive synthesis
+
+Metronome is mixed in at the end of blocks 3–5 when `metronome_enabled` and the current mode is in `METRONOME_MODES`.
+
+## Key Behaviors
+
+### Note release
+| Input source | Synth mode | Sample/pitch/chromatic modes |
+|---|---|---|
+| MIDI note-off | Triggers fade-out (`releasing=True`) | Triggers fade-out |
+| Keyboard mock | Auto note-off after 250ms (`KEYBOARD_NOTE_RELEASE_S`) | No auto note-off — sample plays to end |
+
+### Sustain pedal (CC 64)
+- In **synth**: holds notes; releasing pedal fades all held notes
+- Other modes: ignored
+
+### Metronome
+- **m** key toggles on/off in modes: `synth`, `sample`, `loop`, `chromatic`
+- Arrow keys adjust BPM (±1 / ±5) when metronome is on and no mode-specific arrow binding takes priority
+- BPM range: 20–300
+
+## State Locking
+
+`state.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 state transitions and some mode resets
+
+All mutations to `voices`, `sample_voices`, `loop_buffer`, `loop_state`, and related fields must happen under this lock.
+
+## Persistence
+
+| Data | Location |
+|------|----------|
+| Samples | `samples/note_<midi>.wav` (16-bit mono, 48kHz) |
+| Pitch offsets | `samples/pitch_offsets.json` |
+| Config (devices, synesthesia) | `~/.config/midi_cli/config.json` |

midi_cli-0.3.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# midi-cli
+
+See [ARCHITECTURE.md](ARCHITECTURE.md) for a full developer reference: modes, key behaviors, app flow, state locking, and persistence.
+
+When making changes that affect modes, key bindings, audio behavior, state, or persistence, update ARCHITECTURE.md to reflect the new behavior.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: midi-cli
-Version: 0.1.3
+Version: 0.3.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

{midi_cli-0.1.3 → midi_cli-0.3.0}/midi_cli/app.py

@@ -11,9 +11,35 @@ import midi_cli.state as st
 from midi_cli.audio import audio_callback
 from midi_cli.sampler import load_samples, load_pitch_offsets, save_sample, adjust_pitch, compute_chromatic_samples_async, execute_copy, stop_recording
 from midi_cli.midi import open_midi_input, trigger_keyboard_note, midi_callback
-from midi_cli.ui import draw_ui, reset_trim_state, reset_copy_state, reset_split_state
+from midi_cli.ui import draw_ui, reset_trim_state, reset_copy_state
 from midi_cli.loop import reset_loop_state, cycle_loop_state
 
+def _read_escape_seq(fd):
+    seq = [os.read(fd, 1).decode("utf-8", errors="replace")]
+    if seq[0] == 'O':
+        r, _, _ = select.select([fd], [], [], 0.02)
+        if r:
+            seq.append(os.read(fd, 1).decode("utf-8", errors="replace"))
+    elif seq[0] == '[':
+        while True:
+            r, _, _ = select.select([fd], [], [], 0.02)
+            if not r:
+                break
+            b = os.read(fd, 1).decode("utf-8", errors="replace")
+            seq.append(b)
+            if b.isalpha() or b == '~':
+                break
+            if len(seq) > 16:
+                break
+    return "".join(seq)
+
+
+def _stop_active_voices():
+    """Clear all active voices on mode switch."""
+    with st.voices_lock:
+        st.sample_voices.clear()
+        st.voices.clear()
+
 
 def main():
     from midi_cli.config import load_defaults, get_input_devices, get_output_devices, get_midi_ports, save_config
@@ -60,16 +86,90 @@ def main():
                 ch = os.read(fd, 1).decode("utf-8", errors="replace")
                 if ch in ("q", "\x03"):  # q or Ctrl+C
                     break
+                elif st.config_overlay_open:
+                    if ch == "c":
+                        st.config_overlay_open = False
+                    elif ch == "\x1b":
+                        esc_ready, _, _ = select.select([fd], [], [], 0.02)
+                        if not esc_ready:
+                            st.config_overlay_open = False
+                        else:
+                            seq = _read_escape_seq(fd)
+                            if seq == "[Z":  # Shift+Tab: ignore while overlay open
+                                pass
+                            elif seq == "[A":  # Up: previous field
+                                st.config_focused_field = (st.config_focused_field - 1) % 4
+                            elif seq == "[B":  # Down: next field
+                                st.config_focused_field = (st.config_focused_field + 1) % 4
+                            elif seq in ("[C", "[D"):  # Right/Left: change value
+                                direction = 1 if seq == "[C" else -1
+                                field = st.config_focused_field
+                                if field == 3:  # Synesthesia toggle
+                                    st.synesthesia_enabled = not st.synesthesia_enabled
+                                elif field == 0:  # Input device
+                                    devices = get_input_devices()
+                                    if devices:
+                                        cur = st.input_device
+                                        idx = devices.index(cur) if cur in devices else 0
+                                        st.input_device = devices[(idx + direction) % len(devices)]
+                                elif field == 1:  # Output device
+                                    devices = get_output_devices()
+                                    if devices:
+                                        cur = st.output_device
+                                        idx = devices.index(cur) if cur in devices else 0
+                                        new_device = devices[(idx + direction) % len(devices)]
+                                        stream.stop()
+                                        stream.close()
+                                        st.output_device = new_device
+                                        stream = sd.OutputStream(
+                                            samplerate=st.SAMPLE_RATE,
+                                            blocksize=st.BLOCK_SIZE,
+                                            channels=1,
+                                            callback=audio_callback,
+                                            device=st.output_device,
+                                        )
+                                        stream.start()
+                                elif field == 2:  # MIDI port
+                                    ports = get_midi_ports()
+                                    options = [None] + ports
+                                    cur = st.midi_port
+                                    idx = options.index(cur) if cur in options else 0
+                                    new_port = options[(idx + direction) % len(options)]
+                                    if midi_in is not None:
+                                        midi_in.close_port()
+                                        midi_in.delete()
+                                        midi_in = None
+                                    st.midi_port = new_port
+                                    if new_port is None:
+                                        st.keyboard_mock_mode = True
+                                        st.ui_midi_port = ""
+                                    else:
+                                        midi_in, port_name = open_midi_input(new_port)
+                                        if midi_in is None:
+                                            st.keyboard_mock_mode = True
+                                            st.ui_midi_port = ""
+                                        else:
+                                            st.keyboard_mock_mode = False
+                                            st.ui_midi_port = port_name
+                                save_config({
+                                    "input_device": st.input_device,
+                                    "output_device": st.output_device,
+                                    "midi_port": st.midi_port,
+                                    "synesthesia_enabled": st.synesthesia_enabled,
+                                })
+                    # all other keys are silently swallowed by the overlay
                 elif ch == "\r" and st.mode == "split" and st.split_selected_note is not None and st.split_phase == "markers":
-                    st.split_markers.append(st.split_cursor_pos)
-                    st.split_markers.sort()
-                    # Restart loop from start of new region (last marker → end)
-                    st.split_loop_pos = 0
+                    with st.voices_lock:
+                        st.split_markers.append(st.split_cursor_pos)
+                        st.split_markers.sort()
+                        # Restart loop from start of new region (last marker → end)
+                        st.split_loop_pos = 0
                 elif ch == "\r" and st.mode == "trim" and st.trim_selected_note is not None:
                     if st.trim_step == 0:
                         # Confirm start, advance to end adjustment
                         st.trim_step = 1
-                        st.trim_loop_pos = st.trim_start
+                        with st.voices_lock:
+                            st.trim_loop_pos = st.trim_start
                     else:
                         # Confirm end, slice and save
                         audio = st.samples[st.trim_selected_note][st.trim_start:st.trim_end]
@@ -82,7 +182,8 @@ def main():
                 elif ch == "\r" and st.mode == "copy" and st.copy_confirm_pending:
                     execute_copy()
                 elif ch == "\t":  # Tab: next mode
-                    if st.mode == "record":
+                    if st.record_armed:
+                        st.record_armed = False
                         st.keyboard_recording_notes.clear()
                         if st.recording_note is not None:
                             threading.Thread(target=stop_recording, args=(st.recording_note,), daemon=True).start()
@@ -91,15 +192,27 @@ def main():
                     if st.mode == "copy":
                         reset_copy_state()
                     if st.mode == "split":
-                        reset_split_state()
+                        st.reset_split_state()
                     if st.mode == "loop":
                         with st.voices_lock:
                             reset_loop_state()
+                    _stop_active_voices()
                     st.mode = st.MODES[(st.MODES.index(st.mode) + 1) % len(st.MODES)]
                     if st.mode == "chromatic":
                         st.chromatic_selecting = st.chromatic_root_note is None
                 elif ch == "r" and st.mode == "chromatic" and not st.chromatic_selecting:
                     st.chromatic_selecting = True
+                elif ch == "r" and st.mode == "sample":
+                    if st.record_armed:
+                        st.record_armed = False
+                        st.keyboard_recording_notes.clear()
+                        if st.recording_note is not None:
+                            threading.Thread(target=stop_recording, args=(st.recording_note,), daemon=True).start()
+                    else:
+                        st.record_armed = True
+                elif ch == "c":
+                    st.config_overlay_open = True
+                    st.config_focused_field = 0
                 elif ch == "\x1b":  # escape sequence
                     # Use select on fd with timeout to distinguish bare Escape from sequences
                     esc_ready, _, _ = select.select([fd], [], [], 0.02)
@@ -108,7 +221,8 @@ def main():
                         if st.mode == "trim" and st.trim_selected_note is not None:
                             if st.trim_step == 1:
                                 st.trim_step = 0
-                                st.trim_loop_pos = st.trim_start
+                                with st.voices_lock:
+                                    st.trim_loop_pos = st.trim_start
                             else:
                                 reset_trim_state()
                         elif st.mode == "copy" and (st.copy_source_note is not None or st.copy_confirm_pending):
@@ -120,20 +234,28 @@ def main():
                             if st.split_phase == "assign":
                                 if st.split_current_slice > 0:
                                     st.split_current_slice -= 1
-                                    st.split_loop_pos = 0
+                                    with st.voices_lock:
+                                        st.split_loop_pos = 0
                                 else:
                                     st.split_phase = "markers"
-                                    st.split_looping = False
+                                    with st.voices_lock:
+                                        st.split_looping = False
                             else:
                                 # markers phase
                                 if st.split_markers:
-                                    st.split_markers.pop()
+                                    with st.voices_lock:
+                                        st.split_markers.pop()
                                 else:
                                     st.split_selected_note = None
                     else:
-                        seq = os.read(fd, 2).decode("utf-8", errors="replace")
+                        # Read a complete VT escape sequence. F5-F10 send CSI
+                        # sequences like \x1b[15~ (5 bytes); reading only 2
+                        # bytes would leak digits into the next iteration and
+                        # trigger unintended notes via KEYBOARD_NOTE_MAP.
+                        seq = _read_escape_seq(fd)
                         if seq == "[Z":  # Shift+Tab: previous mode
-                            if st.mode == "record":
+                            if st.record_armed:
+                                st.record_armed = False
                                 st.keyboard_recording_notes.clear()
                                 if st.recording_note is not None:
                                     threading.Thread(target=stop_recording, args=(st.recording_note,), daemon=True).start()
@@ -142,10 +264,11 @@ def main():
                             if st.mode == "copy":
                                 reset_copy_state()
                             if st.mode == "split":
-                                reset_split_state()
+                                st.reset_split_state()
                             if st.mode == "loop":
                                 with st.voices_lock:
                                     reset_loop_state()
+                            _stop_active_voices()
                             st.mode = st.MODES[(st.MODES.index(st.mode) - 1) % len(st.MODES)]
                             if st.mode == "chromatic":
                                 st.chromatic_selecting = st.chromatic_root_note is None
@@ -194,75 +317,28 @@ def main():
                                 st.split_cursor_pos = min(sample_len - 1, st.split_cursor_pos + coarse)
                             elif seq == "[B":  # Down: move cursor back coarse
                                 st.split_cursor_pos = max(0, st.split_cursor_pos - coarse)
-                        elif st.mode == "config":
-                            if seq == "[A":  # Up: previous field
-                                st.config_focused_field = (st.config_focused_field - 1) % 4
-                            elif seq == "[B":  # Down: next field
-                                st.config_focused_field = (st.config_focused_field + 1) % 4
-                            elif seq in ("[C", "[D"):  # Right/Left: change value
-                                direction = 1 if seq == "[C" else -1
-                                field = st.config_focused_field
-                                if field == 3:  # Synesthesia toggle
-                                    st.synesthesia_enabled = not st.synesthesia_enabled
-                                elif field == 0:  # Input device
-                                    devices = get_input_devices()
-                                    if devices:
-                                        cur = st.input_device
-                                        idx = devices.index(cur) if cur in devices else 0
-                                        st.input_device = devices[(idx + direction) % len(devices)]
-                                elif field == 1:  # Output device
-                                    devices = get_output_devices()
-                                    if devices:
-                                        cur = st.output_device
-                                        idx = devices.index(cur) if cur in devices else 0
-                                        new_device = devices[(idx + direction) % len(devices)]
-                                        stream.stop()
-                                        stream.close()
-                                        st.output_device = new_device
-                                        stream = sd.OutputStream(
-                                            samplerate=st.SAMPLE_RATE,
-                                            blocksize=st.BLOCK_SIZE,
-                                            channels=1,
-                                            callback=audio_callback,
-                                            device=st.output_device,
-                                        )
-                                        stream.start()
-                                elif field == 2:  # MIDI port
-                                    ports = get_midi_ports()
-                                    options = [None] + ports
-                                    cur = st.midi_port
-                                    idx = options.index(cur) if cur in options else 0
-                                    new_port = options[(idx + direction) % len(options)]
-                                    if midi_in is not None:
-                                        midi_in.close_port()
-                                        midi_in.delete()
-                                        midi_in = None
-                                    st.midi_port = new_port
-                                    if new_port is None:
-                                        st.keyboard_mock_mode = True
-                                        st.ui_midi_port = ""
-                                    else:
-                                        midi_in, port_name = open_midi_input(new_port)
-                                        if midi_in is None:
-                                            st.keyboard_mock_mode = True
-                                            st.ui_midi_port = ""
-                                        else:
-                                            st.keyboard_mock_mode = False
-                                            st.ui_midi_port = port_name
-                                save_config({
-                                    "input_device": st.input_device,
-                                    "output_device": st.output_device,
-                                    "midi_port": st.midi_port,
-                                    "synesthesia_enabled": st.synesthesia_enabled,
-                                })
+                        elif st.metronome_enabled and st.mode in st.METRONOME_MODES:
+                            if seq == "[C":    # Right: +1 BPM
+                                st.bpm = min(st.BPM_MAX, st.bpm + 1)
+                            elif seq == "[D":  # Left: -1 BPM
+                                st.bpm = max(st.BPM_MIN, st.bpm - 1)
+                            elif seq == "[A":  # Up: +5 BPM
+                                st.bpm = min(st.BPM_MAX, st.bpm + 5)
+                            elif seq == "[B":  # Down: -5 BPM
+                                st.bpm = max(st.BPM_MIN, st.bpm - 5)
                 elif ch == 'a' and st.mode == "split" and st.split_selected_note is not None and st.split_phase == "markers" and st.split_markers:
                     st.split_phase = "assign"
                     st.split_current_slice = 0
-                    st.split_loop_pos = 0
-                    st.split_looping = True
+                    with st.voices_lock:
+                        st.split_loop_pos = 0
+                        st.split_looping = True
                 elif ch == 'l' and st.mode == "loop":
                     with st.voices_lock:
                         cycle_loop_state()
+                elif ch == 'm' and st.mode in st.METRONOME_MODES:
+                    with st.voices_lock:
+                        st.metronome_enabled = not st.metronome_enabled
+                        st.metronome_pos = 0
                 elif st.keyboard_mock_mode and ch in st.KEYBOARD_NOTE_MAP:
                     trigger_keyboard_note(st.KEYBOARD_NOTE_MAP[ch])
                 elif st.keyboard_mock_mode and ch == '`':