move engine to engine/
This commit is contained in:
Loic Coenen
@@ -1,72 +0,0 @@
|
||||
# Multi‑Channel & Bind Feature
|
||||
|
||||
The looper supports up to 16 independent channels (numbered 0–15).
|
||||
Channel 0 is always present and connected to the `looper:input` / `looper:output` audio ports.
|
||||
Additional channels can be created and removed dynamically using MIDI commands.
|
||||
|
||||
## MIDI Ports
|
||||
|
||||
- **`looper:control`** – receives MIDI note‑on events for channel management and state toggling.
|
||||
- **`looper:clock`** – receives MIDI clock messages (0xFA, 0xFC, 0xFB) that affect channel 0 only.
|
||||
|
||||
## Control‑Key Modifier
|
||||
|
||||
Hold the **control key** (MIDI note 64) pressed *before* sending another note to put the looper in “command mode”.
|
||||
While control‑key is active, the next note‑on (with velocity > 0) performs a special action instead of its direct mapping.
|
||||
The control key is released either by sending note‑off (note 64 or any note) or by sending a note‑on while control‑key is already active (the action is performed and control‑key is cleared).
|
||||
|
||||
## Available Commands (under control key)
|
||||
|
||||
| Note | Action |
|
||||
|------|----------------------------------------------------------------------------------------------|
|
||||
| 0–15 | **Bind** the next `control+62` toggle to the channel with that index. |
|
||||
| 60 | **Add** a new dynamic channel (creates `channelX_input` / `channelX_output` ports). |
|
||||
| 61 | **Remove** the highest‑numbered active channel (excluding channel 0). |
|
||||
| 62 | **Toggle** the current bound channel through its state machine: |
|
||||
| | IDLE → RECORD → LOOPING → PAUSED → LOOPING → … (each press advances one step). |
|
||||
| 63 | **Unbind** – reset the bound channel back to **0**. |
|
||||
|
||||
> **Notes:**
|
||||
> - The default bound channel is **0**. If you never send a bind command, `control+62` controls channel 0.
|
||||
> - To bind a different channel, send `control + note <16>` (e.g., control + note 5 binds channel 5).
|
||||
> - Bind is sticky – it stays until overwritten by another bind command.
|
||||
> - To **unbind** (reset to channel 0), send `control + note 63`.
|
||||
|
||||
## Direct Mapping (without control key)
|
||||
|
||||
For backward compatibility, the following notes work **without** the control‑key modifier:
|
||||
|
||||
| Note | Action |
|
||||
|------|----------------------------------------------------------------------------------------------|
|
||||
| 1 | Toggle channel 0 state (IDLE→RECORD→LOOPING→PAUSED→LOOPING…). |
|
||||
| 60 | Add a dynamic channel (same as `control+60`). |
|
||||
| 61 | Remove the highest‑numbered active channel (same as `control+61`). |
|
||||
|
||||
## Example Usage
|
||||
|
||||
1. **Record a loop on channel 0 (using direct note 1)**
|
||||
- Send note‑on, note 1, velocity 127 → channel 0 enters RECORD.
|
||||
- Play some audio into `looper:input`.
|
||||
- Send note‑on, note 1, velocity 127 again → channel 0 enters LOOPING.
|
||||
- The recorded audio repeats indefinitely.
|
||||
|
||||
2. **Use the control‑key to toggle channel 0**
|
||||
- Send `note‑on, note 64` (control key).
|
||||
- Then send `note‑on, note 62` → toggles channel 0 (IDLE→RECORD).
|
||||
- Send `note‑on, note 64` again, then `note‑on, note 62` again → RECORD→LOOPING.
|
||||
|
||||
3. **Add a new channel and bind it**
|
||||
- Send `note‑on, note 64` + `note‑on, note 60` → creates channel 1.
|
||||
- Send `note‑on, note 64` + `note‑on, note 1` → binds channel 1.
|
||||
- Now `control+62` toggles channel 1 instead of channel 0.
|
||||
- Record audio on channel 1 by sending `control+62` twice.
|
||||
|
||||
4. **Remove a dynamic channel**
|
||||
- Send `note‑on, note 64` + `note‑on, note 61` → removes the highest‑numbered active channel (e.g., channel 1).
|
||||
|
||||
## Notes
|
||||
|
||||
- The looper must be connected to a running JACK server.
|
||||
- Channel buffers hold up to 5 seconds of audio at 48 kHz.
|
||||
- After removal, the channel’s audio ports are unregistered on the next main‑loop cycle (deferred to avoid race conditions).
|
||||
- The bind index is stored as an integer (0–15); values outside 0–15 are ignored (the note is processed as a command rather than a bind).
|
||||
@@ -1,38 +0,0 @@
|
||||
# Arbitrary Number of Channels
|
||||
|
||||
## Overview
|
||||
|
||||
Originally the looper had a fixed maximum of 16 channels (`MAX_CHANNELS = 16`).
|
||||
The limitation has been removed; channels are now stored in a **dynamically allocated array** that grows on demand.
|
||||
|
||||
## Implementation
|
||||
|
||||
- The global `channels` is a pointer (`struct channel_t *_Atomic channels`) instead of a fixed‑size array.
|
||||
- An atomic variable `channel_capacity` tracks the allocated size.
|
||||
- Initial allocation is for 8 channels; when a channel index >= current capacity is needed, the array is doubled.
|
||||
- The old array is **not freed immediately** – it is kept alive for at least one real‑time audio cycle (using the same deferred mechanism as port unregistration) to guarantee that the RT callback never accesses freed memory.
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Role |
|
||||
|--------------------|-----------------------------------------------------------|
|
||||
| `src/channel.h` | Removes `MAX_CHANNELS`, adds `channels` pointer declaration and `get_channels_array()` inline accessor. |
|
||||
| `src/looper.c` | Contains `ensure_capacity()`, deferred free, and replaces all fixed‑size loop bounds with `channel_capacity`. |
|
||||
| `src/channel.c` | Adapted to use the current array pointer atomically. |
|
||||
| `src/midi.c` | Uses `atomic_load(&channel_capacity)` for bounds checks. |
|
||||
|
||||
## Thread Safety During Resize
|
||||
|
||||
1. A new, larger array is allocated (`calloc`).
|
||||
2. Existing channels are copied via `memcpy`.
|
||||
3. The global `channels` pointer is swapped with `atomic_exchange`.
|
||||
4. `channel_capacity` is updated.
|
||||
5. The old pointer is stored in `pending_old` along with the current cycle count (`pending_old_cycle`).
|
||||
6. In the main loop, `pending_old` is freed only after `global_rt_cycles` has advanced by at least 1, ensuring any RT callback that loaded the old pointer has finished.
|
||||
|
||||
This is a lightweight RCU‑like pattern that avoids locks and keeps the RT path deterministic.
|
||||
|
||||
## Compatibility
|
||||
|
||||
All existing MIDI commands and FIFO pipe commands work unchanged with the dynamic array.
|
||||
The maximum practical number of channels is limited only by available memory and JACK port limits (typically 1024 per client on modern systems).
|
||||
@@ -1,65 +0,0 @@
|
||||
# Command Architecture
|
||||
|
||||
## Overview
|
||||
|
||||
The looper uses a **lock‑free, single‑producer single‑consumer (SPSC)** command queue to communicate between the real‑time JACK audio thread and the main (non‑RT) thread.
|
||||
There are two families of queues:
|
||||
|
||||
- **`cmd_queue`** (RT‑safe) – used for commands that can be handled directly inside the process callback (`CMD_CYCLE`, `CMD_STOP`, `CMD_BIND_CHANNEL`, `CMD_UNBIND`).
|
||||
The producer is the MIDI handler (`midi_handle_events`) or the FIFO pipe reader (`pipe_thread_func`); the consumer is `process_callback`.
|
||||
|
||||
- **`cmd_queue_main_midi`** / **`cmd_queue_main_fifo`** – used for commands that require memory allocation or JACK API calls (`CMD_ADD_CHANNEL`, `CMD_REMOVE_CHANNEL`).
|
||||
The producer is the MIDI handler (or FIFO reader), and the consumer is `looper_process_commands`, which runs in the main loop approximately every 50 ms.
|
||||
|
||||
## Command Types
|
||||
|
||||
The `command_t` struct (defined in `command.h`) contains:
|
||||
|
||||
- `type` – one of the `cmd_type_t` enumerators.
|
||||
- `channel` – target channel index; `-1` means “current bind channel” for some commands.
|
||||
- `data` – extra parameter (e.g., bind channel number for `CMD_BIND_CHANNEL`).
|
||||
|
||||
### RT‑safe Commands (pushed to `cmd_queue`)
|
||||
|
||||
| Type | Effect |
|
||||
|--------------------|---------------------------------------------------------------------|
|
||||
| `CMD_CYCLE` | Toggle the state machine of the target channel (IDLE→RECORD→LOOPING→PAUSED→LOOPING…). |
|
||||
| `CMD_STOP` | Force the target channel (or all channels, if `channel == -1`) to `STATE_IDLE`. |
|
||||
| `CMD_BIND_CHANNEL` | Set the global `bind_channel` index to `data`. |
|
||||
| `CMD_UNBIND` | Reset `bind_channel` to 0. |
|
||||
|
||||
### Main‑thread Commands (pushed to `cmd_queue_main_midi` / `cmd_queue_main_fifo`)
|
||||
|
||||
| Type | Effect |
|
||||
|---------------------|---------------------------------------------------------------------|
|
||||
| `CMD_ADD_CHANNEL` | Create a new dynamic channel (port registration). |
|
||||
| `CMD_REMOVE_CHANNEL`| Remove the highest‑numbered active dynamic channel (excluding channel 0). |
|
||||
|
||||
## Command Flow
|
||||
|
||||
1. **MIDI input** – `midi_handle_events` parses incoming note‑on events and decides which command to push.
|
||||
RT‑safe commands are pushed to `cmd_queue`; add/remove commands are pushed to `cmd_queue_main_midi`.
|
||||
|
||||
2. **FIFO input** – `pipe_thread_func` reads lines from `/tmp/looper_cmd` and pushes the corresponding command.
|
||||
RT‑safe commands go to `cmd_queue`; add/remove go to `cmd_queue_main_fifo`.
|
||||
|
||||
3. **Process callback** – `process_callback` is invoked by JACK for each audio cycle. It drains `cmd_queue` and applies each command via `apply_command`. This function modifies the channel state and bind index atomically.
|
||||
|
||||
4. **Main loop** – `looper_process_commands` is called in the main loop (≈ every 50 ms). It drains `cmd_queue_main_midi` and `cmd_queue_main_fifo`, performing the necessary port registrations/unregistrations and calling `channel_add` / `channel_remove`.
|
||||
|
||||
## Deferred Port Unregistration
|
||||
|
||||
When a dynamic channel is removed, the RT thread first sets `active = 0`. The main thread waits until it has seen at least one full RT cycle pass (using `global_rt_cycles`) before calling `jack_port_unregister`. This prevents a race between the RT thread still holding a reference to the port buffer and the port being unregistered.
|
||||
|
||||
## SPSC Queue Implementation
|
||||
|
||||
The queue itself (defined in `queue.c`/`queue.h`) is a simple circular buffer with head and tail indices. It uses C11 atomic loads/stores with appropriate memory ordering (`memory_order_acquire`/`memory_order_release`) to guarantee visibility without locks. Capacity is fixed at `QUEUE_CAPACITY` (256 commands). Push/pop operations are O(1) and never block.
|
||||
|
||||
## Thread Safety
|
||||
|
||||
- The JACK process callback runs in an RT thread.
|
||||
- The MIDI handler runs inside the process callback (it is called from `process_callback`).
|
||||
- The FIFO reader lives in a separate POSIX thread.
|
||||
- The main thread runs the rest of the program.
|
||||
|
||||
The two‑queue design ensures that memory‑allocating operations never happen inside the RT thread, while RT‑pertinent commands are processed with minimal latency.
|
||||
@@ -1,90 +0,0 @@
|
||||
# Per‑Channel MIDI Looping
|
||||
|
||||
## Overview
|
||||
|
||||
Each looper channel can be either **audio** or **MIDI**. Audio channels record and loop audio samples (existing behaviour). MIDI channels record and loop MIDI event sequences, using separate JACK MIDI input/output ports. The state machine (`IDLE → RECORD → LOOPING → PAUSED`) operates identically for both types.
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Source | Action |
|
||||
|----------------------------|-----------------|------------------------------------------------------------|
|
||||
| `CMD_ADD_MIDI_CHANNEL` | MIDI note 66 | Adds a new MIDI looping channel |
|
||||
| `add_midi` | FIFO pipe | Same |
|
||||
| `CMD_REMOVE_CHANNEL` | MIDI note 61 | Removes the last‑added channel (audio or MIDI) |
|
||||
| `CMD_CYCLE` | any note binding| Toggles channel state (IDLE→RECORD→LOOPING→PAUSED) |
|
||||
|
||||
## Ports
|
||||
|
||||
When a MIDI channel is created, two JACK MIDI ports are registered:
|
||||
|
||||
- `looper:channel<N>_midi_in` (input)
|
||||
- `looper:channel<N>_midi_out` (output)
|
||||
|
||||
The `<N>` is a global counter, independent of the index inside the internal channel array.
|
||||
|
||||
## Recording
|
||||
|
||||
During `STATE_RECORD`:
|
||||
|
||||
1. All incoming MIDI events on the `_midi_in` port are stored in the channel’s event buffer, along with their frame offset relative to the start of the recording.
|
||||
2. The incoming events are also **forwarded** to the `_midi_out` port, providing a direct pass‑through during recording.
|
||||
|
||||
**Buffer limit:** A channel can hold up to `MAX_MIDI_EVENTS` (1024) events.
|
||||
|
||||
## Looping
|
||||
|
||||
During `STATE_LOOPING`:
|
||||
|
||||
- All recorded events are output at the **start** of every cycle (frame 0). This is a simplification; no per‑event timestamp scheduling is implemented. The loop length is determined by the total number of recorded events.
|
||||
|
||||
## Pass‑Through
|
||||
|
||||
During `STATE_IDLE` (and `STATE_PAUSED` for MIDI) incoming MIDI events are **copied** from `_midi_in` to `_midi_out` unchanged.
|
||||
|
||||
## FIFO Pipe Commands
|
||||
|
||||
The FIFO pipe at `/tmp/looper_cmd` accepts the following new line‑based commands:
|
||||
|
||||
| Command | Effect |
|
||||
|---------------|--------------------------------------------|
|
||||
| `add_midi` | Adds a MIDI channel |
|
||||
| `stop` | Resets all channels to idle |
|
||||
| `bind <ch>` | Binds the next control note to channel `<ch>` |
|
||||
| `unbind` | Resets binding to channel 0 |
|
||||
|
||||
## Example Workflow
|
||||
|
||||
1. Start the looper.
|
||||
2. Connect a MIDI keyboard to `looper:channel1_midi_in`.
|
||||
3. Send MIDI note 66 on `looper:control` to create a MIDI channel.
|
||||
4. Send a CYCLE command (e.g., MIDI note 62 under control key) to start recording.
|
||||
5. Play notes on the keyboard – the events are captured.
|
||||
6. Send CYCLE again to enter LOOPING mode – the captured sequence repeats.
|
||||
7. Send CYCLE again to pause, or send STOP (note 65 under control key) to reset.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
- **Channel structure** (`struct channel_t` in `channel.h`):
|
||||
- `type` field (`CHANNEL_AUDIO` or `CHANNEL_MIDI`)
|
||||
- `loop` union containing `audio_buffer[MAX_BUFFER]` or `midi_events[MAX_MIDI_EVENTS]`
|
||||
- **MIDI event type** (`midi_event_t`):
|
||||
- `timestamp` (frame offset relative to loop start)
|
||||
- `status`, `note`, `velocity`
|
||||
- **Processing** (`process_callback` in `looper.c`):
|
||||
- The callback checks `type` before routing to the appropriate handler block.
|
||||
- MIDI handler reads from `midi_in` port, writes to `midi_out` port.
|
||||
- **Port cleanup**: On channel removal, both MIDI ports are unregistered via `jack_port_unregister()` after a one‑RT‑cycle grace period.
|
||||
|
||||
## Testing
|
||||
|
||||
Integration tests in `tests/integration.c` cover:
|
||||
|
||||
- `test_midi_channel_add` – verifies that sending `add_midi` via FIFO creates `looper:channel<N>_midi_in` ports.
|
||||
- `test_fifo_stop_bind_unbind` – verifies that `stop`, `bind`, and `unbind` FIFO commands are processed correctly.
|
||||
- Other existing tests continue to verify audio‑only functionality.
|
||||
|
||||
Run the test suite with:
|
||||
|
||||
```bash
|
||||
make test
|
||||
```
|
||||
@@ -1,91 +0,0 @@
|
||||
# Scene Switching Engine
|
||||
|
||||
## Overview
|
||||
|
||||
The scene switching engine allows a channel to have multiple independent recording/playback states (scenes).
|
||||
Only one scene per channel is active at a time. The active scene's state (IDLE / RECORD / LOOPING / PAUSED) is
|
||||
controlled independently of other scenes.
|
||||
|
||||
## Data Model
|
||||
|
||||
Each `channel_t` holds an array of up to `MAX_SCENES` (16) `scene_t` structures. Two atomic integers keep track
|
||||
of the number of scenes and which scene is currently active:
|
||||
|
||||
```c
|
||||
atomic_int scene_count; // number of scenes for this channel
|
||||
atomic_int current_scene; // index of the active scene (0 ≤ current_scene < scene_count)
|
||||
```
|
||||
|
||||
Each `scene_t` contains the loop buffer (audio or MIDI events) and the per‑scene atomic state:
|
||||
|
||||
```c
|
||||
union {
|
||||
float audio_buffer[LOOP_BUF_SIZE];
|
||||
midi_event_t midi_events[MAX_MIDI_EVENTS];
|
||||
} loop;
|
||||
|
||||
atomic_int loop_count;
|
||||
atomic_int record_pos;
|
||||
atomic_int playback_pos;
|
||||
atomic_int state; // STATE_IDLE / STATE_RECORD / STATE_LOOPING / STATE_PAUSED
|
||||
atomic_int prev_state; // previous state (used by RT callback to detect transitions)
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Trigger (MIDI) | Trigger (FIFO) | Effect |
|
||||
|--------------------------|------------------------|-----------------------|---------------------------------------------------------|
|
||||
| **CMD_NEXT_SCENE** | note 67 (control key) | `scene_next\n` | Increments `current_scene` (wraps around). |
|
||||
| **CMD_PREV_SCENE** | note 68 (control key) | `scene_prev\n` | Decrements `current_scene` (wraps around). |
|
||||
| **CMD_ADD_SCENE** | note 69 (control key) | `scene_add\n` | Appends a new empty scene, increments `scene_count`. |
|
||||
| **CMD_REMOVE_SCENE** | note 70 (control key) | `scene_remove\n` | Removes the current scene (shifts remaining scenes). |
|
||||
|
||||
All scene commands are processed on the main loop (not in the RT callback). They are pushed to
|
||||
`cmd_queue_main_midi` (for MIDI) or `cmd_queue_main_fifo` (for FIFO) and applied by
|
||||
`looper_process_commands()`.
|
||||
|
||||
## Thread Safety
|
||||
|
||||
- `scene_count` and `current_scene` are `atomic_int`; all reads/writes use `atomic_load`/`atomic_store`.
|
||||
- The per‑scene fields (`loop_count`, `record_pos`, `playback_pos`, `state`, `prev_state`) are also `atomic_int`,
|
||||
so the RT callback and the main loop can safely read and write them concurrently.
|
||||
- The audio loop buffer itself (a plain `float` array) is not atomic. During scene removal the buffer is copied
|
||||
via `memcpy`. If a scene is actively looping, this copy may produce a temporarily inconsistent buffer.
|
||||
**Known limitation:** scene removal should only be performed when the channel is idle (all scenes in
|
||||
`STATE_IDLE`). The integration test `test_scene_add_remove` does exactly this.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
1. **`channel_add_scene`**
|
||||
- Called from main loop.
|
||||
- Checks `scene_count < MAX_SCENES` (atomically).
|
||||
- Calls `init_scene()` to zero the new scene and set its state to `STATE_IDLE`.
|
||||
- Atomically increments `scene_count`.
|
||||
|
||||
2. **`channel_remove_scene`**
|
||||
- Called from main loop.
|
||||
- Refuses if `scene_count <= 1` (at least one scene must always exist).
|
||||
- Shifts all scenes after the current one down one position – each scene field is copied with
|
||||
`atomic_store`/`atomic_load`.
|
||||
- The audio buffer is copied with `memcpy` (see limitation above).
|
||||
- Decrements `scene_count` and adjusts `current_scene` if it would become out of bounds.
|
||||
|
||||
3. **`channel_next_scene` / `channel_prev_scene`**
|
||||
- Called from main loop.
|
||||
- If `scene_count > 1`, atomically increments/decrements `current_scene` (wrapping using modulo).
|
||||
|
||||
4. **RT callback (`process_callback`)**
|
||||
- At the start of each frame it reads `current_scene` atomically to obtain the scene index for that
|
||||
channel.
|
||||
- All per‑scene reads (state, loop_count, record_pos, playback_pos) use `atomic_load`.
|
||||
- When the state changes, the callback atomically resets `record_pos`, `loop_count`, `playback_pos`
|
||||
as appropriate.
|
||||
|
||||
## Tests
|
||||
|
||||
- `test_scene_add_remove` (FIFO) – adds a scene, cycles next, removes the scene, exits.
|
||||
- `test_scene_next_prev_midi` – sends control key + notes 67/68 to switch scenes.
|
||||
- `test_scene_cycle_per_scene` – records a loop on scene 0, switches to scene 1, verifies scene 1 is idle.
|
||||
- `test_scene_add_remove_midi` – sends control key + notes 69/70 to add/remove scenes.
|
||||
|
||||
All scene tests pass as part of `make test`.
|
||||
Reference in New Issue
Block a user