diff --git a/CHANGELOG.md b/CHANGELOG.md index b898ed2..f3fc1e6 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 974e66c..f20c216 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/architecture.md b/architecture.md index 0e6487b..0e08d2f 100644 --- a/architecture.md +++ b/architecture.md @@ -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 diff --git a/checklist.md b/checklist.md index 64a8794..32fb4fd 100644 --- a/checklist.md +++ b/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 diff --git a/config/tests/schema.rs b/config/tests/schema.rs index 8a6434b..227d809 100644 --- a/config/tests/schema.rs +++ b/config/tests/schema.rs @@ -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(); diff --git a/docs/README.md b/docs/README.md index b5657c0..4fe2d6d 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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`. diff --git a/docs/build.md b/docs/build.md index 05cc917..1eb815f 100644 --- a/docs/build.md +++ b/docs/build.md @@ -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. diff --git a/docs/configuration.md b/docs/configuration.md index ab255c0..eac5679 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -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 diff --git a/examples/profiles/media-qbz.toml b/examples/profiles/media-qbz.toml new file mode 100644 index 0000000..889ab08 --- /dev/null +++ b/examples/profiles/media-qbz.toml @@ -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" } }, +]