Johan Le Baut il y a 1 heure
commit
f8dd25e65d

+ 71 - 0
README.md

@@ -0,0 +1,71 @@
+# Rigforge
+
+## Scope
+
+Rigforge is a standalone Raspberry Pi audio pedalboard. The desired routing is described in `config/desired-state.yaml`. Hardware-specific ports and operational settings remain provisional until tested on the target.
+
+## Current target observations
+
+The current target reports Debian GNU/Linux 13.7, AArch64, and a Behringer UMC404HD 192k. ALSA advertises four capture and four playback channels. PipeWire 1.4.2 and WirePlumber are active in the logged-in `jojo` user session, with `Linger=no`.
+
+PipeWire exposed four capture channels named `capture_AUX0` through `capture_AUX3` and four playback channels named `playback_AUX0` through `playback_AUX3`. A four-channel 48 kHz recording was completed, with the guitar on physical input 1 appearing on `capture_AUX0` and the microphone on physical input 3 appearing on `capture_AUX2`; the other channels were at noise floor during that test. A temporary PipeWire link from `capture_AUX0` to `playback_AUX0` produced audible guitar. The target owner reports that `playback_AUX0` feeds output 1L and that Main Out L receives 1L with MIX set to PB and MONITOR set to A. The owner then added `capture_AUX2` and confirmed hearing both guitar and microphone with a 128-frame quantum at 48 kHz; this is an initial successful low-latency listening test, not yet a sustained dropout or headroom measurement. Monitoring duplication, clipping headroom under summed sources and loop returns, and MIDI/OSC behavior have not yet been tested.
+
+The target has `aconnect`, `amidi`, and `oscsend`; ALSA lists the UMC404HD MIDI port. This does not yet verify FCB1010 messages or SooperLooper OSC availability. `amixer -D hw:2 scontents` showed capture and playback controls at 0 dB; no mixer settings have been changed.
+
+## Target preparation recorded so far
+
+Before collecting the target observations, the following commands were run on the current Raspberry Pi OS Lite installation:
+
+```sh
+sudo apt update
+sudo apt upgrade
+sudo apt install --no-install-recommends \\
+  rtkit pipewire pipewire-jack wireplumber \\
+  libspa-0.2-modules liblo-tools
+```
+
+This records the preparation already performed on `rigforge` and is a starting point for documenting a second Pi. It is not yet a verified, version-pinned rebuild procedure: package versions, additional runtime dependencies, audio configuration, and service setup still need to be confirmed before reusing it as a complete deployment recipe.
+
+## Repository layout
+
+- `config/desired-state.yaml`: versioned desired audio topology and provisional target mapping.
+- `config/sooperlooper/fcb1010.slb`: supplied FCB1010 binding file, pending on-target verification.
+- `build/sooperlooper/`: reserved for the later ARM64 Docker build definition.
+- `scripts/validate_desired_state.py`: validates topology and routing invariants without changing the target.
+- `tests/test_desired_state.py`: unit tests for desired-state validation.
+- `artifacts/sooperlooper/arm64/`: reserved for an artifact and its provenance, subject to repository hosting limits and redistribution terms.
+
+The YAML describes desired state; a control surface is not a second source of truth. The initial audio profile declares 48 kHz and a quantum of 128 frames, which was reported to sound good during a temporary target test. At 48 kHz, 128 frames is about 2.7 ms per period, not the end-to-end latency. This runtime value has not yet been made persistent or measured under sustained load; apply it temporarily on the target with `pw-metadata -n settings 0 clock.force-quantum 128` and return to automatic selection with `pw-metadata -n settings 0 clock.force-quantum 0`. Concrete PipeWire ports, buffer settings, package names, services, and artifact installation path will only be recorded as verified after target tests.
+
+Validate the desired-state file on the development PC with:
+
+```sh
+python3 scripts/validate_desired_state.py
+python3 -m unittest discover -s tests -v
+```
+
+The validator checks that there are four distinct physical inputs, one four-channel looper with each source assigned once, a declared mix output, and no active or planned route from looper returns back to looper inputs. It is read-only and does not connect audio ports or modify the target.
+
+## Development PC
+
+The development host is Ubuntu AMD64 with Docker. The SooperLooper source under evaluation is <https://github.com/abarker/sooperlooper-mods>. The Docker build procedure is intentionally not yet provided: first select a tag and inspect that tag's build instructions and licensing. The eventual build command must take an explicit tag, resolve and record its exact commit, build for ARM64, and record artifact architecture, runtime dependencies, provenance, and checksum. The container is for building only; SooperLooper will run natively on the Raspberry Pi.
+
+No SooperLooper artifact or Dockerfile is included at this stage.
+
+## `rigforge` target
+
+No packages, artifacts, services, or permanent audio configuration have been installed or changed by this initial increment. A temporary direct PipeWire test linked `capture_AUX0` and `capture_AUX2` to `playback_AUX0`; guitar and microphone were heard together at 48 kHz / 128 frames. `pw-top` showed the active capture driver at 128 frames with `ERR = 0` during the reported test. The temporary links have since been removed. This is an initial listening check, not a sustained load, dropout, or headroom test.
+
+The next target checks are:
+
+1. Confirm the software-mixed direct path and its gain staging before adding processing or looper returns.
+2. Later, test inputs 2 and 4 with sources when available; for planning only, the four existing capture channels are assumed to work.
+3. Measure sustained stability and headroom at 48 kHz / 128 frames with all active sources; the current `ERR = 0` observation was brief.
+4. Inspect the user service session and resource limits before defining autonomous startup. `Linger=no` currently means the running audio session is associated with the active login; unattended startup is not established.
+5. Verify FCB1010 MIDI messages and the supplied bindings with the eventual SooperLooper build. Verify OSC port readiness and the effect and persistence of `discrete_prefader 0` separately.
+
+Do not treat planned packages, commands, ports, or service settings as target-validated until these checks have been performed.
+
+## Deployment and rollback
+
+Deployment is manual: inspect and test a change, then use `git pull` on `rigforge` only when the change is ready. No CI/CD or auto-pull is configured. Service installation, activation, logs, diagnostics, and rollback commands will be documented after their units and target paths have been tested. Keep the last known working revision available; do not apply unverified audio or service changes during live use.

