feat(M5.4): route pickup-safe APC controls

Route the configured APC MINI faders and buttons through the live mixer, with pickup rearming after external changes and controller reconnects.\n\nTests: cargo test --locked -p fader_master --test live_mixer --all-features\nTests: cargo test --locked -p fader_master midi_runtime::tests --all-features\nTests: cargo clippy --locked -p fader-config -p fader_master --all-targets --all-features -- -D warnings
This commit is contained in:
Dandaedre 2026-10-15 02:51:21 +02:00
parent 5721a713a0
commit 8b5df92d3e
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
9 changed files with 483 additions and 23 deletions

View File

@ -23,8 +23,8 @@ pub use error::ConfigError;
pub use files::{AtomicFile, MigrationError, PersistenceError, StateLoad, migrate_profile};
pub use paths::{XdgEnvironment, XdgPaths};
pub use profile::{
Adapter, Application, Audio, Binding, Fader, Group, NewStreamPolicy, Profile, StartupPolicy,
Surface,
Action, Adapter, Application, Audio, Binding, Fader, Group, MessageKind, NewStreamPolicy,
Profile, StartupPolicy, Surface, TargetKind,
};
pub use state::{
CachedObservation, DesiredWrite, PersistedState, ProfileState, StartupState, UiView,

View File

@ -127,7 +127,7 @@ pub struct Surface {
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
enum TargetKind {
pub enum TargetKind {
Application,
Group,
}
@ -151,14 +151,14 @@ pub struct Fader {
#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
#[serde(rename_all = "snake_case")]
enum Action {
pub enum Action {
Volume,
ToggleMute,
}
#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
#[serde(rename_all = "snake_case")]
enum MessageKind {
pub enum MessageKind {
Cc,
Note,
}
@ -274,6 +274,10 @@ impl Profile {
&self.raw.surfaces
}
pub fn faders(&self) -> &[Fader] {
&self.raw.faders
}
/// Validated bindings.
pub fn bindings(&self) -> &[Binding] {
&self.raw.bindings
@ -434,6 +438,54 @@ impl Surface {
}
}
impl Fader {
pub fn id(&self) -> &str {
&self.id
}
pub const fn target_kind(&self) -> TargetKind {
self.target.kind
}
pub fn target_id(&self) -> &str {
&self.target.id
}
pub const fn pickup(&self) -> bool {
self.pickup
}
pub const fn pickup_tolerance(&self) -> f64 {
self.pickup_tolerance
}
}
impl Binding {
pub fn surface(&self) -> &str {
&self.surface
}
pub fn fader(&self) -> &str {
&self.fader
}
pub const fn action(&self) -> Action {
self.action
}
pub const fn message_kind(&self) -> MessageKind {
self.message.kind
}
pub const fn channel(&self) -> u16 {
self.message.channel
}
pub const fn number(&self) -> u16 {
self.message.number
}
}
fn validate_version(version: u16) -> Result<(), ConfigError> {
if version == SCHEMA_VERSION {
Ok(())

View File

@ -80,6 +80,10 @@ fn arch_pipewire_profile_matches_reported_qobuz_metadata() {
assert_eq!(surface.usb_vendor_id(), Some("09e8"));
assert_eq!(surface.usb_product_id(), Some("0028"));
assert_eq!(surface.usb_serial(), Some("Ver00.10"));
assert_eq!(profile.faders().len(), 3);
assert_eq!(profile.bindings().len(), 6);
assert_eq!(profile.bindings()[0].number(), 48);
assert_eq!(profile.bindings()[5].number(), 98);
}
#[test]

View File

@ -38,3 +38,60 @@ usb_product_id = "0028"
usb_serial = "Ver00.10"
identity_policy = "require_unique"
motorized = false
[[faders]]
id = "music-fader"
target = { kind = "application", id = "music" }
pickup = true
pickup_tolerance = 0.02
[[faders]]
id = "browser-fader"
target = { kind = "application", id = "browser" }
pickup = true
pickup_tolerance = 0.02
[[faders]]
id = "media-fader"
target = { kind = "group", id = "media" }
pickup = true
pickup_tolerance = 0.02
[[bindings]]
surface = "apc-mini"
fader = "music-fader"
action = "volume"
message = { kind = "cc", channel = 1, number = 48 }
[[bindings]]
surface = "apc-mini"
fader = "browser-fader"
action = "volume"
message = { kind = "cc", channel = 1, number = 49 }
[[bindings]]
surface = "apc-mini"
fader = "media-fader"
action = "volume"
message = { kind = "cc", channel = 1, number = 56 }
[[bindings]]
surface = "apc-mini"
fader = "music-fader"
action = "toggle_mute"
edge = "press"
message = { kind = "note", channel = 1, number = 64 }
[[bindings]]
surface = "apc-mini"
fader = "browser-fader"
action = "toggle_mute"
edge = "press"
message = { kind = "note", channel = 1, number = 65 }
[[bindings]]
surface = "apc-mini"
fader = "media-fader"
action = "toggle_mute"
edge = "press"
message = { kind = "note", channel = 1, number = 98 }

View File

@ -2,10 +2,11 @@ use std::collections::{BTreeMap, BTreeSet};
use fader_config::Profile;
use fader_core::{
AdapterCommand, AdapterEvent, ApplicationMatcher, ChannelGains, CommandOrigin, Gain, Mute,
ServerCommand, ServerReducer, StreamHandle, StreamMetadata, ValueState, VolumeMode, mute_view,
plan_volume, volume_view,
AdapterCommand, AdapterEvent, ApplicationMatcher, ChannelGains, CommandOrigin, FaderId, Gain,
Mute, Pickup, PickupState, ServerCommand, ServerReducer, StreamHandle, StreamMetadata,
SurfaceId, ValueState, VolumeMode, mute_view, plan_volume, volume_view,
};
use midi::MidiIntent;
use thiserror::Error;
use volume_lib::WorkerEvent;
@ -35,6 +36,13 @@ struct ConfiguredGroup {
volume_mode: VolumeMode,
}
#[derive(Clone, Debug)]
struct ConfiguredFader {
target: MixerObjectKey,
pickup: bool,
tolerance: f64,
}
/// Pure profile-aware mixer state between the audio worker and IPC clients.
#[derive(Debug)]
pub struct LiveMixerState {
@ -42,6 +50,8 @@ pub struct LiveMixerState {
metadata: BTreeMap<StreamHandle, MetadataView>,
applications: Vec<ConfiguredApplication>,
groups: Vec<ConfiguredGroup>,
faders: BTreeMap<FaderId, ConfiguredFader>,
pickups: BTreeMap<(SurfaceId, FaderId), Pickup>,
devices: Vec<MidiDevice>,
write_ceiling: Gain,
backend: String,
@ -68,6 +78,12 @@ pub enum LiveMixerError {
OfflineObject { kind: MixerObjectKind, id: String },
#[error("mixer object {kind:?} {id:?} contains a read-only stream")]
ReadOnlyObject { kind: MixerObjectKind, id: String },
#[error("MIDI fader {0} is not configured")]
UnknownFader(FaderId),
#[error("pickup state error: {0}")]
Pickup(String),
#[error("invalid runtime profile: {0}")]
Profile(String),
}
impl LiveMixerState {
@ -97,11 +113,36 @@ impl LiveMixerState {
volume_mode: group.volume_mode(),
})
.collect();
let faders = profile
.faders()
.iter()
.map(|fader| {
Ok((
FaderId::new(fader.id())
.map_err(|error| LiveMixerError::Profile(error.to_string()))?,
ConfiguredFader {
target: MixerObjectKey {
kind: match fader.target_kind() {
fader_config::TargetKind::Application => {
MixerObjectKind::Application
}
fader_config::TargetKind::Group => MixerObjectKind::Group,
},
id: fader.target_id().to_owned(),
},
pickup: fader.pickup(),
tolerance: fader.pickup_tolerance(),
},
))
})
.collect::<Result<_, LiveMixerError>>()?;
Ok(Self {
reducer: ServerReducer::new(write_ceiling),
metadata: BTreeMap::new(),
applications,
groups,
faders,
pickups: BTreeMap::new(),
devices: Vec::new(),
write_ceiling,
backend: backend.into(),
@ -132,10 +173,21 @@ impl LiveMixerState {
);
}
WorkerEvent::Adapter(event) => {
let affected_faders = match &event {
AdapterEvent::Observed {
stream,
operation: None,
..
}
| AdapterEvent::StreamRemoved { stream } => self.faders_for_stream(*stream),
_ => Vec::new(),
};
if let AdapterEvent::StreamRemoved { stream } = &event {
self.metadata.remove(stream);
}
return Ok(self.reducer.event(event)?.adapter);
let commands = self.reducer.event(event)?.adapter;
self.rearm_faders(&affected_faders);
return Ok(commands);
}
WorkerEvent::Disconnected { message, .. } => {
self.status = format!("unavailable: {message}");
@ -177,9 +229,147 @@ impl LiveMixerState {
}
pub fn set_devices(&mut self, devices: Vec<MidiDevice>) {
for previous in self
.devices
.iter()
.filter(|device| device.status == "connected")
{
let connection_preserved = devices.iter().any(|device| {
device.id == previous.id
&& device.status == "connected"
&& device.backend_id == previous.backend_id
});
if !connection_preserved && let Ok(surface) = SurfaceId::new(&previous.id) {
self.pickups
.iter_mut()
.filter(|((pickup_surface, _), _)| pickup_surface == &surface)
.for_each(|(_, pickup)| pickup.disconnect());
}
}
self.devices = devices;
}
pub fn midi_intent(
&mut self,
intent: MidiIntent,
sequence: u64,
) -> Result<Vec<AdapterCommand>, LiveMixerError> {
match intent {
MidiIntent::AbsoluteVolume {
surface,
fader,
gain,
} => {
let configured = self
.faders
.get(&fader)
.cloned()
.ok_or_else(|| LiveMixerError::UnknownFader(fader.clone()))?;
let key = (surface, fader);
let target = if configured.pickup {
let needs_arming = self
.pickups
.get(&key)
.is_none_or(|pickup| pickup.state() == PickupState::Unavailable);
if needs_arming {
let observed = self.object_gain(&configured.target).ok_or_else(|| {
LiveMixerError::OfflineObject {
kind: configured.target.kind,
id: configured.target.id.clone(),
}
})?;
let mut pickup = Pickup::new(configured.tolerance)
.map_err(|error| LiveMixerError::Pickup(error.to_string()))?;
pickup.arm(observed);
self.pickups.insert(key.clone(), pickup);
}
let pickup = self.pickups.get_mut(&key).ok_or_else(|| {
LiveMixerError::Pickup("pickup state disappeared".to_owned())
})?;
let Some(target) = pickup.input(gain) else {
return Ok(Vec::new());
};
target
} else {
gain
};
let commands = self.set_volume(
configured.target.clone(),
target,
self.reducer.revision().get(),
sequence,
)?;
self.rearm_other_pickups(&key, &configured.target, target);
Ok(commands)
}
MidiIntent::ToggleMute { fader, .. } => {
let configured = self
.faders
.get(&fader)
.cloned()
.ok_or(LiveMixerError::UnknownFader(fader))?;
self.toggle_mute(configured.target, self.reducer.revision().get(), sequence)
}
}
}
fn object_gain(&self, object: &MixerObjectKey) -> Option<Gain> {
let (handles, _) = self.resolve(object).ok()?;
handles
.into_iter()
.filter_map(|handle| self.reducer.view(handle))
.map(|view| view.channels.maximum())
.max_by(|left, right| left.partial_cmp(right).unwrap_or(std::cmp::Ordering::Equal))
}
fn faders_for_stream(&self, stream: StreamHandle) -> Vec<FaderId> {
self.faders
.iter()
.filter_map(|(fader, configured)| {
self.resolve(&configured.target)
.ok()
.filter(|(handles, _)| handles.contains(&stream))
.map(|_| fader.clone())
})
.collect()
}
fn rearm_faders(&mut self, faders: &[FaderId]) {
let targets: BTreeMap<_, _> = faders
.iter()
.filter_map(|fader| {
let configured = self.faders.get(fader)?;
Some((fader.clone(), self.object_gain(&configured.target)))
})
.collect();
for ((_, fader), pickup) in &mut self.pickups {
if let Some(target) = targets.get(fader) {
match target {
Some(gain) => pickup.arm(*gain),
None => pickup.disconnect(),
}
}
}
}
fn rearm_other_pickups(
&mut self,
source: &(SurfaceId, FaderId),
object: &MixerObjectKey,
target: Gain,
) {
for (key, pickup) in &mut self.pickups {
if key != source
&& self
.faders
.get(&key.1)
.is_some_and(|configured| configured.target == *object)
{
pickup.arm(target);
}
}
}
pub fn request(
&mut self,
request: ClientRequest,

View File

@ -53,6 +53,8 @@ pub enum LocalError {
WorkerDisconnected,
#[error("MIDI runtime configuration failed: {0}")]
MidiRuntime(String),
#[error("MIDI input sequence exhausted")]
MidiSequence,
#[error(transparent)]
Mixer(#[from] crate::live::LiveMixerError),
#[error(transparent)]
@ -170,6 +172,7 @@ pub struct LocalServer {
worker: PulseWorker,
mixer: LiveMixerState,
midi: crate::midi_runtime::MidiRuntime,
midi_sequence: u64,
}
impl LocalServer {
@ -185,6 +188,7 @@ impl LocalServer {
worker: PulseWorker::spawn(BackendEpoch::new(1), 256),
mixer: LiveMixerState::new(write_ceiling, "pulse", profile)?,
midi,
midi_sequence: 1,
})
}
@ -196,7 +200,15 @@ impl LocalServer {
}
pub fn tick(&mut self) -> Result<(), LocalError> {
self.midi.tick();
for intent in self.midi.tick() {
let sequence = self.midi_sequence;
self.midi_sequence = self
.midi_sequence
.checked_add(1)
.ok_or(LocalError::MidiSequence)?;
let commands = self.mixer.midi_intent(intent, sequence)?;
self.submit(commands)?;
}
self.mixer.set_devices(self.midi.snapshot());
match self.worker.receive_timeout(SERVER_TICK) {
Ok(event) => {

View File

@ -5,10 +5,13 @@ use std::{
};
use fader_config::Profile;
use fader_core::SurfaceId;
use fader_core::{
Binding as CoreBinding, BindingAction, BindingKey, Bindings, FaderId, MessageKind, MidiChannel,
MidiData, SurfaceId,
};
use midi::{
DeviceMatch, LinuxIdentityCatalog, MidiInputCatalog, MidiInputConnection, MidiInputEvent,
SurfaceAction, SurfaceAssignment, SurfaceLifecycle, SurfaceStatus,
MidiIntent, MidiRouter, SurfaceAction, SurfaceAssignment, SurfaceLifecycle, SurfaceStatus,
};
use crate::ipc::MidiDevice;
@ -25,6 +28,7 @@ pub struct MidiRuntime {
receiver: Receiver<MidiInputEvent>,
last_scan: Option<Instant>,
scan_error: Option<String>,
router: MidiRouter,
}
impl std::fmt::Debug for MidiRuntime {
@ -61,6 +65,34 @@ impl MidiRuntime {
})
.collect::<Result<Vec<_>, String>>()?;
let lifecycle = SurfaceLifecycle::new(assignments).map_err(|error| error.to_string())?;
let bindings = profile
.bindings()
.iter()
.map(|binding| {
Ok((
BindingKey {
surface: SurfaceId::new(binding.surface())
.map_err(|error| error.to_string())?,
channel: MidiChannel::new(binding.channel())
.map_err(|error| error.to_string())?,
kind: match binding.message_kind() {
fader_config::MessageKind::Cc => MessageKind::ControlChange,
fader_config::MessageKind::Note => MessageKind::Note,
},
number: MidiData::new(binding.number())
.map_err(|error| error.to_string())?,
},
CoreBinding {
fader: FaderId::new(binding.fader()).map_err(|error| error.to_string())?,
action: match binding.action() {
fader_config::Action::Volume => BindingAction::Volume,
fader_config::Action::ToggleMute => BindingAction::ToggleMute,
},
},
))
})
.collect::<Result<Vec<_>, String>>()?;
let router = MidiRouter::new(Bindings::new(bindings).map_err(|error| error.to_string())?);
let (sender, receiver) = sync_channel(EVENT_CAPACITY);
Ok(Self {
lifecycle,
@ -70,10 +102,11 @@ impl MidiRuntime {
receiver,
last_scan: None,
scan_error: None,
router,
})
}
pub fn tick(&mut self) {
pub fn tick(&mut self) -> Vec<MidiIntent> {
if self
.last_scan
.is_none_or(|last| last.elapsed() >= SCAN_INTERVAL)
@ -81,11 +114,16 @@ impl MidiRuntime {
self.scan();
self.last_scan = Some(Instant::now());
}
let mut intents = Vec::new();
loop {
match self.receiver.try_recv() {
// Routing is activated in the next boundary; draining keeps the
// native callback bounded without allowing audio side effects.
Ok(MidiInputEvent::Message { .. }) => {}
Ok(MidiInputEvent::Message {
surface, message, ..
}) => {
if let Some(intent) = self.router.route(&surface, message) {
intents.push(intent);
}
}
Ok(MidiInputEvent::Malformed { error, .. }) => {
self.scan_error = Some(format!("malformed MIDI input: {error}"));
}
@ -99,6 +137,7 @@ impl MidiRuntime {
{
self.scan_error = Some("MIDI input queue overflowed; reconnect required".to_owned());
}
intents
}
#[must_use]
@ -198,6 +237,8 @@ impl MidiRuntime {
#[cfg(test)]
mod tests {
use super::*;
use fader_core::{MidiChannel, MidiData};
use midi::{ButtonEdge, MidiMessage};
#[test]
fn configured_surfaces_exist_as_missing_before_native_discovery() {
@ -215,4 +256,37 @@ mod tests {
}]
);
}
#[test]
fn arch_profile_routes_the_selected_apc_controls() {
let profile =
Profile::parse(include_str!("../../examples/profiles/arch-pipewire.toml")).unwrap();
let mut runtime = MidiRuntime::new(&profile).unwrap();
let surface = SurfaceId::new("apc-mini").unwrap();
let volume = runtime.router.route(
&surface,
MidiMessage::ControlChange {
channel: MidiChannel::new(1).unwrap(),
number: MidiData::new(48).unwrap(),
value: MidiData::new(127).unwrap(),
},
);
assert!(matches!(
volume,
Some(MidiIntent::AbsoluteVolume { fader, .. }) if fader.as_str() == "music-fader"
));
let mute = runtime.router.route(
&surface,
MidiMessage::Note {
channel: MidiChannel::new(1).unwrap(),
number: MidiData::new(64).unwrap(),
velocity: MidiData::new(127).unwrap(),
edge: ButtonEdge::Press,
},
);
assert!(matches!(
mute,
Some(MidiIntent::ToggleMute { fader, .. }) if fader.as_str() == "music-fader"
));
}
}

View File

@ -1,14 +1,16 @@
use fader_config::Profile;
use fader_core::{
AdapterEvent, BackendEpoch, ChannelGains, Gain, Mute, StreamHandle, StreamMetadata,
AdapterEvent, BackendEpoch, ChannelGains, FaderId, Gain, Mute, StreamHandle, StreamMetadata,
SurfaceId,
};
use fader_master::{
ipc::{
ClientRequest, MixerObjectKey, MixerObjectKind, PROTOCOL_VERSION, RequestCommand,
ResponseResult,
ClientRequest, MidiDevice, MixerObjectKey, MixerObjectKind, PROTOCOL_VERSION,
RequestCommand, ResponseResult,
},
live::LiveMixerState,
};
use midi::MidiIntent;
use volume_lib::WorkerEvent;
fn gain(value: f64) -> Gain {
@ -208,3 +210,70 @@ fn lagging_client_cannot_overwrite_an_edit_and_can_resnapshot() {
assert!(snapshot.revision > attached.revision);
assert!(snapshot.objects[0].pending);
}
#[test]
fn midi_volume_waits_for_pickup_crossing_before_dispatch() {
let mut state = ready_state();
let surface = SurfaceId::new("desk-left").unwrap();
let fader = FaderId::new("media-fader").unwrap();
let intent = |value| MidiIntent::AbsoluteVolume {
surface: surface.clone(),
fader: fader.clone(),
gain: gain(value),
};
assert!(state.midi_intent(intent(0.1), 1).unwrap().is_empty());
assert!(state.midi_intent(intent(0.3), 2).unwrap().is_empty());
let commands = state.midi_intent(intent(0.5), 3).unwrap();
assert_eq!(commands.len(), 1);
assert!(matches!(
commands[0],
fader_core::AdapterCommand::SetVolume { .. }
));
}
#[test]
fn external_volume_change_rearms_midi_pickup() {
let mut state = ready_state();
let surface = SurfaceId::new("desk-left").unwrap();
let fader = FaderId::new("media-fader").unwrap();
let intent = |value| MidiIntent::AbsoluteVolume {
surface: surface.clone(),
fader: fader.clone(),
gain: gain(value),
};
assert!(state.midi_intent(intent(0.4), 1).unwrap().len() == 1);
state
.worker_event(observed_for(stream(), [0.8, 0.8], Mute::Unmuted, None))
.unwrap();
assert!(state.midi_intent(intent(0.5), 2).unwrap().is_empty());
assert_eq!(state.midi_intent(intent(0.8), 3).unwrap().len(), 1);
}
#[test]
fn controller_disconnect_forgets_the_tracked_physical_position() {
let mut state = ready_state();
let surface = SurfaceId::new("desk-left").unwrap();
let fader = FaderId::new("media-fader").unwrap();
let intent = |value| MidiIntent::AbsoluteVolume {
surface: surface.clone(),
fader: fader.clone(),
gain: gain(value),
};
let device = |status: &str, backend_id: Option<&str>| MidiDevice {
id: "desk-left".to_owned(),
label: "Left controller".to_owned(),
status: status.to_owned(),
backend_id: backend_id.map(str::to_owned),
error: None,
};
state.set_devices(vec![device("connected", Some("36:0"))]);
assert_eq!(state.midi_intent(intent(0.4), 1).unwrap().len(), 1);
state.set_devices(vec![device("missing", None)]);
assert!(state.midi_intent(intent(0.2), 2).unwrap().is_empty());
assert_eq!(state.midi_intent(intent(0.4), 3).unwrap().len(), 1);
}

10
task.md
View File

@ -177,10 +177,12 @@ Dependencies: M3; M4 for full end-to-end acceptance.
smoke run connected the APC MINI as `36:0`; keep this item open for physical
unplug/replug acceptance and durable editor-managed assignment persistence.
- [ ] **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.
The pure pickup state machine now covers startup inhibition, tolerance and
crossing activation, external-change/reconnect resets, competing surfaces,
and above-range endpoint pickup. Keep this item open until routed live MIDI
uses the state and publishes it to the TUI.
The pure pickup state machine and routed live server cover startup inhibition,
tolerance and crossing activation, external-change/reconnect resets,
competing surfaces, and above-range endpoint pickup. The Arch profile routes
APC MINI CC 48/49/56 and notes 64/65/98 to Music, Browser, and Media. Keep
this item open until pickup state is published to the TUI and profile-switch
rearming is implemented.
- [ ] **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.
M5.1 verification on 2026-10-14: nine decoder/router/transport tests pass with