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

docs: improve documentation

Browse source
This commit is contained in:
George Kiagiadakis 2020-05-19 17:43:08 +03:00
parent 1f4d88b915
commit 29886ccf74
13 changed files with 292 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
README.md
View file

@ -5,9 +5,7 @@ WirePlumber is a modular session / policy manager for
that wraps PipeWire's API, providing convenience for writing the daemon's
modules as well as external tools for managing PipeWire.
# Compiling & Running
# Getting Started
The most recent instructions can be found in the docs:
* [Compilation](docs/index.md)
* [Running](docs/daemon.md)
Please refer to the documentation, which is available online
[here](https://pipewire.pages.freedesktop.org/wireplumber/)

1
docs/api-reference.md Normal file
View file

@ -0,0 +1 @@
# API reference

20
docs/community.md Normal file
View file

@ -0,0 +1,20 @@
# Community Resources
## 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)
## Mailing list
For discussions related to PipeWire **development**, there is
[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)
Please always check that your issue is not already reported before reporting it.

66
docs/contributing.md Normal file
View file

@ -0,0 +1,66 @@
# 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).
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
## Tests
WirePlumber has automated tests that you can easily run with:
```
$ 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:
```
$ 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`.
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
## 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.
You can also run in any other wrapper by setting the `DBG` variable
on `make run`. For example:
```
$ make run DBG="strace"
```
## 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. push that branch on the forked project
5. follow the link shown by `git push` to create the merge request
(or alternatively, visit your forked project on gitlab and create it from there)
For more detailed information, check out
[gitlab's manual on merge requests](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)

94
docs/daemon.md
View file

@ -1,94 +0,0 @@
# Daemon
The WirePlumber daemon implements the session & policy management service.
## Running
1. First of all, you will need to run PipeWire. PipeWire itself comes with
an example session manager that you will need to disable in order to run
WirePlumber. This can be achieved by editing `src/daemon/pipewire.conf.in`
on the PipeWire git tree to disable the execution of the session manager:
```
diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
index bf64c574..e733e76c 100644
--- a/src/daemon/pipewire.conf.in
+++ b/src/daemon/pipewire.conf.in
@@ -24,4 +24,4 @@ load-module libpipewire-module-access
load-module libpipewire-module-adapter
load-module libpipewire-module-link-factory
load-module libpipewire-module-session-manager
-exec build/src/examples/media-session
+#exec build/src/examples/media-session
```
2. Second, you will need to run pipewire: in the **pipewire** source tree, do `make run`
3. Without stopping pipewire, in the **wireplumber** source tree, do `make run`
## Testing with an audio client
The easiest way to test that things are working is to start a gstreamer pipeline
that outputs a test sound to pipewire.
In the **pipewire** source tree, do:
```
$ make shell
$ gst-launch-1.0 audiotestsrc ! pwaudiosink
```
Note that `pwaudiosink` is currently only available in the `agl-next` branch.
It is also possible to easily test *pulseaudio* and *jack* audio clients with
**mplayer**. For example, for pulse clients, do:
```
$ make shell
$ mplayer -ao pulse file.mp3
```
For jack clients, do:
```
$ make shell
$ mplayer -ao jack file.mp3
```
Note that *pipewire-pulseaudio* and *pipewire-jack* compatibility libraries from
the **pipewire** project need to be installed.
## Testing with a video client
Video capturing is also possible using the pipewiresrc **gstreamer** element, which
is included by default when installing **pipewire**. You can capture video buffers
from the default camera by doing the following:
```
$ make shell
$ gst-launch-1.0 pipewiresrc ! videoconvert ! ximagesink
```
## Debugging
The Makefile included with WirePlumber also supports the `gdb` and `valgrind`
targets. So, instead of `make run` you can do `make gdb` or `make valgrind`
to do some debugging.
Getting debug messages on the command line is a matter of setting the
`G_MESSAGES_DEBUG` environment variable as documented in the GLib documentation.
Usually you can just do:
```
G_MESSAGES_DEBUG=all make run
```
Note that this only gives out WirePlumber's debug messages. If you want to also
see *libpipewire*'s debug messages, then you can also set:
```
PIPEWIRE_DEBUG=4 G_MESSAGES_DEBUG=all make run
```
... where `PIPEWIRE_DEBUG` can be set to a value between 1 and 5, with 5 being the
most verbose and 1 the least verbose.

0
docs/configuration.md → docs/daemon/configuration.md
View file

85
docs/daemon/log.md Normal file
View file

@ -0,0 +1,85 @@
# 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=level:category1,category2,...
```
`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`)
`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.
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 ...
## Examples
Show all messages
```
WIREPLUMBER_DEBUG=5
```
Show all messages up to the `debug` level (E, C, W, M, I & D), excluding `trace`
```
WIREPLUMBER_DEBUG=4
```
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=2
```
Show all messages from the wireplumber library
```
WIREPLUMBER_DEBUG=5:wp-*
```
Show all messages from `wp-registry`, libpipewire and all modules
```
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
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.
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).
## Relationship with the PipeWire log handler & PIPEWIRE_DEBUG
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.
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).

38
docs/daemon/running.md Normal file
View file

@ -0,0 +1,38 @@
# Running the WirePlumber Daemon
## Configure PipeWire
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:
```
diff --git a/src/daemon/pipewire.conf.in b/src/daemon/pipewire.conf.in
index b659d460..93299ec2 100644
--- a/src/daemon/pipewire.conf.in
+++ b/src/daemon/pipewire.conf.in
@@ -73,4 +73,4 @@ create-object spa-node-factory factory.name=support.node.driver node.name=Dummy
# Execute the given program. This is usually used to start the
# session manager. run the session manager with -h for options
#
-exec pipewire-media-session # -d alsa-seq,alsa-pcm,bluez5,metadata
+exec wireplumber
```
This setup assumes that WirePlumber is *installed* on the target system.
If you wish
## 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:
1. Comment out with `#` the `exec` line from `pipewire.conf`
2. Run pipewire:
- if it is installed, execute `pipewire`
- if it is **not** installed, execute `make run` in the **pipewire** source tree
3. Without stopping pipewire, run wireplumber:
- if it is installed, execute `wireplumber`
- if it is **not** installed, execute `make run` in the **wireplumber** source tree

