137 lines
8.2 KiB
Markdown
137 lines
8.2 KiB
Markdown
# Plan: Refactor TUI into Standalone FIFO‑Client Binary
|
||
|
||
## Goal
|
||
Extract the TUI from the existing monolithic codebase into a separate `looper-client` binary that communicates with the engine **only** via the FIFO pipe (`/tmp/looper_cmd`).
|
||
The TUI must **not** link to any engine source files (`engine.c`, `dispatcher.c`, `carla.c`, etc.) or use their headers beyond shared type definitions (e.g., `command.h`). All state is maintained by the engine; the TUI sends commands and assumes they succeed.
|
||
|
||
## Background
|
||
- The looper engine runs as a separate JACK client and listens for commands on:
|
||
- FIFO pipe (`/tmp/looper_cmd`) – text‑based commands
|
||
- `looper:control` – MIDI note‑on events
|
||
- The current TUI uses a local `Engine` / `AppState` / `dispatcher` that does **not** talk to the real looper. It was designed for unit testing.
|
||
|
||
## Task 1 – Create a new `client/` directory structure
|
||
- Keep existing `client/src/tui.c` and `client/src/tui.h`.
|
||
- Remove all `#include` directives that reference engine internal headers:
|
||
- `engine.h`
|
||
- `dispatcher.h`
|
||
- `wav_io.h`
|
||
- `transport.h`
|
||
- `carla.h`
|
||
- Remove any `Engine*`, `AppState`, `DispatchFn`, `Clip`, `MidiClip` usage.
|
||
- **Keep** the `FuzzySearch` struct, `draw_rack_view()`, `handle_rack_view()`, `list_wav_files()`, `load_sample_callback`, mouse handling, etc. – they **are not removed**.
|
||
However, every call to engine internals (e.g., `carla_get_available_plugins`, `dispatcher_get_state`, `g_dispatch`, `carla.h` functions) **must be replaced** with a stub that does nothing (or prints a debug message) until the engine implements the corresponding FIFO commands.
|
||
This keeps the UI code compilable and preserves the structure for future implementation.
|
||
|
||
## Task 2 – Implement `send_command()` and open FIFO
|
||
- Add a function:
|
||
|
||
```c
|
||
int send_command(const char *cmd_line);
|
||
```
|
||
|
||
This function:
|
||
- Opens `/tmp/looper_cmd` with `O_WRONLY`.
|
||
- Writes the command string (e.g., `"record 0\n"`).
|
||
- Appends a newline if missing.
|
||
- Closes the file descriptor.
|
||
- Returns 0 on success, -1 on error (prints diagnostic to stderr).
|
||
|
||
- The TUI should call `send_command()` for every user action that should affect the engine.
|
||
|
||
## Task 3 – Map TUI keys to FIFO commands
|
||
Replace each `g_dispatch(action)` with a direct FIFO command string.
|
||
|
||
**Proposed mapping (simplified – can be refined later):**
|
||
|
||
| TUI key/action | FIFO command |
|
||
|--------------------------------------------|-----------------------------------------------------|
|
||
| `'t'` (trigger clip at selected cell) | `record <channel>\n` (channel = `selected_col`) |
|
||
| `'d'` (reset clip) | `stop\n` (global stop) |
|
||
| `'s'` (trigger scene – current row) | `"scene_next\n"` (or `"scene_add\n"`? TBD) |
|
||
| `' '` (toggle transport play/pause) | No corresponding FIFO command yet. Omit for now. |
|
||
| `'S'` (stop transport) | `"stop\n"` |
|
||
| `'q'` (cycle quantize) | No FIFO equivalent – ignore. |
|
||
| `'x'` (reset transport) | `"stop\n"` |
|
||
| `'N'` (play next scene) | `"scene_next\n"` |
|
||
| `'P'` (play previous scene) | `"scene_prev\n"` |
|
||
| `'u'` (undo) | No FIFO equivalent – ignore. |
|
||
| `Ctrl+R` (redo) | Ignore. |
|
||
| `'v'`, `'V'` (visual mode) | Keep visual selection logic but send commands only for `'d'` and `'y'` actions. |
|
||
| `'y'` (yank) | Do nothing (local clipboard only). |
|
||
| `'p'` (paste) | For each pasted cell send `"record <ch>\n"`. |
|
||
| `'m'` (move mode) | No effect on engine – local navigation. |
|
||
| `'z'` (zoom grid selector) | Local navigation only. |
|
||
| `'G'` (toggle audio/MIDI grid) | No FIFO command – ignore. |
|
||
| `'-'` / `'='` (volume) | No FIFO command – ignore. |
|
||
| `\t` (switch to rack view) | Remove entirely. |
|
||
| `':'` command mode | Keep for `:q` (quit) and `:rack` commands (the latter can be removed). |
|
||
| Escape / `'Q'` | Quit the TUI (no command sent). |
|
||
|
||
**Channel binding:**
|
||
- When the user moves selection to a new column, send `"bind <col>\n"` to ensure subsequent commands affect the correct channel. This can be done in the navigation switch cases.
|
||
|
||
## Task 4 – Remove all references to `Engine` and `dispatcher`
|
||
- Delete the lines:
|
||
- `static Engine *g_engine = NULL;`
|
||
- `static DispatchFn g_dispatch = NULL;`
|
||
- Replace calls like `g_dispatch(action)` with `send_command(formatted_string)`.
|
||
- Remove `dispatcher_get_state()` calls – the TUI will no longer query the engine state. Update `draw_cell()` to display only static info (clip index) or a fixed colour (e.g., all green). The state‑dependent colouring is not available without feedback from the engine. For now, show all cells as idle (white) or use a placeholder.
|
||
- Remove the line `AppState state; dispatcher_get_state(&state);` inside draw functions.
|
||
|
||
## Task 5 – Simplify the `tui.h` header
|
||
- Replace the function signatures:
|
||
|
||
```c
|
||
void tui_init(void); // no Engine* argument
|
||
void tui_run(void); // no Engine* argument
|
||
void tui_cleanup(void);
|
||
```
|
||
|
||
- Remove `#include "engine.h"` and `#include "dispatcher.h"`.
|
||
- Remove the `Engine*` parameter from the init and run functions.
|
||
|
||
## Task 6 – Create `client/main.c`
|
||
- Write a simple `main()` that:
|
||
- Optionally opens the FIFO for writing just to check it exists.
|
||
- Calls `tui_init()`.
|
||
- Calls `tui_run()`.
|
||
- Calls `tui_cleanup()`.
|
||
- Returns 0.
|
||
|
||
## Task 7 – Write `client/makefile`
|
||
- Target `looper-client`:
|
||
- Compile `src/tui.c` and `src/main.c` (or `src/client.c` if split).
|
||
- **Do not** link to any engine `.o` files.
|
||
- Link only with `-lncurses` (and `-lm` if needed).
|
||
- Example:
|
||
```makefile
|
||
CC ?= gcc
|
||
CFLAGS ?= -Wall -Wextra -g -I../engine/src
|
||
LDFLAGS ?= -lncurses -lm
|
||
|
||
looper-client: src/tui.c src/main.c
|
||
$(CC) $(CFLAGS) -o $@ $^ $(LDFLAGS)
|
||
```
|
||
|
||
## Task 8 – Remove dead code and unnecessary helpers
|
||
- Delete `utils.c` / `utils.h` if they existed only for TUI – but keep all WAV‑related, rack‑related, and fuzzy‑search code (they are now stubs).
|
||
- Remove `clip_state_to_string()`, `transport_state_to_string()`, `quantize_mode_to_string()`, `clock_source_to_string()` – they are no longer used for display because we have no `AppState`.
|
||
Replace them with static strings that show placeholder text (e.g., `"N/A"`).
|
||
- Remove `state_to_color()` – instead use a fixed colour pair (e.g., all cells white) or remove colour entirely, because we have no clip state.
|
||
- Remove the `mouse` callback if it relied on `dispatcher_get_state` – but keep the function body as a no‑op.
|
||
|
||
## Task 9 – Test the new client
|
||
- Build `looper-client` and verify it compiles without engine object files.
|
||
- Start the engine (`./looper` in `engine/`).
|
||
- Run `./looper-client` and press keys that should generate FIFO commands. Use `cat /tmp/looper_cmd` in another terminal to verify output.
|
||
- Check that commands like `record 2`, `stop`, `bind 3` appear.
|
||
|
||
## Notes / Future Improvements
|
||
- **State feedback:** The TUI currently shows clip state colours. To restore that, a separate FIFO (or shared memory) for engine‑>client status could be added. Not part of this plan.
|
||
- **MIDI grid / rack view:** These depend on engine features not yet exposed via FIFO. They are removed; can be re‑added later.
|
||
- **Transport commands:** The engine does not have a dedicated transport play/pause command via FIFO; it relies on MIDI notes. Future FIFO extension needed.
|
||
|
||
This plan produces a clean, minimal client that interfaces only through the named pipe.
|
||
````
|