doc: sync with master branch

Update doc/ from master branch.

tutorial: fix s16 scale and add some docs
doc: add 'Configuration' page
doc: disable deprecated list
doc: fix some doxygen warnings
doc: put new pulse modules to right place
doc: filter some constructs that confuse doxygen
doc: Fix typo 'statis' -> 'static'
doc: include pipewire-pulse modules explanations also on man page
doc: add pw-v4l2.1 and spa-*.1
doc: add pw-reserve.1
doc: internals/access: update documentation vs current state

doc/dox/programs/index.md

@@ -19,5 +19,12 @@ Manual pages:
 - \subpage page_man_pw-mididump_1
 - \subpage page_man_pw-mon_1
 - \subpage page_man_pw-profiler_1
+- \subpage page_man_pw-reserve_1
 - \subpage page_man_pw-top_1
+- \subpage page_man_pw-v4l2_1
+- \subpage page_man_spa-acp-tool_1
+- \subpage page_man_spa-inspect_1
+- \subpage page_man_spa-json-dump_1
+- \subpage page_man_spa-monitor_1
+- \subpage page_man_spa-resample_1
 - \subpage page_man_libpipewire-modules_7

doc/dox/programs/pipewire-pulse-modules.7.md

@@ -4,21 +4,9 @@ PipeWire Pulseaudio modules
 
 # DESCRIPTION
 
-PipeWire's Pulseaudio emulation implements several Pulseaudio modules.
-It only supports its own built-in modules, and cannot load external
-modules written for Pulseaudio.
+\include{doc} pulse-modules.inc
 
-The built-in modules can be loaded using Pulseaudio client programs, for
-example `pactl load-module \<module-name\> \<module-options\>`.
-They can also added to `pipewire-pulse.conf`, typically by a
-drop-in file in `~/.config/pipewire/pipewire-pulse.conf.d/`
-containing the module name and its arguments
-
-    pulse.cmd = [
-       { cmd = "load-module" args = "module-null-sink sink_name=foo" flags = [ ] }
-    ]
-
-# KNOWN MODULES
+# BUILT-IN MODULES
 
 $(PIPEWIRE_PULSE_MODULES)
 

doc/dox/programs/pw-jack.1.md

@@ -4,7 +4,7 @@ Use PipeWire instead of JACK
 
 # SYNOPSIS
 
-**pw-jack** \[*options*\] *COMMAND* \[*FILE*\]
+**pw-jack** \[*options*\] *COMMAND* \[*ARGUMENTS...*\]
 
 # DESCRIPTION
 

doc/dox/programs/pw-reserve.1.md

@@ -0,0 +1,79 @@
+\page page_man_pw-reserve_1 pw-reserve
+
+The PipeWire device reservation utility
+
+# SYNOPSIS
+
+**pw-reserve** \[*options*\]
+
+# DESCRIPTION
+
+Reserves a device using the DBus `org.freedesktop.ReserveDevice1`
+device reservation scheme [1], waiting until terminated by `SIGINT` or
+another signal.
+
+It can also request other applications to release a device. This can
+be used to make audio servers such as PipeWire, Pulseaudio, JACK, or
+other applications that respect the device reservation protocol, to
+ignore a device, or to release a sound device they are already using
+so that it can be used by other applications.
+
+# OPTIONS
+
+\par -r | \--release
+Request any client currently holding the device to release it, and try
+to reserve it after that. If this option is not given and the device
+is already in use, **pw-reserve** will exit with error status.
+
+\par -n NAME | \--name=NAME
+\parblock
+Name of the device to reserve. By convention, this is
+
+- Audio<em>N</em>: for ALSA card number <em>N</em>
+
+**pw-reserve** can reserve any device name, however PipeWire does
+not currently support other values than listed above.
+\endparblock
+
+\par -a NAME | \--appname=NAME
+Application name to use when reserving the device.
+
+\par -p PRIO | \--priority=PRIO
+Priority to use when reserving the device.
+
+\par -m | \--monitor
+Monitor reservations of a given device, instead of reserving it.
+
+\par -h | \--help
+Show help.
+
+\par \--version
+Show version information.
+
+# EXIT STATUS
+
+If the device reservation succeeds, **pw-reserve** does not exit until
+terminated with a signal. It exits with status 0 if terminated by
+SIGINT or SIGTERM in this case.
+
+Otherwise, it exits with nonzero exit status.
+
+# EXAMPLES
+
+**pw-reserve** -n Audio0
+
+Reserve ALSA card 0, and exit with error if it is already reserved.
+
+**pw-reserve** -n Audio0 -r
+
+Reserve ALSA card 0, requesting any applications that have reserved
+the device to release it for us.
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+[1] https://git.0pointer.net/reserve.git/tree/reserve.txt - A simple device reservation scheme with DBus

doc/dox/programs/pw-v4l2.1.md

