Use `pw_main_loop_quit()` alone, which should be enough
to cause `pw_main_loop_run()` to return. `pw_main_loop_run()`
only returns prematurely when there is an error, but since
there is no error handling in this example, that scenario
is ignored.
Add a module for a fallback dummy sink, which appears dynamically when
no other sinks are present.
Enable it for pipewire-pulse, because Pulseaudio will also show
dynamically a dummy sink.
I don't think PipeWire currently has a way to temporarily alias
module-rtkit to module-rt though, so right now this would break realtime
scheduling for people with modified configs that use module-rtkit.
Use `meson.project_{build,source}_root()` instead of
`meson.{build,source}_root()` because those functions
do not work as expected when used inside a subproject,
and they have been deprecated in meson 0.56.0.
Use this to override the default $PIPEWIRE_CONFIG_DIR/media-session.d
directory. This allows us to have separate configuration directories for
pipewire and media-session.
Make Doxygen see also macros defined inside struct declarations,
and to include also opaque structs.
Keep members in the order they are in the .h file, since Doxygen's
case-insensitive sort by name jumbles things.
The Doxygen autogenerated graphs are very useful and take up lots of
space being on the top, so disable them.
Also disable references/referenced by relations, which add clutter.
Also hide most macro values.
The Doxygen "Modules" page is not very illuminative, as different parts
of the API are mixed together and not all parts are included.
Try to address this:
Put all parts of the public API to some Doxygen group, usually one group
per header file. Use short, systematic names.
Make these groups sub-groups of a few top-level groups, roughly
corresponding to the different logical parts of the API (core, impl,
stream, filter, spa, utilities).
Add an input filter that tries to link e.g.
#define pw_core_add_listener(...) pw_core_method(c,add_listener,...)
to the corresponding declaration in struct pw_core_methods.
Make Doxygen data structure etc. lists less cluttered by hiding
non-public stuff.
Add a Doxygen input filter that marks symbols declared in C files
private, so that they won't appear in the output unless the symbol is
also declared in a header.
The "spa static inline" hack is then also not needed any more.
Media-session itself uses ms.core, there are only two files that could
have a sub-topic but right now they don't use it (match-rules and
metadata).
The modules use the ms.mod.* namespace, so it's trivial to filter on
those.
pw_log_log/logv now go through the topic-based logger using the
"default" topic. Log topics themselves can be allocated by the call
sites. The simplest way to use a topic from e.g. a module:
PW_LOG_TOPIC_STATIC(mod_topic, "mod.foo");
#define PW_LOG_TOPIC_DEFAULT mod_topic
...
void pipewire__module_init() {
PW_LOG_TOPIC_INIT(mod_topic);
...
}
With the #define all pw_log_foo() are now routed through the custom
topic. For the cases where the log topic must be specified, a
pw_logt_foo() set of macros is available.
Log topics are enabled through the PIPEWIRE_DEBUG environment variable
which now supports globs, e.g. PIPEWIRE_DEBUG="*:I;mod.access:D"
to enable global INFO but DEBUG for the access module.
Namespaces documented are "pw", "mod" and "conn", for pipewire-internal
stuff, modules and connection dumping. The latter is special-cased to
avoid spamming the log files, it requires an expcit "conn.<glob>"
pattern to enable.
The "default" topic always exists and is the fallback for any
pw_log_foo() invocation that does not use a topic.
Allow one of "XEWIDT" to refer to none, errors, warnings, info, debug
and trace, respectively because they're immediately recognizable. Well,
except maybe the X.
PIPEWIRE_DEBUG="I" is equivalent to PIPEWIRE_DEBUG="3" for example.
This is a multi-step process involving 4 processes and two modules.
Let's add some graphs to make this slightly easier to comprehend for
those not familiar with how portals work.
A list of reasons why DMA-BUFs have to be treated specially. This
should make it clearer why mmaping DMA-BUFs should be avoided and hint
clients on how treat them correctly
Co-authored-by: columbarius <co1umbarius@protonmail.com>
Describing different behaviour for modifier-less and modifier-aware case
and how a EnumFormat with modifier should be fixated. Also adding a Note
about `SPA_PARAM_BUFFERS_blocks`, which is important for multiplane
DMA-BUFS.
Add module that switches bluez device profile to HFP/HSP if an input
stream (non-monitor, autoconnect) appears, and the current default
output device is bluez one that does not have input route.
When all input streams are gone, switch all changed profiles back.
Pending restore state is saved to session manager state files, in order
to restore it if e.g. devices get disconnected. This usually is not
currently necessary since the bluez5 plugin prefers to connect to A2DP
over HFP, but might matter in future with backchannel-enabled A2DP
codecs.
This adds a new top-level documentation entry for pipewire-media-session
with a list of modules (currently only one). Similar setup to the
pipewire modules, it allows us to document all modules in-place.
This is a good first (top) page to have in the docs, let's move it out
from the pipewire heading.
This doesn't change any of the links and the renaming isn't required
(subpage controls whether it's a top-level item and the meson.build
order decides its spot in he list). Still, better to have the filenames
represent the layout.
Reorganize the docs a little. First a short intro, then list the use
cases, then the responsabilities of the various components, then
the implementation in various places.
Add more info to the main SPA page and split the design vs plugin pages up,
together with some more documentation to ideally lower make this easier to
understand on a glance.
Most of the actual plugin loading documentation are unmodified.
This way doxygen will pick up the #defines for spa_log_error, etc. Without
this define it uses the else part of the condition which uses macros to
construct function names.
Heavily inspired by libinput's litest framework (built around check), this is
a from-scratch framework that simplifies adding tests for various parts of
pipewire. See the pwtest.h documentation for details but the basics are:
- PW_TEST() and PWTEST_SUITE() specify the tests to be run
- Test are run in forked processes, any errors/signals are caught and printed
to the log
- Tests have a custom pipewire daemon started on demand to talk to [1]. The
daemon's log is available in the test output.
- Output is YAML to be processed into whatever format needed
[1] There are limits here, since we can't emulate devices yet there is only
so much we can rely on with the daemon.
This is an attempt of breaking up the documentation, currently spread across
several pages. We're left with a few high-level topics with various things
grouped underneath those.
Further refinement is necessary, but this can now be done in incremental steps
over massive reworks.
While doxygen can handle markdown pages, support for it is very limited:
markdown pages can only be included as a whole page, they get an automatic
title (custom titles are possible but aren't standard markdown) and it's not
possible to use \subpage without messing with the markdown again. Any markdown
page will thus end up as separate item in the doxygen output, not really
suitable for generating a good page hiearchy.
Let's switch the tutorial to use doxygen directly instead of markdown, short
of using code/endcode instead of markdown's ``` there isn't that much
difference anyway but it allows us to structure things nicer in the online
docs.
This requires a helper script: doxygen doesn't differ between static methods
and static inline methods. EXTRACT_STATIC defines whether it parses *any*
static method but we're currently using all C files as input files as well. We
cannot convince doxygen to just parse static inline functions in header files
so for SPA we hack around this: meson passes the spa headers to a shell script
with simply copies those changed to `/* static */ inline void (foo)` and doxygen
then runs on those header files.
The result: we get all spa functions added to your doxygen output at the cost
of a few sed calls.
Theme from doxygen-awesome-css with custom modifications based on the
pipewire.org website to use the same type of blue, grey, etc.
doxygen-awesome-css is MIT licensed, see
https://github.com/jothepro/doxygen-awesome-css
Note that the order of the includes matters - that's how doxygen will sort
them. There is no specific structure other than the include order - one reason
why the headers are being changed. Without polluting the markdown files with
doxygen commands we cannot use \subpage, so all files convert to a regular
\page and are listed as flat hierarchy in the sidebar (and in Related Pages).
Changing the headers at least provides some visual grouping with comon
prefixes.
Keep all files as strings in an array so we can add them to the custom command
input list - this way meson will correctly rebuild documentation on changes.
This tool detects and fixes common English spelling mistakes, with
generally very few mistakes.
Here is the command I used to generate this commit. There were a few
changes that had to be done manually, and of course adding the ignore
file:
```shell
codespell -I .codespell-ignore -x .codespell-ignore -w
```
I didn’t add it to the CI, but this would be a good place for it.
