docs: document M13 media controls and add a validated QBZ profile

Verify: cargo test -p fader-config --quiet: 60 tests passed, including round-trip validation of all 14 example controls; git diff --check passed; documented UI keys and limits reviewed against implementation. Hardware checklist explicitly remains opt-in and unverified.
This commit is contained in:
Dandaedre 2026-10-18 23:06:58 +02:00
parent 0f59b25fc9
commit e11e537e12
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
9 changed files with 209 additions and 15 deletions

View File

@ -1,5 +1,18 @@
# Changelog
## Unreleased
- Add Any/All application selectors and bounded process/Steam metadata with
normalized diagnostics in Config.
- Add the optional MPRIS Media tab: exact/regex player selection, discovery
picker, persisted entry/control editing, MIDI learn/unbind, transport, seeking,
shuffle, repeat and playlist activation.
- Add confirmed media feedback, custom note/CC color mappings, and global,
per-fader and per-media-entry feedback switches.
- Bound media discovery and configuration; expand bounded IPC frames for playlist
snapshots. Rebuild and restart both server and client. Real-controller/player
checks remain opt-in; see the hands-on checklist.
## 0.1.0-rc.2 — 2026-10-18
- Fix persistent stale-revision failures from MIDI volume/mute after saving

View File

@ -19,7 +19,11 @@ cards, including one-row Slim and Bordered slim faders:
## Features
- Match PulseAudio or `pipewire-pulse` streams by application metadata, with
exact and regular-expression capture rules.
exact and regular-expression capture rules, Any/All composition, and available
executable/working-directory and Steam IDs.
- Target MPRIS players directly from the Media tab or MIDI: transport, seeking,
shuffle, repeat and playlists, with confirmed-state feedback and global/local
feedback switches. See [media configuration](docs/configuration.md#media-controls-mpris).
- Control individual applications, non-nesting application groups, and the
default output without changing live audio during discovery.
- Learn volume and mute controls from MIDI, reflect confirmed mute state on

View File

@ -131,13 +131,13 @@ All outer crates depend inward on domain contracts; core depends on none of them
- 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`.
### Planned matching and media-control extensions
### 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.
captures toggle (Any/OR or All/AND). Process metadata uses bounded Pulse-worker
enrichment; MPRIS controls are implemented on the development branch after RC2.
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
@ -164,7 +164,7 @@ namespace-restricted applications may be unavailable. No command lines or full
environments enter diagnostics. The start-time check follows Linux
[/proc/pid/stat](https://man7.org/linux/man-pages/man5/proc_pid_stat.5.html).
MPRIS controls will address matched player instances over D-Bus using identity,
MPRIS controls 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
@ -185,8 +185,7 @@ 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.
feedback is re-enabled and resynchronized. Save activates feedback-gate changes.
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
@ -213,8 +212,11 @@ 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.
limits player count to 32 and lists the first 256 playlist choices per player.
Exhausted player-discovery bounds fail closed rather than selecting from an
incomplete player set. Polling (rather than signal subscriptions) also observes
external playback/capability changes and replacement owners; it trades a bounded
delay and extra reads for a small, recoverable worker without a second event loop.
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

View File

@ -30,6 +30,36 @@ Known mappings: Music `CC48/Note64`, Browser `CC49/Note65`, Media sync
`CC50/Note66`, and Master `CC56/Note98`. The profile polling interval is 10 ms
and accepts 1–100 ms.
## MPRIS/QBZ opt-in checks (new, not yet hardware-qualified)
Use a disposable profile, build with default `mpris` support and restart both
processes. Start QBZ in the same user's desktop session; leave it paused and
start a second, different MPRIS player to check targeting. Configure the real
controller input/output ports (do not overwrite the checked-in examples).
- [ ] Media appears even with no audio stream; P discovers paused QBZ. A manual
exact bus-name selector reaches QBZ only. A broad regex matching both players
reports ambiguity and sends no command.
- [ ] A/E/D, rename, control action/parameter editing and Save/exit survive Save,
server restart and client reconnect. Unsupported controls show unsupported.
- [ ] Learn Play/Pause/Stop, release/hold buttons and U-unbind. Only presses act;
bindings persist after Save/restart. Removing the surface unbinds controls.
- [ ] Only the confirmed Play/Pause/Stop state lights. External player changes
update LEDs. Verify controller-specific on/off colors; reconnect resynchronizes.
- [ ] Global, per-fader and per-entry feedback switches send no output while off,
including no clearing messages. Re-enable/Save restores observed indicators.
- [ ] Seek forward/back and absolute position, shuffle, repeat and playlist
activation work where QBZ reports support. Unsupported properties stay disabled.
- [ ] Quit/restart QBZ, switch profiles and unplug/replug the controller. Errors
recover; expired commands are not replayed against a replacement player.
Hardware-free D-Bus qualification (creates its own bus and fake players, never
controls desktop applications):
```sh
dbus-run-session -- cargo test -p fader_master private_bus -- --ignored
```
## Mixer smoke test
- [x] TUI shows Music, Browser, Media, Master, and the APC backend ID; startup

View File

@ -6,6 +6,20 @@ const EXAMPLE: &str = include_str!("../../examples/profiles/desktop.toml");
const ARCH_PIPEWIRE: &str = include_str!("../../examples/profiles/arch-pipewire.toml");
const ARCHITECTURE: &str = include_str!("../../architecture.md");
#[test]
fn documented_media_profile_validates_and_round_trips_all_action_kinds() {
let source = include_str!("../../examples/profiles/media-qbz.toml");
let profile = Profile::parse(source).unwrap();
assert_eq!(profile.media()[0].controls.len(), 14);
assert_eq!(
profile,
Profile::parse(&profile.to_toml().unwrap()).unwrap()
);
let mut document = fader_config::ProfileDocument::parse(source).unwrap();
document.set_media_entry(&profile.media()[0]).unwrap();
assert_eq!(document.preview().unwrap().media(), profile.media());
}
#[test]
fn media_configuration_has_a_bounded_ipc_budget() {
let mut source = EXAMPLE.to_owned();

View File

@ -8,6 +8,8 @@
profiles, TOML concepts, migration, validation, and operational commands.
- [Example PipeWire/APC MINI profile](../examples/profiles/arch-pipewire.toml)
- [Example desktop profile](../examples/profiles/desktop.toml)
- [MPRIS controls and editing](configuration.md#media-controls-mpris)
- [Example QBZ media profile](../examples/profiles/media-qbz.toml)
- [Hands-on functional checklist](../checklist.md)
For everyday layout editing: select a fader or separator and press `E`.

View File

@ -9,7 +9,7 @@ The default build includes the PulseAudio protocol adapter and links to
libpulse. MPRIS is enabled by default and also links to libdbus-1. On a Debian-family Linux system, install:
```sh
sudo apt-get install build-essential pkg-config libasound2-dev libpulse-dev libudev-dev libdbus-1-dev
sudo apt-get install build-essential pkg-config libasound2-dev libpulse-dev libudev-dev libdbus-1-dev dbus
rustup toolchain install 1.88.0 \
--profile minimal \
--component rustfmt \
@ -32,10 +32,10 @@ session bus, not playerctl. CI native runners need libdbus development files too
The hardware-free protocol fixture runs with:
```sh
dbus-run-session -- cargo test -p fader_master private_bus_discovers -- --ignored
dbus-run-session -- cargo test -p fader_master private_bus -- --ignored
```
The `Server Name` reported by the last command should contain `PulseAudio (on
The `Server Name` reported by `pactl info` should contain `PulseAudio (on
PipeWire ...)`. Arch packages the headers with `libpulse`, rather than in a
separate development package. The application communicates with PipeWire
through `pipewire-pulse`; it does not require the standalone PulseAudio server.

View File

@ -195,9 +195,96 @@ This already works when the browser exposes a title ending in ` - YouTube`
no browser-name condition or combined window-title matching is required.
Applications must expose this metadata for it to match.
AND selectors and richer process metadata are planned extensions, followed by
direct MPRIS media controls; see M13 in [the backlog](../task.md). They are not
required for the YouTube selector above and are not available in RC2.
AND selectors, richer process metadata and direct MPRIS controls are implemented
on the development branch after RC2; rebuild and restart both server and client.
They are not required for the YouTube selector above.
### Media controls (MPRIS)
The **Media** tab (`3`, or `Tab`) appears when the server has MPRIS support and
can connect to the user's session bus. No running players is a valid empty state.
A later disconnect keeps the tab and configured entries visible. Config reports
why support is unavailable. No keyboard emulation or `playerctl` is used; paused
players are discoverable without an audio stream.
In Media, `A` adds an entry, `E` edits its name/selector/feedback/controls, and
`D` asks before deleting the entry. Select a control and press `Enter` to send it.
Unsupported, offline or ambiguous targets cannot be invoked. Draft edits must be
saved with `S` before commands use them. Entries remain configured while offline.
In the entry editor, `P` lists discovered players. Selecting one prefers its
stable DesktopEntry, falling back to its bus name. You can manually choose
`bus_name`, `desktop_entry` or `identity`, and exact or regex matching. Regexes
use substring matching unless anchored; `(?i)` enables case-insensitivity.
Multiple matches block commands—narrow the selector to an exact instance when
necessary. Instance-specific bus-name suffixes may change across restarts.
Failed identity reads also block identity-based selection until discovery recovers.
`A` inside the editor adds a control, and `D` removes the selected control from
the local edit. Enter a control row to edit its action; use left/right to choose
the action. Seek offsets and positions are milliseconds, bounded to one day.
For playlists, left/right cycles observed playlist IDs and displays their names;
Enter permits manual object-path input. Absolute position uses the observed track
ID and requires a known track length. Shuffle and repeat require the player to
report those properties; playlists require the optional Playlists interface.
Playlist-content editing is not supported. Choose **Save and return to entry**,
then **Save and exit (draft)**, and `S` to persist/activate. Entry validation runs
again at Save and exit; Esc discards the entry edit.
Select a control in the list and press `L` to choose a MIDI device and learn its
input. `U` in that prompt unbinds the selected control; Esc cancels learning.
Save to activate the learned binding. Notes trigger on presses, CCs on zero to
nonzero transitions; releases and repeated held values do not repeat commands.
One physical input cannot also be bound to another media or mixer action.
See the validated [complete media profile](../examples/profiles/media-qbz.toml).
An entry uses this shape (append to a profile containing the `buttons` surface):
```toml
[[media]]
id = "qbz"
label = "QBZ"
feedback_enabled = true
selector = { field = "bus_name", pattern = "org.mpris.MediaPlayer2.com.blitzfc.qbz", regex = false }
controls = [
{ id = "play", action = { kind = "play" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 40 } } },
{ id = "pause", action = { kind = "pause" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 41 } } },
]
```
Actions are `play`, `pause`, `stop`, `play_pause`, `next`, `previous`,
`seek` (`offset_ms`), `set_position` (`position_ms`), `shuffle_toggle`,
`shuffle` (`enabled`), `repeat_cycle`, `repeat` (`mode = "None"`, `"Track"` or
`"Playlist"`) and `playlist` (`id`, a player-reported D-Bus object path).
All actions may have a MIDI binding. Unbound actions remain usable from the TUI.
Feedback defaults to the same learned note/channel, with 127 on and 0 off, when
the surface has an output port. CC inputs have no implicit feedback. Play, Pause
and Stop lights follow the mutually exclusive **observed** playback state, not
the last button pressed. PlayPause follows Playing; shuffle, repeat and playlist
lights follow the properties the player reports. Seek/next/previous have no
latched indicator. Polling picks up external changes; an accepted command is not
proof that a player changed state. Unavailable/ambiguous state clears enabled
indicators. Successful output is deduplicated and reconnects resynchronize it.
For device-specific colors or CC output, learn first, then edit the control's
Custom feedback fields. The equivalent binding field is:
```toml
feedback = { message = { kind = "note", channel = 1, number = 40 }, on = 3, off = 0 }
```
Color values depend on the controller. Root `feedback_enabled = false` overrides
both per-fader and per-media-entry switches, including explicit mappings. Disabled
feedback sends **nothing**, not even a clearing message; old LEDs may remain lit.
Re-enable and Save to resynchronize. Removing a MIDI device unbinds media controls
without deleting entries.
Limits: 128 entries, 64 controls per entry, 256-byte selectors, 256 KiB of media
configuration; discovery handles up to 32 players and lists the first 256 playlists
per player. Oversized/incomplete player discovery fails closed. Calls time out and
errors are reported; missing players are rediscovered automatically. Timed-out
commands are not replayed. Restart both processes after upgrading the IPC build.
### Groups and faders

View File

@ -0,0 +1,42 @@
# Replace port names with your controller's ports, or learn from the TUI.
schema_version = 1
id = "media-qbz"
startup = "adopt"
new_stream = "adopt"
feedback_enabled = true
bindings = []
[audio]
adapter = "auto"
max_gain = 1.0
[[surfaces]]
id = "buttons"
label = "Media buttons"
input_port = "Example Controller MIDI 1"
output_port = "Example Controller MIDI 1"
identity_policy = "require_unique"
motorized = false
[[media]]
id = "qbz"
label = "QBZ"
feedback_enabled = true
selector = { field = "bus_name", pattern = "org.mpris.MediaPlayer2.com.blitzfc.qbz", regex = false }
controls = [
{ id = "play", action = { kind = "play" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 40 } } },
{ id = "pause", action = { kind = "pause" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 41 } } },
{ id = "stop", action = { kind = "stop" }, binding = { surface = "buttons", message = { kind = "note", channel = 1, number = 42 } } },
{ id = "toggle", action = { kind = "play_pause" } },
{ id = "next", action = { kind = "next" } },
{ id = "previous", action = { kind = "previous" } },
{ id = "back", action = { kind = "seek", offset_ms = -10000 } },
{ id = "forward", action = { kind = "seek", offset_ms = 10000 } },
{ id = "beginning", action = { kind = "set_position", position_ms = 0 } },
{ id = "shuffle", action = { kind = "shuffle_toggle" } },
{ id = "shuffle-off", action = { kind = "shuffle", enabled = false } },
{ id = "repeat", action = { kind = "repeat_cycle" } },
{ id = "repeat-track", action = { kind = "repeat", mode = "Track" } },
# Select an actual playlist from the player in the editor; this is a placeholder.
{ id = "favorites", action = { kind = "playlist", id = "/playlist/favorites" } },
]