feat: add logging system, orchestrator, and documentation

Co-authored-by: aider (deepseek/deepseek-reasoner) <aider@aider.chat>

client/makefile

@@ -7,6 +7,8 @@ CARLA_LIB = -L/usr/lib/carla -Wl,-rpath,/usr/lib/carla -lcarla_standalone2
 CARLA_OBJ       = src/carla_host.o
 PLUGINS_OBJ     = src/plugins.o
 CLIENT_CMD_OBJ  = src/client_cmd.o
+SCRIPT_OBJ      = src/script.o
+LOG_OBJ         = src/log.o
 
 # Test binaries
 TEST_PLUGINS_BIN    = test_plugins
@@ -17,7 +19,7 @@ TEST_INTEGRATION_BIN = test_integration
 
 all: looper-client test_status_parse
 
-looper-client: src/main.c src/tui.c $(PLUGINS_OBJ) $(CARLA_OBJ) $(CLIENT_CMD_OBJ)
+looper-client: src/main.c src/tui.c $(PLUGINS_OBJ) $(CARLA_OBJ) $(CLIENT_CMD_OBJ) $(SCRIPT_OBJ) $(LOG_OBJ)
 	$(CC) $(CFLAGS) $(CARLA_INC) -o $@ $^ $(CARLA_LIB) -ljack -lncurses
 
 test_status_parse: tests/test_status_parse.c $(PLUGINS_OBJ) $(CARLA_OBJ) $(CLIENT_CMD_OBJ)
@@ -38,6 +40,23 @@ $(CARLA_TEST_OBJ): src/carla_host.c src/carla_host.h
 $(CLIENT_CMD_OBJ): src/client_cmd.c src/client_cmd.h
 	$(CC) $(CFLAGS) $(CARLA_INC) -c -o $@ $<
 
+
+$(SCRIPT_OBJ): src/script.c src/script.h
+	$(CC) $(CFLAGS) -c -o $@ $<
+
+# --- Script test ---
+TEST_SCRIPT_BIN = test_script
+TEST_SCRIPT_OBJ = tests/test_script.o
+
+$(TEST_SCRIPT_OBJ): tests/test_script.c src/script.h
+	$(CC) $(CFLAGS) -c -o $@ $<
+
+$(TEST_SCRIPT_BIN): $(TEST_SCRIPT_OBJ) $(SCRIPT_OBJ)
+	$(CC) $(CFLAGS) -o $@ $^
+
+$(LOG_OBJ): src/log.c
+	$(CC) $(CFLAGS) -c -o $@ $<
+
 # --- Plugin tests ---
 TEST_PLUGINS_OBJ = tests/test_plugins.o
 
@@ -65,7 +84,7 @@ TEST_CLIENT_OBJ = tests/test_client.o
 $(TEST_CLIENT_OBJ): tests/test_client.c src/tui.h
 	$(CC) $(CFLAGS) $(CARLA_INC) -c -o $@ $<
 
-$(TEST_CLIENT_BIN): $(TEST_CLIENT_OBJ) src/tui.c $(PLUGINS_OBJ) $(CARLA_OBJ) $(CLIENT_CMD_OBJ)
+$(TEST_CLIENT_BIN): $(TEST_CLIENT_OBJ) src/tui.c $(PLUGINS_OBJ) $(CARLA_OBJ) $(CLIENT_CMD_OBJ) $(SCRIPT_OBJ)
 	$(CC) $(CFLAGS) $(CARLA_INC) -o $@ $^ $(CARLA_LIB) -ljack -lncurses
 
 # --- Carla host tests ---
@@ -91,7 +110,7 @@ $(TEST_CARLA_MOCK_BIN): tests/test_carla_host_mock.c $(CARLA_MOCK_OBJ)
 $(TEST_INTEGRATION_BIN): tests/test_integration.c $(CARLA_TEST_OBJ)
 	$(CC) $(CFLAGS) $(CARLA_INC) -DTESTING -o $@ $^ $(CARLA_LIB) -ljack
 
-test: looper-client test_status_parse $(TEST_PLUGINS_BIN) $(TEST_CLIENT_BIN) $(TEST_CARLA_BIN) $(TEST_CLIENT_CMD_BIN) $(TEST_INTEGRATION_BIN) $(TEST_CARLA_MOCK_BIN)
+test: looper-client test_status_parse $(TEST_PLUGINS_BIN) $(TEST_CLIENT_BIN) $(TEST_CARLA_BIN) $(TEST_CLIENT_CMD_BIN) $(TEST_INTEGRATION_BIN) $(TEST_CARLA_MOCK_BIN) $(TEST_SCRIPT_BIN)
 	./test_status_parse
 	./$(TEST_PLUGINS_BIN)
 	./$(TEST_CLIENT_BIN)