+ 151 - 0
config/desired-state.yaml

@@ -0,0 +1,151 @@
+---
+schema_version: 1
+
+system:
+  target:
+    hostname: rigforge
+    os_family: debian
+    os_version: "13"
+    architecture: aarch64
+  audio_stack:
+    pipewire: expected
+    wireplumber: expected
+    user_services: expected
+  components:
+    - id: audio-interface
+      kind: audio-interface
+      model: Behringer UMC404HD 192k
+      observed: true
+    - id: looper
+      kind: multichannel-looper
+      software: SooperLooper
+      instance_count: 1
+      loop_count: 1
+      channels_per_loop: 4
+      required_for_initial_audio_test: false
+    - id: midi-controller
+      kind: midi-controller
+      model: Behringer FCB1010
+      connection: UMC404HD MIDI 1
+      observed_by_alsa: true
+    - id: control-surface
+      kind: optional-observer
+      software: Open Stage Control
+      required_for_audio: false
+
+modes:
+  live:
+    standalone: true
+    network_required_for_audio: false
+  studio:
+    enabled: false
+    transport: ethernet
+
+sources:
+  - id: guitar
+    physical_input: 1
+    channel: mono
+    capture_port: alsa_input.hw_U192k_0:capture_AUX0
+    treatments: []
+    destinations:
+      - direct_mix
+      - looper_input_1
+  - id: bass
+    physical_input: 2
+    channel: mono
+    capture_port: alsa_input.hw_U192k_0:capture_AUX1
+    treatments: []
+    destinations:
+      - direct_mix
+      - looper_input_2
+  - id: voice
+    physical_input: 3
+    channel: mono
+    capture_port: alsa_input.hw_U192k_0:capture_AUX2
+    treatments: []
+    destinations:
+      - direct_mix
+      - looper_input_3
+  - id: synth
+    physical_input: 4
+    channel: mono
+    capture_port: alsa_input.hw_U192k_0:capture_AUX3
+    treatments: []
+    destinations:
+      - direct_mix
+      - looper_input_4
+
+routing:
+  status: provisional-unverified
+  looper_inputs:
+    - source: guitar
+      channel: 1
+    - source: bass
+      channel: 2
+    - source: voice
+      channel: 3
+    - source: synth
+      channel: 4
+  mix:
+    id: direct_mix
+    channel: mono
+    includes:
+      - guitar
+      - bass
+      - voice
+      - synth
+      - looper_returns
+    output_port: alsa_output.hw_U192k_0:playback_AUX0
+    output_port_status: verified-reported-target-mapping
+    physical_output: UMC output 1L to Main Out L
+    hardware_monitor_settings:
+      mix: PB
+      monitor: A
+    hardware_output_status: reported-by-target-owner
+  looper_returns:
+    destination: direct_mix
+    feed_looper_inputs: false
+  monitoring:
+    hardware_monitoring: verify-on-target
+    software_monitoring: verify-on-target
+    avoid_duplicate_monitoring: true
+  level_management:
+    source_sum: verify-headroom-on-target
+    overdub_sum: verify-headroom-on-target
+    return_sum: verify-headroom-on-target
+  physical_output_label: UMC output 1L to Main Out L
+  physical_output_status: reported-by-target-owner
+
+parameters:
+  sample_rate_hz: 48000
+  quantum_frames: 128
+  quantum_status: initial-target-value-tested-temporarily
+  quantum_apply_method: PipeWire clock.force-quantum runtime setting
+  audio_test_level: low
+  reconciliation_mode: observe-only
+
+connections:
+  - from: capture_AUX0
+    to: guitar
+    status: observed-port-unverified-operation
+  - from: capture_AUX1
+    to: bass
+    status: observed-port-unverified-operation
+  - from: capture_AUX2
+    to: voice
+    status: observed-port-unverified-operation
+  - from: capture_AUX3
+    to: synth
+    status: observed-port-unverified-operation
+  - from: direct_mix
+    to: playback_AUX0
+    status: candidate-unverified-physical-output
+  - from: looper_returns
+    to: direct_mix
+    status: planned
+  - from: looper_returns
+    to: looper_inputs
+    status: explicitly-forbidden
+  - from: UMC404HD-MIDI-1
+    to: SooperLooper-MIDI
+    status: observed-device-unverified-routing

