looper/breakup.md

# Integration Plan: Carla Plugin Host (Client‑side)

## 1. Strategy

Carla lives in the **client** (the TUI), not the looper engine.  
The client becomes a lightweight JACK client itself, capable of loading plugins via the Carla host API and bridging audio/MIDI between the looper’s JACK ports and the plugin’s ports.

## 2. Client (TUI) – new modules

### 2.1 Carla dependency
- Link the client binary with `libcarla_host` (C static/shared library).
- Use the official `carla_standalone.h` API.

### 2.2 New files `client/src/plugins.c` / `plugins.h`
Functions (same signatures as before, but run **inside the client**):

- `int plugin_load(const char *binary, const char *plugin_id, int *out_id)`
- `int plugin_unload(int id)`
- `int plugin_connect(int id, const char *port_name, const char *looper_port)`
- `int plugin_disconnect(const char *from, const char *to)`
- `void plugin_set_bypass(int id, bool bypass)`

The module owns the list of loaded plugins, their Carla‑native IDs, and the mapping between looper JACK ports and plugin ports.

### 2.3 JACK client for plugin I/O
- In `client/src/tui.c` (or a new `client/src/jack_io.c`), open a JACK client with `jack_client_open()`.
- Register input/output ports that will be connected to the looper’s ports (usually via `jack_connect` called once at start‑up).
- In the process callback, copy audio between looper ports and plugin ports (using Carla’s `process()`‑like functions).
- This keeps the engine completely unaware of plugins.

## 3. TUI commands (colon‑mode)

All already exist in the plan; only the implementation target changes:

- `:from <port>`   → describe a looper output port (e.g., `looper:out_0`)
- `:to <port>`     → destination port (e.g., `plugin1:in_left`)
- `:addplugin <path>` → loads the plugin and, if `from`/`to` are set, connects them automatically
- `:connect`       → creates a JACK‑connection between the stored `from` and `to` (or, if one side belongs to a plugin, uses Carla’s internal connect)
- `:disconnect`
- `:rack`          → toggles rack view (list of plugins with ports and bypass status)
- `:grid`          → back to the original grid view

## 4. Rack view (TUI)

Identical to the original description, but the data comes from the **client’s internal Carla handle** instead of the status FIFO.

## 5. Integration Tests

### 5.1 Mock plugin (client‑side)
- Create `client/tests/mock_plugin/mock_plugin.c`.
- A trivial JACK client that copies input to output and adds a 1 kHz tone when the input is silent.
- Compiled to `libmock_plugin.so` → the TUI’s plugin loader will load it.

### 5.2 Test infrastructure (client/tests)
- Start the TUI in a headless test mode (or fork a child and feed it commands via stdin).
- Observe the status output (sent to stdout or a temporary file) to verify plugin list and connections.

### 5.3 Test cases (new file `client/tests/test_plugin_client.c`)
- `test_plugin_load_unload` – load mock plugin, confirm list shows 1 entry, unload, confirm list empty.
- `test_plugin_connect_audio` – load plugin, connect to looper ports, inject audio from a test JACK client, verify plugin output reaches a monitor port.
- `test_rack_view` – send `:rack` command, parse the printed lines, verify they match the expected layout.
- (Later) `test_bypass` – load, bypass, verify audio passes unaltered.

## 6. Build System Changes

- **client/makefile**:
  - Add `-lcarla_host` to `LDFLAGS`.
  - Add `plugins.c` (and optionally `jack_io.c`) to `SRCS`.
  - Build mock plugin as a separate target.
- **engine/makefile** – no changes (engine stays pure looper).
- **top‑level makefile** – no changes.

## 7. Implementation Steps (ordered)

1. **Add Carla dependency & stub tests (client side)**
   - Link client binary with `-lcarla_host`.
   - Create `client/src/plugins.h` / `client/src/plugins.c` with stub implementations.
   - Create `client/tests/test_plugins.c` with failing (**Red**) unit tests for:
     - `plugin_load` returns -1 on NULL binary
     - `plugin_unload` returns -1 on invalid id
     - (optional) `plugin_connect` returns -1 on invalid id
   - Add a `test` target in `client/makefile` that builds and runs `test_plugins`.
   - Verify the tests compile and pass (**Green**).

2. **Implement real Carla integration (client side)**
   - Open a private JACK client inside the TUI using `jack_client_open()`.
   - Implement `plugin_load` / `plugin_unload` using Carla’s `carla_new_native` etc.
   - Write integration tests that load a mock plugin and verify it appears in the rack.

3. **Add `:addplugin` command parsing in TUI**
   - When colon mode is entered, parse `:addplugin <path>`.
   - Call the underlying `plugin_load` and update the internal plugin list.

4. **Implement rack view (TUI)**
   - Toggle between grid view and plugin‑list view.
   - Display plugin name, ID, bypass status.
   - Add `B`, `D`, `X` keybindings.

5. **Build mock plugin and write integration tests**
   - Create `client/tests/mock_plugin/mock_plugin.c`.
   - Target `libmock_plugin.so`.
   - Write tests in `client/tests/test_plugin_client.c`:
     - `test_plugin_load_unload`
     - `test_plugin_connect_audio`
     - `test_rack_view`

6. **Polish and document**
   - Clean up error messages, handle edge cases.
   - Add comments to new modules.
   - Update root `README` with Carla instructions.