43
docs/index.md
View file

@ -5,37 +5,28 @@ WirePlumber is a modular session / policy manager for
that wraps PipeWire's API, providing convenience for writing the daemon's
modules as well as external tools for managing PipeWire.
## Compiling
* [Installing WirePlumber](installation/from-source.md)
### Dependencies
## The WirePlumber Daemon
In order to compile WirePlumber you will need:
The WirePlumber daemon implements the session & policy management service.
It follows a modular design, having plugins that implement the actual
management functionality.
* GLib >= 2.58
* PipeWire 0.3 (master)
* [Running the WirePlumber Daemon](daemon/running.md)
* [Daemon Configuration](daemon/configuration.md)
* [Debug Logging](daemon/log.md)
At the moment, due to heavy development of both PipeWire and WirePlumber,
it is not always the case that the latest master of WirePlumber works with the
latest master of PipeWire. The safest PipeWire branch to use with WirePlumber
master is the `agl-next` branch from
[my personal clone](https://gitlab.freedesktop.org/gkiagia/pipewire)
## The WirePlumber Library
### Compilation
The WirePlumber Library provides API that allows you
to extend the WirePlumber daemon, to write management or status tools
for PipeWire (apps that don't do actual media streaming)
and to write custom session managers for embedded devices.
WirePlumber uses the meson build system. For compatibility and ease of use,
though, a Makefile is also provided. The Makefile works only after the initial
configuration of the project with meson.
* [API Reference](gi-index)
Here is the very basic sequence of compiling for the first time:
```
$ meson build
$ make
```
## Resources
### Running automated tests
WirePlumber has a few automated tests that you can easily run with:
```
$ make test
```
* [Contribute to WirePlumber](contributing.md)
* [Reach out to the community](community.md)

55
docs/installation/from-source.md Normal file
View file

@ -0,0 +1,55 @@
# Installing WirePlumber
## Dependencies
In order to compile WirePlumber you will need:
* GLib >= 2.58
* PipeWire 0.3 (>= 0.3.5 highly recommended)
For building gobject-introspection data, you will also need `g-ir-scanner`,
which is usually shipped together with the gobject-introspection development
files.
For building documentation, you will also need [hotdoc](https://hotdoc.github.io/).
Most distributions do not ship this, but you can install it easily using python's
`pip` package manager.
## Compilation
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:
```
meson [build directory] [source directory] [--prefix=/path] [...options...]
```
Assuming you want to build in a directory called `build` inside the source
tree, you can run:
```
$ meson build . --prefix=/usr
$ ninja -C build
```
### Additional options
- `-Dintrospection=[enabled|disabled|auto]`: Force enable or force disable
building gobject-introspection data. The default value is `auto`, which means
that g-i will be built if `g-ir-scanner` is found and skipped otherwise.
- `-Ddocs=[enabled|disabled|auto]`: Force enable or force disable building
documentation. The default value is `auto`, which means that documentation
will be built if `hotdoc` is found and skipped otherwise. Note that building
the documentation also requires gobject-introspection data to be built.
## Installation
To install, simply run the `install` target with ninja:
```
$ ninja -C build install
```
To revert the installation, there is also an `uninstall` target:
```
$ ninja -C build uninstall
```

1
docs/library.md
View file

@ -1 +0,0 @@
# Library API

2
docs/meson.build
View file

@ -30,7 +30,7 @@ wp_doc = hotdoc.generate_doc('wireplumber',
project_version: wireplumber_api_version,
sitemap: 'sitemap.txt',
index: 'index.md',
gi_index: 'library.md',
gi_index: 'api-reference.md',
gi_smart_index: true,
gi_sources: [wp_gir[0].full_path()],
gi_c_sources: [wp_lib_sources, wp_lib_headers, wpenums_c, wpenums_h],

8
docs/sitemap.txt
View file

@ -1,4 +1,8 @@
index.md
installation/from-source.md
daemon/running.md
daemon/configuration.md
daemon/log.md
gi-index
daemon.md
configuration.md
contributing.md
community.md