@@ -0,0 +1,40 @@
+\page page_man_pw-v4l2_1 pw-v4l2
+
+Use PipeWire instead of V4L2
+
+# SYNOPSIS
+
+**pw-v4l2** \[*options*\] *COMMAND* \[*ARGUMENTS...*\]
+
+# DESCRIPTION
+
+**pw-v4l2** runs a command using a compatibility layer that maps PipeWire
+video devices to be visible to applications using V4L2.
+
+This is implemented by preloading a shared library via LD_PRELOAD,
+which translates library calls that try to access V4L2 devices.
+
+# OPTIONS
+
+\par -h
+Show help.
+
+\par -r NAME
+The name of the remote instance to connect to. If left unspecified, a
+connection is made to the default PipeWire instance.
+
+\par -v
+Verbose operation.
+
+# EXAMPLES
+
+**pw-v4l2** v4l2-ctl --list-devices
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)",

doc/dox/programs/spa-acp-tool.1.md

@@ -0,0 +1,80 @@
+\page page_man_spa-acp-tool_1 spa-acp-tool
+
+The PipeWire ALSA profile debugging utility
+
+# SYNOPSIS
+
+**spa-acp-tool** \[*COMMAND*\]
+
+# DESCRIPTION
+
+Debug tool for exercising the ALSA card profile probing code, without
+running PipeWire.
+
+May be used to debug problems where PipeWire has incorrectly
+functioning ALSA card profiles.
+
+# COMMANDS
+
+\par help | h
+Show available commands
+
+\par quit | q
+Quit
+
+\par card ID | c ID
+Probe card
+
+\par info | i
+List card info
+
+\par list | l
+List all objects
+
+\par list-verbose | lv
+List all data
+
+\par list-profiles [ID] | lpr [ID]
+List profiles
+
+\par set-profile ID | spr ID
+Activate a profile
+
+\par list-ports [ID] | lp [ID]
+List ports
+
+\par set-port ID | sp ID
+Activate a port
+
+\par list-devices [ID] | ld [ID]
+List available devices
+
+\par get-volume ID | gv ID
+Get volume from device
+
+\par set-volume ID VOL | v ID VOL
+Set volume on device
+
+\par inc-volume ID | v+ ID
+Increase volume on device
+
+\par dec-volume ID | v- ID
+Decrease volume on device
+
+\par get-mute ID | gm ID
+Get mute state from device
+
+\par set-mute ID VAL | sm ID VAL
+Set mute on device
+
+\par toggle-mute ID  | m ID
+Toggle mute on device
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)"

doc/dox/programs/spa-inspect.1.md

@@ -0,0 +1,28 @@
+\page page_man_spa-inspect_1 spa-inspect
+
+The PipeWire SPA plugin information utility
+
+# SYNOPSIS
+
+**spa-inspect** *FILE*
+
+# DESCRIPTION
+
+Displays information about a SPA plugin.
+
+Lists the SPA factories contained, and tries to instantiate them.
+
+# EXAMPLES
+
+**spa-inspect** $(SPA_PLUGINDIR)/bluez5/libspa-codec-bluez5-sbc.so
+
+Display information about a plugin.
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)"

doc/dox/programs/spa-json-dump.1.md

@@ -0,0 +1,24 @@
+\page page_man_spa-json-dump_1 spa-json-dump
+
+SPA JSON to JSON converter
+
+# SYNOPSIS
+
+**spa-json** *FILE*
+
+# DESCRIPTION
+
+Reads a SPA JSON file, and outputs it as standard JSON.
+
+# EXAMPLES
+
+**spa-json-dump** $(PIPEWIRE_CONFDATADIR)/pipewire.conf
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)"

doc/dox/programs/spa-monitor.1.md

@@ -0,0 +1,26 @@
+\page page_man_spa-monitor_1 spa-monitor
+
+The PipeWire SPA device debugging utility
+
+# SYNOPSIS
+
+**spa-monitor** *FILE*
+
+# DESCRIPTION
+
+Load a SPA plugin and instantiate a device from it.
+
+This is only useful for debugging device plugins.
+
+# EXAMPLES
+
+**spa-monitor** $(SPA_PLUGINDIR)/jack/libspa-jack.so
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)"

doc/dox/programs/spa-resample.1.md

@@ -0,0 +1,47 @@
+\page page_man_spa-resample_1 spa-resample
+
+The PipeWire resampler debugging utility
+
+# SYNOPSIS
+
+**spa-resample** \[*OPTIONS*\] *INFILE* *OUTFILE*
+
+# DESCRIPTION
+
+Use the PipeWire resampler to resample input file to output file,
+following the given options.
+
+This is useful only for testing the resampler.
+
+# OPTIONS
+
+\par -r RATE | \--rate=RATE
+Output sample rate.
+
+\par -f FORMAT | \--format=FORMAT
+Output sample format (s8 | s16 | s32 | f32 | f64).
+
+\par -q QUALITY | \--quality=QUALITY
+Resampler output quality (0-14).
+
+\par -c FLAGS | \--cpuflags=FLAGS
+See \ref spa_cpu "spa/support/cpu.h".
+
+\par -h
+Show help.
+
+\par -v
+Verbose operation.
+
+# EXAMPLES
+
+**spa-resample** -r 48000 -f s32 in.wav out.wav
+
+# AUTHORS
+
+The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
+PipeWire is available from <$(PACKAGE_URL)>
+
+# SEE ALSO
+
+\ref page_man_pipewire_1 "pipewire(1)"