[Pkg-utopia-maintainers] Bug#1068019: wireplumber: please include manpages or other documentation that would hint that wpctl accepts @DEFAULT_SINK@

[Daniel Kahn Gillmor]

Package: wireplumber
Version: 0.4.17-1+b1
Severity: normal
X-Debbugs-Cc: Daniel Kahn Gillmor <dkg at fifthhorseman.net>

I am trying to use wireplumber from the command line (or as a backend to
another controlling tool).  the wireplumber package includes `wpctl`,
which appears to be the thing that i want to use, but there is no manual
page or other local documentation.

I had set myself a basic task: be able to mute and unmute the system
volume using `wpctl`.  Even if i install the wireplumber-doc package,
the html files there don't give me suggestions about how to use wpctl to
control the system volume.  It appears i have to first read and parse
the output of `wpctl status`, which is very messy.

I had to resort to the Arch Wiki
(https://wiki.archlinux.org/title/WirePlumber) to learn that instead of
a numeric ID, i can specify @DEFAULT_SINK@ to do the simple, obvious
thing.

This was not evident from the output of "wpctl --help", and there is no
manual page installed to provide at hint.  Even knowing what to search
for, the only part of the debian packages that i could find evidence of
this critical interface for baseline usability is two places:

0 dkg at alice:~$ grep DEFAULT $(dpkg -L wireplumber-doc wireplumber) 2> /dev/null
/usr/share/doc/wireplumber/html/releases.html:<li><p>wpctl now supports using <code class="docutils literal notranslate"><span class="pre">@DEFAULT_{AUDIO_,VIDEO_,}{SINK,SOURCE}@</span></code> as ID,
/usr/share/zsh/site-functions/_wpctl:    'pw-defaults:defaults:(@DEFAULT_SINK@ @DEFAULT_SOURCE@)' \
2 dkg at alice:~$

Since i don't use zsh, i couldn't even get such a hint from tab
completion.

Please provide better documentation that would enable the user to
discover this from the package itself.  I shouldn't need to search the
Arch wiki (which might itself warns that it might be out of date due to
configuration changes, etc, and anyway might not be relevant to the
version of wireplumber i have installed).

        --dkg

-- System Information:
Debian Release: trixie/sid
  APT prefers testing-debug
  APT policy: (500, 'testing-debug'), (500, 'testing'), (500, 'stable'), (500, 'oldstable'), (200, 'unstable-debug'), (200, 'unstable'), (1, 'experimental-debug'), (1, 'experimental')
Architecture: amd64 (x86_64)

Kernel: Linux 6.6.15-amd64 (SMP w/4 CPU threads; PREEMPT)
Kernel taint flags: TAINT_FIRMWARE_WORKAROUND
Locale: LANG=en_US.UTF-8, LC_CTYPE=en_US.UTF-8 (charmap=UTF-8), LANGUAGE not set
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)

Versions of packages wireplumber depends on:
ii  dbus-user-session [default-dbus-session-bus]  1.14.10-4
ii  dbus-x11 [dbus-session-bus]                   1.14.10-4
ii  init-system-helpers                           1.66
ii  libc6                                         2.37-15
ii  libglib2.0-0                                  2.78.4-1
ii  libpipewire-0.3-0                             1.0.3-1
ii  libwireplumber-0.4-0                          0.4.17-1+b1
ii  pipewire                                      1.0.3-1

Versions of packages wireplumber recommends:
ii  pipewire-pulse  1.0.3-1

Versions of packages wireplumber suggests:
pn  libspa-0.2-bluetooth  <none>
pn  libspa-0.2-libcamera  <none>
pn  wireplumber-doc       <none>

-- no debconf information
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 324 bytes
Desc: not available
URL: <http://alioth-lists.debian.net/pipermail/pkg-utopia-maintainers/attachments/20240329/bdaee02f/attachment.sig>