302 lines
9.2 KiB
Markdown
302 lines
9.2 KiB
Markdown
# 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
|