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:
parent
0f59b25fc9
commit
e11e537e12
13
CHANGELOG.md
13
CHANGELOG.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
30
checklist.md
30
checklist.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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();
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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" } },
|
||||
]
|
||||
Loading…
Reference in New Issue