From dc27b764fcba7057028bd4710d3e6f140117ef13 Mon Sep 17 00:00:00 2001 From: Dandaedre Date: Sun, 18 Oct 2026 21:48:54 +0200 Subject: [PATCH] docs: plan M13 matching and media control stretch goals Document the existing media.name YouTube regex as sufficient. Order AND selectors and process/Steam metadata before targeted MPRIS controls, with dependencies and acceptance criteria; distinguish planned schema from current RC2 behavior. Validation: git diff --cached --check passed; reviewed selector example against current supported fields and OR semantics, and checked M13 references across configuration guide, architecture and backlog. Documentation only; runtime tests not required. --- architecture.md | 30 ++++++++++++++++++++++++++++++ docs/configuration.md | 17 +++++++++++++++++ task.md | 28 ++++++++++++++++++++++++++++ 3 files changed, 75 insertions(+) diff --git a/architecture.md b/architecture.md index 67d761a..505e9db 100644 --- a/architecture.md +++ b/architecture.md @@ -131,6 +131,36 @@ 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 + +The agreed stretch-goal order is AND selectors and richer process metadata, +then targeted MPRIS media controls (M13 in `task.md`). These are future work, +not additions to the current profile 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. +Exact normalized field names and schema syntax remain implementation decisions. + +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 protocol boundary follows the +[MPRIS Player interface](https://specifications.freedesktop.org/mpris/latest/Player_Interface.html). + ## 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. diff --git a/docs/configuration.md b/docs/configuration.md index 8b3aeb4..1147335 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -127,6 +127,23 @@ Supported fields are `application.name`, `application.id`, `application.process.binary`, and `media.name`. Exact matches are whole-string and case-sensitive. Regexes use Rust's bounded `regex` syntax. +To capture YouTube playback by its reported media title, use: + +```toml +selectors = [ + { field = "media.name", regex = '(?i) - YouTube$' }, +] +``` + +This already works when the browser exposes a title ending in ` - YouTube` +(as observed with Waterfox). The media-title selector alone is sufficient; +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. + ### Groups and faders Groups contain application IDs, never other groups. The TUI presents eligible diff --git a/task.md b/task.md index 3499ab5..b5adb00 100644 --- a/task.md +++ b/task.md @@ -570,6 +570,34 @@ Dependencies: all required feature milestones; hardware-only ALSA remains an exp isolated cargo-binstall verification passed. The release API confirms a non-draft prerelease; build provenance is recorded in `docs/releasing.md`. +## M13 — Stretch goals: matching and targeted media controls + +Agreed order: M13.1 and M13.2 first, then M13.3. These do not change RC2's +supported configuration or mark the remaining release qualifications complete. +The existing `media.name` selector `(?i) - YouTube$` already satisfies the +YouTube capture use case; no browser-name condition is needed. + +- [ ] **M13.1 AND selectors:** add explicit conjunction while preserving existing + OR-list behavior. Dependencies: M1.2, M9.5. Acceptance: configuration and TUI + express the composition clearly; exact/regex and missing-field behavior are + deterministic; existing profiles retain their matches; invalid composition + is rejected before activation; save/reload preserves the expression. +- [ ] **M13.2 Richer process metadata:** enrich stream metadata with available + process paths and Steam launch identity, then expose validated matcher fields + and useful diagnostics. Dependencies: M1.2, M4. Acceptance: bounded adapter + reads, PID-reuse protection, selective Steam environment keys, and explicit + unavailable state for exited/inaccessible/sandboxed processes. Tests cover + native and Proton-like fixtures, Steam IDs, non-Steam processes and path-only + hints; a `steamapps` path must not be treated as proof Steam launched a game. +- [ ] **M13.3 Targeted MPRIS controls:** add Play, Pause and PlayPause via matched + player identity/desktop ID/bus name, without keyboard simulation. + Dependencies: M13.1, M13.2, M5.2, M9.5. Acceptance: a QBZ-specific binding + affects only its resolved player; paused players with no audio stream remain + discoverable; ambiguous matches are surfaced; missing players, unsupported + capabilities, disconnects and timeouts are recoverable. Cover MIDI learn, + saved configuration, TUI controls and confirmed playback-state feedback with + a fake D-Bus adapter before opt-in player integration checks. + ## User requirement coverage | # | Requirement | Work items |