diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..c1501ea --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# Project steward + +Act as the Rust project steward for fader_master: a Linux MIDI-to-application-volume server with pluggable audio backends and a TUI. Maintain the design in `architecture.md` and the ordered backlog in `task.md`. This file is the persistent project-agent role for future sessions; it does not create a background service. + +## Working method and commits + +- Read the architecture, task dependencies, repository status, and affected code before changing behavior. Select the smallest independently testable acceptance criterion. +- For behavior changes, write a meaningful failing test, implement the behavior, and refactor with tests green. Use one commit per tested behavior or tightly coupled acceptance-test group; do not combine unrelated milestones or commit a deliberately failing intermediate state. +- Include the test and implementation in the same commit. Record the test command and result in the commit body. Documentation-only commits should record document validation rather than inventing runtime tests. +- Before each commit inspect the staged diff and run relevant tests. Before completing a milestone run the workspace gates below. If a gate is blocked, report its exact cause; never describe it as passing or mark an unverified implementation task complete. +- Update task checkboxes only when their acceptance criteria pass. Keep design decisions, configuration examples, and user documentation consistent with implementation. +- Preserve user edits. Stage specific files. Do not amend, reset, force-push, or publish without authorization. Local incremental commits are requested for this project. +- Keep research spikes bounded. Verify current dependency APIs, licenses, MSRV, and native prerequisites before adding a crate. Explain material tradeoffs in the architecture. + +## Rust standards + +- Use stable Rust, edition 2024, and workspace-managed dependency versions and package metadata. Select and test an explicit MSRV and pin a reproducible toolchain as an implementation task. Track Cargo.lock for the application workspace. +- Prefer simple modules and typed boundaries over speculative frameworks. Use newtypes for IDs, validated volumes, revisions, and MIDI channel/data ranges; enums for states and capabilities. +- Keep domain logic independent of Tokio, terminal rendering, filesystem access, and native audio/MIDI handles. Make state transitions deterministic and directly testable. +- Use typed library errors (`thiserror`) and contextual executable errors (`anyhow`). Handle disconnects, invalid input, full queues, and unavailable devices as normal errors. Avoid production `unwrap`, `expect`, unchecked indexing, and panic-based control flow. +- Prefer safe Rust. Confine necessary FFI/unsafe to adapter boundaries, document safety invariants, and review lifetimes and thread affinity. Never force native handles to be Send/Sync. +- Give state one owner. Use bounded channels, explicit cancellation, finite timeouts, and joined worker shutdown. Never block a MIDI callback or async executor on native event loops or disk writes. +- Validate TOML before side effects. Keep stable user IDs separate from ephemeral backend IDs. Preserve unknown/offline/mixed states instead of substituting zero or unmuted. +- Preserve channel balance, bound amplification, and never change live audio during discovery or default startup. Confirm operations before reporting success. +- Document public contracts and non-obvious invariants. Keep lints enabled; any suppression must be narrow and justified. Avoid unrelated formatting and dependency churn. + +## Verification + +Run targeted tests during development, then these gates for an implementation milestone: + +```sh +cargo fmt --all -- --check +cargo check --workspace --all-targets --all-features +cargo test --workspace --all-targets --all-features +cargo test --workspace --doc --all-features +cargo clippy --workspace --all-targets --all-features -- -D warnings +cargo build --workspace --release --all-features +``` + +Also test the default build, no-default-features build, and each optional backend independently once feature flags exist. Provision native development libraries in CI. Hardware-free domain, fake-adapter, config, and TUI tests must run without an audio daemon or USB device. Keep real audio/hardware checks separately opt-in and document their fixtures and prerequisites. Add property tests for numerical conversions and state invariants; use a fake clock for retries and coalescing. Test observable behavior, including failure paths, rather than private implementation details. + +Current baseline: the workspace is a scaffold, not an implementation of the architecture. Its Jenkinsfile lacks doctests and Clippy warning enforcement; Cargo.lock is currently ignored. Fix these deliberately in the foundation milestone. diff --git a/README.md b/README.md index 2cc9a7c..29368a9 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,14 @@ # fader_master -Rushed test implementation of a midi-fader based software +Linux application volume and mute control from one or more USB MIDI surfaces. + +This repository currently contains an early Rust workspace and TUI prototype. +The server, audio adapters, persistent bindings, and configuration editor are +planned in the following documents: + +- [Architecture and library research](architecture.md) +- [Implementation tasks and acceptance tests](task.md) +- [Project-agent instructions and test/commit workflow](AGENTS.md) # References diff --git a/architecture.md b/architecture.md new file mode 100644 index 0000000..9544baa --- /dev/null +++ b/architecture.md @@ -0,0 +1,229 @@ +# fader_master architecture + +Status: proposed implementation design, researched 2026-10-05. The current workspace contains placeholder MIDI/audio libraries, a Hello World executable, and a basic Ratatui example. Features below are planned, not shipped. + +## Purpose and scope + +Run a per-user Linux server that receives controls from multiple USB MIDI surfaces, records requested state, resolves virtual application/group targets, and dispatches volume/mute commands through one selected audio adapter. Observe external audio changes and send confirmed state to every relevant TUI and MIDI output. + +The MVP controls application playback streams, not microphone capture, routing, DSP, or audio samples. An application may have zero, one, or many streams. ALSA hardware mixer targets are an explicit extension, not a substitute for application control. + +## Structure + +```mermaid +flowchart LR + HW[USB MIDI surfaces] <--> MIDI[MIDI transport and device profiles] + MIDI <-->|commands and confirmed feedback| SERVER[Server: single state owner] + TUI[TUI: mixer and editor] <-->|local IPC| SERVER + SERVER <--> CONFIG[TOML profiles and state] + SERVER --> OBJECTS[Virtual applications and groups] + OBJECTS --> PORT[Audio adapter commands] + PORT --> PULSE[PulseAudio protocol] + PORT --> PW[Native PipeWire] + PORT --> ALSA[ALSA mixer] + PULSE --> EVENTS[Snapshots and observed changes] + PW --> EVENTS + ALSA --> EVENTS + EVENTS --> SERVER +``` + +Only the server mutates domain state. Virtual objects resolve commands; they do not own native backend handles. Feedback follows observations, never a direct MIDI-to-audio shortcut. + +| Workspace location | Planned responsibility | +| --- | --- | +| New `core` directory, package `fader-core` | Pure domain types, target resolution, commands/events, reducer, audio adapter contract | +| New `config` directory, package `fader-config` | TOML schemas, validation, migration, atomic persistence | +| Existing `sound`, currently package `volume_lib` | Audio workers; `pulse`, `pipewire`, `alsa-mixer` features; fake adapter | +| Existing `midi` | MIDI transport, parsing, device identity, bindings, feedback, pickup | +| Existing `tui` | Mixer/editor/devices/status tabs and IPC client; no native audio access | +| Existing `fader_master` | CLI, server orchestration, IPC, worker lifecycle and logging | + +All outer crates depend inward on domain contracts; core depends on none of them. Start with modules inside these crates, splitting further only when warranted. An internal audio worker contract accepts typed commands and emits typed events; do not require native handles or callback objects to implement async traits or cross threads. + +## Domain model and matching + +- `SurfaceId`, `FaderId`, `ApplicationId`, `GroupId`, and `ProfileId` are stable persisted user IDs. Renaming a display label preserves its ID. +- A physical binding is `(surface ID, MIDI channel, message kind, control number) -> fader ID + action`. A logical fader targets exactly one `Application` or `Group` (later `HardwareMixer`). Several faders/surfaces may target the same object. +- An application object has selectors on explicit normalized fields: `application.name`, `application.id`, `application.process.binary`, or `media.name`. Preserve raw backend metadata for inspection. Never silently substitute one field for another. +- Matchers are `exact` (case-sensitive whole-string equality) or `regex` (Rust regex syntax, substring search unless anchored). Multiple selectors for an application are ORed. Missing properties do not match. Compile patterns once at config validation, with length/complexity limits; show actual matches in the editor. +- A matching application controls all its current playback streams. Stopped applications remain configured and display offline; new streams are discovered dynamically. Runtime handles include backend connection epoch plus object ID and an incarnation where needed to prevent ID-reuse bugs. PIDs, backend indices, and discovery order are never durable identity. +- Groups reference application IDs only in v1; no nested groups or cycles. Overlapping selectors/groups are allowed: deduplicate resolved streams within each command and show overlap in the editor. Separate commands are serialized by server arrival order; the last accepted command touching a stream wins. Overlap is shared control, not multiple multiplicative gain layers. +- Maintain requested state, observed per-stream/per-channel state, pending operation IDs, errors, and availability separately. A write acknowledgment means accepted by the adapter; success requires observation/readback. Derived objects can be `mixed`, `offline`, `pending`, or `partially failed`. + +## Volume and mute semantics + +The core stores finite, non-negative linear amplitude gain; `1.0` is unity, `0.0` is silence. Adapters convert native representations explicitly; PulseAudio volume numbers and PipeWire linear gain must not be treated as interchangeable percentages. Preserve per-channel balance by scaling channel gains relative to their maximum. If all channels are zero, an explicit nonzero command initializes them equally. Tests cover silence, clipping, NaN/infinity rejection, and round trips. + +The initial physical fader curve maps its normalized position linearly to gain in `[0, 1]`; future dB curves are explicit profile options. Above-unity writes require explicit configuration, with a finite maximum. External over-limit observations remain visible without being rewritten or silently clamped; feedback clips only the physical representation. Mute is an independent boolean: zero volume does not imply mute, and changing volume does not unmute. + +For an application or group, display maximum member stream gain as the aggregate fader position plus a mixed indicator when gains differ. Display mute as `all-muted`, `all-unmuted`, `mixed`, or `unavailable`. A toggle mutes all when any member is unmuted; otherwise it unmutes all. Unmute leaves volumes untouched and clears mute on all members, including independently muted members; there is no hidden pre-group mute restore in v1. + +Support two explicit group volume modes: + +1. `absolute` (default): a move to `g` sets each resolved stream's scalar gain to `g`, preserving each stream's channel balance. This is predictable for absolute USB faders. +2. `relative`: derive `g / old_max` from the latest member snapshot and scale members together, preserving relative gains until a limit clips. If `old_max == 0`, set all to `g`. External edits rebase the next move. A move to zero loses cross-stream ratios; recovery uses the defined equal-gain fallback. Document this in the editor. + +Group dispatch is best effort because audio APIs do not offer a transaction across arbitrary streams. Track results per stream, keep successful changes, show failures, and refresh observations. Do not pretend to roll back atomically. Backend workers preserve server write ordering per stream and per property; volume and mute can be tracked independently. + +Default startup, reconnect, profile switching, and new-stream discovery adopt live state without writes. A deliberate command while an application is offline stores pending intent for display but is not replayed on launch by default. An explicit `restore` policy may apply saved object intents to newly matched streams after full discovery, with validated bounds and visible status; conflicting restored targets use documented profile order, last matching target wins. Persist that order and test it. Never resurrect backend handles or pending operation IDs from disk. + +## Server state transitions and concurrency + +Use a Tokio event task as the single domain owner. MIDI, IPC, persistence, and audio workers send owned messages. A pure reducer produces state changes and effects, making the sequence testable without devices. + +1. Decode and validate a MIDI/TUI command with origin, surface, active profile revision, and sequence number. +2. Resolve its fader/object and current stream membership. Record desired state and pending operation before emitting adapter effects. “Record” means immediate in-memory state; durable TOML checkpoints are debounced, not a disk write on every MIDI packet. +3. Dispatch absolute per-stream volume/mute operations with operation ID, backend epoch, and config generation. Coalesce unsent volume updates to the latest value per stream/property. Resolve mute toggles to explicit booleans in accepted order, so two rapid presses toggle twice even before confirmation. +4. Process acceptance/failure and observed events. Serialize in-flight writes per property and retain newer pending intent when an older observation arrives. Where the backend cannot correlate notifications to requests, treat notifications as observed state, use readback and finite timeout to settle pending operations, and do not invent correlation IDs from equal values. +5. Recompute affected virtual objects, publish revisioned views, schedule checkpointing, and enqueue device feedback from observed values. External changes follow the same path but cause no audio write. Timeouts trigger readback; disconnects invalidate handles and pending operations. + +PulseAudio and native PipeWire event loops run on their own owner threads. In particular, PipeWire Rust objects are not generally Send/Sync; transfer commands and copied data, not handles. [PipeWire Rust threading documentation](https://pipewire.pages.freedesktop.org/pipewire-rs/pipewire/index.html) + +Use bounded `mpsc` for ordered work and `watch` for latest display snapshots. Keep button edges and lifecycle events separate from coalescible fader motion. A MIDI callback only parses/copies bounded input and tries to enqueue; on overflow set an explicit fault/resync flag rather than silently losing mute edges. A dropped button edge cannot be reconstructed from an audio snapshot: report the fault and require a new user press, never guess a toggle. Dedicate output workers to rate-limited MIDI feedback. [Tokio synchronization primitives](https://docs.rs/tokio/latest/tokio/sync/index.html) + +On shutdown stop accepting commands, stop callbacks, drain with deadlines, checkpoint confirmed state, close native connections, and join workers. Reconnect with bounded exponential backoff and cancellation; resnapshot before accepting writes. Keep other surfaces working when one disconnects. Stale backend/config generations cannot update current state. + +## Audio adapter selection and contract + +Each adapter provides probe/connect, capabilities, subscribe-and-snapshot, set-volume, set-mute, readback, and shutdown through a command/event worker boundary. Events include ready, snapshot begin/end, stream upsert/remove, operation result, observed state, and disconnected. Missing metadata/capabilities must be explicit. + +Subscribe before enumeration, buffer intervening events, and reconcile using an adapter-specific barrier/readback so a stream created or changed during enumeration is not lost. Pulse notifications may require fetching fresh stream info; events are not necessarily complete state. Repeated full snapshots replace state, rather than accumulating phantom streams. + +| Adapter | Scope and selection | +| --- | --- | +| `pulse` | First implementation. Enumerate playback sink inputs, read properties/channel volumes/mute, change volume/mute, subscribe to changes. Supports PulseAudio and PipeWire's PulseAudio-compatible service. Native PipeWire-only stream coverage needs explicit testing; do not claim completeness. | +| `pipewire` | Native playback stream discovery and SPA parameter control/observation. Implement after a spike proves writable parameters, correct linear gain/mute handling, metadata, and reconnect behavior with the active session manager. | +| `alsa-mixer` | Optional explicit hardware mixer targets only; report playback switch/mute support per element. Reject application/group targets requiring application discovery. Never silently fall back to system Master volume. | + +`adapter = "auto"` probes enabled candidates with timeouts in configured preference order (initially `pulse`, then `pipewire`). Pick the first reachable backend satisfying required capabilities; retain it until disconnect or explicit reload. Use API connection/capability probes, not process names. Manual selection fails visibly if unavailable, with no fallback. An unbuilt backend yields an actionable feature error. Auto mode never activates two adapters on the same graph and excludes ALSA unless the profile explicitly requests hardware-only targets. Expose selected protocol, reported server identity, missing capabilities, and probe failures. + +PulseAudio compatibility is provided by `pipewire-pulse`; ALSA's mixer API exposes mixer controls. The restriction of ALSA to hardware targets here is a design conclusion from that API model. [PipeWire PulseAudio service](https://docs.pipewire.org/devel/page_man_pipewire-pulse_1.html), [Pulse introspection](https://docs.rs/libpulse-binding/latest/libpulse_binding/context/introspect/index.html), [ALSA mixer interface](https://www.alsa-project.org/alsa-doc/alsa-lib/mixer.html) + +## Multiple MIDI surfaces and feedback + +Use `midir` for input/output connections. A device profile maps CC/note/pitch-bend messages to controls and output messages; v1 supports 7-bit absolute CC and note/CC mute buttons, then 14-bit pairs, pitch bend, and declared relative encoder dialects. Channel values in TOML are 1–16 and translate once at the transport boundary. Note-on velocity zero is release. Toggle actions fire on press only; validate malformed lengths and data bytes. Ignore unrelated clock/active-sensing traffic; arbitrary SysEx protocols are deferred. + +Persist a user surface ID plus matching hints: backend port identifier where usable, input/output port names, USB VID/PID, serial when available, and optional physical path. MIDI port indices and names alone are not durable identity. Linux identity enrichment may require ALSA sequencer-to-device mapping and udev; verify this bridge in a spike, since midir alone does not guarantee USB serial metadata. Identical serial-less devices cannot always be distinguished after moving USB ports: require explicit assignment when ambiguous and retain a disconnected placeholder rather than binding arbitrarily. + +Keep bindings for absent surfaces. Re-enumerate ports on hotplug notifications or a bounded periodic scan, reconnect matching input/output ports independently, and resynchronize output from current observed state. Missing output does not disable input. Two devices may send the same channel/CC without collision because the surface ID is part of the key. [midir input/connection API](https://docs.rs/midir/latest/midir/struct.MidiInput.html), [udev discovery/monitoring](https://docs.rs/udev/latest/udev/) + +Output capabilities are explicit: mute LED, value display, motorized fader, or none. Non-motorized devices may still receive supported LED/display feedback; never assume every surface has LEDs. Mixed mute uses a declared mixed indicator, otherwise LED on only for all-muted and the TUI shows mixed. Send full supported state on attach and incremental changes thereafter. Device feedback failures are separate from audio operation failures. + +Non-motorized absolute controls default to pickup: after startup, external changes, another surface's move, or profile switch, wait until the physical value crosses or enters a configured tolerance around the observed target before sending volume commands. First input establishes position; an out-of-range external volume uses the nearest physical endpoint. Relative encoders do not need pickup. Reset pickup on disconnect/rebind. For motors, add touch-aware inhibition before enabling motor output; unsupported touch means no claimed touch protection. + +Avoid feedback loops with direction/origin tracking, quantization-aware equality, rate limiting, and device-specific echo suppression. MIDI has no universal request IDs: generic time-window byte suppression can swallow real input, so only enable it for documented echoing device profiles and test it. Server observations never themselves generate audio commands. + +## TOML configuration, persistence, and switching + +All durable application data is TOML: profiles, device profiles/bindings, active profile selection, and last observed state and saved desired object values. Runtime sockets and log streams are not configuration stores. Use XDG config/state/runtime directories with validated ownership, falling back only according to the applicable XDG rules; do not put sockets in a shared predictable `/tmp` path. + +- `~/.config/fader_master/config.toml`: schema version and selected profile. +- `~/.config/fader_master/profiles/.toml`: adapter policy, applications, groups, surfaces, faders and bindings. +- `~/.config/fader_master/devices/.toml`: reusable MIDI output/input protocol profiles when needed. +- `~/.local/state/fader_master/state.toml`: schema version, per-profile confirmed object/channel state and separately validated desired object volume/mute, remembered assignments, last selected UI view. No ephemeral backend handles or pending operation IDs; cached observations are marked stale until refreshed. Desired values may include commands issued offline, but are applied after restart only under explicit restore policy. + +The following proposed profile is syntactically valid TOML, not a claim that a parser is implemented. Sample application and MIDI names must be selected from actual discovery. CLI overrides apply for the session; persist them only on explicit Save. + +```toml +schema_version = 1 +id = "desktop" +startup = "adopt" +new_stream = "adopt" + +[audio] +adapter = "auto" +preference = ["pulse", "pipewire"] +max_gain = 1.0 + +[[applications]] +id = "music" +label = "Music" +selectors = [{ field = "application.name", exact = "Music Player" }] + +[[applications]] +id = "browser" +label = "Browser" +selectors = [{ field = "application.process.binary", regex = '^(firefox|chromium)$' }] + +[[groups]] +id = "media" +label = "Media" +members = ["music", "browser"] +volume_mode = "absolute" + +[[surfaces]] +id = "desk-left" +label = "Left controller" +input_port = "Example Controller MIDI 1" +output_port = "Example Controller MIDI 1" +identity_policy = "require_unique" +motorized = false + +[[faders]] +id = "media-fader" +target = { kind = "group", id = "media" } +pickup = true +pickup_tolerance = 0.02 + +[[bindings]] +surface = "desk-left" +fader = "media-fader" +action = "volume" +message = { kind = "cc", channel = 1, number = 0 } + +[[bindings]] +surface = "desk-left" +fader = "media-fader" +action = "toggle_mute" +edge = "press" +message = { kind = "note", channel = 1, number = 32 } +feedback = { kind = "note", channel = 1, number = 32, on = 127, off = 0 } +``` + +Reject unknown schema versions/fields, duplicate IDs/physical bindings, dangling references, invalid matchers/ranges, unsupported capability requirements, and unsafe profile paths. Use forward migrations with backups; never downgrade silently. Validate the whole candidate before changing live mappings or files. + +Write same-directory temporary files, flush/fsync, rename atomically, then sync the directory. Debounce state writes (initial target: 500 ms after changes, maximum 2 s between dirty checkpoints), flush on orderly shutdown, and document the corresponding crash-loss window. Permission/disk-full errors leave the old file usable and show an unsaved state. Preserve user comments in profile edits with `toml_edit`. The server is the sole writer; TUI edits carry a base revision and conflict if stale. Detect out-of-process file edits before saving rather than overwriting them. + +Profile switch: parse/validate candidate, prepare/probe required resources without writes, pause input briefly, drain old writes with a deadline, obtain fresh state, then commit a new config generation and publish bindings/feedback together. Abort on prepare failure and retain the old profile. If an old in-flight call cannot be safely drained, close/reconnect and reconcile before activation; generation tags alone do not cancel native writes. In-flight group membership is fixed at command acceptance. Re-arm pickup, invalidate stale queued commands, and adopt live volumes by default. Persist the active profile pointer only after successful activation; disk failure leaves the active runtime profile clearly marked unsaved. Durable crash-atomic multi-file transactions are not claimed. + +## CLI, IPC, and TUI + +Plan `fader_master serve`, `tui`, `validate --config PATH`, `devices`, `status`, and `profile switch ID`. Run one server per user/runtime namespace with an owned Unix socket and lock; TUI disconnect must not stop MIDI control. No network listener. Bound IPC message size and queue sizes, enforce socket permissions/peer identity, negotiate protocol version, use request IDs and revisioned snapshots, and resnapshot after missed deltas. Length-prefixed UTF-8 TOML messages reuse Serde schemas initially; cap frames before allocation. + +TUI tabs: + +- **Mixer:** faders, resolved applications/streams, volume, mute, mixed/offline/pending/errors, pickup status. +- **Editor:** create/edit/delete application selectors, groups, faders, surface bindings, and MIDI learn; preview matches and conflicts. Draft changes do not affect audio; Validate, Apply, Save, Cancel are distinct. Referenced deletion requires reassignment or explicit cascade confirmation in the UI. +- **Devices / status:** MIDI assignments and ambiguity resolution, manual/auto backend choice, capability/probe errors, active profile and persistence errors. + +MIDI learn reserves the selected control and suppresses its normal action while learning. Save sends a revisioned request to the server; it never writes files from the TUI. Restore terminal state on errors and exit. Use logs away from the active terminal display. + +## Library research and choices + +These are fit-for-purpose recommendations based on primary documentation, not benchmark winners. Recheck maintenance, API compatibility, license compatibility with this repository, MSRV, and native dependencies when implementing; pin resolved dependencies in Cargo.lock. Avoid upgrading the existing Ratatui dependency just to write this plan. + +| Concern | Recommendation and tradeoff | Primary source | +| --- | --- | --- | +| USB MIDI | `midir`; owns input/output connections, Linux transport support. Prefer this to hand-written ALSA MIDI FFI; supplement persistent identity separately. | [midir](https://docs.rs/midir/latest/midir/) | +| Pulse protocol | `libpulse-binding`; exposes asynchronous introspection/control. Keep callbacks on an owned loop. Prefer this to parsing `pactl` output; simple playback APIs do not provide the control plane. | [libpulse-binding](https://docs.rs/libpulse-binding/latest/libpulse_binding/) | +| Native PipeWire | Official `pipewire` Rust bindings; full native object access, with more SPA/graph complexity. Keep behind a feature and capability spike. | [pipewire-rs](https://pipewire.pages.freedesktop.org/pipewire-rs/pipewire/index.html) | +| Hardware mixer | `alsa` for mixer controls and optional MIDI identity enrichment; feature-gated. No promise of application volume control. | [alsa::mixer](https://docs.rs/alsa/latest/alsa/mixer/index.html) | +| Async orchestration | `tokio`, limited features for runtime/sync/time/net/signal; native loops remain dedicated threads. Prefer over building timers/IPC/cancellation manually. | [Tokio sync](https://docs.rs/tokio/latest/tokio/sync/index.html) | +| TUI / events | Keep `ratatui` plus its compatible `crossterm`; in-process test backend and terminal event support. | [Ratatui](https://ratatui.rs/), [Crossterm](https://docs.rs/crossterm/latest/crossterm/) | +| Typed config | `serde` + `toml`; `toml_edit` for preserving profile formatting/comments. Custom semantic validation is still necessary. | [Serde](https://docs.rs/serde/latest/serde/), [toml](https://docs.rs/toml/latest/toml/), [toml_edit](https://docs.rs/toml_edit/latest/toml_edit/) | +| Matching | `regex`, compiled at load; predictable supported syntax, no need for lookaround/backreferences. | [regex](https://docs.rs/regex/latest/regex/) | +| Device metadata | Optional `udev`; enumerate/monitor Linux devices. Does not itself solve MIDI-port-to-USB association. | [udev](https://docs.rs/udev/latest/udev/) | +| CLI | `clap` derive for typed subcommands/help. | [clap](https://docs.rs/clap/latest/clap/) | +| Errors | `thiserror` in libraries; `anyhow` at executable boundaries. | [thiserror](https://docs.rs/thiserror/latest/thiserror/), [anyhow](https://docs.rs/anyhow/latest/anyhow/) | +| Diagnostics | `tracing` with a compatible subscriber for structured operation/backend/surface context; rate-limit noisy events. | [tracing](https://docs.rs/tracing/latest/tracing/) | +| Tests / temporary files | Standard Rust tests, `proptest` for conversion/reducer invariants, `tempfile` for filesystem fixtures and same-directory temp files; atomic durability still requires explicit sync. | [proptest](https://docs.rs/proptest/latest/proptest/), [tempfile](https://docs.rs/tempfile/latest/tempfile/) | + +Avoid CPAL/Rodio for this task: the needed boundary is an existing sound server's control plane, not a new playback engine. Avoid shelling out on every fader movement. Avoid a database, plugin ABI, web service, or scripting engine until an actual requirement justifies one. + +Native build prerequisites to verify in CI: pkg-config and C toolchain; ALSA development files for Linux MIDI/mixer; libpulse development files for Pulse; PipeWire/SPA headers and any bindgen/libclang requirements of the selected binding release; libudev development files if enabled. Feature-specific builds must work without unrelated native libraries. + +## Verification and remaining design risks + +Use deterministic fake adapters with reorderable events, failures, a fake clock, and a recorder of dispatched commands. Contract tests run against each audio implementation; real-daemon fixtures run in isolated sessions and never assume a developer's desktop can be modified. MIDI tests inject bytes and capture output; physical-device tests verify LED protocols and identity behavior separately. TUI uses a test backend and synthetic input. Benchmark sustained multi-surface fader traffic with bounded memory, eventual final-value delivery, and no starved mute events; set measured latency targets after the first working vertical slice. + +Highest-risk spikes are native PipeWire stream control, conversion/channel semantics, serial-less device identity, snapshot races, and MIDI echo/motor protocols. Their acceptance tests are explicit in `task.md`. Shipping the Pulse vertical slice first reduces risk while preserving all adapter boundaries. diff --git a/task.md b/task.md new file mode 100644 index 0000000..786e5a1 --- /dev/null +++ b/task.md @@ -0,0 +1,150 @@ +# Implementation tasks + +This is the build plan for `architecture.md`. All implementation boxes start unchecked because the repository is a scaffold. Follow `AGENTS.md`: one local commit per passing behavior/test increment, with the implementation and test together. A milestone below normally needs several commits; do not make one giant milestone commit or separate failing-test commits. Record focused test commands/results in commit bodies. + +## Planning delivered + +- [x] Inspect the workspace and define the project-steward role in `AGENTS.md`. +- [x] Specify state ownership, adapter boundaries, matching/groups, MIDI identity/feedback, and TOML lifecycle in `architecture.md`. +- [x] Research libraries using linked primary documentation and identify bounded technical spikes. +- [x] Define implementation order, acceptance tests, and requirement coverage below. + +Planning validation: parse the architecture's TOML example, verify local Markdown links and cross-references, check all 15 requirements are mapped below, and run `git diff --check`. No runtime behavior is changed by these documents. + +Baseline test attempt on 2026-10-05: `cargo test --workspace --all-targets --offline` could not run because `compact_str v0.8.2` was not cached. This is an environment/dependency limitation, not a passing suite or evidence of a code failure. Cargo generated an ignored lockfile during resolution. Foundation work must establish a complete baseline with dependencies available. + +## M0 — Reproducible Rust foundation + +Dependencies: planning. + +- [ ] **M0.1 Toolchain and build:** select/test an MSRV and pinned toolchain, centralize workspace metadata/dependencies, track Cargo.lock for the executable, document native build prerequisites. Acceptance: a fresh supported Linux checkout builds and tests reproducibly with `--locked`; the chosen MSRV builds the chosen dependency set. +- [ ] **M0.2 CI gates:** align Jenkins with AGENTS.md, including doctests, Clippy `-D warnings`, release build and later backend feature matrix. Acceptance: representative formatting/lint/test failures fail the pipeline; default and full-feature builds pass with provisioned dependencies. +- [ ] **M0.3 Domain boundary:** add `fader-core` and `fader-config`, wire current crates inward, remove placeholder arithmetic tests as real contracts replace them. Acceptance: core tests run without a terminal, sound daemon, native device connection, or Tokio runtime; dependency graph has no cycles. + +## M1 — Domain state and virtual objects + +Dependencies: M0. + +- [ ] **M1.1 Typed values:** stable IDs, finite gain, channel vectors, mute/availability/mixed states, revisions and backend epochs. Tests: invalid ranges/NaN/infinity rejected; gain/silence/channel-balance properties hold; IDs cannot be interchanged accidentally. +- [ ] **M1.2 Application selectors:** normalized metadata, exact/regex matching, OR selectors, multiple live streams and offline objects. Tests: anchored/unanchored/case-sensitive cases, missing fields, malformed regex, stream creation/removal and backend ID reuse. +- [ ] **M1.3 Fader resolution:** surface binding -> fader -> application/group -> deduplicated live streams. Tests: identical CCs on different surfaces stay separate, multiple faders can share an object, and overlap never writes the same stream twice per operation. +- [ ] **M1.4 Group gain:** absolute and relative modes with channel balance, aggregate max/mixed state, zero fallback and clipping. Tests: heterogeneous members, externally changed members, all-zero recovery, empty group, late joiner adopting live state, and partial failure. +- [ ] **M1.5 Mute:** explicit set/toggle independent of volume. Tests: mixed-group toggle mutes all, fully muted toggle unmutes all, two rapid toggles cancel logically, zero gain does not imply mute, and unmute does not alter gain. + +## M2 — TOML schemas and safe persistence + +Dependencies: M1 types; runtime activation follows in M10. + +- [ ] **M2.1 Schema and validation:** profile, application/group/fader/binding/device, and state schemas; check all references and capabilities. Tests: architecture example parses semantically, round trip preserves meaning, invalid IDs/duplicate bindings/unknown fields/schema versions fail with useful paths, all supported MIDI ranges are checked. +- [ ] **M2.2 Atomic files:** XDG paths, same-directory temp/rename/fsync, restrictive ownership, comment-preserving edits and migration backups. Tests: disk/permission/write failures keep the old document readable; malformed/missing state is recoverable; unsafe profile paths and incompatible migrations are rejected. +- [ ] **M2.3 Checkpoints:** per-profile observed state and separate validated desired object volume/mute, surface assignments, UI preferences, debounce and shutdown flush. Tests with a fake clock: sustained movement causes bounded writes and final state persists; crash/restart treats cached observations as stale, never restores runtime IDs or pending requests; an offline command survives restart as saved intent but only explicit restore applies it when the application launches (adopt emits no write). + +## M3 — Server and fake-adapter vertical slice + +Dependencies: M1, M2. No real USB/audio device required. + +- [ ] **M3.1 Reducer/effects:** one owner, command origins/revisions, desired/pending/observed state. Tests: accepted intent is recorded before adapter dispatch; success requires readback/observation; failure leaves actual state truthful; external changes update views without an outgoing audio command. +- [ ] **M3.2 Worker contract:** capabilities, snapshot barriers, readback, per-property ordered writes, operation results and fake backend. Tests: changes during snapshot are reconciled, old epoch/incarnation events are ignored, stream removal during write is handled, and newer pending intent survives an older completion. +- [ ] **M3.3 Load and ordering:** bounded channels, latest-volume coalescing, preserved mute ordering, overflow fault reporting. Tests: burst ends at latest value, toggles are not silently lost or guessed, memory stays bounded, and final readback resolves ambiguous acknowledgments. +- [ ] **M3.4 Lifecycle:** startup adopt, optional explicit restore, unavailable status, reconnect/backoff and orderly shutdown. Tests: startup emits no writes by default; reconnect resnapshots; restore conflict order is deterministic; disconnect expires in-flight state; cancellation joins workers and flushes state. + +Exit: simulated MIDI input changes a virtual object through a fake adapter; observation generates a confirmed snapshot and feedback effect. + +## M4 — PulseAudio adapter and real audio slice + +Dependencies: M3. + +- [ ] **M4.1 Bounded API spike:** verify libpulse-binding event loop, sink-input enumeration/properties, native volume conversion, change subscriptions and readback on PulseAudio and pipewire-pulse. Record native prerequisites and visibility limitations. Acceptance: isolated test streams are discovered and volume/mute changes are observed in both directions; no shell parsing in the production path. +- [ ] **M4.2 Implement worker:** own native handles on their loop thread; copy callback data; reconcile enumeration races. Contract tests: add/remove/change, operation error, unavailable daemon, reconnect, balanced stereo and multichannel conversion, external mixer edit. +- [ ] **M4.3 Adapter policy:** configured/CLI override, auto probe order/capabilities, diagnostics and feature errors. Tests: manual failure never falls back; auto chooses one authority, skips incapable candidates and never substitutes ALSA Master for applications; disconnect follows retry policy. +- [ ] **M4.4 Real-daemon fixture:** isolated playback streams and external control client. Acceptance: server command and external change both converge to the observed value/mute; stream churn and daemon restart recover. Document commands and opt-in fixture requirements; do not label mocks as hardware verification. + +## M5 — MIDI transport, device identity, and first controller + +Dependencies: M3; M4 for full end-to-end acceptance. + +- [ ] **M5.1 Decode/bind:** midir connections; absolute 7-bit CC, note/CC press/release; validate channels/data. Tests: malformed/truncated messages, note-on zero, ignored clock traffic, unknown controls, duplicate press policy and surface-specific routing. +- [ ] **M5.2 Identity spike:** inspect port identifiers and ALSA/udev USB mapping; establish serial/path/manual fallback policy. Acceptance: record metadata actually exposed by tested controllers, distinguish two identical models where possible, and demonstrate explicit ambiguity resolution where not possible. +- [ ] **M5.3 Multi-surface lifecycle:** persist user IDs and independent input/output assignment; hotplug scanning/notification, retries and absent placeholders. Tests: unplug/replug/reboot-style port reorder preserve assignments; ambiguous serial-less matches stay unassigned; one failed device does not stop another. +- [ ] **M5.4 Pickup:** crossing/tolerance, current physical position, reset on external change/rebind/reconnect/profile switch. Tests: old physical position cannot jump audio at startup; crossing activates; another surface re-arms pickup; above-range target can be picked up at the endpoint. +- [ ] **M5.5 Physical smoke test:** one controller -> server -> application audio; then two controllers with overlapping MIDI message numbers. Acceptance: correct applications respond, bindings persist, and USB loss leaves server running. Record controller/firmware and environment. + +## M6 — Confirmed MIDI feedback + +Dependencies: M4, M5. + +- [ ] **M6.1 Output profiles:** mute LED/value/motor capabilities, output pairing, mixed-state policy. Tests: confirmed/internal and external changes reach all bound surfaces; outputless surfaces receive no unsupported message; pending/failed writes never produce false success feedback. +- [ ] **M6.2 Feedback lifecycle:** attach snapshot, rate limits, deduplication, separate audio/output errors, documented device-specific echo suppression. Tests: feedback echoed as input cannot oscillate volume/mute; rapid updates converge; suppression does not swallow a genuine tested input sequence. +- [ ] **M6.3 Extended controllers:** 14-bit CC/pitch bend, explicit relative encoder modes, motor output and touch handling for declared profiles. Tests: endpoints/byte-pair ordering, relative increments, no motor push while touched, and non-motorized profile never receives motor commands. Hardware-verify every shipped specialized profile. + +## M7 — Local server interface and CLI + +Dependencies: M3, M2; may proceed after the fake-adapter slice. + +- [ ] **M7.1 CLI:** serve/tui/validate/devices/status/profile switch arguments and override precedence. Tests: help/errors, invalid config has no side effects, explicit override wins for the session without silently modifying disk. +- [ ] **M7.2 IPC:** owned Unix socket, one-instance lock, version negotiation, length-bounded TOML frames, request IDs and revisioned state. Tests: wrong peer permissions, oversized/truncated/incompatible messages, second server, stale socket recovery and slow/disconnected client. +- [ ] **M7.3 Client resync:** full snapshot on attach/lag and revision checks for edits. Tests: TUI exit never stops the server; reconnect shows current observations; concurrent clients cannot overwrite each other's edits unnoticed. + +## M8 — Live TUI + +Dependencies: M7, M4 for real use. + +- [ ] **M8.1 Mixer:** replace blocking prototype with event-driven client views and volume/mute actions. Test-backend assertions: groups/applications, mixed/offline/pending/error indicators, pickup state, resize and keyboard navigation reflect snapshots accurately. +- [ ] **M8.2 Devices/status:** show adapter selection/probe errors, device mappings, ambiguity and persistence problems. Tests: disconnected/unsupported states have useful actions; manual backend selection validates rather than silently applying incompatible mappings. +- [ ] **M8.3 Terminal lifecycle:** restoration on normal/error exit, nonblocking refresh, logging away from display. Tests: injected IO/client failure releases terminal guard; polling/refresh does not block server operation. + +## M9 — TUI configuration editor + +Dependencies: M8, M2, M1. + +- [ ] **M9.1 Editor drafts:** separate tab to create/edit/delete applications, groups and faders; target/member selection, matcher preview, validation errors and referenced-delete handling. Tests: invalid regex/dangling member rejected; Cancel has no side effects; creating a group/fader produces the expected semantic TOML. +- [ ] **M9.2 Surface bindings / MIDI learn:** select surface, listen for one supported control, preview conflicts and save binding. Tests: learning suppresses the normal action, other surfaces are not captured accidentally, cancellation restores routing, duplicate binding is rejected. +- [ ] **M9.3 Apply/save/conflict:** server-owned revisioned edits, separate live apply and persistence. Tests: stale edits conflict, external file edits are not overwritten, comments survive save, write failure is shown as unsaved and leaves previous disk config usable. + +## M10 — Transactional profile swapping + +Dependencies: M9, M6, M7. + +- [ ] **M10.1 Prepare/activate:** validate/probe candidate, pause/drain old writes, obtain new snapshot and atomically publish generation/mappings. Tests: invalid profile/unavailable manual adapter keeps old profile; late commands/events do not reach new targets; un-drainable native operations force reconciliation before activation. +- [ ] **M10.2 Restore/adopt policy:** default switch adopts live state; explicit restore uses saved object intents and deterministic overlap ordering. Tests: no surprise startup/switch write, restore limits enforced, offline/new members follow configured policy, pickup/feedback resync happens on every surface. +- [ ] **M10.3 Durable selection:** save active pointer after successful activation and reconcile state namespaces. Tests: disk failure marks active runtime selection unsaved, restart selects last durably saved profile, and corruption cannot silently activate an unintended profile. + +## M11 — Native PipeWire and optional ALSA mixer + +Dependencies: M4 adapter contract; native PipeWire follows a working Pulse slice. + +- [ ] **M11.1 PipeWire spike:** verify playback node classification, writable SPA volume/mute parameters, channel balance, application properties, notifications and thread ownership. Acceptance: isolated native and Pulse-origin playback streams have documented coverage under a session manager; unsupported objects produce capability errors. +- [ ] **M11.2 Native implementation:** implement feature-gated worker and run shared contract suite plus real-daemon scenarios. Tests: external changes, reconnect, stream churn, snapshot races and normalized gain match domain semantics; auto never double-writes through Pulse and native APIs. +- [ ] **M11.3 ALSA hardware extension:** add explicit hardware target schema/UI selection, mixer element discovery/control, event/readback and capability reporting. Tests: unsupported mute rejected, integer/dB scaling round trips, external mixer changes observed, application profile never silently maps to master hardware gain. +- [ ] **M11.4 Feature matrix:** default Pulse, native-only, mixer-only, no backend, full-feature builds. Acceptance: each isolated feature builds with only its documented native prerequisites; manual selection of an unbuilt adapter gives a useful diagnostic. + +## M12 — Reliability and release + +Dependencies: all required feature milestones; hardware-only ALSA remains an explicitly scoped extension. + +- [ ] **M12.1 Adversarial replay:** deterministic reconnect/churn/write-failure/echo/reordered-event/profile-switch scenarios. Property tests preserve domain invariants; command storms stay bounded and converge without starving mute or shutdown. +- [ ] **M12.2 Integration matrix:** PulseAudio, pipewire-pulse, native PipeWire, two controllers, external desktop mixer, reload/restart, read-only/full state directory. Record fixtures, supported device profiles and known limitations; never run destructive audio tests on the user's current session by default. +- [ ] **M12.3 Packaging:** example TOML profiles, schema/migration documentation, build/install guide, optional systemd user unit and troubleshooting. Acceptance: fresh user install can discover, bind, edit, save, restart and reconnect without root or manual state repair. +- [ ] **M12.4 Release gates:** all workspace/default/feature/MSRV checks, reproducible lockfile, license review and dependency advisory review using maintained tooling selected at implementation time. Measure/control latency under multi-surface load and publish the tested envelope. + +## User requirement coverage + +| # | Requirement | Work items | +| --- | --- | --- | +| 1 | MIDI -> server records intent -> audio adapter | M3.1–M3.3, M5.1, M5.5 | +| 2 | Different sound manager adapters | M4, M11 | +| 3 | Automatic/manual selection | M4.3, M8.2, M11.4 | +| 4 | Exact/regex application selectors | M1.2, M9.1 | +| 5 | One fader controls grouped applications | M1.3–M1.4 | +| 6 | Mute/unmute | M1.5, M4.2, M6.1 | +| 7 | Load current volume/mute/state | M3.2–M3.4, M4.2, M10.2 | +| 8 | TUI tab creates/edits groups and faders | M9 | +| 9 | Fader -> virtual application/group -> adapter | M1.3, M3.1–M3.2 | +| 10 | External audio changes update state | M3.1–M3.2, M4.4, M11.2 | +| 11 | Server sends state back to MIDI surfaces | M6 | +| 12 | Concurrent surfaces and remembered bindings | M5.2–M5.5, M2.3 | +| 13 | Architecture with design improvements | architecture.md; pickup, epochs, partial failures, atomic reload | +| 14 | Swappable configuration; durable data in TOML | M2, M9.3, M10 | +| 15 | Library research | architecture.md library table; M4.1, M5.2, M11.1 | + +First implementation target: M0, then a hardware-free M1/M2/M3 slice; follow with Pulse and one MIDI controller before broadening backend or device protocol support.