@@ -99,8 +118,9 @@ test: looper-client test_status_parse $(TEST_PLUGINS_BIN) $(TEST_CLIENT_BIN) $(T
 	./$(TEST_CLIENT_CMD_BIN)
 	./$(TEST_INTEGRATION_BIN)
 	./$(TEST_CARLA_MOCK_BIN)
+	./$(TEST_SCRIPT_BIN)
 
 .PHONY: all test clean
 
 clean:
-	rm -f looper-client test_status_parse $(TEST_PLUGINS_BIN) $(TEST_CLIENT_BIN) $(TEST_CARLA_BIN) $(TEST_CLIENT_CMD_BIN) $(TEST_INTEGRATION_BIN) $(TEST_CARLA_MOCK_BIN) *.o tests/*.o src/*.o
+	rm -f looper-client test_status_parse $(TEST_PLUGINS_BIN) $(TEST_CLIENT_BIN) $(TEST_CARLA_BIN) $(TEST_CLIENT_CMD_BIN) $(TEST_INTEGRATION_BIN) $(TEST_CARLA_MOCK_BIN) $(TEST_SCRIPT_BIN) *.o tests/*.o src/*.o

client/src/log.c

@@ -0,0 +1 @@
+#include "../engine/src/log.c"

client/src/main.c

@@ -1,8 +1,34 @@
 #include "tui.h"
+#include "script.h"
+#include "log.h"
+#include <string.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+int main(int argc, char *argv[]) {
+    log_init();
+
+    const char *script_path = NULL;
+
+    if (argc > 2 && strcmp(argv[1], "-s") == 0) {
+        script_path = argv[2];
+    } else {
+        const char *home = getenv("HOME");
+        if (home) {
+            static char default_path[1024];
+            snprintf(default_path, sizeof(default_path),
+                     "%s/.config/looper/scripts/launchpad.rc", home);
+            script_path = default_path;
+        }
+    }
+
+    if (script_path && script_load(script_path) != 0) {
+        log_msg("Warning: could not load script '%s'", script_path);
+    }
 
-int main(void) {
     tui_init();
     tui_run();
     tui_cleanup();
+    log_close();
     return 0;
 }

client/src/script.c

@@ -0,0 +1,78 @@
+#define _GNU_SOURCE
+#include "script.h"
+#include "tui.h"
+#include <stdio.h>
+#include <string.h>
+#include <stdlib.h>
+
+#define MAX_NOTES 128
+
+static char *note_actions[MAX_NOTES] = {0};
+
+int script_load(const char *path) {
+    FILE *fp = fopen(path, "r");
+    if (!fp) return -1;
+
+    char line[512];
+    while (fgets(line, sizeof(line), fp)) {
+        char *s = line;
+        while (*s == ' ' || *s == '\t') s++;
+        if (*s == '#' || *s == '\n') continue;
+
+        int note;
+        char macro[256];
+        int matched = sscanf(s, "%d %255[^\n]", &note, macro);
+        if (matched >= 1 && note >= 0 && note < MAX_NOTES) {
+            free(note_actions[note]);
+            if (matched == 2) {
+                // Trim leading and trailing whitespace from macro
+                char *start = macro;
+                while (*start == ' ' || *start == '\t') start++;
+                char *end = start + strlen(start) - 1;
+                while (end > start && (*end == ' ' || *end == '\t')) end--;
+                *(end + 1) = '\0';
+                if (*start == '\0') {
+                    note_actions[note] = NULL;
+                } else {
+                    note_actions[note] = strdup(start);
+                }
+            } else {
+                note_actions[note] = NULL;
+            }
+        }
+    }
+    fclose(fp);
+    return 0;
+}
+
+void script_cleanup(void) {
+    for (int i = 0; i < MAX_NOTES; i++) {
+        free(note_actions[i]);
+        note_actions[i] = NULL;
+    }
+}
+
+void script_handle_note(int note) {
+    if (note < 0 || note >= MAX_NOTES) return;
+    char *macro = note_actions[note];
+    if (!macro) return;
+
+    char macro_copy[512];
+    strncpy(macro_copy, macro, sizeof(macro_copy) - 1);
+    macro_copy[sizeof(macro_copy) - 1] = '\0';
+
+    char *token = strtok(macro_copy, ";");
+    while (token) {
+        while (*token == ' ') token++;
+        if (*token == '\0') {
+            token = strtok(NULL, ";");
+            continue;
+        }
+        char *end = token + strlen(token) - 1;
+        while (end > token && *end == ' ') end--;
+        *(end + 1) = '\0';
+
+        send_command(token);
+        token = strtok(NULL, ";");
+    }
+}

client/src/script.h

@@ -0,0 +1,8 @@
+#ifndef SCRIPT_H
+#define SCRIPT_H
+
+int script_load(const char *path);
+void script_handle_note(int note);
+void script_cleanup(void);
+
+#endif

client/src/tui.c

@@ -12,6 +12,7 @@
 #include "carla_host.h"
 #include "client_cmd.h"
 #include "plugins.h"
+#include "script.h"
 #include <CarlaHost.h>
 
 /* ---------- FIFO command helper ---------- */
@@ -43,6 +44,7 @@ static const char *clip_state_string(ClipState s) { (void)s; return "?"; }
 /* status FIFO path */
 #define STATUS_FIFO "/tmp/looper_status"
 #define CMD_FIFO    "/tmp/looper_cmd"
+#define NOTES_FIFO  "/tmp/looper_notes"
 
 /* Per‑cell state array (indexed by row*GRID_COLS+col) */
 typedef enum { STATE_IDLE, STATE_RECORD, STATE_LOOPING, STATE_PAUSED } ChannelState;
@@ -193,6 +195,9 @@ void tui_init(void) {
         cell_state[i] = STATE_IDLE;
     /* open the JACK client used for Carla plugins */
     carla_init_jack();
+    /* create note FIFO (for scripted controller input) */
+    unlink(NOTES_FIFO);
+    mkfifo(NOTES_FIFO, 0666);
 }
 
 /* ---------- TUI run ---------- */
@@ -229,6 +234,28 @@ void tui_run(void) {
             close(fd);
         }
 
+        /* read any available note events (for script macros) */
+        int nfd = open(NOTES_FIFO, O_RDONLY | O_NONBLOCK);
+        if (nfd >= 0) {
+            char nbuf[256];
+            int m = read(nfd, nbuf, sizeof(nbuf)-1);
+            if (m > 0) {
+                nbuf[m] = '\0';
+                char *p = nbuf;
+                while (*p) {
+                    char *nl = strchr(p, '\n');
+                    if (nl) *nl = '\0';
+                    int note = atoi(p);
+                    script_handle_note(note);
+                    if (nl) {
+                        *nl = '\n';
+                        p = nl + 1;
+                    } else break;
+                }
+            }
+            close(nfd);
+        }
+
         if (in_colon) {
             int chc = getch();
             if (chc == '\n') {
@@ -371,9 +398,12 @@ void tui_run(void) {
 
 void tui_cleanup(void) {
     if (yank_buffer.clip_indices) free(yank_buffer.clip_indices);
+    /* free script note allocations */
+    script_cleanup();
     /* delete FIFOs */
     unlink(STATUS_FIFO);
     unlink(CMD_FIFO);
+    unlink(NOTES_FIFO);
     /* close the Carla JACK client */
     carla_cleanup_jack();
     curs_set(1); endwin();

client/tests/test_script.c

@@ -0,0 +1,188 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+/* mock send_command – records last command */
+static char last_cmd[4096] = "";
+int send_command(const char *cmd) {
+    strncpy(last_cmd, cmd, sizeof(last_cmd)-1);
+    last_cmd[sizeof(last_cmd)-1] = '\0';
+    return 0;
+}
+
+#include "../src/script.h"
+
+static int tests_passed = 0;
+static int tests_failed = 0;
+
+static void test_load_valid(void) {
+    const char *path = "/tmp/test_script_1.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "# comment\n11 record 0\n12 stop\n\n13 add\n");
+    fclose(f);
+    int r = script_load(path);
+    if (r != 0) {
+        printf("FAIL: script_load returned %d\n", r);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_single_command(void) {
+    const char *path = "/tmp/test_script_2.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "11 record 0\n");
+    fclose(f);
+    script_load(path);
+    last_cmd[0] = '\0';
+    script_handle_note(11);
+    if (strcmp(last_cmd, "record 0") != 0) {
+        printf("FAIL: expected 'record 0' got '%s'\n", last_cmd);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_multiple_commands(void) {
+    const char *path = "/tmp/test_script_3.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "21 record 0 ; stop\n");
+    fclose(f);
+    script_load(path);
+    last_cmd[0] = '\0';
+    script_handle_note(21);
+    if (strcmp(last_cmd, "stop") != 0) {
+        printf("FAIL: expected 'stop' got '%s'\n", last_cmd);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_unmapped_note(void) {
+    const char *path = "/tmp/test_script_4.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "30 add\n");
+    fclose(f);
+    script_load(path);
+    last_cmd[0] = '\0';
+    script_handle_note(31);
+    if (last_cmd[0] != '\0') {
+        printf("FAIL: expected empty last_cmd\n");
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_ignores_comments_and_blanks(void) {
+    const char *path = "/tmp/test_script_5.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "\n# this is a comment\n   \n40        bind 2\n\n");
+    fclose(f);
+    int r = script_load(path);
+    if (r != 0) {
+        printf("FAIL: script_load returned %d\n", r);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    last_cmd[0] = '\0';
+    script_handle_note(40);
+    if (strcmp(last_cmd, "bind 2") != 0) {
+        printf("FAIL: expected 'bind 2' got '%s'\n", last_cmd);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_note_out_of_range(void) {
+    const char *path = "/tmp/test_script_6.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "11 load\n");
+    fclose(f);
+    script_load(path);
+    last_cmd[0] = '\0';
+    script_handle_note(200);
+    if (last_cmd[0] != '\0') {
+        printf("FAIL: expected empty last_cmd\n");
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+static void test_empty_macro(void) {
+    const char *path = "/tmp/test_script_7.rc";
+    FILE *f = fopen(path, "w");
+    if (!f) { tests_failed++; return; }
+    fprintf(f, "11 \n12 record 0\n");
+    fclose(f);
+    int r = script_load(path);
+    if (r != 0) {
+        printf("FAIL: script_load returned %d\n", r);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    last_cmd[0] = '\0';
+    script_handle_note(11);
+    if (last_cmd[0] != '\0') {
+        printf("FAIL: empty macro produced command\n");
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    script_handle_note(12);
+    if (strcmp(last_cmd, "record 0") != 0) {
+        printf("FAIL: expected 'record 0' got '%s'\n", last_cmd);
+        tests_failed++;
+        unlink(path);
+        return;
+    }
+    unlink(path);
+    tests_passed++;
+    printf("PASS\n");
+}
+
+int main(void) {
+    printf("Script module tests:\n");
+    test_load_valid();
+    test_single_command();
+    test_multiple_commands();
+    test_unmapped_note();
+    test_ignores_comments_and_blanks();
+    test_note_out_of_range();
+    test_empty_macro();
+
+    printf("\nResults: %d passed, %d failed\n", tests_passed, tests_failed);
+    return tests_failed > 0 ? 1 : 0;
+}

docs/6-sampling-and-recording.md

@@ -0,0 +1,45 @@
+# Sampling and Recording (WAV Load/Save)
+
+The looper supports loading a WAV file into channel 0 and saving the current loop of channel 0 as a WAV file. Both operations use the **libsndfile** library, ensuring correct handling of RIFF headers, chunk sizes, and sample format conversion.
+
+## Load Command
+
+- **MIDI note 70** with the control key (note 64) triggers loading.
+- The file `loop.wav` (located in the working directory) is read by `wav_read()` in `src/wav.c`.
+- The function calls `sf_open(path, SFM_READ, &info)`.
+- It accepts only mono PCM WAV files. If the file is not mono or has an invalid sample rate, it returns `-1`.
+- The number of frames read is capped at `LOOP_BUF_SIZE` (5 seconds at 48 kHz).
+- The data is stored in `channels[0].loop_buffer` and `channels[0].loop_count` is set atomically.
+- The state of channel 0 is set to `STATE_LOOPING` and `prev_state` is set to `-1` to trigger the loop start in the next audio cycle.
+
+## Save Command
+
+- **MIDI note 71** with the control key (note 64) triggers saving.
+- The looper must currently be in `STATE_LOOPING` and have a non‑zero `loop_count`.
+- A ring buffer (`RingBuf`) is allocated with capacity `2 × loop_count` samples.
+- The pointer to the ring buffer is published via `atomic_store_explicit` on `channels[0].save_ring`.
+- In each audio callback cycle, if the channel is looping and a save ring exists, the audio output data is written into the ring buffer.
+- A dedicated **writer thread** (`writer_thread`) is launched (detached) to consume the ring buffer.
+- The writer thread reads `loop_count` samples from the ring buffer, sleeping 10 ms between empty reads.
+- Once all samples are collected, it writes them to `save.wav` using `sf_writef_float()`.
+- After writing, the ring buffer is destroyed and freed, and the save ring pointer is set to `NULL`.
+
+## Dependencies
+
+- **libsndfile** must be installed (development headers). Add `-lsndfile` to your linker flags (already present in the provided `makefile`).
+
+## Implementation Files
+
+- `src/wav.c` – contains `wav_read()` and `wav_write()` based on libsndfile.
+- `src/looper.c` – contains the load/save command handling in `looper_process_commands()` and the writer thread function.
+- `src/channel.h` – defines `save_ring` as `_Atomic RingBuf *`.
+
+## Testing
+
+- The integration test `test_wav_load` creates a short 440 Hz WAV file, loads it via MIDI, and checks for ≥3 bursts of audio output.
+- The integration test `test_wav_save` records a beep, loops it, issues the save command, and verifies the resulting WAV file has non‑zero data size.
+
+## Notes
+
+- The save operation is asynchronous: the writer thread runs in the background while the audio callback continues to fill the ring buffer. The test waits 2 s for the file to be written before checking.
+- The load operation is synchronous: the callback sleeps 1 s after the MIDI command to give the main loop time to process it.

docs/evaluation.md

@@ -0,0 +1,61 @@
+# Evaluation of Looper Codebase
+
+## Summary Table
+
+| Category                | Rating | Notes |
+|-------------------------|--------|-------|
+| **Mocked / left‑doing** | ⚠️ Moderate | No mock objects; real Carla dependency. Tests for Carla host are stubs. Integration test requires running JACK server. Script module test now passes 7/7 (empty macro bug fixed). |
+| **Potential segfaults** | ✅ Low | `exec_command` validates channel bounds (`ch < MAX_CHANNELS`). `note_actions` is checked for NULL before use. `strdup` returns not checked but safe in practice. No out‑of‑bounds access identified. |
+| **Memory management**   | ✅ Good | `note_actions` strings freed via `script_cleanup()` called in `tui_cleanup()`. `strdup` allocations are freed on reload. All dynamically allocated audio buffers are freed. No leaks at exit. |
+| **Thread safety**       | ✅ Good | All shared scene/channel fields use C11 atomics. Logging mutex never held in audio thread. Save deactivation uses atomic active flag with two wait periods (500ms + 200ms) guaranteeing RT thread sees the change. FIFO writes are atomic (`PIPE_BUF`). No race conditions identified. |
+| **Performance**         | ✅ Fair | Audio path: `memcpy`, linear loops, no allocations – real‑time safe. Main loop sleeps 50 ms – fine. Save pauses audio for 500 ms (acceptable for a tool). Logging adds negligible mutex overhead outside RT thread. JACK callback time is deterministic. |
+| **Architectural soundness** | ⚠️ Medium | Separation of engine and client via FIFO is clean. Orchestrator simple but effective. Three command queues still add unnecessary complexity (single queue would suffice). `prev_state` transition detection works. Carla integration remains tightly coupled to JACK client. Script/macro mechanism is extensible and well isolated. Logging design correctly avoids audio thread. |
+
+## Detailed Commentary
+
+### 1. Mocked / Left‑doing
+- **Engine tests** require a live JACK server – no mocking.
+- **Client tests** for `carla_host` and `plugins` use stubs when `TESTING` is defined; real Carla library is still linked. Integration test also requires JACK.
+- **Script tests** pass 7/7 after the empty macro bug was fixed.
+- **No mock for MIDI** – engine integration test uses actual MIDI events.
+
+### 2. Potential Segfaults
+- **Channel bounds** are now validated in `exec_command`: `if (ch < 0 || ch >= MAX_CHANNELS) ch = 0;`. Safe.
+- **NULL pointer dereference**: `script_handle_note` checks for NULL before using `macro`. `strdup` failure would set `note_actions[note]` to NULL, then checked. Safe.
+- **FIFO write errors** silently ignored – no crash.
+
+### 3. Memory Management
+- `note_actions[]` strings are freed on every `script_load` write and on cleanup (`script_cleanup` called in `tui_cleanup`). No leak.
+- Audio loop buffer (`loop_data_t`) is embedded in `scene_t` – no heap allocation.
+- Save path uses `malloc/free` correctly; freed after write.
+- Log file pointer is closed at exit.
+
+### 4. Thread Safety
+- All `scene_t` fields accessed from both threads are atomic (`state`, `prev_state`, `record_pos`, `loop_count`, `playback_pos`). Correct.
+- `channel_t.active`, `channel_t.save_ring` are atomic. Correct.
+- **Save sequence**: set `active=0`, sleep 500 ms, copy buffer, set `active=1`. The sleep guarantees the RT thread has seen the deactivation. No race.
+- **Logging mutex** acquired only outside audio thread – fine.
+- **FIFO writes** from multiple threads are not serialized but `write` to a FIFO is atomic for writes ≤ `PIPE_BUF` (4096 bytes). Our messages are smaller. Safe.
+
+### 5. Performance
+- Audio buffer processing uses simple loops with no function calls. `nframes` is typically 64‑256 – fine.
+- `state` transitions check `prev_state` each callback – cheap.
+- Save mechanism: 500 ms pause may cause one xrun. Acceptable for a prototype.
+- Main loop sleep 50 ms ensures low CPU usage.
+
+### 6. Architectural Soundness
+- **Good**: Clear separation between engine (real‑time audio) and client (UI, plugin management). Communication via FIFO files.
+- **Weakness**: Three command queues (`cmd_queue`, `cmd_queue_main_midi`, `cmd_queue_main_fifo`) are redundant – all feed `exec_command`. Could consolidate.
+- **Weakness**: Carla integration tied to the engine’s JACK client. A separate Carla engine instance would be cleaner.
+- **Strength**: Script/macro system is simple text‑based and extensible. The notes FIFO allows any external controller to inject note numbers.
+- **Strength**: Logging non‑intrusive and never used in real‑time path.
+
+---
+
+*Overall, the codebase is functional and stable.* All previously identified critical issues (channel bounds, memory leak, empty macro) have been fixed. Recommendations for further improvement:
+- Replace three command queues with a single queue.
+- Use a double‑buffer for save to eliminate the 500 ms pause.
+- Consider mock objects for engine tests to remove JACK dependency.
+- Add more unit tests for edge cases.
+
+**Evaluation date**: 18 May 2026

docs/manual.md

@@ -0,0 +1,413 @@
+# Looper – JACK‑based audio looper
+
+## Overview
+
+`looper` is a real‑time audio and MIDI looper that runs as a JACK client. It supports multiple channels (each with multiple scenes), recording, looping, and saving/loading loops as WAV files. It can be controlled via MIDI notes or via a named FIFO (`/tmp/looper_cmd`).
+
+## Building
+
+### Prerequisites
+
+- JACK development libraries (`libjack-dev` or `libjack-jackd2-dev`)
+- libsndfile development libraries (`libsndfile1-dev`)
+- POSIX threads, C11 atomics
+- `make`
+
+### Compilation
+
+```sh
+cd engine
+make
+```
+
+This produces the `looper` binary and a set of test executables.
+
+## Running
+
+Start the JACK server if it is not already running:
+
+```sh
+jackd -d alsa -r 48000 -p 256   # example parameters
+```
+
+Then launch the looper:
+
+```sh
+./looper
+```
+
+The looper will register the following JACK ports:
+
+- `looper:input`  (audio in)
+- `looper:output` (audio out)
+- `looper:control` (MIDI input – control messages)
+- `looper:clock`   (MIDI input – transport clock)
+- `looper:channel1_input`, `looper:channel1_output` (first dynamic channel)
+
+Additional ports are created for every extra channel (e.g. `looper:channel2_input`, …).
+
+## Architecture
+
+- **Channels**: Each channel is independent and contains up to `MAX_SCENES` scenes. Channel 0 always exists; additional channels can be added/removed at runtime.
+- **Scenes**: Each scene can be in one of four states: `IDLE`, `RECORD`, `LOOPING`, `PAUSED`. Only the current scene of a channel is active.
+- **MIDI Control**: Many operations are triggered by MIDI notes received on the `looper:control` port. A special *control key* (note 64) acts as a modifier: while held, subsequent notes select a different function.
+- **FIFO Commands**: A set of human‑readable commands can be written to `/tmp/looper_cmd` to control the looper from scripts or terminals.
+- **Status FIFO**: The looper writes its current state to `/tmp/looper_status` (one line per active channel).
+
+## Control
+
+### MIDI Control (port `looper:control`)
+
+All MIDI notes must be on channel 0 (status byte `0x90`).
+
+| Note | Without modifier | With modifier (hold note 64) |
+|------|------------------|-----------------------------|
+| 0    | – (reserved)     | **Bind channel** – set the channel that will be affected by subsequent commands (note value = channel index). |
+| 1    | **Cycle** – toggles the current scene of the *bound* channel (or channel 0 if unbound) through IDLE→RECORD→LOOPING→PAUSED→LOOPING→… | – |
+| 62   | –                | **Cycle** – same as note 1 but always acts on the bound channel. |
+| 63   | –                | **Unbind** – resets the bound channel to channel 0. |
+| 64   | –                | *Control key* – held while other notes are pressed to apply the modifier column. |
+| 70   | –                | **Load WAV** – loads `loop.wav` from the current directory into channel 0's current scene. |
+| 71   | –                | **Save WAV** – saves the current loop (if the scene is in LOOPING state) to `save.wav`. |
+
+*Notes for developers*: The MIDI handler is implemented in `engine/src/midi.c`. The control‑key state is stored in `atomic_int control_key_active`.
+
+### FIFO Commands (file `/tmp/looper_cmd`)
+
+Write a line to the FIFO; each line activates one command.
+
+| Command line          | Description |
+|-----------------------|-------------|
+| `record <ch>`         | Cycle the current scene of channel `<ch>` (same as MIDI note 1). |
+| `stop`                | Force all scenes of the bound channel to IDLE. |
+| `add`                 | Add a new audio channel. |
+| `add_midi`            | Add a new MIDI channel. |
+| `remove`              | Remove the last added dynamic channel. |
+| `bind <ch>`           | Bind subsequent commands to channel `<ch>`. |
+| `unbind`              | Unbind (revert to channel 0). |
+| `scene_add`           | Add a new scene to the bound channel. |
+| `scene_remove`        | Remove the current scene (not the last one) from the bound channel. |
+| `scene_next`          | Switch to the next scene of the bound channel. |
+| `scene_prev`          | Switch to the previous scene of the bound channel. |
+| `load`                | Load `loop.wav` into channel 0's current scene. |
+| `save`                | Save the current loop (if in LOOPING state) to `save.wav`. |
+
+#### Example session (shell)
+
+```sh
+# record something on channel 0
+echo "record 0" > /tmp/looper_cmd
+# after some seconds, stop recording (cycle again)
+echo "record 0" > /tmp/looper_cmd
+# now the loop plays back; save it
+echo "save" > /tmp/looper_cmd
+# add a new channel
+echo "add" > /tmp/looper_cmd
+# bind to that channel (assuming it is channel 1)
+echo "bind 1" > /tmp/looper_cmd
+# record a loop on channel 1
+echo "record 1" > /tmp/looper_cmd
+```
+
+### MIDI Clock (port `looper:clock`)
+
+The looper responds to a subset of MIDI Real Time messages:
+
+| Message | Action |
+|---------|--------|
+| `0xFA` (Start) | If channel 0's current scene is IDLE, switches it to RECORD. |
+| `0xFC` (Stop)  | Sets channel 0's current scene to IDLE. |
+| `0xFB` (Continue) | If channel 0's current scene is PAUSED, switches it to LOOPING. |
+
+These allow synchronisation with an external sequencer.
+
+## Detailed Behaviour
+
+### Audio Channels
+
+- **IDLE**: Input is passed through to output (live monitoring).
+- **RECORD**: Input is written to the loop buffer (up to `LOOP_BUF_SIZE` frames). The buffer is written circularly; when the buffer is full, recording overwrites from the beginning.
+- **LOOPING**: The recorded loop is played back repeatedly. The loop length equals the number of frames written during the last RECORD session (stored in `loop_count`).
+- **PAUSED**: Output is silent; the loop is not playing.
+
+Transitioning from RECORD→LOOPING immediately finalises the loop length and begins playback from the start of the buffer.
+
+### MIDI Channels
+
+MIDI channels work similarly but record MIDI events instead of audio. Received MIDI events are stored in a fixed-size array (`MAX_MIDI_EVENTS`). During LOOPING, all recorded events are played back at the beginning of each cycle (timestamps are not used in playback) – this is suitable for drum patterns and short phrases.
+
+### Dynamic Channels
+
+You can add and remove channels at runtime using FIFO commands or MIDI notes. Each new channel gets its own audio input/output ports and, for MIDI channels, separate MIDI ports. Removing a channel deactivates it and eventually unregisters its ports. The removal happens with a one‑second grace delay to avoid disrupting the audio thread.
+
+### Scenes
+
+Each channel can have several scenes (default one). You can add/remove scenes and switch between them. Only the current scene is active; switching scenes preserves their individual state and loop data. This allows you to prepare multiple loops on the same channel and swap between them.
+
+### Loading WAV files
+
+The `load` command reads a file named `loop.wav` (mono, 16‑bit PCM, any sample rate) from the working directory. It loads the audio into channel 0's current scene, sets the scene state to LOOPING, and begins playback. The loop length is the number of frames read (up to `LOOP_BUF_SIZE`).
+
+### Saving WAV files
+
+The `save` command writes the current loop of channel 0's current scene to `save.wav` (mono, 16‑bit PCM, same sample rate as the JACK server). Saving is synchronous – the audio thread is briefly deactivated to safely copy the buffer. The file is created in the working directory.
+
+### Status FIFO
+
+The looper periodically writes its state to `/tmp/looper_status`. Each line has the format:
+
+```
+CH=<channel> SC=<scene_index> STATE=<IDLE|RECORD|LOOPING|PAUSED>
+```
+
+This can be used by external monitoring tools or scripts to track the looper's state.
+
+## Testing
+
+### Engine Tests
+
+The `engine` directory contains several test executables that are built by `make test`. They require a running JACK server.
+
+```sh
+cd engine
+make test
+```
+
+Tests include:
+
+- Audio pass‑through (connectivity)
+- Loop recording and playback (counts bursts of audio)
+- Dynamic channel creation and removal
+- Control‑key modifier and channel binding
+- WAV file loading and saving
+
+Test results are reported to stdout. If any test fails, the exit code is non‑zero.
+
+### Client Tests
+
+The `client` directory also contains unit and integration tests. They can be run with:
+
+```sh
+cd client
+make test
+```
+
+These tests verify the client command parser, plugin stubs, Carla host interface, and status FIFO parsing. They do **not** require a running JACK server for the mock‑based tests.
+
+---
+
+# Client (TUI Application)
+
+The looper project includes a terminal‑based user interface client that runs alongside the engine. It provides a grid view of channels/scenes, a rack view for managing LV2/VST plugins via Carla, and a command line (`:`‑mode) for advanced operations.
+
+## Building the Client
+
+```sh
+cd client
+make
+```
+
+This produces the `looper-client` binary and a test executable (`test_status_parse`).
+
+## Running the Client
+
+Start the looper engine first (see [Running the Engine](#running)), then launch the client:
+
+```sh
+./looper-client
+```
+
+The client will connect to the engine via the FIFO `/tmp/looper_cmd` and read status from `/tmp/looper_status`. It opens a ncurses interface.
+
+## TUI Keybindings
+
+| Key | Action |
+|-----|--------|
+| `h` / Left | Move selection left |
+| `j` / Down | Move selection down |
+| `k` / Up | Move selection up |
+| `l` / Right | Move selection right |
+| `t` | Toggle recording on the selected channel (sends `record N`) |
+| `s` | Switch to next scene |
+| `S` | Switch to previous scene |
+| `d` / `D` | Stop all scenes on the bound channel |
+| `a` | Add a new audio channel |
+| `A` | Add a new MIDI channel |
+| `r` | Remove the last dynamic channel |
+| `b` | Bind to the selected channel (sends `bind N`) |
+| `u` | Unbind (revert to channel 0) |
+| `?` | Toggle help overlay |
+| `R` | Toggle rack view (for plugin management) |
+| `Esc` / `Q` | Quit (in grid mode) or return to grid (in rack mode) |
+| `:` | Enter colon‑command mode (see below) |
+
+### Rack View (plugin management)
+
+When you press `R`, the TUI switches to a rack view showing all plugins loaded via Carla. In this mode:
+
+| Key | Action |
+|-----|--------|
+| `j` / Down | Select next plugin |
+| `k` / Up | Select previous plugin |
+| `b` / `B` | Bypass the selected plugin |
+| `d` / `D` | Unload the selected plugin |
+| `x` / `X` | Disconnect all JACK connections for the selected plugin |
+| `Esc` | Return to grid view |
+
+## Colon Commands
+
+Press `:` to enter command‑line mode. Type a command and press `Enter`. The following commands are recognised:
+
+| Command | Description |
+|---------|-------------|
+| `from <port>` | Store a source port name (e.g. `looper:out_0`) |
+| `to <port>` | Store a destination port name (e.g. `plugin:in`) |
+| `addplugin <path>` | Load a plugin from the given binary path. If `from` and `to` are set, it also auto‑connects the plugin. |
+| `connect [from] [to]` | Connect two JACK ports. If omitted, uses stored `from`/`to`. |
+| `disconnect [from] [to]` | Disconnect two JACK ports. |
+| `rack` | Switch to rack view (same as `R`) |
+| `grid` | Switch to grid view |
+
+### Example colon session
+
+```
+:from looper:channel1_output
+:to system:playback_2
+:addplugin /usr/lib/lv2/amsynth.lv2/amsynth.so
+:connect looper:channel1_output amsynth:in
+```
+
+## Status Display
+
+The TUI reads the engine’s status FIFO (`/tmp/looper_status`) and displays the state of each channel as coloured cells in a 8×8 grid:
+
+- **White** (IDLE) – channel is monitoring
+- **Red** (RECORD) – channel is recording
+- **Green** (LOOPING) – loop is playing back
+- **Blue** (PAUSED) – loop is paused
+- **Cyan** – currently selected cell
+
+The status is updated continuously in real time.
+
+## Plugin Management Internals
+
+The client uses the **Carla** host library to load and manage plugins. You must have Carla development libraries installed (`libcarla-standalone-dev` or equivalent). Plugins are loaded in a separate Carla engine instance, and their JACK ports are connected to the looper’s ports using the looper’s own JACK client.
+
+The `carla_host.c` module wraps Carla’s API and provides `carla_load`, `carla_unload`, `carla_connect`, etc. The `plugins.c` module provides a simpler interface used by the command parser.
+
+## Communication with the Engine
+
+All actions in the TUI are translated into FIFO commands written to `/tmp/looper_cmd`. The engine’s pipe reader thread picks them up and executes them. The status FIFO `/tmp/looper_status` is polled by the TUI’s main loop to update the display.
+
+---
+
+## Configuration
+
+The following constants can be adjusted at compile time by editing `engine/src/channel.h` and `engine/src/looper.c`:
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| `MAX_CHANNELS` | 8 | Maximum number of dynamic channels. |
+| `MAX_SCENES` | 4 | Maximum scenes per channel. |
+| `LOOP_BUF_SIZE` | 48000 * 8 | Maximum loop length in frames (8 seconds at 48 kHz). |
+| `MAX_MIDI_EVENTS` | 1024 | Maximum MIDI events that can be recorded per scene. |
+
+## Troubleshooting
+
+- **No sound**: Ensure that the JACK server is running and that you have connected `looper:output` to your system playback ports.
+- **MIDI not working**: Use `jack_connect` to connect your controller's output to `looper:control`. The note must be on MIDI channel 0.
+- **save.wav not created**: The scene must be in `LOOPING` state before issuing the save command. Also verify that a loop has been recorded (loop length > 0).
+- **FIFO not working**: The FIFO is created automatically. You can write to it with a simple `echo "record 0" > /tmp/looper_cmd`. If you get "no such file or directory", start the looper first.
+
+## Source Code Organisation
+
+| File | Purpose |
+|------|---------|
+| `engine/src/main.c` | Entry point; opens JACK client, calls `looper_init()` and enters the main loop. |
+| `engine/src/looper.c` | Core logic: `process_callback`, `looper_process_commands`, command execution, WAV load/save. |
+| `engine/src/channel.c` | Channel and scene management (`channel_add`, `channel_remove`, `init_scene`, etc.). |
+| `engine/src/midi.c` | MIDI event parsing and handling for the control port. |
+| `engine/src/queue.c` | Lock‑free SPSC queue used for passing commands between threads. |
+| `engine/src/ringbuffer.c` | Ring buffer used for saving loop audio to disk asynchronously (deprecated, now synchronous). |
+| `engine/src/pipe.c` | FIFO reader thread that translates text lines into `command_t` structs. |
+| `engine/src/wav.c` | WAV file reading and writing (libsndfile wrapper). |
+| `engine/src/command.h` | `command_t` type definition and `cmd_type_t` enum. |
+| `engine/src/channel.h` | Data structures for `channel_t`, `scene_t`, `loop_data_t`. |
+| `engine/src/looper.h` | Function prototypes for callbacks and initialisation. |
+| `engine/tests/` | Integration tests for the above features. |
+
+## License
+
+[Add your license information here.]
+
+---
+
+## Orchestrator and Logging
+
+The orchestrator (`orchestrator.c`, built to `./looper`) launches both the engine and the TUI client in a single process group. It handles graceful shutdown of both children when you press Ctrl+C.
+
+### Building
+
+```sh
+make            # builds engine, client, and orchestrator
+```
+
+The target `orchestrator` is built by the top‑level `make` automatically.
+
+### Running
+
+```sh
+./looper               # starts engine and client
+./looper -s ~/my.rc    # loads a custom script file for the launchpad
+```
+
+To stop, press `Ctrl+C`. The orchestrator sends `SIGTERM` to both children and waits for them to exit.
+
+### Logging
+
+Both the engine and the client write messages to `/tmp/looper.log` (appended). The file is opened at startup and closed at shutdown. The audio thread (`process_callback`) never calls any logging function, so real‑time performance is unaffected.
+
+To watch the log in real time:
+
+```sh
+tail -f /tmp/looper.log
+```
+
+### Launchpad Scripting (via notes FIFO)
+
+The client reads note events from `/tmp/looper_notes` (created automatically). You can feed note numbers into this FIFO using any external tool (JACK MIDI‑to‑FIFO bridge, shell script, etc.). Each line must contain a single integer note number (0–127). The client then calls `script_handle_note`, which executes the macro associated with that note in the currently loaded script file.
+
+The default script path is `~/.config/looper/scripts/launchpad.rc`. A sample script:
+
+```sh
+mkdir -p ~/.config/looper/scripts
+cat > ~/.config/looper/scripts/launchpad.rc << 'EOF'
+# Grid notes 11‑88
+11 record 0
+12 record 1
+13 record 2
+...
+# Right column (scene triggers)
+19 scene_next
+29 scene_next
+39 scene_next
+...
+# Top row control keys 91‑98
+91 stop
+92 scene_prev
+93 load
+94 save
+95 add
+96 remove
+97 add_midi
+98 unbind
+EOF
+```
+
+You can override the script path with the `-s` flag:
+
+```sh
+./looper -s /home/user/my_custom.rc
+```
+
+*Manual generated from the looper source code v1.0.*

docs/manual_test_protocols.md

@@ -0,0 +1,301 @@
+# Manual Test Protocols – Guitar / Audio Looper
+
+This document provides step‑by‑step manual testing procedures using a real guitar (or any line‑level mono audio source) with the `looper` engine.
+
+## Prerequisites
+
+- A running JACK server (e.g. `jackd -d alsa -r 48000 -p 256`)
+- The looper binary compiled (`cd engine && make`)
+- An audio interface recognised by ALSA (or PulseAudio JACK bridge)
+- A guitar connected to your interface’s input
+- `qjackctl` (optional, for visual wiring) or knowledge of `jack_connect` commands
+
+## Test 1 – Basic Audio Pass‑Through (Guitar Monitor)
+
+1. Start the looper in a terminal:
+   ```sh
+   ./looper
+   ```
+
+2. Launch `qjackctl` (or use `jack_connect` from shell) to view available ports.
+
+3. Connect your interface’s capture port to the looper’s input:
+   ```sh
+   jack_connect system:capture_1 looper:input
+   ```
+
+4. Connect the looper’s output to your interface playback ports:
+   ```sh
+   jack_connect looper:output system:playback_1
+   ```
+
+5. Pluck a few strings – you should hear your guitar coming through the looper immediately (channel 0 is in **IDLE** state, which passes input straight to output).
+
+6. To stop, press `Ctrl+C` in the looper terminal.
+
+**Expected result**: You hear your guitar with no latency issues (depending on JACK buffer size). If you hear nothing, check port names with `jack_lsp`.
+
+---
+
+## Test 2 – Record a Short Loop (MIDI Control)
+
+### 2a – Using MIDI keyboard (or a MIDI controller)
+
+1. Start the looper as above.
+2. Connect your MIDI controller to the looper’s control port:
+   ```sh
+   jack_connect <controller>:midi_out looper:control
+   ```
+   Replace `<controller>` with the actual MIDI port name (use `jack_lsp` to find it).
+
+3. Send **note 1** (velocity 127) to switch channel 0 into **RECORD** state.
+   - On most keyboards, this is the C# key two octaves above middle C (MIDI note 1). Press it once.
+
+4. Play your guitar for about 2 seconds. The looper is recording.
+
+5. Press **note 1** again. The looper transitions to **LOOPING** state. The recorded 2‑second phrase starts playing back repeatedly.
+
+6. You should hear the loop repeating. Pluck strings while the loop plays – the IDLE monitoring is still active on channel 0 (the loop is mixed with the live input).
+
+7. Press **note 1** a third time to **PAUSE** the loop; press again to resume.
+
+### 2b – Using FIFO commands (if you have no MIDI keyboard)
+
+1. Start the looper.
+2. Open a second terminal.
+3. Send:
+   ```sh
+   echo "record 0" > /tmp/looper_cmd
+   ```
+4. Play guitar for a few seconds.
+5. Send again:
+   ```sh
+   echo "record 0" > /tmp/looper_cmd
+   ```
+6. Loop should start repeating. Test pause by sending again (second command cycles IDLE→RECORD→LOOPING→PAUSED→…).
+
+**Expected result**: The loop repeats seamlessly. If you hold a chord while the loop is playing, the live input still passes through.
+
+---
+
+## Test 3 – Save the Loop to a WAV File
+
+1. Ensure a loop is playing (LOOPING state) on channel 0.
+
+2. Send the save command:
+   ```sh
+   echo "save" > /tmp/looper_cmd
+   ```
+   or (MIDI) press control‑key (note 64) + note 71.
+
+3. After a brief delay (the loop buffer is written synchronously), a file `save.wav` appears in the engine directory.
+
+4. Check the file size is > 44 bytes and play it with any media player:
+   ```sh
+   aplay save.wav
+   ```
+
+**Expected result**: The saved file contains exactly what the looper was playing (your recorded guitar phrase). The RMS of the playback should be similar to the live signal.
+
+---
+
+## Test 4 – Load a WAV File into a Channel
+
+1. Put a mono 16‑bit WAV file named `loop.wav` in the engine directory (e.g. a short drum loop or a guitar riff).
+
+2. Start the looper and send the load command:
+   ```sh
+   echo "load" > /tmp/looper_cmd
+   ```
+   or (MIDI) control‑key + note 70.
+
+3. The loaded audio begins playing immediately on channel 0 (state = LOOPING).
+
+4. Verify you hear the loop repeating.
+
+**Expected result**: The WAV is loaded and plays correctly. The loop length matches the duration of the file (up to `LOOP_BUF_SIZE` frames, default 8 seconds).
+
+---
+
+## Test 5 – Dynamic Channel Creation and Binding
+
+1. Start the looper.
+
+2. Add a second audio channel:
+   ```sh
+   echo "add" > /tmp/looper_cmd
+   ```
+
+3. Check that new ports appear:
+   ```sh
+   jack_lsp | grep channel1
+   ```
+
+4. Bind the client to channel 1:
+   ```sh
+   echo "bind 1" > /tmp/looper_cmd
+   ```
+
+5. Connect your guitar to both channels for stereo testing? Not necessary. But you can route differently.
+
+6. Now when you send `record 1`, the bind ensures the command affects channel 1 instead of channel 0.
+
+7. Repeat the record/loop process on channel 1, while channel 0 continues its own loop.
+
+**Expected result**: Two independent loops can play simultaneously without interfering.
+
+---
+
+## Test 6 – Scene Switching
+
+1. Make sure a loop is playing on channel 0.
+
+2. Add a second scene to channel 0:
+   ```sh
+   echo "scene_add" > /tmp/looper_cmd
+   ```
+   (Only adds scene if `MAX_SCENES` not exceeded, default 4.)
+
+3. Switch to the new scene:
+   ```sh
+   echo "scene_next" > /tmp/looper_cmd
+   ```
+   The playback stops because the new scene is IDLE.
+
+4. Record a different phrase on the new scene (send `record 0`).
+
+5. Switch back to the first scene (`scene_prev`) – the original loop resumes.
+
+**Expected result**: Different independent loops in separate scenes; switching scenes does not lose previously recorded loops.
+
+---
+
+## Test 7 – MIDI Clock Sync
+
+If you have an external MIDI clock source (e.g. a drum machine or DAW sending MIDI start/stop):
+
+1. Connect the clock source to `looper:clock` port.
+
+2. Send MIDI Start (`0xFA`). The looper’s current scene (if IDLE) transitions to RECORD.
+
+3. Send MIDI Stop (`0xFC`). The current scene goes IDLE (loop stops).
+
+4. Send MIDI Continue (`0xFB`) while the scene is PAUSED – it resumes LOOPING.
+
+**Expected result**: Transport commands control looper state reliably.
+
+---
+
+## Test 8 – Edge Cases
+
+### 8a – Rapid toggling
+
+Cycle the RECORD/LOOPING/PAUSED states many times in quick succession (send `record 0` every 200 ms for 5 seconds). The looper should not crash or produce glitches.
+
+### 8b – Remove channel while playing
+
+Add a channel, start a loop on it, then remove the channel with:
+```sh
+echo "remove" > /tmp/looper_cmd
+```
+The loop should stop gracefully after a one‑second grace period; the client should not crash.
+
+### 8c – Save empty loop
+
+Attempt to `save` when the current scene is not LOOPING or loop_count == 0. No file should be created. The engine should log a message to stderr.
+
+---
+
+## Environment Variables
+
+- `LOOPER_CMD_FIFO` (overrides `/tmp/looper_cmd`) – useful for running multiple instances for testing.
+- `JACK_DEFAULT_SERVER` (JACK environment) – can be set to run a separate JACK server.
+
+---
+
+## Troubleshooting
+
+- **No audio after connection**: Ensure `jack_lsp` shows both source and destination ports, and that the looper is the only client using those ports.
+- **MIDI not recognised**: Verify that `midi_control_port` is created (`looper:control`). Use `jack_midi_dump` to see if note events arrive.
+- **“save.wav not created“** after save command: The scene must be in LOOPING state and `loop_count` > 0. Check the engine’s terminal output for error messages.
+
+---
+
+## Carla Plugin Management Manual Tests
+
+### Test C1 – Load a plugin via colon command
+
+1. Ensure the looper engine is running, and the client (`looper-client`) is also running.
+
+2. In the client, enter colon mode (`:`) and type:
+   ```
+   from looper:output
+   ```
+   then press Enter.
+
+3. Enter colon mode again and type:
+   ```
+   to system:playback_1
+   ```
+
+4. Load a test LV2 plugin (e.g., /usr/lib/lv2/amsynth.lv2/amsynth.so):
+   ```
+   addplugin /usr/lib/lv2/amsynth.lv2/amsynth.so
+   ```
+
+5. The plugin should be loaded into Carla and its JACK ports are automatically connected (if `from` and `to` were set). You should see the plugin appear in the rack view when you press `R`.
+
+6. Play some audio through the looper – it should be processed by the plugin.
+
+### Test C2 – Toggle bypass
+
+1. In rack view (`R`), select the plugin using `j`/`k`.
+
+2. Press `b` or `B` to toggle bypass.
+
+3. The effect should stop processing (bypass mode active); pressing again reactivates.
+
+### Test C3 – Disconnect a plugin
+
+1. In rack view, select the plugin.
+
+2. Press `x` or `X` to disconnect all its JACK connections.
+
+3. The plugin should no longer be connected to any looper ports; the audio should pass through unaffected.
+
+### Test C4 – Unload a plugin
+
+1. In rack view, select the plugin.
+
+2. Press `d` or `D` to unload (remove) the plugin.
+
+3. The plugin disappears from the rack list.
+
+### Test C5 – Manual connection using colon commands
+
+1. Set `from` and `to` ports as in Test C1.
+
+2. Load a plugin without auto‑connection:
+   - Do **not** set `from`/`to`, or set them after loading.
+   - Use `addplugin` with only a path.
+
+3. Manually connect ports in colon mode:
+   ```
+   connect looper:output amsynth:in
+   ```
+   The connection should be established.
+
+4. Verify in `jack_lsp` that the ports are connected.
+
+### Test C6 – Disconnect using colon commands
+
+1. After a manual connection, disconnect using:
+   ```
+   disconnect looper:output amsynth:in
+   ```
+
+2. The ports should be disconnected.
+
+---
+
+*Last updated:* 18 May 2026

engine/makefile

@@ -1,8 +1,8 @@
 CC ?= gcc
 CFLAGS ?= -Wall -Wextra -g -Isrc 
-LDFLAGS ?= -ljack -lm
+LDFLAGS ?= -ljack -lm -lsndfile -lpthread
 
-SRC = src/main.c src/looper.c src/channel.c src/midi.c src/queue.c src/pipe.c
+SRC = src/main.c src/looper.c src/channel.c src/midi.c src/queue.c src/pipe.c src/ringbuffer.c src/wav.c src/log.c
 OBJ = $(SRC:.c=.o)
 
 looper: $(OBJ)
@@ -12,10 +12,10 @@ src/%.o: src/%.c
 	$(CC) $(CFLAGS) -c -o $@ $<
 
 integration: looper tests/integration.c
-	$(CC) $(CFLAGS) -o integration_test tests/integration.c -ljack -lm
+	$(CC) $(CFLAGS) -o integration_test tests/integration.c -ljack -lm -lsndfile -lpthread
 
 test_status_fifo: looper tests/test_status_fifo.c
-	$(CC) $(CFLAGS) -o test_status_fifo tests/test_status_fifo.c -ljack -lm
+	$(CC) $(CFLAGS) -o test_status_fifo tests/test_status_fifo.c -ljack -lm -lsndfile -lpthread
 
 test: integration test_status_fifo
 	./test_status_fifo

engine/src/channel.c

@@ -6,131 +6,126 @@
 #include <string.h>
 
 /* Helper: zero a scene and set its state to IDLE */
-static void init_scene(scene_t *sc) {
+void init_scene(scene_t *sc) {
   memset(sc, 0, sizeof(scene_t));
   atomic_store(&sc->state, STATE_IDLE);
   atomic_store(&sc->prev_state, -1);
 }
 
 void channel_add(jack_client_t *client, int idx) {
-  struct channel_t *cur = get_channels_array();
-
   char in_name[64], out_name[64];
   snprintf(in_name, sizeof(in_name), "channel%d_input", next_channel_id);
   snprintf(out_name, sizeof(out_name), "channel%d_output", next_channel_id);
 
-  cur[idx].audio_in = jack_port_register(
+  /* Always register audio ports (needed for pass-through even for MIDI
+   * channels?) */
+  channels[idx].audio_in = jack_port_register(
       client, in_name, JACK_DEFAULT_AUDIO_TYPE, JackPortIsInput, 0);
-  cur[idx].audio_out = jack_port_register(
+  channels[idx].audio_out = jack_port_register(
       client, out_name, JACK_DEFAULT_AUDIO_TYPE, JackPortIsOutput, 0);
-  if (!cur[idx].audio_in || !cur[idx].audio_out) {
+  if (!channels[idx].audio_in || !channels[idx].audio_out) {
     fprintf(stderr, "Failed to register ports for channel %d\n",
             next_channel_id);
-    atomic_store(&cur[idx].active, 0);
+    /* Do NOT mark channel active – process loop will skip it */
+    atomic_store(&channels[idx].active, 0);
     return;
   }
 
-  atomic_store(&cur[idx].active, 1);
+  /* If this is a MIDI channel, register MIDI ports */
-  cur[idx].type = CHANNEL_AUDIO;
+  if (channels[idx].type == CHANNEL_MIDI) {
-  atomic_store(&cur[idx].scene_count, 1);
+    char midi_in_name[64], midi_out_name[64];
-  atomic_store(&cur[idx].current_scene, 0);
+    snprintf(midi_in_name, sizeof(midi_in_name), "channel%d_midi_in",
-  init_scene(&cur[idx].scenes[0]);
+             next_channel_id);
-
+    snprintf(midi_out_name, sizeof(midi_out_name), "channel%d_midi_out",
-  next_channel_id++;
+             next_channel_id);
-  atomic_fetch_add(&channel_count, 1);
+    channels[idx].midi_in = jack_port_register(
-}
+        client, midi_in_name, JACK_DEFAULT_MIDI_TYPE, JackPortIsInput, 0);
-
+    channels[idx].midi_out = jack_port_register(
-void channel_add_midi(jack_client_t *client, int idx) {
+        client, midi_out_name, JACK_DEFAULT_MIDI_TYPE, JackPortIsOutput, 0);
-  struct channel_t *cur = get_channels_array();
+    if (!channels[idx].midi_in || !channels[idx].midi_out) {
-
-  char in_name[64], out_name[64];
-  snprintf(in_name, sizeof(in_name), "channel%d_midi_in", next_channel_id);
-  snprintf(out_name, sizeof(out_name), "channel%d_midi_out", next_channel_id);
-
-  cur[idx].midi_in = jack_port_register(client, in_name, JACK_DEFAULT_MIDI_TYPE,
-                                        JackPortIsInput, 0);
-  cur[idx].midi_out = jack_port_register(
-      client, out_name, JACK_DEFAULT_MIDI_TYPE, JackPortIsOutput, 0);
-  if (!cur[idx].midi_in || !cur[idx].midi_out) {
       fprintf(stderr, "Failed to register MIDI ports for channel %d\n",
               next_channel_id);
-    atomic_store(&cur[idx].active, 0);
+      atomic_store(&channels[idx].active, 0);
+      jack_port_unregister(client, channels[idx].audio_in);
+      jack_port_unregister(client, channels[idx].audio_out);
       return;
     }
+  } else {
+    channels[idx].midi_in = NULL;
+    channels[idx].midi_out = NULL;
+  }
 
-  atomic_store(&cur[idx].active, 1);
+  atomic_store(&channels[idx].active, 1);
-  cur[idx].type = CHANNEL_MIDI;
+  /* Initialise first scene */
-  atomic_store(&cur[idx].scene_count, 1);
+  channels[idx].scene_count = 1;
-  atomic_store(&cur[idx].current_scene, 0);
+  channels[idx].current_scene = 0;
-  init_scene(&cur[idx].scenes[0]);
+  init_scene(&channels[idx].scenes[0]);
+
+  channels[idx].save_ring = NULL;
+  atomic_store(&channels[idx].save_complete, 0);
 
   next_channel_id++;
-  atomic_fetch_add(&channel_count, 1);
+  channel_count++;
 }
 
 void channel_remove(jack_client_t *client, int idx) {
   (void)client;
-  struct channel_t *cur = get_channels_array();
+  atomic_store(&channels[idx].active, 0);
-  atomic_store(&cur[idx].active, 0);
   atomic_fetch_sub(&channel_count, 1);
 }
 
 void channel_add_scene(jack_client_t *client, int idx) {
   (void)client;
-  struct channel_t *cur = get_channels_array();
+  if (atomic_load(&channels[idx].scene_count) >= MAX_SCENES)
-  if (atomic_load(&cur[idx].scene_count) >= MAX_SCENES)
     return;
-  int ns = atomic_load(&cur[idx].scene_count);
+  int ns = atomic_load(&channels[idx].scene_count);
-  init_scene(&cur[idx].scenes[ns]);
+  init_scene(&channels[idx].scenes[ns]);
-  atomic_fetch_add(&cur[idx].scene_count, 1);
+  atomic_fetch_add(&channels[idx].scene_count, 1);
 }
 
 void channel_remove_scene(jack_client_t *client, int idx) {
   (void)client;
-  struct channel_t *cur = get_channels_array();
+  int sc = atomic_load(&channels[idx].scene_count);
-  int sc = atomic_load(&cur[idx].scene_count);
   if (sc <= 1)
     return;
-  int cs = atomic_load(&cur[idx].current_scene);
+  int cs = atomic_load(&channels[idx].current_scene);
   /* shift remaining scenes down (atomic copy of fields) */
   for (int i = cs; i < sc - 1; i++) {
-    atomic_store(&cur[idx].scenes[i].loop_count,
+    atomic_store(&channels[idx].scenes[i].loop_count,
-                 atomic_load(&cur[idx].scenes[i + 1].loop_count));
+                 atomic_load(&channels[idx].scenes[i + 1].loop_count));
-    atomic_store(&cur[idx].scenes[i].record_pos,
+    atomic_store(&channels[idx].scenes[i].record_pos,
-                 atomic_load(&cur[idx].scenes[i + 1].record_pos));
+                 atomic_load(&channels[idx].scenes[i + 1].record_pos));
-    atomic_store(&cur[idx].scenes[i].playback_pos,
+    atomic_store(&channels[idx].scenes[i].playback_pos,
-                 atomic_load(&cur[idx].scenes[i + 1].playback_pos));
+                 atomic_load(&channels[idx].scenes[i + 1].playback_pos));
-    atomic_store(&cur[idx].scenes[i].state,
+    atomic_store(&channels[idx].scenes[i].state,
-                 atomic_load(&cur[idx].scenes[i + 1].state));
+                 atomic_load(&channels[idx].scenes[i + 1].state));
-    atomic_store(&cur[idx].scenes[i].prev_state,
+    atomic_store(&channels[idx].scenes[i].prev_state,
-                 atomic_load(&cur[idx].scenes[i + 1].prev_state));
+                 atomic_load(&channels[idx].scenes[i + 1].prev_state));
     /* copy loop data (may race with RT thread; acceptable for this release) */
-    memcpy(cur[idx].scenes[i].loop.audio_buffer,
+    memcpy(channels[idx].scenes[i].loop.audio_buffer,
-           cur[idx].scenes[i + 1].loop.audio_buffer,
+           channels[idx].scenes[i + 1].loop.audio_buffer,
            LOOP_BUF_SIZE * sizeof(float));
   }
-  atomic_fetch_sub(&cur[idx].scene_count, 1);
+  atomic_fetch_sub(&channels[idx].scene_count, 1);
-  int new_sc = atomic_load(&cur[idx].scene_count);
+  int new_sc = atomic_load(&channels[idx].scene_count);
   if (cs >= new_sc)
-    atomic_store(&cur[idx].current_scene, new_sc - 1);
+    atomic_store(&channels[idx].current_scene, new_sc - 1);
 }
 
 void channel_next_scene(jack_client_t *client, int idx) {
   (void)client;
-  struct channel_t *cur = get_channels_array();
+  int sc = atomic_load(&channels[idx].scene_count);
-  int sc = atomic_load(&cur[idx].scene_count);
   if (sc > 1) {
-    int cs = atomic_load(&cur[idx].current_scene);
+    int cs = atomic_load(&channels[idx].current_scene);
-    atomic_store(&cur[idx].current_scene, (cs + 1) % sc);
+    atomic_store(&channels[idx].current_scene, (cs + 1) % sc);
   }
 }
 
 void channel_prev_scene(jack_client_t *client, int idx) {
   (void)client;
-  struct channel_t *cur = get_channels_array();
+  int sc = atomic_load(&channels[idx].scene_count);
-  int sc = atomic_load(&cur[idx].scene_count);
   if (sc > 1) {
-    int cs = atomic_load(&cur[idx].current_scene);
+    int cs = atomic_load(&channels[idx].current_scene);
-    atomic_store(&cur[idx].current_scene, (cs - 1 + sc) % sc);
+    atomic_store(&channels[idx].current_scene, (cs - 1 + sc) % sc);
   }
 }

engine/src/channel.h

@@ -5,23 +5,14 @@
 #include <jack/jack.h>
 #include <stdatomic.h>
 
+#define MAX_SCENES 4
 #define LOOP_BUF_SIZE  (5 * 48000)
-
 #define MAX_MIDI_EVENTS 1024
+#define MAX_CHANNELS   16
 
-#define MAX_SCENES 16
+#include "ringbuffer.h"
 
-typedef enum {
+typedef enum { CHANNEL_AUDIO, CHANNEL_MIDI } channel_type_t;
-    CHANNEL_AUDIO,
-    CHANNEL_MIDI
-} channel_type_t;
-
-typedef struct {
-    jack_nframes_t timestamp;   /* frame offset relative to loop start */
-    unsigned char  status;
-    unsigned char  note;
-    unsigned char  velocity;
-} midi_event_t;
 
 typedef enum {
     STATE_IDLE,
@@ -30,46 +21,58 @@ typedef enum {
     STATE_PAUSED
 } looper_state;
 
+/* Structure for a recorded or playing MIDI event */
+typedef struct {
+    jack_nframes_t timestamp;
+    unsigned char status;
+    unsigned char note;
+    unsigned char velocity;
+} midi_event_t;
+
+/* Loop data for a scene */
 typedef struct {
-    union {
     float          audio_buffer[LOOP_BUF_SIZE];
     midi_event_t   midi_events[MAX_MIDI_EVENTS];
-    } loop;
+} loop_data_t;
+
+/* A single scene within a channel */
+typedef struct {
+    atomic_int state;
+    atomic_int prev_state;
     atomic_int loop_count;
     atomic_int record_pos;
     atomic_int playback_pos;
-    atomic_int    state;
+    loop_data_t loop;
-    atomic_int    prev_state;
 } scene_t;
 
 struct channel_t {
-    channel_type_t type;
+    channel_type_t type;          /* AUDIO or MIDI */
     atomic_int    active;
     jack_port_t  *audio_in;
     jack_port_t  *audio_out;
-    jack_port_t  *midi_in;
+    jack_port_t  *midi_in;       /* NULL for audio channels */
     jack_port_t  *midi_out;
+    int           scene_count;   /* number of scenes (max MAX_SCENES) */
+    int           current_scene; /* index of currently active scene */
     scene_t       scenes[MAX_SCENES];
-    atomic_int    scene_count;
+
-    atomic_int    current_scene;
+    _Atomic RingBuf *save_ring;
+    atomic_int       save_complete;   /* 1 when writer is done; RT thread must stop writing */
 };
 
 /* Globals declared in looper.c */
-extern struct channel_t *_Atomic channels;
+extern struct channel_t channels[MAX_CHANNELS];
-extern atomic_int  channel_capacity;
 extern atomic_int  channel_count;
+extern atomic_int  channel_capacity;
 extern int         next_channel_id;
+extern atomic_int  cmd_add;
+extern atomic_int  cmd_remove;
+extern atomic_int  cmd_load;
+extern atomic_int  cmd_save;
 
-/* Safe accessor for the real‑time thread (returns a snapshot of the current pointer) */
+void init_scene(scene_t *sc);
-static inline struct channel_t *get_channels_array(void) {
-    return atomic_load(&channels);
-}
-
 void channel_add(jack_client_t *client, int idx);
 void channel_remove(jack_client_t *client, int idx);
-void channel_add_midi(jack_client_t *client, int idx);
-
-/* Scene management (called from main loop) */
 void channel_add_scene(jack_client_t *client, int idx);
 void channel_remove_scene(jack_client_t *client, int idx);
 void channel_next_scene(jack_client_t *client, int idx);

engine/src/command.h

@@ -9,6 +9,8 @@ typedef enum {
     CMD_ADD_CHANNEL,    // add a new dynamic channel
     CMD_REMOVE_CHANNEL, // remove last dynamic channel
     CMD_ADD_MIDI_CHANNEL, // add a new dynamic MIDI channel
+    CMD_LOAD,           // load WAV file into channel 0
+    CMD_SAVE,           // save loop as WAV file
     CMD_NEXT_SCENE,
     CMD_PREV_SCENE,
     CMD_ADD_SCENE,

engine/src/log.c

@@ -0,0 +1,32 @@
+#include "log.h"
+#include <stdio.h>
+#include <stdarg.h>
+#include <stdlib.h>
+#include <pthread.h>
+
+static FILE *logfile = NULL;
+static pthread_mutex_t log_mutex = PTHREAD_MUTEX_INITIALIZER;
+
+void log_init(void) {
+    logfile = fopen("/tmp/looper.log", "a");
+    if (!logfile)
+        logfile = stderr;
+    setbuf(logfile, NULL);
+}
+
+void log_msg(const char *fmt, ...) {
+    if (!logfile) return;
+    pthread_mutex_lock(&log_mutex);
+    va_list args;
+    va_start(args, fmt);
+    vfprintf(logfile, fmt, args);
+    va_end(args);
+    fputc('\n', logfile);
+    pthread_mutex_unlock(&log_mutex);
+}
+
+void log_close(void) {
+    if (logfile && logfile != stderr)
+        fclose(logfile);
+    logfile = NULL;
+}

engine/src/log.h

@@ -0,0 +1,8 @@
+#ifndef LOG_H
+#define LOG_H
+
+void log_init(void);
+void log_msg(const char *fmt, ...);
+void log_close(void);
+
+#endif

engine/src/looper.c

@@ -1,13 +1,15 @@
 // cppcheck-suppress missingIncludeSystem
 #include "looper.h"
 #include "channel.h"
-#include "command.h"
 #include "midi.h"
+#include "pipe.h"
 #include "queue.h"
+#include "wav.h"
 #include <fcntl.h>
 #include <jack/jack.h>
 #include <jack/midiport.h>
 #include <math.h>
+#include <pthread.h>
 #include <stdatomic.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -15,20 +17,25 @@
 #include <sys/stat.h>
 #include <unistd.h>
 
+/* Global command queues (used by midi.c and pipe.c) */
+spsc_queue_t cmd_queue;
+spsc_queue_t cmd_queue_main_midi;
+spsc_queue_t cmd_queue_main_fifo;
+
 #define STATUS_FIFO "/tmp/looper_status"
 
+/* writer status fd */
+static int status_fd = -1;
+
 static void looper_write_status(void) {
-  int fd = open(STATUS_FIFO, O_WRONLY | O_NONBLOCK);
+  if (status_fd < 0)
-  if (fd < 0)
     return;
-  struct channel_t *cur = get_channels_array();
-  int cap = atomic_load(&channel_capacity);
   char buf[256];
-  for (int ch = 0; ch < cap; ch++) {
+  for (int ch = 0; ch < MAX_CHANNELS; ch++) {
-    if (!atomic_load(&cur[ch].active))
+    if (!atomic_load(&channels[ch].active))
       continue;
-    int sc_idx = atomic_load(&cur[ch].current_scene);
+    int sc_idx = atomic_load(&channels[ch].current_scene);
-    int state = atomic_load(&cur[ch].scenes[sc_idx].state);
+    int state = atomic_load(&channels[ch].scenes[sc_idx].state);
     const char *state_str;
     switch (state) {
     case STATE_IDLE:
@@ -49,122 +56,121 @@ static void looper_write_status(void) {
     int n = snprintf(buf, sizeof(buf), "CH=%d SC=%d STATE=%s\n", ch, sc_idx,
                      state_str);
     if (n > 0) {
-      int ret = write(fd, buf, n);
+      int ret = write(status_fd, buf, n);
       (void)ret;
     }
   }
-  close(fd);
 }
 
 /* Global state (shared across files) */
-struct channel_t *_Atomic channels = NULL;
+struct channel_t channels[MAX_CHANNELS];
-atomic_int channel_capacity = 0;
 atomic_int channel_count = 0;
+atomic_int channel_capacity = MAX_CHANNELS;
 int next_channel_id = 1;
-spsc_queue_t cmd_queue_main_midi;
+atomic_int cmd_add = 0;
-spsc_queue_t cmd_queue_main_fifo;
+atomic_int cmd_remove = 0;
-atomic_int global_rt_cycles = 0;
+atomic_int cmd_load = 0;
+atomic_int cmd_save = 0;
 jack_port_t *midi_control_port = NULL;
 jack_port_t *midi_clock_port = NULL;
 atomic_int control_key_active = 0;
 atomic_int bind_channel = 0;
-spsc_queue_t cmd_queue;
 
-/* Deferred removal index and cycle counter */
+/* Deferred removal index (1 second grace) */
 static int pending_unregister_idx = -1;
-static int pending_unregister_cycle = 0;
 
-/* Deferred free of old channel array (must not free while RT thread may hold
+/* sample rate holder */
- * pointer) */
+static int global_sample_rate = 0;
-static struct channel_t *pending_old = NULL;
-static int pending_old_cycle = 0;
 
-/* Helper: grow the channel array so that index idx is valid */
+/* execute a single command (called from looper_process_commands) */
-static int ensure_capacity(jack_client_t *client, int idx) {
+static void exec_command(command_t cmd, jack_client_t *client) {
-  (void)client;
+  int ch = cmd.channel;
-  int cur_cap = atomic_load(&channel_capacity);
+  if (ch < 0 || ch >= MAX_CHANNELS)
-  if (idx < cur_cap)
+    ch = 0;
-    return 0;
-  int new_cap = cur_cap == 0 ? 8 : cur_cap;
-  while (new_cap <= idx)
-    new_cap *= 2;
-  struct channel_t *new_arr = calloc(new_cap, sizeof(struct channel_t));
-  if (!new_arr)
-    return -1;
-  /* copy existing channels */
-  if (cur_cap > 0)
-    memcpy(new_arr, atomic_load(&channels), cur_cap * sizeof(struct channel_t));
-  /* atomically publish new array, defer free of old */
-  struct channel_t *old = atomic_exchange(&channels, new_arr);
-  atomic_store(&channel_capacity, new_cap);
-  /* schedule old pointer for later deallocation (after RT cycle) */
-  pending_old = old;
-  pending_old_cycle = atomic_load(&global_rt_cycles);
-  return 0;
-}
-
-static void apply_command(command_t cmd) {
-  int cap = atomic_load(&channel_capacity);
-  struct channel_t *cur = get_channels_array();
 
   switch (cmd.type) {
-  case CMD_CYCLE:
+  case CMD_CYCLE: {
-    if (cmd.channel >= 0 && cmd.channel < cap) {
+    int sc_idx = atomic_load(&channels[ch].current_scene);
-      int sc_idx = atomic_load(&cur[cmd.channel].current_scene);
+    scene_t *sc_ptr = &channels[ch].scenes[sc_idx];
-      scene_t *sc = &cur[cmd.channel].scenes[sc_idx];
+    int state = atomic_load(&sc_ptr->state);
-      int cst = atomic_load(&sc->state);
+    switch (state) {
-      int next;
-      switch (cst) {
     case STATE_IDLE:
-        next = STATE_RECORD;
+      atomic_store(&sc_ptr->state, STATE_RECORD);
       break;
     case STATE_RECORD:
-        next = STATE_LOOPING;
+      atomic_store(&sc_ptr->state, STATE_LOOPING);
       break;
     case STATE_LOOPING:
-        next = STATE_PAUSED;
+      atomic_store(&sc_ptr->state, STATE_PAUSED);
       break;
     case STATE_PAUSED:
-        next = STATE_LOOPING;
+      atomic_store(&sc_ptr->state, STATE_LOOPING);
-        break;
-      default:
-        next = STATE_IDLE;
       break;
     }
-      atomic_store(&sc->state, next);
-    }
     break;
+  }
   case CMD_STOP:
-    if (cmd.channel >= 0 && cmd.channel < cap) {
+    for (int s = 0; s < atomic_load(&channels[ch].scene_count); s++) {
-      struct channel_t *ch = &cur[cmd.channel];
+      atomic_store(&channels[ch].scenes[s].state, STATE_IDLE);
-      int sc_cnt = atomic_load(&ch->scene_count);
+      atomic_store(&channels[ch].scenes[s].prev_state, -1);
-      for (int s = 0; s < sc_cnt; s++) {
-        atomic_store(&ch->scenes[s].state, STATE_IDLE);
-        atomic_store(&ch->scenes[s].loop_count, 0);
-        atomic_store(&ch->scenes[s].record_pos, 0);
-        atomic_store(&ch->scenes[s].playback_pos, 0);
-        atomic_store(&ch->scenes[s].prev_state, -1);
-      }
-    } else {
-      for (int i = 0; i < cap; i++) {
-        struct channel_t *ch = &cur[i];
-        int sc_cnt = atomic_load(&ch->scene_count);
-        for (int s = 0; s < sc_cnt; s++) {
-          atomic_store(&ch->scenes[s].state, STATE_IDLE);
-          atomic_store(&ch->scenes[s].loop_count, 0);
-          atomic_store(&ch->scenes[s].record_pos, 0);
-          atomic_store(&ch->scenes[s].playback_pos, 0);
-          atomic_store(&ch->scenes[s].prev_state, -1);
-        }
-      }
     }
     break;
+
+  case CMD_ADD_CHANNEL:
+  case CMD_ADD_MIDI_CHANNEL: {
+    int idx;
+    for (idx = 0; idx < MAX_CHANNELS; idx++)
+      if (!channels[idx].active)
+        break;
+    if (idx < MAX_CHANNELS)
+      channel_add(client, idx);
+    break;
+  }
+
+  case CMD_REMOVE_CHANNEL: {
+    int remove_idx = -1;
+    for (int idx = 1; idx < MAX_CHANNELS; idx++)
+      if (channels[idx].active)
+        remove_idx = idx;
+    if (remove_idx != -1) {
+      channel_remove(client, remove_idx);
+      pending_unregister_idx = remove_idx;
+    }
+    break;
+  }
+
   case CMD_BIND_CHANNEL:
     atomic_store(&bind_channel, cmd.data);
     break;
+
   case CMD_UNBIND:
     atomic_store(&bind_channel, 0);
     break;
+
+  case CMD_LOAD:
+    atomic_store(&cmd_load, 1);
+    break;
+
+  case CMD_SAVE:
+    atomic_store(&cmd_save, 1);
+    break;
+
+  case CMD_ADD_SCENE:
+    channel_add_scene(client, ch);
+    break;
+
+  case CMD_REMOVE_SCENE:
+    channel_remove_scene(client, ch);
+    break;
+
+  case CMD_NEXT_SCENE:
+    channel_next_scene(client, ch);
+    break;
+
+  case CMD_PREV_SCENE:
+    channel_prev_scene(client, ch);
+    break;
+
   default:
     break;
   }
@@ -183,59 +189,31 @@ int process_callback(jack_nframes_t nframes, void *arg) {
     }
   }
 
-  /* drain RT‑safe commands */
-  command_t cmd;
-  while (queue_pop(&cmd_queue, &cmd)) {
-    apply_command(cmd);
-  }
-
   /* process each active channel */
-  struct channel_t *active_channels = get_channels_array();
+  for (int c = 0; c < MAX_CHANNELS; c++) {
-  int cap = atomic_load(&channel_capacity);
+    if (!atomic_load(&channels[c].active))
-  for (int c = 0; c < cap; c++) {
-    if (!atomic_load(&active_channels[c].active))
       continue;
 
     /* Guard against NULL ports (e.g. if port registration failed) */
-    if (active_channels[c].type == CHANNEL_AUDIO) {
+    if (!channels[c].audio_in || !channels[c].audio_out) {
-      if (!active_channels[c].audio_in || !active_channels[c].audio_out) {
+      fprintf(stderr, "WARN: channel %d has NULL audio port(s), skipping\n", c);
-        fprintf(stderr, "WARN: channel %d has NULL audio port(s), skipping\n",
-                c);
       continue;
     }
-    } else {
-      /* CHANNEL_MIDI */
-      if (!active_channels[c].midi_in || !active_channels[c].midi_out) {
-        fprintf(stderr, "WARN: channel %d has NULL MIDI port(s), skipping\n",
-                c);
-        continue;
-      }
-    }
-
-    /* Obtain current scene pointer */
-    int sc_idx = atomic_load(&active_channels[c].current_scene);
-    scene_t *sc = &active_channels[c].scenes[sc_idx];
-
-    const jack_default_audio_sample_t *in =
-        (const jack_default_audio_sample_t *)jack_port_get_buffer(
-            active_channels[c].audio_in, nframes);
-    jack_default_audio_sample_t *out =
-        (jack_default_audio_sample_t *)jack_port_get_buffer(
-            active_channels[c].audio_out, nframes);
-    if (!out)
-      continue;
 
+    /* For each channel, use the current scene */
+    int sc_idx = atomic_load(&channels[c].current_scene);
+    scene_t *sc = &channels[c].scenes[sc_idx];
     int state = atomic_load(&sc->state);
-    int prev_state = atomic_load(&sc->prev_state);
+    int prev = atomic_load(&sc->prev_state);
 
-    if (state != prev_state) {
+    if (state != prev) {
       switch (state) {
       case STATE_RECORD:
         atomic_store(&sc->record_pos, 0);
         atomic_store(&sc->loop_count, 0);
         break;
       case STATE_LOOPING:
-        if (atomic_load(&sc->record_pos) > 0)
+        if (prev == STATE_RECORD && atomic_load(&sc->record_pos) > 0)
           atomic_store(&sc->loop_count, atomic_load(&sc->record_pos));
         atomic_store(&sc->playback_pos, 0);
         break;
@@ -244,12 +222,16 @@ int process_callback(jack_nframes_t nframes, void *arg) {
       }
     }
 
-    if (active_channels[c].type == CHANNEL_MIDI) {
+    /* Handle MIDI channels separately */
+    if (channels[c].type == CHANNEL_MIDI) {
       /* MIDI channel handling */
+      void *midi_in_buf = jack_port_get_buffer(channels[c].midi_in, nframes);
+      void *midi_out_buf = jack_port_get_buffer(channels[c].midi_out, nframes);
+      if (!midi_out_buf)
+        continue;
+
       switch (state) {
       case STATE_RECORD: {
-        void *midi_in_buf =
-            jack_port_get_buffer(active_channels[c].midi_in, nframes);
         if (midi_in_buf) {
           jack_nframes_t nevents = jack_midi_get_event_count(midi_in_buf);
           jack_midi_event_t ev;
@@ -267,9 +249,6 @@ int process_callback(jack_nframes_t nframes, void *arg) {
             }
           }
           /* forward incoming MIDI to output during record */
-          void *midi_out_buf =
-              jack_port_get_buffer(active_channels[c].midi_out, nframes);
-          if (midi_out_buf) {
           jack_midi_clear_buffer(midi_out_buf);
           for (jack_nframes_t j = 0; j < nevents; j++) {
             if (jack_midi_event_get(&ev, midi_in_buf, j) != 0)
@@ -277,13 +256,9 @@ int process_callback(jack_nframes_t nframes, void *arg) {
             jack_midi_event_write(midi_out_buf, ev.time, ev.buffer, ev.size);
           }
         }
-        }
         break;
       }
       case STATE_LOOPING: {
-        void *midi_out_buf =
-            jack_port_get_buffer(active_channels[c].midi_out, nframes);
-        if (midi_out_buf) {
         jack_midi_clear_buffer(midi_out_buf);
         int cnt = atomic_load(&sc->loop_count);
         if (cnt > 0) {
@@ -295,20 +270,14 @@ int process_callback(jack_nframes_t nframes, void *arg) {
             jack_midi_event_write(midi_out_buf, 0, msg, 3);
           }
         }
-        }
         break;
       }
       case STATE_PAUSED:
-        /* no output */
+        jack_midi_clear_buffer(midi_out_buf);
         break;
       default: /* IDLE */
-      {
-        void *midi_in_buf =
-            jack_port_get_buffer(active_channels[c].midi_in, nframes);
-        void *midi_out_buf =
-            jack_port_get_buffer(active_channels[c].midi_out, nframes);
-        if (midi_in_buf && midi_out_buf) {
         jack_midi_clear_buffer(midi_out_buf);
+        if (midi_in_buf) {
           jack_nframes_t nevents = jack_midi_get_event_count(midi_in_buf);
           jack_midi_event_t ev;
           for (jack_nframes_t j = 0; j < nevents; j++) {
@@ -317,25 +286,30 @@ int process_callback(jack_nframes_t nframes, void *arg) {
             jack_midi_event_write(midi_out_buf, ev.time, ev.buffer, ev.size);
           }
         }
-      } break;
+        break;
       }
-      if (state == STATE_LOOPING) {
+      continue;
-        atomic_store(&sc->loop_count, atomic_load(&sc->record_pos));
     }
-    } else {
+
-      /* audio channel handling */
+    /* Audio channel handling */
-      jack_nframes_t i;
+    const jack_default_audio_sample_t *in =
+        (const jack_default_audio_sample_t *)jack_port_get_buffer(
+            channels[c].audio_in, nframes);
+    jack_default_audio_sample_t *out =
+        (jack_default_audio_sample_t *)jack_port_get_buffer(
+            channels[c].audio_out, nframes);
+    if (!out)
+      continue;
+
     switch (state) {
     case STATE_RECORD:
       if (in) {
         float *f_out = (float *)out;
         const float *f_in = (const float *)in;
-          for (i = 0; i < nframes; i++) {
+        for (jack_nframes_t i = 0; i < nframes; i++) {
-            int rp = atomic_load(&sc->record_pos);
+          int rp = atomic_fetch_add(&sc->record_pos, 1);
-            if (rp < LOOP_BUF_SIZE) {
+          if (rp < LOOP_BUF_SIZE)
             sc->loop.audio_buffer[rp] = f_in[i];
-              atomic_store(&sc->record_pos, rp + 1);
-            }
           f_out[i] = f_in[i];
         }
       } else {
@@ -348,7 +322,7 @@ int process_callback(jack_nframes_t nframes, void *arg) {
       if (loop_cnt > 0) {
         float *outf = (float *)out;
         int pp = atomic_load(&sc->playback_pos);
-          for (i = 0; i < nframes; i++) {
+        for (jack_nframes_t i = 0; i < nframes; i++) {
           outf[i] = sc->loop.audio_buffer[pp];
           pp = (pp + 1) % loop_cnt;
         }
@@ -371,12 +345,21 @@ int process_callback(jack_nframes_t nframes, void *arg) {
       }
       break;
     }
+
+    /* push loop output into save ring if saving (atomic load) */
+    RingBuf *r = (RingBuf *)atomic_load_explicit(&channels[c].save_ring,
+                                                 memory_order_acquire);
+    if (r != NULL && !atomic_load(&channels[c].save_complete)) {
+      if (state == STATE_LOOPING && atomic_load(&sc->loop_count) > 0) {
+        const float *outf = (const float *)out;
+        ring_write(r, outf, nframes);
+      }
     }
 
     atomic_store(&sc->prev_state, state);
   }
 
-  /* MIDI clock events – affect channel 0 only */
+  /* MIDI clock events – affect current scene of channel 0 */
   if (midi_clock_port) {
     void *midi_clock_buf = jack_port_get_buffer(midi_clock_port, nframes);
     if (midi_clock_buf) {
@@ -389,25 +372,22 @@ int process_callback(jack_nframes_t nframes, void *arg) {
           unsigned char msg = cev.buffer[0];
           switch (msg) {
           case 0xFA: {
-            struct channel_t *cur = atomic_load(&channels);
+            int sc0 = atomic_load(&channels[0].current_scene);
-            int sc_idx = atomic_load(&cur[0].current_scene);
+            int s = atomic_load(&channels[0].scenes[sc0].state);
-            int s = atomic_load(&cur[0].scenes[sc_idx].state);
             if (s == STATE_IDLE)
-              atomic_store(&cur[0].scenes[sc_idx].state, STATE_RECORD);
+              atomic_store(&channels[0].scenes[sc0].state, STATE_RECORD);
             break;
           }
           case 0xFC: {
-            struct channel_t *cur = atomic_load(&channels);
+            int sc0 = atomic_load(&channels[0].current_scene);
-            int sc_idx = atomic_load(&cur[0].current_scene);
+            atomic_store(&channels[0].scenes[sc0].state, STATE_IDLE);
-            atomic_store(&cur[0].scenes[sc_idx].state, STATE_IDLE);
             break;
           }
           case 0xFB: {
-            struct channel_t *cur = atomic_load(&channels);
+            int sc0 = atomic_load(&channels[0].current_scene);
-            int sc_idx = atomic_load(&cur[0].current_scene);
+            int s = atomic_load(&channels[0].scenes[sc0].state);
-            int s = atomic_load(&cur[0].scenes[sc_idx].state);
             if (s == STATE_PAUSED)
-              atomic_store(&cur[0].scenes[sc_idx].state, STATE_LOOPING);
+              atomic_store(&channels[0].scenes[sc0].state, STATE_LOOPING);
             break;
           }
           default:
@@ -418,7 +398,6 @@ int process_callback(jack_nframes_t nframes, void *arg) {
     }
   }
 
-  atomic_fetch_add_explicit(&global_rt_cycles, 1, memory_order_release);
   return 0;
 }
 
@@ -435,38 +414,47 @@ void jack_shutdown_cb(void *arg) {
  * looper initialisation
  * ---------------------------------------------------------------- */
 int looper_init(jack_client_t *client) {
+  /* store sample rate for writer thread */
+  global_sample_rate = jack_get_sample_rate(client);
+
   /* create status FIFO (ignore if already exists) */
   mkfifo(STATUS_FIFO, 0666);
 
+  /* open the status FIFO for reading+writing so writes work even without reader
+   */
+  status_fd = open(STATUS_FIFO, O_RDWR);
+  if (status_fd < 0) {
+    perror("open status FIFO");
+  }
+
   queue_init(&cmd_queue);
   queue_init(&cmd_queue_main_midi);
   queue_init(&cmd_queue_main_fifo);
 
-  /* allocate initial array for at least one channel */
+  /* start the FIFO reader thread */
-  if (ensure_capacity(client, 0) != 0) {
+  pipe_start_reader();
-    fprintf(stderr, "Cannot allocate channel array\n");
-    return -1;
-  }
-  struct channel_t *init = atomic_load(&channels);
-  /* channel 0 */
-  atomic_store(&init[0].active, 1);
-  atomic_store(&init[0].scene_count, 1);
-  atomic_store(&init[0].current_scene, 0);
-  atomic_store(&init[0].scenes[0].loop_count, 0);
-  atomic_store(&init[0].scenes[0].record_pos, 0);
-  atomic_store(&init[0].scenes[0].playback_pos, 0);
-  atomic_store(&init[0].scenes[0].state, STATE_IDLE);
-  atomic_store(&init[0].scenes[0].prev_state, -1);
 
-  init[0].audio_in = jack_port_register(
+  /* channel 0 */
+  channels[0].active = 1;
+  channels[0].type = CHANNEL_AUDIO; /* default */
+  channels[0].current_scene = 0;
+  channels[0].scene_count = 1;
+  init_scene(&channels[0].scenes[0]); /* sets state IDLE, prev_state -1 */
+  atomic_store(&channels[0].scenes[0].loop_count, 0);
+  atomic_store(&channels[0].scenes[0].record_pos, 0);
+  atomic_store(&channels[0].scenes[0].playback_pos, 0);
+  atomic_store_explicit(&channels[0].save_ring, NULL, memory_order_release);
+  atomic_store(&channels[0].save_complete, 0);
+
+  channels[0].audio_in = jack_port_register(
       client, "input", JACK_DEFAULT_AUDIO_TYPE, JackPortIsInput, 0);
-  init[0].audio_out = jack_port_register(
+  channels[0].audio_out = jack_port_register(
       client, "output", JACK_DEFAULT_AUDIO_TYPE, JackPortIsOutput, 0);
-  if (!init[0].audio_in || !init[0].audio_out) {
+  if (!channels[0].audio_in || !channels[0].audio_out) {
     fprintf(stderr, "Could not create audio ports for channel 0\n");
     return -1;
   }
-  atomic_store(&channel_count, 1);
+  channel_count = 1;
 
   midi_control_port = jack_port_register(
       client, "control", JACK_DEFAULT_MIDI_TYPE, JackPortIsInput, 0);
@@ -477,6 +465,12 @@ int looper_init(jack_client_t *client) {
     return -1;
   }
 
+  /* Give JACK time to register the ports before clients connect */
+  {
+    struct timespec req = {.tv_sec = 0, .tv_nsec = 500000000};
+    nanosleep(&req, NULL);
+  }
+
   return 0;
 }
 
@@ -484,196 +478,103 @@ int looper_init(jack_client_t *client) {
  * main‑loop command processing
  * ---------------------------------------------------------------- */
 void looper_process_commands(jack_client_t *client) {
-  /* Drain main‑loop command queues (add/remove) */
+  /* process commands from the three queues FIRST */
   command_t cmd;
-  while (queue_pop(&cmd_queue_main_midi, &cmd)) {
+  while (queue_pop(&cmd_queue, &cmd))
-    switch (cmd.type) {
+    exec_command(cmd, client);
-    case CMD_ADD_CHANNEL: {
+  while (queue_pop(&cmd_queue_main_midi, &cmd))
-      int cap = atomic_load(&channel_capacity);
+    exec_command(cmd, client);
-      int idx;
+  while (queue_pop(&cmd_queue_main_fifo, &cmd))
-      for (idx = 0; idx < cap; idx++)
+    exec_command(cmd, client);
-        if (!atomic_load(&(get_channels_array()[idx].active)))
-          break;
-      if (idx == cap) {
-        if (ensure_capacity(client, idx) != 0)
-          break;
-      }
-      channel_add(client, idx);
-      break;
-    }
-    case CMD_ADD_MIDI_CHANNEL: {
-      int cap = atomic_load(&channel_capacity);
-      int idx;
-      for (idx = 0; idx < cap; idx++)
-        if (!atomic_load(&(get_channels_array()[idx].active)))
-          break;
-      if (idx == cap) {
-        if (ensure_capacity(client, idx) != 0)
-          break;
-      }
-      channel_add_midi(client, idx);
-      break;
-    }
-    case CMD_REMOVE_CHANNEL: {
-      int cap = atomic_load(&channel_capacity);
-      int remove_idx = -1;
-      for (int idx = 1; idx < cap; idx++)
-        if (atomic_load(&(get_channels_array()[idx].active)))
-          remove_idx = idx;
-      if (remove_idx != -1) {
-        channel_remove(client, remove_idx);
-        pending_unregister_idx = remove_idx;
-        pending_unregister_cycle = atomic_load(&global_rt_cycles);
-      }
-      break;
-    }
-    case CMD_ADD_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_add_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_REMOVE_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_remove_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_NEXT_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_next_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_PREV_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_prev_scene(client, ch);
-      }
-      break;
-    }
-    default:
-      break;
-    }
-  }
-  while (queue_pop(&cmd_queue_main_fifo, &cmd)) {
-    switch (cmd.type) {
-    case CMD_ADD_CHANNEL: {
-      int cap = atomic_load(&channel_capacity);
-      int idx;
-      for (idx = 0; idx < cap; idx++)
-        if (!atomic_load(&(get_channels_array()[idx].active)))
-          break;
-      if (idx == cap) {
-        if (ensure_capacity(client, idx) != 0)
-          break;
-      }
-      channel_add(client, idx);
-      break;
-    }
-    case CMD_ADD_MIDI_CHANNEL: {
-      int cap = atomic_load(&channel_capacity);
-      int idx;
-      for (idx = 0; idx < cap; idx++)
-        if (!atomic_load(&(get_channels_array()[idx].active)))
-          break;
-      if (idx == cap) {
-        if (ensure_capacity(client, idx) != 0)
-          break;
-      }
-      channel_add_midi(client, idx);
-      break;
-    }
-    case CMD_REMOVE_CHANNEL: {
-      int cap = atomic_load(&channel_capacity);
-      int remove_idx = -1;
-      for (int idx = 1; idx < cap; idx++)
-        if (atomic_load(&(get_channels_array()[idx].active)))
-          remove_idx = idx;
-      if (remove_idx != -1) {
-        channel_remove(client, remove_idx);
-        pending_unregister_idx = remove_idx;
-        pending_unregister_cycle = atomic_load(&global_rt_cycles);
-      }
-      break;
-    }
-    case CMD_ADD_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_add_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_REMOVE_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_remove_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_NEXT_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_next_scene(client, ch);
-      }
-      break;
-    }
-    case CMD_PREV_SCENE: {
-      int cap = atomic_load(&channel_capacity);
-      int bind = atomic_load(&bind_channel);
-      int ch = bind;
-      if (ch < cap) {
-        channel_prev_scene(client, ch);
-      }
-      break;
-    }
-    default:
-      break;
-    }
-  }
 
-  /* Deferred port unregistration – wait until RT thread has seen active=0 */
+  /* Unregister any ports that were marked for deferred removal.
+     By now the real‑time thread has had at least one full cycle
+     to see the `active = 0` store. */
   if (pending_unregister_idx != -1) {
-    int current_cycle = atomic_load(&global_rt_cycles);
-    if (current_cycle - pending_unregister_cycle >= 1) {
     int idx = pending_unregister_idx;
-      struct channel_t *cur = atomic_load(&channels);
+    if (channels[idx].audio_in)
-      if (cur[idx].audio_in)
+      jack_port_unregister(client, channels[idx].audio_in);
-        jack_port_unregister(client, cur[idx].audio_in);
+    if (channels[idx].audio_out)
-      if (cur[idx].audio_out)
+      jack_port_unregister(client, channels[idx].audio_out);
-        jack_port_unregister(client, cur[idx].audio_out);
-      if (cur[idx].midi_in)
-        jack_port_unregister(client, cur[idx].midi_in);
-      if (cur[idx].midi_out)
-        jack_port_unregister(client, cur[idx].midi_out);
     pending_unregister_idx = -1;
   }
+
+  /* ---------- add channel ---------- */
+  if (atomic_exchange(&cmd_add, 0)) {
+    int idx;
+    for (idx = 0; idx < MAX_CHANNELS; idx++)
+      if (!channels[idx].active)
+        break;
+    if (idx < MAX_CHANNELS) {
+      channel_add(client, idx);
+    }
   }
 
-  /* Deferred free of old channel array – wait until RT thread has seen new
+  /* ---------- remove channel ---------- */
-   * pointer */
+  if (atomic_exchange(&cmd_remove, 0)) {
-  if (pending_old != NULL) {
+    int remove_idx = -1;
-    int current_cycle = atomic_load(&global_rt_cycles);
+    for (int idx = 1; idx < MAX_CHANNELS; idx++)
-    if (current_cycle - pending_old_cycle >= 1) {
+      if (channels[idx].active)
-      free(pending_old);
+        remove_idx = idx;
-      pending_old = NULL;
+    if (remove_idx != -1) {
+      /* Mark inactive now; ports will be unregistered next round */
+      channel_remove(client, remove_idx);
+      pending_unregister_idx = remove_idx;
+    }
+  }
+
+  /* ---------- load command ---------- */
+  if (atomic_exchange(&cmd_load, 0)) {
+    float *buf = NULL;
+    unsigned frames = 0;
+    printf("LOAD: wav_read called\n");
+    if (wav_read("loop.wav", &buf, &frames) == 0 && frames > 0) {
+      printf("LOAD: success, frames=%u\n", frames);
+      int sc_idx = atomic_load(&channels[0].current_scene);
+      scene_t *sc = &channels[0].scenes[sc_idx];
+      if (frames > LOOP_BUF_SIZE)
+        frames = LOOP_BUF_SIZE;
+      memcpy(sc->loop.audio_buffer, buf, frames * sizeof(float));
+      atomic_store(&sc->loop_count, (int)frames);
+      atomic_store(&sc->record_pos, 0);
+      atomic_store(&sc->playback_pos, 0);
+      atomic_store(&sc->state, STATE_LOOPING);
+      atomic_store(&sc->prev_state, -1);
+      free(buf);
+    } else {
+      fprintf(stderr, "Failed to load loop.wav\n");
+      printf("LOAD: FAILED\n");
+    }
+  }
+
+  /* ---------- save command (synchronous) ---------- */
+  if (atomic_exchange(&cmd_save, 0)) {
+    int sc_idx = atomic_load(&channels[0].current_scene);
+    scene_t *sc = &channels[0].scenes[sc_idx];
+    int lc = atomic_load(&sc->loop_count);
+    if (atomic_load(&sc->state) == STATE_LOOPING && lc > 0) {
+      /* Deactivate channel to prevent RT thread from reading the buffer */
+      int was_active = atomic_load(&channels[0].active);
+      if (was_active) {
+        atomic_store(&channels[0].active, 0);
+        struct timespec req = {.tv_sec = 0, .tv_nsec = 500000000}; /* 500 ms */
+        nanosleep(&req, NULL);
+      }
+      /* Now safe to copy the loop buffer */
+      float *data = malloc((size_t)lc * sizeof(float));
+      if (data) {
+        memcpy(data, sc->loop.audio_buffer, (size_t)lc * sizeof(float));
+        unsigned sr = (unsigned)global_sample_rate;
+        if (sr == 0) sr = 48000;
+        wav_write("save.wav", data, (unsigned)lc, sr);
+        free(data);
+      }
+      /* Reactivate channel – use a shorter sleep to reduce xrun risk */
+      if (was_active) {
+        struct timespec req = {.tv_sec = 0, .tv_nsec = 200000000}; /* 200 ms */
+        nanosleep(&req, NULL);
+        atomic_store(&channels[0].active, 1);
+      }
     }
   }
 

engine/src/main.c

@@ -1,6 +1,6 @@
 // cppcheck-suppress missingIncludeSystem
 #include "looper.h"
-#include "pipe.h"
+#include "log.h"
 #include <jack/jack.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -10,15 +10,20 @@
 int main(int argc, char *argv[]) {
   (void)argc;
   (void)argv;
+
+  log_init();
+  log_msg("looper engine starting");
+
   const char *client_name = "looper";
   jack_options_t options = JackNullOption;
   jack_status_t status;
 
   jack_client_t *client = jack_client_open(client_name, options, &status);
   if (client == NULL) {
-    fprintf(stderr, "jack_client_open() failed, status = 0x%2.0x\n", status);
+    log_msg("jack_client_open() failed, status = 0x%2.0x", status);
     if (status & JackServerFailed)
-      fprintf(stderr, "Unable to connect to JACK server\n");
+      log_msg("Unable to connect to JACK server");
+    log_close();
     return 1;
   }
 
@@ -29,33 +34,30 @@ int main(int argc, char *argv[]) {
   jack_on_shutdown(client, jack_shutdown_cb, NULL);
 
   if (looper_init(client) != 0) {
-    fprintf(stderr, "looper initialisation failed\n");
+    log_msg("looper initialisation failed");
-    jack_client_close(client);
-    return 1;
-  }
-
-  if (pipe_start_reader() != 0) {
-    fprintf(stderr, "pipe reader initialisation failed\n");
     jack_client_close(client);
+    log_close();
     return 1;
   }
 
   if (jack_activate(client)) {
-    fprintf(stderr, "Cannot activate client\n");
+    log_msg("Cannot activate client");
     jack_client_close(client);
+    log_close();
     return 1;
   }
 
-  fprintf(stderr, "looper running (client name '%s')\n", client_name);
+  log_msg("looper running (client name '%s')", client_name);
 
   while (1) {
     looper_process_commands(client);
     {
-      struct timespec ts = {.tv_sec = 0, .tv_nsec = 1000000};
+      struct timespec ts = {.tv_sec = 0, .tv_nsec = 50000000};
       nanosleep(&ts, NULL);
-    } /* check commands every 1 ms */
+    }
   }
 
   jack_client_close(client);
+  log_close();
   return 0;
 }

engine/src/midi.c

@@ -1,16 +1,20 @@
 // cppcheck-suppress missingIncludeSystem
 #include "midi.h"
 #include "channel.h"
-#include "command.h"
 #include "queue.h"
 #include <jack/jack.h>
 #include <jack/midiport.h>
 #include <stdatomic.h>
 
-extern atomic_int control_key_active;
+/* queues declared in looper.c */
-extern atomic_int bind_channel;
 extern spsc_queue_t cmd_queue;
 extern spsc_queue_t cmd_queue_main_midi;
+extern atomic_int control_key_active;
+extern atomic_int cmd_add;
+extern atomic_int cmd_remove;
+extern atomic_int cmd_load;
+extern atomic_int cmd_save;
+extern atomic_int bind_channel;
 
 void midi_handle_events(void *port_buffer, jack_nframes_t nframes) {
   (void)nframes;
@@ -35,27 +39,40 @@ void midi_handle_events(void *port_buffer, jack_nframes_t nframes) {
         int ck = atomic_load(&control_key_active);
         if (ck) {
           atomic_store(&control_key_active, 0);
-          if (note < 16 && note < atomic_load(&channel_capacity)) {
+          if (note < 16) {
-            command_t cmd = {
+            atomic_store(&bind_channel, note);
-                .type = CMD_BIND_CHANNEL, .channel = -1, .data = note};
-            queue_push(&cmd_queue, cmd);
           } else {
             switch (note) {
-            case 60: {
+            case 60:
-              command_t cmd = {
+              atomic_store(&cmd_add, 1);
-                  .type = CMD_ADD_CHANNEL, .channel = -1, .data = 0};
+              break;
-              queue_push(&cmd_queue_main_midi, cmd);
+            case 61:
-            } break;
+              atomic_store(&cmd_remove, 1);
-            case 61: {
+              break;
-              command_t cmd = {
+            case 62: /* trigger looper – channel via bind_channel */
-                  .type = CMD_REMOVE_CHANNEL, .channel = -1, .data = 0};
+            {
-              queue_push(&cmd_queue_main_midi, cmd);
-            } break;
-            case 62: {
               int bch = atomic_load(&bind_channel);
-              if (bch >= 0 && bch < atomic_load(&channel_capacity)) {
+              if (bch >= 0 && bch < MAX_CHANNELS) {
-                command_t cmd = {.type = CMD_CYCLE, .channel = bch, .data = 0};
+                int sc_idx = atomic_load(&channels[bch].current_scene);
-                queue_push(&cmd_queue, cmd);
+                int cur = atomic_load(&channels[bch].scenes[sc_idx].state);
+                switch (cur) {
+                case STATE_IDLE:
+                  atomic_store(&channels[bch].scenes[sc_idx].state,
+                               STATE_RECORD);
+                  break;
+                case STATE_RECORD:
+                  atomic_store(&channels[bch].scenes[sc_idx].state,
+                               STATE_LOOPING);
+                  break;
+                case STATE_LOOPING:
+                  atomic_store(&channels[bch].scenes[sc_idx].state,
+                               STATE_PAUSED);
+                  break;
+                case STATE_PAUSED:
+                  atomic_store(&channels[bch].scenes[sc_idx].state,
+                               STATE_LOOPING);
+                  break;
+                }
               }
             } break;
             case 63: {
@@ -97,19 +114,31 @@ void midi_handle_events(void *port_buffer, jack_nframes_t nframes) {
         } else {
           /* direct mapping */
           switch (note) {
-          case 1: {
+          case 1: /* toggle channel 0 */
-            command_t cmd = {.type = CMD_CYCLE, .channel = 0, .data = 0};
+          {
-            queue_push(&cmd_queue, cmd);
+            int sc0 = atomic_load(&channels[0].current_scene);
-          } break;
+            int cur0 = atomic_load(&channels[0].scenes[sc0].state);
-          case 60: {
+            switch (cur0) {
-            command_t cmd = {.type = CMD_ADD_CHANNEL, .channel = -1, .data = 0};
+            case STATE_IDLE:
-            queue_push(&cmd_queue_main_midi, cmd);
+              atomic_store(&channels[0].scenes[sc0].state, STATE_RECORD);
-          } break;
+              break;
-          case 61: {
+            case STATE_RECORD:
-            command_t cmd = {
+              atomic_store(&channels[0].scenes[sc0].state, STATE_LOOPING);
-                .type = CMD_REMOVE_CHANNEL, .channel = -1, .data = 0};
+              break;
-            queue_push(&cmd_queue_main_midi, cmd);
+            case STATE_LOOPING:
+              atomic_store(&channels[0].scenes[sc0].state, STATE_PAUSED);
+              break;
+            case STATE_PAUSED:
+              atomic_store(&channels[0].scenes[sc0].state, STATE_LOOPING);
+              break;
+            }
           } break;
+          case 60:
+            atomic_store(&cmd_add, 1);
+            break;
+          case 61:
+            atomic_store(&cmd_remove, 1);
+            break;
           default:
             break;
           }

engine/src/pipe.c

@@ -37,14 +37,14 @@ static void *pipe_thread_func(void *arg) {
 
       if (strcmp(line, "add") == 0) {
         command_t cmd = {.type = CMD_ADD_CHANNEL, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
       } else if (strcmp(line, "add_midi") == 0) {
         command_t cmd = {
             .type = CMD_ADD_MIDI_CHANNEL, .channel = -1, .data = 0};
         queue_push(&cmd_queue_main_fifo, cmd);
       } else if (strcmp(line, "remove") == 0) {
         command_t cmd = {.type = CMD_REMOVE_CHANNEL, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
       } else if (strncmp(line, "record ", 7) == 0) {
         int ch = atoi(line + 7);
         command_t cmd = {.type = CMD_CYCLE, .channel = ch, .data = 0};
@@ -61,16 +61,22 @@ static void *pipe_thread_func(void *arg) {
         queue_push(&cmd_queue, cmd);
       } else if (strcmp(line, "scene_add") == 0) {
         command_t cmd = {.type = CMD_ADD_SCENE, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
       } else if (strcmp(line, "scene_remove") == 0) {
         command_t cmd = {.type = CMD_REMOVE_SCENE, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
       } else if (strcmp(line, "scene_next") == 0) {
         command_t cmd = {.type = CMD_NEXT_SCENE, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
       } else if (strcmp(line, "scene_prev") == 0) {
         command_t cmd = {.type = CMD_PREV_SCENE, .channel = -1, .data = 0};
-        queue_push(&cmd_queue_main_fifo, cmd);
+        queue_push(&cmd_queue, cmd);
+      } else if (strcmp(line, "load") == 0) {
+        command_t cmd = {.type = CMD_LOAD, .channel = -1, .data = 0};
+        queue_push(&cmd_queue, cmd);
+      } else if (strcmp(line, "save") == 0) {
+        command_t cmd = {.type = CMD_SAVE, .channel = -1, .data = 0};
+        queue_push(&cmd_queue, cmd);
       }
       /* ignore unknown lines */
     }

engine/src/queue.h

@@ -1,6 +1,7 @@
 #ifndef QUEUE_H
 #define QUEUE_H
 
+#include <stdatomic.h>
 #include "command.h"
 #include <stdbool.h>
 
@@ -15,8 +16,8 @@ typedef struct {
     command_t  buffer[QUEUE_CAPACITY];
     /* head: index where next element will be written (producer only)
      * tail: index of next element to read (consumer only) */
-    int head;
+    atomic_int head;
-    int tail;
+    atomic_int tail;
 } spsc_queue_t;
 
 /* Initialise queue (must be called once before any push/pop). */

engine/src/ringbuffer.c

@@ -0,0 +1,65 @@
+#include "ringbuffer.h"
+#include <stdlib.h>
+
+static inline size_t load_head(const RingBuf *r) {
+  return atomic_load_explicit(&r->head, memory_order_relaxed);
+}
+static inline size_t load_tail(const RingBuf *r) {
+  return atomic_load_explicit(&r->tail, memory_order_relaxed);
+}
+static inline void store_head(RingBuf *r, size_t v) {
+  atomic_store_explicit(&r->head, v, memory_order_release); // release after data written
+}
+static inline void store_tail(RingBuf *r, size_t v) {
+  atomic_store_explicit(&r->tail, v, memory_order_release); // release after data read
+}
+
+int ring_init(RingBuf *r, size_t capacity) {
+  r->buf = (float *)malloc(capacity * sizeof(float));
+  if (!r->buf) return -1;
+  r->capacity = capacity;
+  atomic_init(&r->head, 0);
+  atomic_init(&r->tail, 0);
+  return 0;
+}
+
+void ring_destroy(RingBuf *r) {
+  free(r->buf);
+  r->buf = NULL;
+  r->capacity = 0;
+}
+
+size_t ring_write(RingBuf *r, const float *data, size_t count) {
+  size_t tail = load_tail(r);           // producer reads consumer's tail (relaxed is fine)
+  size_t head = load_head(r);           // own head
+  size_t cap = r->capacity;
+  size_t used = (head >= tail) ? (head - tail) : (cap - (tail - head));
+  size_t avail = cap - 1 - used;
+  if (count > avail) count = avail;
+  if (count == 0) return 0;
+
+  size_t pos = head;
+  for (size_t i = 0; i < count; ++i) {
+    r->buf[pos] = data[i];
+    pos = (pos + 1) % cap;
+  }
+  store_head(r, pos); // release – makes data visible to consumer
+  return count;
+}
+
+size_t ring_read(RingBuf *r, float *data, size_t count) {
+  size_t head = atomic_load_explicit(&r->head, memory_order_acquire); // acquire – see producer's writes
+  size_t tail = load_tail(r);           // own tail
+  size_t cap = r->capacity;
+  size_t used = (head >= tail) ? (head - tail) : (cap - (tail - head));
+  if (count > used) count = used;
+  if (count == 0) return 0;
+
+  size_t pos = tail;
+  for (size_t i = 0; i < count; ++i) {
+    data[i] = r->buf[pos];
+    pos = (pos + 1) % cap;
+  }
+  store_tail(r, pos); // release – makes consumer's tail visible to producer
+  return count;
+}

engine/src/ringbuffer.h

@@ -0,0 +1,19 @@
+#ifndef RINGBUFFER_H
+#define RINGBUFFER_H
+
+#include <stddef.h>
+#include <stdatomic.h>
+
+typedef struct {
+    atomic_size_t head;
+    atomic_size_t tail;
+    size_t        capacity;
+    float        *buf;
+} RingBuf;
+
+int  ring_init(RingBuf *r, size_t capacity);
+void ring_destroy(RingBuf *r);
+size_t ring_write(RingBuf *r, const float *data, size_t count);
+size_t ring_read(RingBuf *r, float *data, size_t count);
+
+#endif

engine/src/wav.c

@@ -0,0 +1,49 @@
+#include "wav.h"
+#include "channel.h"
+#include <sndfile.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+int wav_read(const char *path, float **buffer, unsigned *frames) {
+  SF_INFO info;
+  info.format = 0;
+  SNDFILE *sf = sf_open(path, SFM_READ, &info);
+  if (!sf)
+    return -1;
+
+  /* We need mono 16-bit PCM; refuse anything else */
+  if (info.channels != 1 || info.samplerate <= 0) {
+    sf_close(sf);
+    return -1;
+  }
+
+  unsigned total = (info.frames > (sf_count_t)LOOP_BUF_SIZE)
+                       ? LOOP_BUF_SIZE
+                       : (unsigned)info.frames;
+  float *buf = (float *)malloc(total * sizeof(float));
+  if (!buf) {
+    sf_close(sf);
+    return -1;
+  }
+
+  sf_count_t nread = sf_readf_float(sf, buf, total);
+  sf_close(sf);
+  *buffer = buf;
+  *frames = (unsigned)nread;
+  return 0;
+}
+
+int wav_write(const char *path, const float *data, unsigned frames,
+              unsigned sample_rate) {
+  SF_INFO info;
+  info.samplerate = sample_rate;
+  info.channels = 1;
+  info.format = SF_FORMAT_WAV | SF_FORMAT_PCM_16;
+  SNDFILE *sf = sf_open(path, SFM_WRITE, &info);
+  if (!sf)
+    return -1;
+
+  sf_writef_float(sf, data, frames);
+  sf_close(sf);
+  return 0;
+}

engine/src/wav.h

@@ -0,0 +1,9 @@
+#ifndef WAV_H
+#define WAV_H
+
+#include <stddef.h>
+
+int wav_read(const char *path, float **buffer, unsigned *frames);
+int wav_write(const char *path, const float *data, unsigned frames, unsigned sample_rate);
+
+#endif

makefile

@@ -1,14 +1,17 @@
-# Top‑level Makefile – delegates build/clean/test to subdirectories
+# Top-level Makefile – delegates build/clean/test to subdirectories
 
 SUBDIRS = engine client
 
-.PHONY: all build clean test check format $(SUBDIRS)
+.PHONY: all build clean test check format orchestrator $(SUBDIRS)
 
-all: build
+all: build orchestrator
 
 build: $(SUBDIRS)
 	@echo "Build complete."
 
+orchestrator: orchestrator.c
+	$(CC) -Wall -Wextra -std=c11 -o looper orchestrator.c
+
 $(SUBDIRS):
 	$(MAKE) -C $@
 
@@ -17,6 +20,7 @@ test:
 	$(MAKE) -C client test
 
 clean:
+	rm -f looper
 	@for dir in $(SUBDIRS); do \
 	    echo "Cleaning $$dir..."; \
 	    $(MAKE) -C $$dir clean; \

orchestrator.c

@@ -0,0 +1,51 @@
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <signal.h>
+#include <sys/wait.h>
+#include <string.h>
+
+static pid_t engine_pid = 0;
+static pid_t client_pid = 0;
+
+static void cleanup(int sig) {
+    (void)sig;
+    if (engine_pid > 0) kill(engine_pid, SIGTERM);
+    if (client_pid > 0) kill(client_pid, SIGTERM);
+    while (wait(NULL) > 0);
+    _exit(0);
+}
+
+int main(int argc, char *argv[]) {
+    signal(SIGINT, cleanup);
+    signal(SIGTERM, cleanup);
+
+    engine_pid = fork();
+    if (engine_pid == 0) {
+        execl("./engine/looper", "looper", NULL);
+        perror("execl engine");
+        _exit(1);
+    }
+
+    client_pid = fork();
+    if (client_pid == 0) {
+        if (argc > 2 && strcmp(argv[1], "-s") == 0) {
+            execl("./client/looper-client", "looper-client", "-s", argv[2], NULL);
+        } else {
+            execl("./client/looper-client", "looper-client", NULL);
+        }
+        perror("execl client");
+        _exit(1);
+    }
+
+    int status;
+    pid_t exited = wait(&status);
+    if (exited == engine_pid) {
+        kill(client_pid, SIGTERM);
+        wait(NULL);
+    } else if (exited == client_pid) {
+        kill(engine_pid, SIGTERM);
+        wait(NULL);
+    }
+    return 0;
+}