+ 14 - 0
config/sooperlooper/fcb1010.slb

@@ -0,0 +1,14 @@
+0 n 1  note record_or_overdub 0  0 1  norm 0 127
+0 n 2  note undo 0  0 1  norm 0 127
+0 n 3  note redo 0  0 1  norm 0 127
+0 n 4  note mute 0  0 1  norm 0 127
+0 n 5  note mute_trigger 0  0 1  norm 0 127
+0 on 10  set select_next_loop 0  0 1  norm 0 127
+0 n 11  note record_or_overdub 0  0 1  norm 0 127
+0 n 12  note undo 0  0 1  norm 0 127
+0 n 13  note redo 0  0 1  norm 0 127
+0 n 14  note mute 0  0 1  norm 0 127
+0 on 20  set select_next_loop 0  0 1  norm 0 127
+0 cc 109  set wet 0  0 1  gain 0 127
+0 cc 111  set wet 0  0 1  gain 0 127
+0 cc 114  set pitch_shift 0  -12 12  integer 0 127

BIN
scripts/__pycache__/validate_desired_state.cpython-310.pyc


+ 184 - 0
scripts/validate_desired_state.py

@@ -0,0 +1,184 @@
+import argparse
+import sys
+from pathlib import Path
+
+import yaml
+
+
+def validate_state(state):
+    errors = []
+    if not isinstance(state, dict):
+        return ["document root must be a mapping"]
+
+    # Establish the declared source map before validating looper references.
+    sources = state.get("sources")
+    if not isinstance(sources, list):
+        return ["sources must be a list"]
+
+    source_by_id = {}
+    physical_inputs = set()
+    capture_ports = set()
+    for index, source in enumerate(sources):
+        location = f"sources[{index}]"
+        if not isinstance(source, dict):
+            errors.append(f"{location} must be a mapping")
+            continue
+        source_id = source.get("id")
+        if not isinstance(source_id, str) or not source_id:
+            errors.append(f"{location}.id must be a non-empty string")
+        elif source_id in source_by_id:
+            errors.append(f"duplicate source id: {source_id}")
+        else:
+            source_by_id[source_id] = source
+
+        physical_input = source.get("physical_input")
+        if not isinstance(physical_input, int) or isinstance(physical_input, bool):
+            errors.append(f"{location}.physical_input must be an integer")
+        elif physical_input in physical_inputs:
+            errors.append(f"duplicate physical input: {physical_input}")
+        else:
+            physical_inputs.add(physical_input)
+
+        capture_port = source.get("capture_port")
+        if not isinstance(capture_port, str) or not capture_port:
+            errors.append(f"{location}.capture_port must be a non-empty string")
+        elif capture_port in capture_ports:
+            errors.append(f"duplicate capture port: {capture_port}")
+        else:
+            capture_ports.add(capture_port)
+
+    # Keep the first four-channel milestone tied to its four named instruments.
+    expected_source_ids = {"guitar", "bass", "voice", "synth"}
+    if set(source_by_id) != expected_source_ids:
+        errors.append("source ids must be guitar, bass, voice, and synth exactly once")
+    if len(sources) != 4:
+        errors.append(f"exactly four sources are required, got {len(sources)}")
+    if physical_inputs != {1, 2, 3, 4}:
+        errors.append("physical inputs must cover 1 through 4 exactly once")
+
+    # The required looper is one instance containing one four-channel loop.
+    system = state.get("system")
+    components = system.get("components") if isinstance(system, dict) else None
+    if not isinstance(components, list):
+        errors.append("system.components must be a list")
+        components = []
+    loopers = [item for item in components if isinstance(item, dict) and item.get("id") == "looper"]
+    if len(loopers) != 1:
+        errors.append(f"exactly one looper component is required, got {len(loopers)}")
+    elif loopers[0].get("instance_count") != 1:
+        errors.append("looper.instance_count must be 1")
+    elif loopers[0].get("loop_count") != 1:
+        errors.append("looper.loop_count must be 1")
+    elif loopers[0].get("channels_per_loop") != 4:
+        errors.append("looper.channels_per_loop must be 4")
+
+    routing = state.get("routing")
+    if not isinstance(routing, dict):
+        errors.append("routing must be a mapping")
+        return errors
+
+    looper_inputs = routing.get("looper_inputs")
+    if not isinstance(looper_inputs, list):
+        errors.append("routing.looper_inputs must be a list")
+        looper_inputs = []
+    # Check that each source is assigned exactly once across all loop channels.
+    input_channels = set()
+    input_sources = set()
+    for index, loop_input in enumerate(looper_inputs):
+        location = f"routing.looper_inputs[{index}]"
+        if not isinstance(loop_input, dict):
+            errors.append(f"{location} must be a mapping")
+            continue
+        source_id = loop_input.get("source")
+        channel = loop_input.get("channel")
+        if source_id not in source_by_id:
+            errors.append(f"{location}.source references unknown source: {source_id}")
+        if source_id in input_sources:
+            errors.append(f"source is assigned to multiple looper inputs: {source_id}")
+        input_sources.add(source_id)
+        if not isinstance(channel, int) or isinstance(channel, bool) or channel not in range(1, 5):
+            errors.append(f"{location}.channel must be an integer from 1 through 4")
+        elif channel in input_channels:
+            errors.append(f"duplicate looper input channel: {channel}")
+        else:
+            input_channels.add(channel)
+    if len(looper_inputs) != 4 or input_channels != {1, 2, 3, 4}:
+        errors.append("looper inputs must cover channels 1 through 4 exactly once")
+    if input_sources != set(source_by_id):
+        errors.append("each declared source must map to exactly one looper input")
+
+    mix = routing.get("mix")
+    if not isinstance(mix, dict):
+        errors.append("routing.mix must be a mapping")
+    else:
+        output_port = mix.get("output_port")
+        if not isinstance(output_port, str) or not output_port:
+            errors.append("routing.mix.output_port must be a non-empty string")
+        mix_id = mix.get("id")
+        if not isinstance(mix_id, str) or not mix_id:
+            errors.append("routing.mix.id must be a non-empty string")
+        includes = mix.get("includes")
+        if not isinstance(includes, list) or "looper_returns" not in includes:
+            errors.append("routing.mix.includes must include looper_returns")
+
+    # Loop returns join the output mix but must never feed the loop inputs.
+    returns = routing.get("looper_returns")
+    if not isinstance(returns, dict):
+        errors.append("routing.looper_returns must be a mapping")
+    elif returns.get("feed_looper_inputs") is not False:
+        errors.append("routing.looper_returns.feed_looper_inputs must be false")
+
+    connections = state.get("connections", [])
+    if not isinstance(connections, list):
+        errors.append("connections must be a list")
+        connections = []
+    # An explicitly-forbidden connection documents policy; any other status is actionable.
+    for index, connection in enumerate(connections):
+        if not isinstance(connection, dict):
+            errors.append(f"connections[{index}] must be a mapping")
+            continue
+        if (
+            connection.get("from") == "looper_returns"
+            and connection.get("to") in {
+                "looper_inputs",
+                "looper_input_1",
+                "looper_input_2",
+                "looper_input_3",
+                "looper_input_4",
+            }
+            and connection.get("status") != "explicitly-forbidden"
+        ):
+            errors.append(f"connections[{index}] routes looper returns into looper inputs")
+
+    return errors
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "state_file",
+        nargs="?",
+        type=Path,
+        default=Path(__file__).resolve().parents[1] / "config" / "desired-state.yaml",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        with args.state_file.open(encoding="utf-8") as state_stream:
+            state = yaml.safe_load(state_stream)
+    except (OSError, yaml.YAMLError) as error:
+        print(f"Unable to load {args.state_file}: {error}", file=sys.stderr)
+        return 2
+
+    errors = validate_state(state)
+    if errors:
+        for error in errors:
+            print(f"ERROR: {error}", file=sys.stderr)
+        return 1
+
+    print(f"Valid desired state: {args.state_file}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

BIN
tests/__pycache__/test_desired_state.cpython-310.pyc


+ 71 - 0
tests/test_desired_state.py

@@ -0,0 +1,71 @@
+import copy
+import sys
+import unittest
+from pathlib import Path
+
+import yaml
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+from validate_desired_state import validate_state
+
+
+class DesiredStateValidationTests(unittest.TestCase):
+    @classmethod
+    def setUpClass(cls):
+        with (ROOT / "config" / "desired-state.yaml").open(encoding="utf-8") as stream:
+            cls.state = yaml.safe_load(stream)
+
+    def test_current_desired_state_is_valid(self):
+        self.assertEqual(validate_state(self.state), [])
+
+    def test_requires_four_sources_and_unique_physical_inputs(self):
+        state = copy.deepcopy(self.state)
+        state["sources"][0]["physical_input"] = 2
+        errors = validate_state(state)
+        self.assertTrue(any("duplicate physical input" in error for error in errors))
+        self.assertTrue(any("physical inputs must cover 1 through 4" in error for error in errors))
+
+        state = copy.deepcopy(self.state)
+        state["sources"].pop()
+        errors = validate_state(state)
+        self.assertTrue(any("exactly four sources" in error for error in errors))
+
+    def test_requires_one_four_channel_loop(self):
+        state = copy.deepcopy(self.state)
+        state["system"]["components"][1]["channels_per_loop"] = 2
+        self.assertIn("looper.channels_per_loop must be 4", validate_state(state))
+
+        state = copy.deepcopy(self.state)
+        state["routing"]["looper_inputs"][3]["channel"] = 3
+        errors = validate_state(state)
+        self.assertTrue(any("duplicate looper input channel" in error for error in errors))
+        self.assertTrue(any("cover channels 1 through 4" in error for error in errors))
+
+    def test_requires_declared_mix_output(self):
+        state = copy.deepcopy(self.state)
+        state["routing"]["mix"]["output_port"] = ""
+        self.assertIn("routing.mix.output_port must be a non-empty string", validate_state(state))
+
+    def test_return_exclusion_marker_is_not_an_active_connection(self):
+        self.assertEqual(validate_state(self.state), [])
+
+        state = copy.deepcopy(self.state)
+        forbidden_connection = next(
+            connection
+            for connection in state["connections"]
+            if connection.get("status") == "explicitly-forbidden"
+        )
+        forbidden_connection["status"] = "planned"
+        self.assertTrue(
+            any("routes looper returns into looper inputs" in error for error in validate_state(state))
+        )
+
+        state = copy.deepcopy(self.state)
+        state["routing"]["looper_returns"]["feed_looper_inputs"] = True
+        self.assertIn("routing.looper_returns.feed_looper_inputs must be false", validate_state(state))
+
+
+if __name__ == "__main__":
+    unittest.main()