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.
This commit is contained in:
Dandaedre 2026-10-18 21:48:54 +02:00
parent 704bb3aeaa
commit dc27b764fc
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
3 changed files with 75 additions and 0 deletions

View File

@ -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.

View File

@ -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

28
task.md
View File

@ -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 |