60 KiB
fader_master architecture
Status as of 2026-10-16: the Linux server runs native MIDI and Pulse-compatible
audio workers, a reconnecting live TUI, managed profiles, MIDI learn and mute
feedback, and a persisted mixer/configuration editor. The combined launcher
starts a server only when none is available. Layouts include horizontal strips,
stacked faders, configurable separators/spacers, themes, and pickup indicators.
Native PipeWire, runtime relative groups, and the unchecked acceptance work in
task.md remain unfinished.
Foundation and implementation history
Release preparation uses a project-local POSIX wrapper around rust_realease,
with Cargo metadata as the version authority and an exact SSH-to-public-HTTPS
repository mapping. The initial artifact target is x86-64 GNU/Linux because
the executable requires native ALSA, Pulse and udev libraries. All three binary
entry points share one archive; standalone downloads are also planned. Cross
supplies native build prerequisites; publication remains a separate explicit
operation. See release contract and outstanding qualification.
The following foundation notes describe the original milestone boundaries; the runtime and UI contracts later in this document describe the current system.
Rust 1.88.0 is the pinned toolchain and tested MSRV. The workspace inherits
package metadata, including the existing custom LICENSE through license-file.
core contains typed IDs, finite gain/channel vectors, normalized selectors,
stream identities, logical routing, device-scoped bindings, group gain planning,
and serial mute intent planning. config contains strict version-1 profile,
device-capability, and persisted-state schemas. Parsing validates stable IDs,
selectors, references, duplicate IDs and physical bindings, audio/MIDI bounds,
and feedback/output capabilities before returning a document. It serializes a
canonical semantic round trip. XDG resolution, private directory/file modes,
owner/symlink checks, same-directory atomic replacement with file and directory
sync, recoverable state loads, comment-preserving application-label edits, and
forward-migration backups are implemented. A pure monotonic checkpoint
coordinator owns the 500 ms debounce, two-second maximum dirty interval, and
shutdown flush. Restart views force cached observations stale and retain desired
intent separately; adopt produces no audio write, while restore checks the
profile write ceiling before yielding application-join intent. MIDI/audio crates
are adapter boundaries without native handles or transport behavior yet.
Stable IDs contain 1–64 ASCII bytes, start with an alphanumeric character, and
otherwise allow alphanumerics, _, and -. Selector patterns contain 1–256
bytes; regex compilation has a 1 MiB size limit. Missing normalized properties
never fall back to raw metadata. Group references cannot nest. Logical routing
validates references and returns ordered, deduplicated stream sets. Physical
binding lookup includes surface, channel, message kind, and control number.
Group gain plans clip each stream at the explicit write ceiling, preserve channel ratios, and leave observations unchanged. Relative scaling divides a stream's maximum by the aggregate maximum before multiplication to avoid intermediate overflow. Partial confirmations and late members are represented by supplying updated observations to the next plan; asynchronous dispatch belongs to M3. Mute planning stores accepted per-stream intent so rapid toggles and overlapping targets compose. The future reducer must clear intent only after checking that an operation completion is current, or on removal/disconnect. Display state is always derived from observations.
Added dependencies were verified from their downloaded package manifests:
thiserror 2.0.21 requires Rust 1.77, regex 1.13.1 requires 1.65, and the
test-only proptest 1.11.0 requires 1.85. Each offers MIT OR Apache-2.0 and
requires no audio/MIDI development library. All compile on the pinned 1.88.0
toolchain. Regex provides bounded compiled matching, thiserror implements typed
library errors, and proptest exercises numerical invariants. Cargo.lock records
the resolved versions; dependency versions are workspace-managed.
M2.1 adds serde 1.0.229 (Rust 1.56) and toml 0.8.23 / toml_edit 0.22.27 (Rust 1.66), each MIT OR Apache-2.0 with no native prerequisite.
Serde defines strict data shapes and TOML supplies parsing and canonical
serialization; the resolved toml_edit dependency will also underpin M2.2
comment-preserving edits. These versions compile on the pinned Rust 1.88.0.
M2.2 directly uses rustix 1.1.5 (Rust 1.65, Apache-2.0 WITH
LLVM-exception OR Apache-2.0 OR MIT) for safe effective-user checks and
tempfile 3.27.0 (Rust 1.63, MIT OR Apache-2.0) for collision-safe
same-directory temporary files. Neither adds a native system-library
prerequisite, and both compile on the pinned toolchain.
M4 begins with libpulse-binding 2.30.1 and libpulse-sys 1.23.0. Both
declare Rust 1.63 and MIT OR Apache-2.0, compile on the pinned Rust 1.88.0,
and require libpulse development files through pkg-config. The default
compatibility feature targets PulseAudio 8 or newer. The adapter uses the
asynchronous protocol API on an owned mainloop, deep-copies callback data, and
converts software volumes through VolumeLinear; it does not parse pactl.
Purpose and scope
Run a per-user Linux server that receives controls from multiple USB MIDI surfaces, records requested state, resolves virtual application/group/default-output 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 and the selected backend's default output sink, not microphone capture, routing, DSP, or audio samples. An application may have zero, one, or many streams. The output target follows the server's current default sink and remains distinct from ALSA hardware mixer elements, which are an explicit extension rather than a substitute for application control.
Structure
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 |
|---|---|
Existing core directory, package fader-core |
Pure domain types and target resolution; commands/events, reducer and adapter contract follow in M3 |
Existing config directory, package fader-config |
Empty boundary; TOML schemas, validation, migration, atomic persistence follow in M2 |
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, andProfileIdare 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 oneApplication,Group, or thedefaultoutput (later, an explicitHardwareMixer). Several faders/surfaces may target the same object. - An application object has selectors on explicit normalized fields:
application.name,application.id,application.process.binary, ormedia.name. Preserve raw backend metadata for inspection. Never silently substitute one field for another. - Matchers are
exact(case-sensitive whole-string equality) orregex(Rust regex syntax, substring search unless anchored). Applicationselector_modedefaults toany(OR);allrequires every selector (AND). Missing properties do not match. Empty lists and unknown modes are rejected. 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, orpartially failed.
Planned matching and media-control extensions
The agreed stretch-goal order is AND selectors and richer process metadata,
then targeted MPRIS media controls (M13 in task.md). Selector composition is
implemented in the domain/configuration layer and the fader editor's Match
captures toggle (Any/OR or All/AND). Process metadata has a first bounded Pulse
adapter implementation; media controls remain planned, not current schema.
The existing media.name regex (?i) - YouTube$ is sufficient for YouTube
streams whose reported title has that suffix. Do not couple this use case to
browser identity, window-title concatenation, or the future AND matcher.
AND composition must preserve the meaning of existing OR selector lists and
keep field matching explicit, validated, and visible in the editor. Process
enrichment belongs in an adapter, not the domain matcher: resolve available
executable/working-directory and Steam launch metadata from the reported PID,
with bounded reads, process-reuse checks, and unavailable values on failure.
Read only relevant environment keys; do not expose entire environments or
command lines in diagnostics. Steam IDs and launch context are evidence;
steamapps paths are a fallback installation hint, not proof of launch origin.
The implemented process fields are application.process.executable,
application.process.working_directory, steam.app_id and steam.game_id.
Pulse callbacks copy only reported PID/machine ID; enrichment runs afterward on
the adapter worker. Require the reported machine ID to equal the local one,
read start time before/after inspection, and discard values if the process
changes or disappears. Reads are bounded (stat 4 KiB, environment 64 KiB), and
only nonzero numeric SteamAppId/SteamGameId values leave the environment parser.
Missing/oversized/inaccessible values remain absent; paths are not launch proof.
Reported PIDs are best-effort hints, not authenticated identities; remote and
namespace-restricted applications may be unavailable. No command lines or full
environments enter diagnostics. The start-time check follows Linux
/proc/pid/stat.
MPRIS controls will address matched player instances over D-Bus using identity,
desktop ID or bus-name selectors, with Play, Pause and PlayPause actions. Keep
media-player discovery independent of active audio streams so paused players
remain controllable. Extend MIDI learn, capability/state reporting and TUI
editing through the server owner; use confirmed playback state for feedback.
Resolve multiple matches explicitly rather than choosing an arbitrary player.
This controls players such as QBZ directly, without synthetic keyboard input.
The approved Media tab lists configured player/control sets with stable IDs,
labels, explicit exact/regex selectors and observed state. Discovery supplies a
picker without a builtin player catalogue; manual selectors remain available.
Multiple matches are ambiguous and block commands. The server advertises session
bus availability to the client: no running players is an empty list, not a reason
to hide the tab; a later disconnect retains the tab with an unavailable status.
The scope includes Stop/Next/Previous, relative and absolute seeking, shuffle,
repeat and playlist discovery/activation, gated by player capabilities. Playlist
content editing is not included. Learn/unbind, validated editing and persisted
configuration follow the mixer conventions.
Feedback uses confirmed state, with exclusive Play/Pause/Stop indicators and
explicit device-specific colour mappings; default note output is same-note 127/0.
Global and per-fader/per-media-entry switches gate MIDI output. Global off sends
no messages (even clearing messages), so existing lights may remain lit until
feedback is re-enabled and resynchronized. These additions remain planned until
their individual M13 acceptance criteria pass.
Global and per-fader gates now use feedback_enabled (default true) at root and
fader-table scope, applied on configuration Save, including explicit mappings.
The protocol boundary follows the
MPRIS Player interface.
The hardware-free media crate defines player selectors, capability-aware
actions, observed playback state, configuration entries and MIDI feedback rules.
[[media]] entries have stable IDs, labels, a selector, a default-enabled feedback
gate, and controls with stable IDs/actions/optional bindings. Configuration
validates selectors, limits, references and input collisions with mixer bindings
before activation. Entry editing is transactional; removing a surface unbinds its
media controls without deleting entries. The live server routes media MIDI press
edges through the bounded worker and exposes discovery, capabilities and state
over IPC. The optional Media tab edits draft entries and controls; Save activates
them. Learn/unbind is scoped to a selected control and surface. Media commands
are not retried by the client after ambiguous transport failures.
The MPRIS adapter uses pinned dbus 0.9.12 (MIT/Apache-2.0) and system
libdbus-1; its upstream manifest does not declare an MSRV, so compatibility is
verified by building with the repository's Rust 1.88 toolchain. A dedicated
joined thread owns the blocking connection. Calls have 200 ms timeouts, polling
uses 250 ms intervals, and the command queue holds at most 32 requests. Discovery
limits player count to 32 and playlist choices to 256 per player. Exhausted
discovery bounds fail closed rather than selecting from an incomplete result.
Commands resolve a fresh snapshot and address a unique bus owner, not a reusable
well-known name; feedback comes only from readback. Missing optional properties
remain unavailable. Connection failure triggers reconnect; configuration
activation fences queued and in-flight work before replacing the active profile.
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.
Recognize two group volume models, but enable only sync groups in the current runtime:
absolute(also called sync, current default and only accepted profile mode): a move togsets each resolved stream's scalar gain tog, preserving each stream's channel balance. This is predictable for absolute USB faders.relative(reserved): each member remembers the channel vector from its last independent application-fader or external edit as that member's maximum. A normalized group positionpscales the member between silence and that maximum (p * member_max), preserving channel balance. A group write or its confirmation never rebases the remembered maximum; a later independent/external edit rebases only that member. Moving to zero therefore remains reversible. Newly resolved members adopt their live state as their initial maximum, and removed members lose their anchor.
The pure domain planner for the reserved relative model exists and is tested,
but profile validation rejects volume_mode = "relative" until the runtime can
track write origin and lifecycle for those anchors. Examples and live routing
use volume_mode = "absolute" only.
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. Live MIDI/TUI input against an offline or read-only target is a visible, nonfatal no-op and is never replayed when the target appears. A future explicit saved-intent workflow may retain a deliberate offline command for display, but only 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.
- Decode and validate a MIDI/TUI command with origin, surface, active profile revision, and sequence number.
- 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.
- 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.
- 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.
- 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
Pulse subscription notifications caused by the server's own confirmed writes retain their originating operation when their copied volume/mute state matches the expected echo. They remain observations, but must not masquerade as external edits and repeatedly re-arm a non-motorized fader during motion. A different observed state clears the echo expectation and remains an external change that re-arms pickup.
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
The production audio dispatcher retains a bounded server-owned queue in front of a one-slot native worker command lane. Its independent event lane remains large enough for a complete startup snapshot; command backpressure must never shrink snapshot capacity. Replace unsent volume commands for the same stream with their newest value and explicitly supersede the older operation; never coalesce mute edges. A full non-coalescible queue or event lane is a visible fault, not permission to drop an action. Drain copied worker events in batches so native round-trip latency cannot starve MIDI input or local clients.
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 plus the current default output sink; read channel volumes/mute, change them, and subscribe to both stream and default-output 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, Pulse introspection, ALSA mixer interface
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. On Linux, bridge midir's ALSA client:port through the sequencer client's card number to the udev sound/cardN device; user/virtual clients legitimately have no card. Match USB devices by serial first, physical ID_PATH second, and unique VID/PID/port-name last. Identical serial-less devices without a retained path require explicit current-port assignment and remain unresolved when ambiguous after topology changes. See the identity spike.
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, udev discovery/monitoring
Note-based mute bindings default to same-note feedback when an output port is configured. Other output capabilities (CC LEDs, value displays, motors) require explicit configuration. 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.
The first implemented output slice is binding-level mute feedback. A binding
with feedback sends its declared note or CC on value only for a uniformly
confirmed muted target, sends off for uniformly unmuted or mixed state, and
sends nothing for an unavailable target. Successful messages are deduplicated;
an independently reconnected output invalidates that cache and receives a full
current refresh. Pending intent is never treated as confirmation.
When learning a new mute binding, the editor may copy on/off values only
from an unambiguous convention already used by feedback of the same message kind
on that surface; the new feedback address follows the learned control. Missing
or conflicting conventions leave the explicit mapping absent. The runtime
defaults every note-based mute binding to its input channel and note, with
on=127/off=0, when its surface has an output port. No device identity or note
whitelist is required. Explicit feedback settings override kind, channel,
number, and on/off values for alternate device protocols. CC input bindings
still require explicit feedback. Defaults are resolved without rewriting TOML
and reflect confirmed mute state, not an immediate echo of every input event.
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.
At startup, apply already-queued audio snapshot events before MIDI messages collected in the same server turn. This gives pickup a live target for the controller's first sweep without replaying input or issuing a startup write.
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/<id>.toml: adapter policy, applications, groups, surfaces, faders and bindings.~/.config/fader_master/devices/<id>.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.
When no explicit profile path is supplied, a missing active selection creates a
safe default profile with a pickup-enabled default-output fader before
atomically publishing its active pointer. This provides a useful keyboard mixer
and a target for MIDI Learn without guessing application identities. A
missing profile named by an existing valid active pointer is initialized with
that stable ID. Existing files, malformed selections, and explicit missing
paths are never overwritten by this first-run recovery.
The following profile is parsed and semantically validated by an automated test
and mirrored at examples/profiles/desktop.toml. Sample application and MIDI
names must still be selected from actual discovery. CLI overrides apply for the
session; persist them only on explicit Save.
schema_version = 1
id = "desktop"
startup = "adopt"
new_stream = "adopt"
[ui]
default_controller = "desk-left"
theme = "default"
status_display = "detailed"
[runtime]
poll_interval_ms = 10
[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 }
runtime.poll_interval_ms controls how long both the server state owner and the
native audio worker may wait between MIDI/IPC/command/notification polls. It
defaults to 10 ms when omitted and is validated within 1..=100. Lower values
can reduce worst-case control latency at the cost of more wake-ups; higher
values reduce wake-ups but make physical control and external-state updates less
responsive. It does not change the bounded coalescing policy or cause every
intermediate fader sample to be written.
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.
Editor mutations are first applied to a cloned, comment-preserving document and the complete candidate profile is semantically validated before the draft is replaced. Invalid matchers, duplicate IDs, and referenced deletes therefore leave the prior draft unchanged. The v1 editor creates absolute groups; relative group controls remain a reserved future mode. Schema arrays that default empty, including bindings, applications, groups, and faders, may be omitted from valid TOML; creation edits materialize them lazily and removal from an omitted empty array is a no-op. A present malformed section is rejected during startup.
The live mixer revision and configuration-draft revision are independent. The public mixer revision also includes a routing-generation offset advanced on Save/reset/profile switch, while the audio reducer keeps its own revision. Validate public revisions only at the external client request boundary. MIDI intents run synchronously under the server's state owner against current routing and must not pass reducer revisions to that check. Mixing these revisions made every MIDI volume/mute action fail after reconfiguration, propagating a stale revision error out of the server loop. Genuine stale client requests still resnapshot and retry; they must not bypass the public revision check. Draft edits are serialized by the server, require the caller's expected draft revision, and never mutate live routing or audio as a side effect. Successful draft edits are explicitly marked unsaved until a later Save command. A layout move names one stable entry and an absolute destination, so the server may rebase that operation onto a newer shared draft instead of flashing the optimistic order and rejecting it solely because another draft edit landed.
MIDI learn is scoped to one configured surface, logical fader, and action. While armed, messages from that surface are withheld from normal routing; unrelated surfaces continue normally. The first compatible CC or note press becomes a validated draft binding, while cancellation restores routing immediately.
Save is the only editor commit action. It first validates and prepares the profile-derived matching, groups, faders, pickup, and MIDI routing, compares the exact on-disk bytes with the server's load/save baseline, and uses the atomic writer. Save commits the server's latest validated shared draft even when the requester's displayed revision is older; a future revision remains invalid. After persistence succeeds, the server activates the prepared routing while retaining confirmed audio observations and issuing no audio write. Conflicts or persistence failures retain the previous file, live configuration, and dirty draft.
The implemented atomic writer checks that its parent and any existing target
are owned by the effective user and are not symlinks. It creates mode-0600
temporary files in the destination directory, streams and syncs their content,
renames over the destination, and syncs the parent directory. Application
directories are mode 0700. Missing state and malformed readable state are
distinct recoverable load outcomes; malformed bytes are retained for diagnosis.
Profile migration accepts only versions below the current schema, validates the
replacement first, and durably backs up the original bytes before replacement.
Server startup invokes the registered migration for pre-versioned/schema-0
profiles, preserving TOML comments and reporting the .v0.bak path. A malformed
document, invalid migrated candidate, unknown future schema, or existing backup
aborts without replacing the profile. Validation-only commands never migrate.
Checkpoint changes are written after 500 ms without another change and at least
every two seconds during sustained input, then flushed once more on orderly
shutdown. A process or machine crash can therefore lose up to the latest
unflushed interval; atomic replacement protects the preceding checkpoint.
Revision conflict handling belongs to the server/editor boundary in M9.3.
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.
The Pulse implementation accepts a profile switch only when its bounded dispatch queue and published objects have no pending operation. A busy switch is rejected for retry after readback/reconciliation rather than publishing over in-flight native work. The committed mapping generation advances the public mixer revision, invalidating commands created from the prior profile.
The active pointer is a strict versioned TOML document containing one validated
profile ID. A successful runtime switch writes it atomically after activation.
Failure does not roll back the running generation, but marks the selection
unsaved; startup without --config accepts only this pointer and never guesses
another profile when it is absent or corrupt.
Profile switching adopts confirmed live state unless the caller explicitly
requests restore. Explicit restore validates the selected profile's saved
desired values and gain ceiling before activation, applies online application
intents in profile order, and retains offline intents only when the candidate's
new-stream policy is restore.
CLI, IPC, and TUI
Provide fader_master_server as the persistent server,
fader_master_client as the reconnecting TUI, and fader_master as an all-in-one
launcher. Combined mode probes the authenticated/versioned local server first
and starts an in-process server only when none responds. A startup race is
resolved by the socket's one-instance ownership rather than creating a second
authority. An embedded server receives an orderly cancellation and is joined
when its TUI exits; a reused external server is left running. The compatible
fader_master serve, tui, validate --config PATH, devices, status, and
profile switch ID commands remain available. Run one server per user/runtime
namespace with an owned Unix socket and lock; TUI disconnect must not stop an
external server's 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.
Configuration snapshots include the valid sibling profile IDs discovered by
the server. The Config view presents them in a modal selector and requests the
same adopt-mode transactional switch as profile switch ID; invalid profile
documents are not advertised, and activation errors retain the current profile.
The TUI owns blocking IPC on a background thread. Its render/input thread reads a shared local snapshot only, applies optimistic volume/mute changes, and queues work without waiting for a socket response. Pending volume work is latest-value-per-object; mute presses remain a bounded FIFO. Confirmed snapshots replace the local base and retain optimistic overlays until observation settles them. Poll quickly while writes are pending, slowly while idle, and resnapshot then retry a bounded number of times after stale mutations so consecutive server revisions cannot roll an optimistic edit back. Revision conflicts are recognized from their protocol message rather than a transport-specific I/O kind and are presented as recoverable warnings. Start immediately with a disconnected placeholder when the socket is absent, retain the last confirmed items across transport failures, surface the connection error inside the terminal, and keep retrying so starting or restarting the server reconnects without restarting the TUI.
Quit and terminal restoration are local operations. Terminal state is restored before client teardown; teardown requests worker cancellation and joins within a short grace period, but detaches a worker whose in-flight server request remains wedged. That worker exits after the request returns and observes cancellation, so a crashed or hung server can never trap the terminal in raw mode.
Mixer-object snapshots also aggregate pickup state across configured physical
volume bindings. They expose unavailable, waiting, tracking, or mixed;
controls are instantiated from the profile before discovery so the first live
observation can arm them without waiting for an initial MIDI packet.
The same client snapshot retains configured MIDI-device placeholders and their backend IDs/errors. The compact mixer status line distinguishes connected, connecting, missing, ambiguous, and failed devices, adding a connect/select action where the user can resolve the state.
Unclaimed MIDI input ports are also published with their current backend ID, stable port name, and available USB identity. Config can add one as a durable surface draft; the first added surface becomes the default controller, and Save rebuilds the MIDI runtime before Learn is enabled. On creation of a missing managed profile, exactly one discovered input is adopted automatically. No choice is guessed when discovery returns zero or multiple inputs.
Terminal restoration is guarded around all fallible client/run work after terminal initialization. The restore action is injectable for failure-path tests; client and transport diagnostics stay in the rendered status area rather than being printed over the alternate screen.
Terminal colors come from semantic theme palettes rather than renderer-local
literals. The built-ins are Default, Dracula, Nord, Gruvbox Dark, Catppuccin
Mocha, and Solarized Dark. ui.theme stores the profile palette, t cycles its
draft value, and Save persists it. tui --theme NAME remains a session-only
startup override. Theme selection never changes audio. Each palette defines
background, foreground, accent/selection, secondary meter, muted, warning,
error, and meter track colors so status meaning remains consistent across
themes.
ui.status_display controls pickup feedback without changing pickup behavior.
The persisted modes are detailed (pickup: tracking), compact (LIVE),
symbol (a state-specific Unicode glyph), color (one fixed glyph using the
semantic status color), and hidden (no pickup indicator). Detailed is the
backward-compatible default. Both mixer orientations use the same mapping;
horizontal mode reserves the pickup footer row even when the indicator is
hidden or the fader has no MIDI assignment, keeping every meter the same height.
The TUI is mixer-first rather than exposing the profile's normalized tables as
separate tabs. Its main list is an ordered presentation of logical faders and
named separators. A layout entry references a stable fader ID or defines a
stable separator ID and label. Fader entries retain their position while
hidden; hiding is presentation-only and never deletes the target, selectors,
MIDI bindings, or saved state. Profiles without an explicit layout synthesize
one visible entry for every declared fader in declaration order. Validation
rejects duplicate layout IDs, duplicate fader references, and dangling fader
references. Each fader layout entry also stores a slim, standard, or thick
density. Layout moves and separator insertion normalize the TOML tables' source
positions to a shared layout anchor before serialization. Parsed tables retain
their old source positions, so vector order alone does not survive serialization;
the normalized anchor preserves the requested order and each entry's comments
across Save and server restart.
Omitted density defaults to standard for existing profiles. Vertical
mode keeps the stacked card layout: Slim is a single terminal row while the
other sizes retain progressively more detail. Horizontal mode uses side-by-side
console-style fader strips with bottom-up meters, state, percentage, pickup
status when enabled, and a label at the bottom; density controls strip width.
Horizontal separators are labeled inline divider columns so every layout entry
stays in a single row, with the selected entry kept inside the width-bounded viewport.
Vertical separators remain full-width rows between stacked cards.
Arrow-key controls follow that spatial model: vertical mode selects entries
with Up/Down and changes volume with Left/Right, while horizontal mode selects
with Left/Right and changes volume with Up/Down. Holding Shift reorders entries
along the active selection axis; J/K remain orientation-independent selection
aliases, and Shift+J/K provides an orientation-independent reorder path for
terminals that do not distinguish Shift+Arrow.
Lowercase h and ? open an orientation-aware keyboard-help popup with mixer,
configuration, and global controls. Hiding is deliberately assigned to Shift+H
so the common help key does not perform a destructive presentation edit.
The always-visible quick-help footer omits intuitive navigation, volume, and
alternative bindings; it keeps compact non-obvious actions with Add, Edit, and
Delete shown separately. The detailed popup documents J/K, ?, and Home/End.
The selected main-list entry can be moved directly. A opens a chooser for an
application fader, group, or separator. Creating an application fader adds its
application target with a deliberately non-matching exact selector, while a new
group starts empty in absolute mode; both operations add a visible layout entry
and open the field-oriented fader editor. Because draft targets do not exist in
the active runtime yet, the TUI synthesizes a non-writable DRAFT row labeled
"save to activate" until Save publishes the real online or offline object. D
confirms removal of either a separator or a fader with its bindings and layout
entry. A fader's application or group target is also removed when no other fader
owns it; applications still referenced by a group are retained. These compound
edits validate and publish as one draft transaction, so no dangling intermediate
configuration is observable.
The draft must still be saved before it becomes active.
A centered separator dialog edits its name, size, and decoration. Names may be
empty; the stable ID still identifies each separator. Plain with
an empty name creates a spacer, and an unnamed Line/Double separator draws an
unbroken rule. Separator size is independent of fader density:
slim, standard (default), thick, or fill. Size controls height in the
stacked layout and width in the side-by-side layout. Decorations are plain,
line (default), double, or box. A slim stacked separator occupies one
row, or three for a box. Viewports fit entries using their minimum extents
before distributing remaining space evenly among visible Fill separators;
expansion never evicts a fader or wraps the horizontal row. Editing a fader
presents domain fields rather than a serialized command:
- Name: rename the application or group display label while retaining its stable target and fader IDs. Default-output labels remain backend-owned.
- Capture: application selector field, exact/regex mode, and pattern. Pattern values open in a cursor-aware modal with insertion, Backspace, Delete, Home/End, accept, and cancel controls; group faders instead present a member summary that opens a multi-select popup, plus the currently available group mode. Capture also has a Save and exit row to submit field/mode changes without reopening Pattern. Both submission paths validate the current selector using the domain's bounded exact/regex rules before queueing the draft edit; invalid input retains the form and an inline error. Configuration Save remains the separate persistence/activation operation.
- Volume control: controller selection and Learn MIDI. The learn prompt
offers
Uto unbind the current volume assignment andEscto cancel. - Mute control: controller selection and Learn MIDI, with the same prompt shortcuts scoped to the mute assignment. Unbinding cancels capture first, preserves the other action, and retains the selected controller for relearning.
- Size: Slim, Bordered slim, Standard, or Thick vertical presentation for this fader.
- Visibility: Hide from mixer or Show in mixer without changing routing.
Groups select application-targeting faders in a checked multi-select popup; the server stores their deduplicated application IDs because group membership is an audio-domain relationship, not a dependency on a particular physical control. The popup shows this translation and prevents group or output faders from being chosen as members. Absolute remains the only selectable group mode until the reserved relative-mode runtime work is complete.
The secondary Config tab is not an alternative object editor. It presents profile theme, mixer orientation and pickup-status selection, a popup listing all hidden faders for individual restoration, unsaved and Save state, active profile/backend status, the server-resolved loaded configuration path, MIDI-learn cancellation, and MIDI device diagnostics. Object and layout edits stay on the main mixer. Its quick-help footer calls out Left/Right layout switching alongside Save and navigation. There is no separate hidden-fader mode: hidden rows disappear from the mixer and are restored from this popup at their retained layout positions. MIDI devices are selectable settings rows. Their details popup shows stable and backend identity, connection status, and errors, and sets or clears the same profile-backed default controller used by MIDI learn. Removing a device is a confirmed draft edit that atomically removes its surface, bindings, and any default-controller reference; the running MIDI topology changes on Save.
Config also exposes a confirmed emergency reset for the active profile. The
server, never the TUI process, preserves the current on-disk bytes beside the
profile as <profile>.toml.reset.bak, atomically replaces the profile with the
safe default-output configuration, and activates it without issuing audio writes.
The reset clears drafts, routing, MIDI assignments, and presentation settings,
while retaining process-level runtime timing that cannot change under a live
native worker. It does not delete sibling profiles, the active-profile pointer,
or checkpoint state.
Every value presented as configuration is read from the server-owned validated
profile draft and every edit targets that same profile field. The TUI must not
invent parallel configuration defaults or overwrite unrelated fields; local
state is limited to clearly transient navigation and presentation choices such
as selection, open dialogs, and an explicit CLI theme override.
ui.default_controller references a configured MIDI surface. Unassigned volume
and mute controls use that surface for MIDI learn; an explicit binding continues
to name its own surface. The Config tab shows and changes this persisted
default.
Draft changes do not affect live routing or audio. Save is the single server-owned revisioned commit: it persists the validated profile and activates its routing and MIDI configuration. Validation or persistence errors preserve the draft and the prior live configuration. MIDI learn reserves the selected action and suppresses its normal action, and Unset removes only that fader/action binding. Device/backend status remains available from the mixer without requiring a separate configuration table browser.
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 0.11.1 (MIT); owns input/output connections and uses ALSA on Linux. Prefer this to hand-written ALSA MIDI FFI; supplement persistent identity separately. It declares no MSRV, so the locked release is compiled in the Rust 1.88 gate. |
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 |
| Native PipeWire | Official pipewire Rust bindings; full native object access, with more SPA/graph complexity. Keep behind a feature and capability spike. |
pipewire-rs |
| Hardware mixer | alsa for mixer controls and optional MIDI identity enrichment; feature-gated. No promise of application volume control. |
alsa::mixer |
| 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 |
| TUI / events | Keep ratatui plus its compatible crossterm; in-process test backend and terminal event support. |
Ratatui, Crossterm |
| Typed config | serde + toml; toml_edit for preserving profile formatting/comments. Custom semantic validation is still necessary. |
Serde, toml, toml_edit |
| Matching | regex, compiled at load; predictable supported syntax, no need for lookaround/backreferences. |
regex |
| Device metadata | Optional udev; enumerate/monitor Linux devices. Does not itself solve MIDI-port-to-USB association. |
udev |
| CLI | clap derive for typed subcommands/help. |
clap |
| Errors | thiserror in libraries; anyhow at executable boundaries. |
thiserror, anyhow |
| Diagnostics | tracing with a compatible subscriber for structured operation/backend/surface context; rate-limit noisy events. |
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, 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.