fdo-mirrors/wireplumber
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/wireplumber.git synced 2026-05-02 22:38:22 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: tidy up most documents and try to update the information in them

Browse source 
- use code blocks properly
- use note/important blocks
- stop using ` for emphasis, use `` or * appropriately
- update info on contributing, community, running, logging
This commit is contained in:
George Kiagiadakis 2021-05-26 19:20:05 +03:00
parent f2d4ed17da
commit 5d7cdfabec
7 changed files with 381 additions and 220 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/rst/community.rst
View file

@ -7,20 +7,18 @@ Discussion chat channel
-----------------------
WirePlumber does not have its own discussion channel, but you can ask questions
in the generic `#pipewire` IRC channel (on irc.freenode.org or
`#freenode_#pipewire:matrix.org` if you are joining via matrix)
in the generic **#pipewire** IRC channel on `irc.oftc.net <https://www.oftc.net/>`_
Mailing list
------------
For discussions related to PipeWire **development**, there is
`the pipewire devel mailing list <https://lists.freedesktop.org/mailman/listinfo/pipewire-devel>`_
`the pipewire-devel mailing list <https://lists.freedesktop.org/mailman/listinfo/pipewire-devel>`_
Reporting issues
----------------
If you have found an issue with WirePlumber and wish to report it,
please create a ticket on gitlab,
`here <https://gitlab.freedesktop.org/pipewire/wireplumber/-/issues>`_
If you have found an issue with WirePlumber and wish to report it, please
`create a ticket on GitLab <https://gitlab.freedesktop.org/pipewire/wireplumber/-/issues>`_
Please always check that your issue is not already reported before reporting it.

75
docs/rst/contributing.rst
View file

@ -6,53 +6,70 @@ Contributing to WirePlumber
Coding style
------------
WirePlumber uses the
`GNOME C Coding Style <https://developer.gnome.org/programming-guidelines/unstable/c-coding-style.html.en>`_
with K&R brace placement and 2-space indentation, similar to
`GStreamer <https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/developing.html#what-is-the-coding-style-for-gstreamer-code>`_.
WirePlumber uses the `GNOME C Coding Style`_ with K&R brace placement
and 2-space indentation, similar to `GStreamer's Coding Style`_.
When in doubt, just follow the example of the existing code.
WirePlumber ships with a `editorconfig <https://editorconfig.org/>`_ file.
If your code editor / IDE supports this, it should automatically set up
the indentation settings.
* When submitting changes for review, please ensure that the coding style of the changes respects the coding style of the project.
.. important::
When submitting changes for review, please ensure that the coding style
of the changes respects the coding style of the project.
.. _GNOME C Coding Style: https://developer.gnome.org/programming-guidelines/unstable/c-coding-style.html.en
.. _GStreamer's Coding Style: https://gstreamer.freedesktop.org/documentation/frequently-asked-questions/developing.html#what-is-the-coding-style-for-gstreamer-code
Tests
^^^^^
-----
See
:ref:`testing`
See :ref:`testing`
Running in gdb / valgrind / etc...
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
----------------------------------
The Makefile included with WirePlumber supports the `gdb` and `valgrind`
targets. So, instead of `make run` you can do `make gdb` or `make valgrind`
to do some debugging.
The Makefile included with WirePlumber supports the ``gdb`` and ``valgrind``
targets. So, instead of ``make run`` you can do ``make gdb`` or
``make valgrind`` to do some debugging.
You can also run in any other wrapper by setting the `DBG` variable
on `make run`. For example::
You can also run in any other wrapper by setting the ``DBG`` variable
on ``make run``. For example:
$ make run DBG="strace"
.. code:: console
$ make run DBG="strace"
You may also use ``wp-uninstalled.sh`` directly as a wrapper to set up the
environment and then execute any command. For example:
.. code:: console
$ ./wp-uninstalled.sh gdb --args wpctl status
Merge requests
^^^^^^^^^^^^^^
--------------
In order to submit changes to the project, you should create a merge request.
To do this,
1. fork the project on https://gitlab.freedesktop.org/pipewire/wireplumber
2. clone the forked project on your computer
3. make changes in a new git branch
4. rebase your changes on top of the latest `master` of the main repository
5. push that branch on the forked repository
6. follow the link shown by `git push` to create the merge request
(or alternatively, visit your forked repository on gitlab and create it from there)
While creating the merge request, it is important to enable the
`allow commits from members who can merge to the target branch` option
so that maintainers are able to rebase your branch, since WirePlumber uses
a fast-forward merge policy.
1. fork the project on https://gitlab.freedesktop.org/pipewire/wireplumber
2. clone the forked project on your computer
3. make changes in a new git branch
4. rebase your changes on top of the latest ``master`` of the main repository
5. push that branch on the forked repository
6. follow the link shown by ``git push`` to create the merge request
(or alternatively, visit your forked repository on gitlab and
create it from there)
For more detailed information, check out
`gitlabs manual on merge requests <https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html>`_
.. important::
While creating the merge request, it is important to enable the
**allow commits from members who can merge to the target branch** option
so that maintainers are able to rebase your branch, since WirePlumber uses
a fast-forward merge policy.
For more detailed information, check out `gitlab's manual on merge requests`_
.. _gitlab's manual on merge requests: https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html

