From a5e58536dd315a0d08226fc5d4f45c871c9f8b8d Mon Sep 17 00:00:00 2001 From: George Kiagiadakis Date: Fri, 5 Sep 2025 18:15:08 +0300 Subject: [PATCH] docs: add wpctl man page and Tools documentation section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add comprehensive wpctl documentation that generates both HTML docs and an installable man page from a single RST source. Closes: #825 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude --- docs/conf.py.in | 10 ++ docs/meson.build | 20 +++ docs/rst/index.rst | 6 + docs/rst/meson.build | 1 + docs/rst/tools/meson.build | 3 + docs/rst/tools/wpctl.rst | 309 +++++++++++++++++++++++++++++++++++++ 6 files changed, 349 insertions(+) create mode 100644 docs/rst/tools/meson.build create mode 100644 docs/rst/tools/wpctl.rst diff --git a/docs/conf.py.in b/docs/conf.py.in index 24be3a8d..d0ea6ab9 100644 --- a/docs/conf.py.in +++ b/docs/conf.py.in @@ -6,6 +6,10 @@ author = 'Collabora' release = '@VERSION@' version = '@VERSION@' +# -- General configuration --------------------------------------------------- + +smartquotes = False + # -- Breathe configuration --------------------------------------------------- extensions = [ @@ -43,3 +47,9 @@ html_css_files = ['custom.css'] graphviz_output_format = "svg" pygments_style = "friendly" + +# -- Options for manual page output ----------------------------------------- + +man_pages = [ + ('tools/wpctl', 'wpctl', 'WirePlumber Control CLI', ['The WirePlumber Developers'], 1) +] diff --git a/docs/meson.build b/docs/meson.build index f24ae6dd..d5eec97d 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -102,6 +102,26 @@ if build_doc install_dir: wireplumber_doc_dir, build_by_default: true, ) + + # Generate man pages directory with sphinx + custom_target('manpages', + command: [sphinx_p, + '-q', # quiet + '-E', # rebuild from scratch + '-b', 'man', # man page builder + '-d', '@PRIVATE_DIR@', # doctrees dir + '-c', '@OUTDIR@', # conf.py dir + '@CURRENT_SOURCE_DIR@/rst', # source dir + '@OUTDIR@', # output directory + ], + depend_files: [ + sphinx_conf, sphinx_files, + ], + output: ['wpctl.1'], + install: true, + install_dir: get_option('mandir') / 'man1', + build_by_default: true, + ) endif # Build GObject introspection diff --git a/docs/rst/index.rst b/docs/rst/index.rst index 06315bd1..71ccae9a 100644 --- a/docs/rst/index.rst +++ b/docs/rst/index.rst @@ -44,6 +44,12 @@ Table of Contents scripting/existing_scripts.rst scripting/custom_scripts.rst +.. toctree:: + :maxdepth: 2 + :caption: Tools + + tools/wpctl.rst + .. toctree:: :maxdepth: 2 :caption: Resources diff --git a/docs/rst/meson.build b/docs/rst/meson.build index 2705ea95..1e2beee3 100644 --- a/docs/rst/meson.build +++ b/docs/rst/meson.build @@ -8,4 +8,5 @@ subdir('design') subdir('policies') subdir('library') subdir('scripting') +subdir('tools') subdir('resources') diff --git a/docs/rst/tools/meson.build b/docs/rst/tools/meson.build new file mode 100644 index 00000000..8c9a1437 --- /dev/null +++ b/docs/rst/tools/meson.build @@ -0,0 +1,3 @@ +sphinx_files += files( + 'wpctl.rst', +) diff --git a/docs/rst/tools/wpctl.rst b/docs/rst/tools/wpctl.rst new file mode 100644 index 00000000..b132f879 --- /dev/null +++ b/docs/rst/tools/wpctl.rst @@ -0,0 +1,309 @@ +wpctl(1) +======== + +SYNOPSIS +-------- + +**wpctl** [*COMMAND*] [*COMMAND_OPTIONS*] + +DESCRIPTION +----------- + +**wpctl** is a command-line control tool for WirePlumber, the PipeWire session +manager. It provides an interface to inspect, control, and configure audio and +video devices, nodes, and their properties within a PipeWire media server. + +WirePlumber manages audio and video routing, device configuration, and session +policies. **wpctl** allows users to interact with these components, change +volume levels, set default devices, inspect object properties, and modify +settings. + +COMMANDS +-------- + +status +^^^^^^ + +**wpctl status** [**-k**\|\ **--nick**] [**-n**\|\ **--name**] + +Displays the current state of objects in PipeWire, including devices, sinks, +sources, filters, and streams. Shows a hierarchical view of the audio/video +system. + +Options: + **-k**, **--nick** + Display device and node nicknames instead of descriptions + **-n**, **--name** + Display device and node names instead of descriptions + +get-volume +^^^^^^^^^^ + +**wpctl get-volume** *ID* + +Displays volume information about the specified node, including current volume +level and mute state. + +Arguments: + *ID* + Node ID or special identifier (see `SPECIAL IDENTIFIERS`_) + +inspect +^^^^^^^ + +**wpctl inspect** *ID* [**-r**\|\ **--referenced**] [**-a**\|\ **--associated**] + +Displays detailed information about the specified object, including all +properties and metadata. + +Arguments: + *ID* + Object ID or special identifier + +Options: + **-r**, **--referenced** + Show objects that are referenced in properties + **-a**, **--associated** + Show associated objects + +set-default +^^^^^^^^^^^ + +**wpctl set-default** *ID* + +Sets the specified device node to be the default target of its kind (capture or +playback) for new streams that require auto-connection. + +Arguments: + *ID* + Sink or source node ID + +set-volume +^^^^^^^^^^ + +**wpctl set-volume** *ID* *VOL*\ [**%**]\ [**-**\|\ **+**] [**-p**\|\ **--pid**] [**-l** *LIMIT*\|\ **--limit** *LIMIT*] + +Sets the volume of the specified node. + +Arguments: + *ID* + Node ID, special identifier, or PID (with --pid) + *VOL*\ [**%**]\ [**-**\|\ **+**] + Volume specification: + + - *VOL* - Set volume to specific value (1.0 = 100%) + - *VOL*\ **%** - Set volume to percentage (50% = 0.5) + - *VOL*\ **+** - Increase volume by value + - *VOL*\ **-** - Decrease volume by value + - *VOL*\ **%+** - Increase volume by percentage + - *VOL*\ **%-** - Decrease volume by percentage + +Options: + **-p**, **--pid** + Treat ID as a process ID and affect all nodes associated with it + **-l** *LIMIT*, **--limit** *LIMIT* + Limit final volume to below this value (floating point, 1.0 = 100%) + +Examples: + Set volume to 50%: ``wpctl set-volume @DEFAULT_SINK@ 0.5`` + + Increase volume by 10%: ``wpctl set-volume 42 10%+`` + + Set volume for all nodes of PID 1234: ``wpctl set-volume --pid 1234 0.8`` + +set-mute +^^^^^^^^ + +**wpctl set-mute** *ID* **1**\|\ **0**\|\ **toggle** [**-p**\|\ **--pid**] + +Changes the mute state of the specified node. + +Arguments: + *ID* + Node ID, special identifier, or PID (with --pid) + **1**\|\ **0**\|\ **toggle** + Mute state: 1 (mute), 0 (unmute), or toggle current state + +Options: + **-p**, **--pid** + Treat ID as a process ID and affect all nodes associated with it + +set-profile +^^^^^^^^^^^ + +**wpctl set-profile** *ID* *INDEX* + +Sets the profile of the specified device to the given index. + +Arguments: + *ID* + Device ID or special identifier + *INDEX* + Profile index (integer, 0 typically means 'off') + +set-route +^^^^^^^^^ + +**wpctl set-route** *ID* *INDEX* + +Sets the route of the specified device to the given index. + +Arguments: + *ID* + Device node ID or special identifier + *INDEX* + Route index (integer, 0 typically means 'off') + +clear-default +^^^^^^^^^^^^^ + +**wpctl clear-default** [*ID*] + +Clears the default configured node. If no ID is specified, clears all default +nodes. + +Arguments: + *ID* (optional) + Settings ID to clear (0-2 for Audio/Sink, Audio/Source, Video/Source). + If omitted, clears all defaults. + +settings +^^^^^^^^ + +**wpctl settings** [*KEY*] [*VAL*] [**-d**\|\ **--delete**] [**-s**\|\ **--save**] [**-r**\|\ **--reset**] + +Shows, changes, or removes WirePlumber settings. + +Arguments: + *KEY* (optional) + Setting key name + *VAL* (optional) + Setting value (JSON format) + +Options: + **-d**, **--delete** + Delete the saved setting value (no KEY means delete all) + **-s**, **--save** + Save the setting value (no KEY means save all, no VAL means current value) + **-r**, **--reset** + Reset the setting to its default value + +Behavior: + - No arguments: Show all settings + - KEY only: Show specific setting value + - KEY and VAL: Set specific setting value + +set-log-level +^^^^^^^^^^^^^ + +**wpctl set-log-level** [*ID*] *LEVEL* + +Sets the log level of a client. + +Arguments: + *ID* (optional) + Client ID. If omitted, applies to WirePlumber. Use 0 for PipeWire server. + *LEVEL* + Log level (e.g., ``0``, ``1``, ``2``, ``3``, ``4``, ``5``, ``E``, ``W``, ``N``, ``I``, ``D``, ``T``). + Use ``-`` to unset the log level. + +SPECIAL IDENTIFIERS +------------------- + +Instead of numeric IDs, **wpctl** accepts these special identifiers for +commonly used defaults: + +**@DEFAULT_SINK@**, **@DEFAULT_AUDIO_SINK@** + The current default audio sink (playback device) + +**@DEFAULT_SOURCE@**, **@DEFAULT_AUDIO_SOURCE@** + The current default audio source (capture device) + +**@DEFAULT_VIDEO_SOURCE@** + The current default video source (camera) + +These identifiers are resolved at runtime to the appropriate node IDs. + +EXIT STATUS +----------- + +**wpctl** returns the following exit codes: + +0 + Success +1 + General error (e.g., invalid arguments, connection failure) +2 + Could not connect to PipeWire +3 + Command-specific error (e.g., object not found) + +EXAMPLES +-------- + +Display system status:: + + wpctl status + +Set default audio sink:: + + wpctl set-default 42 + +Set volume to 75% on default sink:: + + wpctl set-volume @DEFAULT_SINK@ 75% + +Increase volume by 5% on a specific node:: + + wpctl set-volume 42 5%+ + +Mute the default source:: + + wpctl set-mute @DEFAULT_SOURCE@ 1 + +Toggle mute on default sink:: + + wpctl set-mute @DEFAULT_SINK@ toggle + +Inspect a device with associated objects:: + + wpctl inspect --associated 30 + +Show all WirePlumber settings:: + + wpctl settings + +Set a specific setting:: + + wpctl settings bluetooth.autoswitch true + +Save all current settings:: + + wpctl settings --save + +Set log level for WirePlumber to debug:: + + wpctl set-log-level D + +Set log level for a specific client:: + + wpctl set-log-level 42 W + +NOTES +----- + +Object IDs can be found using the **status** command. The hierarchical display +shows IDs for devices, nodes, and other objects. + +Volume values are floating-point numbers where 1.0 represents 100% volume. +Values can exceed 1.0 to introduce volume amplification. + +When using the **--pid** option, **wpctl** will find all audio nodes associated +with the specified process ID and apply the operation to all of them. + +SEE ALSO +-------- + +**pipewire**\ (1), **pw-cli**\ (1), **pw-dump**\ (1), **wireplumber**\ (1) + +WirePlumber Documentation: https://pipewire.pages.freedesktop.org/wireplumber/