138
docs/rst/daemon-logging.rst
View file

@ -4,81 +4,135 @@ Debug Logging
=============
Getting debug messages on the command line is a matter of setting the
`WIREPLUMBER_DEBUG` environment variable. The generic syntax is::
``WIREPLUMBER_DEBUG`` environment variable. The generic syntax is:
WIREPLUMBER_DEBUG=level:category1,category2,...
.. code::
`level` can be a number from 1 to 5 and defines the minimum debug level to show::
1 - warnings, critical warnings and fatal errors (`W`, `C` & `E` in the log)
2 - normal messages (`M`)
3 - informational messages (`I`)
4 - debug messages (`D`)
5 - trace messages (`T`)
WIREPLUMBER_DEBUG=level:category1,category2,...
`category1,category2,...` is an *optional* comma-separated list of debug
categories to show. Any categories not listed here will not appear in the log.
``level`` can be a number from 1 to 5 and defines the minimum debug level to show:
0. critical warnings and fatal errors (``C`` & ``E`` in the log)
1. warnings (``W``)
2. normal messages (``M``)
3. informational messages (``I``)
4. debug messages (``D``)
5. trace messages (``T``)
``category1,category2,...`` is an *optional* comma-separated list of debug
categories to show. Any categories not listed here will *not* appear in the log.
If no categories are specified, then all messages are printed.
Categories support `glob style patterns <https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
containing '*' and '?', for convenience.
Categories support
`glob style patterns <https://developer.gnome.org/glib/stable/glib-Glob-style-pattern-matching.html>`_
containing ``*`` and ``?``, for convenience.
Well known categories include:
* **wireplumber**: messages from the wireplumber daemon
* **pw**: messages from libpipewire & spa plugins
* **wp-***: messages from libwireplumber
* **wp-core**: messages from `WpCore`
* **wp-proxy**: messages from `WpProxy` ... and so on ...
* **m-***: messages from wireplumber modules
* **m-monitor**: messages from `libwireplumber-module-monitor`
* **m-session-settings**: messages from `libwireplumber-module-session-settings` ... and so on ...
- **wireplumber**: messages from the wireplumber daemon
- **pw**: messages from libpipewire & spa plugins
- **wp-***: messages from libwireplumber
- **wp-core**: messages from *WpCore*
- **wp-proxy**: messages from *WpProxy*
- ... and so on ...
- **m-***: messages from wireplumber modules
- **m-default-profile**: messages from *libwireplumber-module-default-profile*
- **m-default-routes**: messages from *libwireplumber-module-default-routes*
- ... and so on ...
- **script/***: messages from scripts
- **script/policy-node**: messages from the *policy-node.lua* script
- ... and so on ...
Examples
--------
Show all messages::
Show all messages:
WIREPLUMBER_DEBUG=5
.. code::
Show all messages up to the `debug` level (E, C, W, M, I & D), excluding `trace` ::
WIREPLUMBER_DEBUG=5
WIREPLUMBER_DEBUG=4
Show all messages up to the *debug* level (E, C, W, M, I & D), excluding *trace*:
Show all messages up to the `message` level (E, C, W & M),
excluding `info`, `debug` & `trace`
(this is also the default when `WIREPLUMBER_DEBUG` is omitted) ::
.. code::
WIREPLUMBER_DEBUG=2
WIREPLUMBER_DEBUG=4
Show all messages from the wireplumber library ::
Show all messages up to the *message* level (E, C, W & M),
excluding *info*, *debug* & *trace*
(this is also the default when ``WIREPLUMBER_DEBUG`` is omitted):
WIREPLUMBER_DEBUG=5:wp-*
.. code::
Show all messages from `wp-registry`, libpipewire and all modules ::
WIREPLUMBER_DEBUG=2
WIREPLUMBER_DEBUG=5:wp-registry,pw,m-*
Show all messages from the wireplumber library:
.. code::
WIREPLUMBER_DEBUG=5:wp-*
Show all messages from ``wp-registry``, libpipewire and all modules:
.. code::
WIREPLUMBER_DEBUG=5:wp-registry,pw,m-*
Relationship with the GLib log handler & G_MESSAGES_DEBUG
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---------------------------------------------------------
Older versions of WirePlumber used to use `G_MESSAGES_DEBUG` to control their
Older versions of WirePlumber used to use ``G_MESSAGES_DEBUG`` to control their
log output, which is the environment variable that affects GLib's default
log handler.
As of WirePlumber 0.3, `G_MESSAGES_DEBUG` is no longer used, since libwireplumber
replaces the default log handler.
As of WirePlumber 0.3, ``G_MESSAGES_DEBUG`` is no longer used, since
libwireplumber replaces the default log handler.
If you are writing your own application based on libwireplumber, you can choose
if you want to replace this log handler using the flags passed to
[wp_init()](wp_init).
:c:func:`wp_init`.
Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-----------------------------------------------------------
libpipewire uses the `PIPEWIRE_DEBUG` environment variable, with a similar syntax.
libpipewire uses the ``PIPEWIRE_DEBUG`` environment variable, with a similar syntax.
WirePlumber replaces the log handler of libpipewire with its own, rendering
`PIPEWIRE_DEBUG` useless. Instead, you should use `WIREPLUMBER_DEBUG` and the
`pw` category to control log messages from libpipewire & its plugins.
``PIPEWIRE_DEBUG`` useless. Instead, you should use ``WIREPLUMBER_DEBUG`` and the
``pw`` category to control log messages from libpipewire & its plugins.
If you are writing your own application based on libwireplumber, you can choose
if you want to replace this log handler using the flags passed to
[wp_init()](wp_init).
:c:func:`wp_init`.
Mapping of PipeWire debug levels to WirePlumber
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Both WirePlumber and PipeWire support 6 levels of debug logging, from 0 to 5
PipeWire uses a slightly different semantic for the first 3 levels:
===== ======== ===========
Level PipeWire WirePlumber
===== ======== ===========
0 no log Critical / fatal Errors
1 Errors Warnings
2 Warnings Messages
===== ======== ===========
When PipeWire log messages are printed by the WirePlumber log handler, the
level number stays the same and the semantic changes. PipeWire's errors are
printed in the ``W`` category and PipeWire's warnings are printed in the
``M`` category.
In WirePlumber's (actually GLib's) semantics, this feels more appropriate
because:
- GLib's errors are fatal (``abort()`` is called)
- GLib's critical warnings are assertion failures (i.e. programming mistakes,
not runtime errors)
- PipeWire's errors are neither fatal, nor programming mistakes; they are
just bad situations that are not meant to happen
- GLib's warnings are exactly that: bad runtime situations that are not meant
to happen, so mapping PipeWire errors to GLib warnings makes sense
- The **Messages** log level does not exist in PipeWire, so it can be used to
fill the gap for PipeWire warnings

2
docs/rst/index.rst
View file

@ -24,6 +24,6 @@ Table of Contents
:caption: Resources
contributing.rst
community.rst
testing.rst
community.rst
releases.rst

8
docs/rst/installing-wireplumber.rst
View file

@ -35,14 +35,14 @@ WirePlumber uses the `meson build system <https://mesonbuild.com/>`_
To configure the project, you need to first run `meson`.
The basic syntax is shown below:
.. code:: bash
.. code:: console
meson [--prefix=/path] [...options...] [build directory] [source directory]
Assuming you want to build in a directory called 'build' inside the source
tree, you can run:
.. code:: bash
.. code:: console
$ meson setup --prefix=/usr build
$ meson compile -C build
@ -110,12 +110,12 @@ Installation
To install, simply run the **install** target with ninja:
.. code:: bash
.. code:: console
$ ninja -C build install
To revert the installation, there is also an **uninstall** target:
.. code:: bash
.. code:: console
$ ninja -C build uninstall

117
docs/rst/running-wireplumber-daemon.rst
View file

@ -3,31 +3,70 @@
Running the WirePlumber daemon
==============================
Configure PipeWire
------------------
Replacing pipewire-media-session
--------------------------------
PipeWire 0.3 comes with an example session manager that you will need
to disable and replace with WirePlumber. This can be achieved by editing
**src/daemon/pipewire.conf.in** in the PipeWire git tree or
**/etc/pipewire/pipewire.conf** in an existing installation:
PipeWire 0.3 comes with an example session manager (pipewire-media-session)
that you will need to disable and replace with WirePlumber.
Here, is the set of changes required to disable the default session manager and
to replace it with WirePlumber::
systemd
^^^^^^^
diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
index cebded96..dee1743b 100644
--- a/src/daemon/pipewire.conf.in
+++ b/src/daemon/pipewire.conf.in
@@ -99,7 +99,8 @@ exec = {
# Start the session manager. Run the session manager with -h for
# options.
#
- "@media_session_path@" = { args = ""}
+ #"@media_session_path@" = { args = ""}
+ "wireplumber" = {}
#
# You can optionally start the pulseaudio-server here as well
# but it better to start it as a systemd service.
In most cases, ``pipewire-media-session`` is started by a systemd service unit,
``pipewire-media-session.service``.
To switch to WirePlumber, you will first need to disable that service:
.. code:: console
$ systemctl --user --now disable pipewire-media-session
... and then, enable and use ``wireplumber.service`` in its place:
.. code:: console
$ systemctl --user --now enable wireplumber
pipewire.conf
^^^^^^^^^^^^^
On some systems, ``pipewire-media-session`` is not started by systemd, but it
is started by pipewire itself via a configuration option in ``pipewire.conf``
To switch to wireplumber, you will need to edit
**/etc/pipewire/pipewire.conf** in an existing installation or
**src/daemon/pipewire.conf.in** in the PipeWire git tree
and change the appropriate line in the ``exec`` section:
.. code:: diff
--- /etc/pipewire/pipewire.conf.bak
+++ /etc/pipewire/pipewire.conf
@@ -204,7 +204,7 @@ context.exec = [
# but it is better to start it as a systemd service.
# Run the session manager with -h for options.
#
- #{ path = "/usr/bin/pipewire-media-session" args = "" }
+ { path = "wireplumber" args = "" }
#
# You can optionally start the pulseaudio-server here as well
# but it is better to start it as a systemd service.
.. code:: diff
diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
index bbafa134..16ef687b 100644
--- a/src/daemon/pipewire.conf.in
+++ b/src/daemon/pipewire.conf.in
@@ -220,7 +220,7 @@ context.exec = [
# but it is better to start it as a systemd service.
# Run the session manager with -h for options.
#
- @comment@{ path = "@media_session_path@" args = "" }
+ { path = "wireplumber" args = "" }
#
# You can optionally start the pulseaudio-server here as well
# but it is better to start it as a systemd service.
This setup assumes that WirePlumber is *installed* on the target system.
@ -36,16 +75,34 @@ Run independently or without installing
If you wish to debug WirePlumber, it may be useful to run it separately from
PipeWire or run it directly from the source tree without installing.
To do so -
To do so:
1. Comment out with *#* the *"wireplumber" = {}* line from *pipewire.conf*
1. Ensure that neither *WirePlumber* nor *pipewire-media-session*
are running or started together with PipeWire
2. Run pipewire.
- If any of those is started by systemd,
* if it is installed, execute *pipewire*
* if it is **not** installed, execute *make run* in the **pipewire** source tree
- Stop the relevant systemd service, ``wireplumber.service``
or ``pipewire-media-session.service``
- Disable that service as well if you intend to restart PipeWire
(so that the session manager is not restarted with it)
3. Without stopping pipewire, run wireplumber.
- If any of those is started from pipewire.conf,
* if it is installed, execute *wireplumber*
* if it is **not** installed, execute *make run* in the **wireplumber** source tree
- Kill it, in order to stop it temporarily: ``killall wireplumber``
or ``killall pipewire-media-session``
- Comment out with ``#`` the relevant ``{ path = "..." args = "" }``
line from the ``exec`` section in ``pipewire.conf``,
if you intend to restart PipeWire
2. Ensure that PipeWire is running
3. Without stopping PipeWire, run WirePlumber.
- if it is installed, execute ``wireplumber``
- if it is **not** installed, execute ``make run`` in the source tree,
or use the ``wp-uninstalled.sh`` script:
.. code:: console
$ ./wp-uninstalled.sh wireplumber

251
docs/rst/testing.rst
View file

@ -6,47 +6,55 @@ Testing
Automated unit tests
--------------------
WirePlumber has automated tests that you can easily run with::
WirePlumber has automated tests that you can easily run with:
$ meson test -C build
.. code:: console
$ meson test -C build
This will automatically compile all test dependencies, so you can be sure
that this always tests your latest changes.
If you wish to run a specific test instead of all of them, you can run::
If you wish to run a specific test instead of all of them, you can run:
$ meson test -C build test-name
.. code:: console
$ meson test -C build test-name
When debugging a single test, you can additionally enable verbose test output
by appending *-v* and you can also run the test in gdb by appending *--gdb*.
by appending ``-v`` and you can also run the test in gdb by appending ``--gdb``.
For more information on how to use *'meson test'*, please refer to
`mesons manual <https://mesonbuild.com/Unit-tests.html>`_
For more information on how to use ``meson test``, please refer to
`meson's manual <https://mesonbuild.com/Unit-tests.html>`_
* When submitting changes for review, always ensure that all tests pass
.. important::
When submitting changes for review, always ensure that all tests pass
Please note that many WirePlumber tests require specific SPA test plugins
to be available in your PipeWire installation. More specifically, PipeWire
needs to be configured with the following options enabled::
needs to be configured with the following options enabled:
-Dvideotestsrc=true -Daudiotestsrc=true -Dtest=true
.. code:: console
-Dvideotestsrc=true -Daudiotestsrc=true -Dtest=true
If these SPA plugins are not found in the system, some tests will fail.
This is expected.
WirePlumber examples
^^^^^^^^^^^^^^^^^^^^
--------------------
WirePlumber ships examples in *'test/examples'*.
Execute them from the top-level directory like this::
WirePlumber ships examples in ``test/examples``.
Execute them from the top-level directory with ``wp-uninstalled.sh``:
$ WIREPLUMBER_MODULE_DIR=build/modules ./build/tests/examples/audiotestsrc-play
.. code:: console
$ ./wp-uninstalled.sh ./build/tests/examples/audiotestsrc-play
Assuming there is no other process actively using *'hw:0,0'* from alsa, the above
example should play a test tone on *'hw:0,0'* without errors.
Assuming there is no other process actively using ``hw:0,0`` from alsa,
the above example should play a test tone on ``hw:0,0`` without errors.
Native API clients
------------------
@ -54,50 +62,60 @@ Native API clients
pw-cat
^^^^^^
Using the default endpoint::
Using the default endpoint:
$ wpctl status # verify the default endpoints
$ pw-record test.wav
$ pw-play test.wav
.. code:: console
$ wpctl status # verify the default endpoints
$ pw-record test.wav
$ pw-play test.wav
Using a non-default endpoint::
Using a non-default endpoint:
$ pw-record --list-targets # find the node id
$ pw-record --target <node_id> test.wav
$ pw-play --list-targets # find the node id
$ pw-play --target <node_id> test.wav
.. code:: console
$ pw-record --list-targets # find the node id
$ pw-record --target <node_id> test.wav
$ pw-play --list-targets # find the node id
$ pw-play --target <node_id> test.wav
or
Use the commands::
.. code:: console
$ wpctl status # find the capture & playback endpoint ids
$ pw-record --target <endpoint_id> test.wav
$ pw-play --target <endpoint_id> test.wav
$ wpctl status # find the capture & playback endpoint ids
$ pw-record --target <endpoint_id> test.wav
$ pw-play --target <endpoint_id> test.wav
.. note::
.. note:: node ids and endpoint ids can be used interchangeably when specifying
targets in all use cases.
node ids and endpoint ids can be used interchangeably when specifying
targets in all use cases
video-play
^^^^^^^^^^
Using the default endpoint::
Using the default endpoint:
$ cd path/to/pipewire-source-dir
$ ./build/src/examples/video-play
.. code:: console
$ cd path/to/pipewire-source-dir
$ ./build/src/examples/video-play
Using a non-default endpoint::
Using a non-default endpoint:
$ wpctl status # find the endpoint id from the list
$ cd path/to/pipewire-source-dir
$ ./build/src/examples/video-play <endpoint_id>
.. code:: console
$ wpctl status # find the endpoint id from the list
$ cd path/to/pipewire-source-dir
$ ./build/src/examples/video-play <endpoint_id>
.. note:: Tip: enable videotestsrc in wireplumber's configuration to have more video
sources available (see `videotestsrc.node.disabled` in the configuration directory)
.. tip::
enable videotestsrc in wireplumber's configuration to have more video
sources available
PulseAudio compat API clients
-----------------------------
@ -105,29 +123,25 @@ PulseAudio compat API clients
pacat
^^^^^
Using the default endpoint::
Using the default endpoint:
$ wpctl status # verify the default endpoints
$ pw-pulse parecord test.wav
$ pw-pulse paplay test.wav
Using a non-default endpoint::
$ wpctl status # find the capture & playback endpoint ids
$ PIPEWIRE_NODE=<endpoint_id> pw-pulse parecord test.wav
$ PIPEWIRE_NODE=<endpoint_id> pw-pulse paplay test.wav
.. code:: console
$ wpctl status # verify the default endpoints
$ parecord test.wav
$ paplay test.wav
pavucontrol
^^^^^^^^^^^
Use the command::
Use the command:
$ pw-pulse pavucontrol
.. code:: console
* Volume level meters should work
* Changing the volume should work
$ pavucontrol
* Volume level meters should work
* Changing the volume should work
ALSA compat API clients
-----------------------
@ -135,33 +149,38 @@ ALSA compat API clients
aplay / arecord
^^^^^^^^^^^^^^^
.. note:: unless you have installed PipeWire in the default system prefix
(`/usr`), the ALSA compat API will not work, unless you copy
`libasound_module_pcm_pipewire.so` in the alsa plugins directory
(usually `/usr/<libdir>/alsa-lib/`) and that you add the contents of
`pipewire-alsa/conf/50-pipewire.conf` in your `~/.asoundrc`
(or anywhere else, system-wide, where libasound can read it)
.. note::
Using the default endpoint::
unless you have installed PipeWire in the default system prefix
(``/usr``), the ALSA compat API will not work, unless you copy
``libasound_module_pcm_pipewire.so`` in the alsa plugins directory
(usually ``/usr/<libdir>/alsa-lib/``) and that you add the contents of
``pipewire-alsa/conf/50-pipewire.conf`` in your ``~/.asoundrc``
(or anywhere else, system-wide, where libasound can read it)
$ wpctl status # verify the default endpoints
$ arecord -D pipewire -f S16_LE -r 48000 test.wav
$ aplay -D pipewire test.wav
Using the default endpoint:
.. code:: console
Using a non-default endpoint::
$ wpctl status # verify the default endpoints
$ arecord -D pipewire -f S16_LE -r 48000 test.wav
$ aplay -D pipewire test.wav
$ wpctl status # find the capture & playback endpoint ids
$ PIPEWIRE_NODE=<endpoint_id> arecord -D pipewire -f S16_LE -r 48000 test.wav
$ PIPEWIRE_NODE=<endpoint_id> aplay -D pipewire test.wav
Using a non-default endpoint:
.. code:: console
$ wpctl status # find the capture & playback endpoint ids
$ PIPEWIRE_NODE=<endpoint_id> arecord -D pipewire -f S16_LE -r 48000 test.wav
$ PIPEWIRE_NODE=<endpoint_id> aplay -D pipewire test.wav
or
Use the commands::
.. code:: console
$ wpctl status # find the capture & playback endpoint ids
$ arecord -D pipewire:NODE=<endpoint_id> -f S16_LE -r 48000 test.wav
$ aplay -D pipewire:NODE=<endpoint_id> test.wav
$ wpctl status # find the capture & playback endpoint ids
$ arecord -D pipewire:NODE=<endpoint_id> -f S16_LE -r 48000 test.wav
$ aplay -D pipewire:NODE=<endpoint_id> test.wav
JACK compat API clients
@ -170,26 +189,27 @@ JACK compat API clients
qjackctl
^^^^^^^^
Use the commands::
.. code:: console
pw-jack qjackctl
$ pw-jack qjackctl
* This should correctly connect.
* The "Graph" window should show the PipeWire graph.
* This should correctly connect.
* The "Graph" window should show the PipeWire graph.
jack_simple_client
^^^^^^^^^^^^^^^^^^
Use the commands::
.. code:: console
$ wpctl status # find the target endpoint id
$ wpctl inspect <endpoint_id> # find the node.id
$ PIPEWIRE_NODE=<node_id> pw-jack jack_simple_client
$ wpctl status # find the target endpoint id
$ wpctl inspect <endpoint_id> # find the node.id
$ PIPEWIRE_NODE=<node_id> pw-jack jack_simple_client
.. note::
.. note:: The JACK layer is not controlled by the session manager, it creates its own
links; which is why it is required to specify a node id (endpoint id will not
work)
The JACK layer is not controlled by the session manager, it creates its own
links; which is why it is required to specify a node id (endpoint id will not
work)
Device Reservation
------------------
@ -199,18 +219,26 @@ with PulseAudio
1. With PulseAudio running, start a pulseaudio client.
Use the command::
.. code:: console
$ gst-launch-1.0 audiotestsrc ! pulsesink
$ gst-launch-1.0 audiotestsrc ! pulsesink
2. Start PipeWire & WirePlumber
- The device in use by PA will not be available in PW
3. Stop the PA client
- A few seconds later, WirePlumber should assume control of the device
4. *'wpctl status'* should be able to confirm that the device is available
4. ``wpctl status`` should be able to confirm that the device is available
5. Start a PA client again
- It should not be able to play; it will just freeze
6. Stop WirePlumber
- The PA client should immediately start playing
with JACK
@ -218,33 +246,40 @@ with JACK
1. Start PipeWire & WirePlumber
* All devices should be available
- All devices should be available
2. Start *'jackdbus'*
2. Start ``jackdbus``
1. through *'qjackctl'*:
1. through ``qjackctl``:
* Enable *'Setup'* -> *'Misc'* -> *'Enable JACK D-Bus interface'*
- Enable *Setup* -> *Misc* -> *Enable JACK D-Bus interface*
- Click *Start* on the main window
* Click *'Start'* on the main window
2. or manually:
2. or manually:
- Run ``jackdbus auto``
- Run ``qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StartServer``
* Run *'jackdbus auto'*
3. Wait a few seconds and run ``wpctl status`` to inspect
* Run *'qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StartServer'*
3. Wait a few seconds and run *'wpctl status'* to inspect
- The devices taken by JACK should no longer be available
- There should be two *'JACK System'* endpoints (sink & source)
4. Run an audio client on PipeWire (ex *'pw-play test.wav'*)
- Notice how audio now goes through JACK
5. Stop JACK
- through *'qjackctl'*, click *'Stop'*
- or manually: *'qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StopServer'*
6. Wait a few seconds and run *'wpctl status'* to inspect
- The devices that were release by JACK should again be available
- There should be no *'JACK System'* endpoint
- There should be two *JACK System* endpoints (sink & source)
.. note:: You may also start WirePlumber *after* starting JACK. It should immediately
go to the state described in step 3
4. Run an audio client on PipeWire (ex ``pw-play test.wav``)
- Notice how audio now goes through JACK
5. Stop JACK
- through ``qjackctl``, click *Stop*
- or manually: ``qdbus org.jackaudio.service /org/jackaudio/Controller org.jackaudio.JackControl.StopServer``
6. Wait a few seconds and run ``wpctl status`` to inspect
- The devices that were release by JACK should again be available
- There should be no *JACK System* endpoint
.. note::
You may also start WirePlumber *after* starting JACK. It should immediately
go to the state described in step 3