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/Doxyfile.in

@@ -14,6 +14,7 @@ SHOW_INCLUDE_FILES     = NO
 GENERATE_TODOLIST      = NO
 GENERATE_TESTLIST      = NO
 GENERATE_BUGLIST       = NO
+GENERATE_DEPRECATEDLIST= NO
 QUIET                  = YES
 WARN_NO_PARAMDOC       = YES
 HAVE_DOT               = @HAVE_DOT@
@@ -23,8 +24,9 @@ FILE_PATTERNS          = "*.h" "*.c"
 RECURSIVE              = YES
 EXAMPLE_PATH           = "@top_srcdir@/src/examples" \
                          "@top_srcdir@/spa/examples" \
-                         "@top_srcdir@/doc"
+                         "@top_srcdir@/doc/examples" \
-EXAMPLE_PATTERNS       = "*.c"
+                         "@top_srcdir@/doc/dox"
+EXAMPLE_PATTERNS       = "*.c" "*.inc"
 
 GENERATE_MAN           = YES
 MAN_EXTENSION          = 3

doc/dox/api/spa-design.dox

@@ -10,7 +10,7 @@ Types are generally divided into two categories:
 - Integer types: These are enumerations used in the parts where high
                  performance/ease of use/low space overhead is needed.
 
-The SPA type is system is statis and very simple but still allows you
+The SPA type is system is static and very simple but still allows you
 to make and introspect complex object type hierarchies.
 
 See the type system docs for more info.

doc/dox/config/index.md

@@ -0,0 +1,42 @@
+\page page_config Configuration
+
+One of the design goals of PipeWire is to be able to closely control
+and configure all aspects of the processing graph.
+
+A fully configured PipeWire setup runs various pieces, each with their
+configuration options and files:
+
+- **pipewire**: The PipeWire main daemon that runs and coordinates the processing.
+
+- **pipewire-pulse**: The PipeWire PulseAudio replacement server. It also configures
+  the properties of the PulseAudio clients connecting to it.
+
+- **wireplumber**: Most configuration of devices is performed by the session manager.
+  It typically loads ALSA and other devices and configures the profiles, port volumes and more.
+  The session manager also configures new clients and links them to the targets, as configured
+  in the session manager policy.
+
+- **PipeWire clients**: Each native PipeWire client also loads a configuration file.
+  Emulated JACK client also have separate configuration.
+
+# Configuration Settings
+
+Configuration of daemons:
+
+- [PipeWire daemon configuration](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PipeWire)
+- [WirePlumber daemon configuration](https://pipewire.pages.freedesktop.org/wireplumber/)
+- [PipeWire PulseAudio daemon configuration](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio)
+
+Configuration of devices:
+
+- [WirePlumber configuration](https://pipewire.pages.freedesktop.org/wireplumber/daemon/configuration.html)
+- [Device runtime settings](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-Devices)
+
+Configuration for client applications, either connecting via the
+native PipeWire interface, or the emulated ALSA, JACK, or PulseAudio
+interfaces:
+
+- [PipeWire native clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-client)
+- [PipeWire ALSA clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-ALSA)
+- [PipeWire JACK clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-JACK)
+- [PipeWire PulseAudio clients](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/Config-PulseAudio)

doc/dox/index.dox

@@ -11,6 +11,16 @@ PipeWire is low-level multimedia framework that provides:
 See \ref page_overview for an overview of PipeWire and \ref page_design
 for the design principles guiding PipeWire.
 
+# Documentation
+
+- \ref page_config
+- \ref page_programs
+- \ref page_modules
+- \ref page_pulse_modules
+
+See our [Wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home) for
+more information on how to configure and use PipeWire.
+
 # Components
 
 PipeWire ships with the following components:
@@ -27,11 +37,6 @@ PipeWire ships with the following components:
 
 See \ref page_api.
 
-# More Documentation
-
-See our [Wiki](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home) for
-More information on how to configure and use PipeWire.
-
 # Resources
 
 - [PipeWire and AGL](https://wiki.automotivelinux.org/_media/pipewire_agl_20181206.pdf)

doc/dox/internals/access.dox

@@ -82,15 +82,14 @@ module does nothing.
 
 If the property is not set it will go through a set of checks to determine
 the permissions for a client. See the \ref page_module_access documentation
-for details, particularly on the values documented below. Depending on the
+for details.
-value of the \ref PW_KEY_ACCESS property one the following happens:
 
-- `"allowed"`, `"unrestricted"`:  ALL permissions are set on the core
+Depending on the resolution, it grants permissions to the client as follows:
+
+- `"unrestricted"`:  ALL permissions are set on the core
     object and the client will be able to resume.
-- `"restricted"`, `"flatpak"`, `"$access.force"`:  No permissions are set on
+- any other value: No permissions are set on the core object
-    the core object and the client will be suspended.
+  and the client will be suspended.
-- `"rejected"`: An error is sent to the client and the client is
-    suspended.
 
 As detailed above, the client may be suspended. In that case the session
 manager or another client is required to configure permissions on the object
@@ -101,8 +100,7 @@ for it to resume.
 The session manager listens for new clients to appear. It will use the
 \ref PW_KEY_ACCESS property to determine what to do.
 
-For clients that are suspended with `"restricted"`, `"flatpak"` or
+For clients that are not unrestricted, the session manager needs to set permissions on the
-`"$access.force"` access, the session manager needs to set permissions on the
 client for the various PipeWire objects in the graph that it is allowed to
 interact with.  To resume a client, the session manager needs to set
 permission `R` on the core object for the client.

doc/dox/internals/design.dox

@@ -51,7 +51,7 @@ See \ref page_module_protocol_native for details.
 The functionality of the server is implemented and extended with modules and
 extensions. Modules are server side bits of logic that hook into various
 places to provide extra features. This mostly means controlling the processing
-graph in some way. See \ref page_pipewire_modules for a list of current
+graph in some way. See \ref page_modules for a list of current
 modules.
 
 Extensions are the client side version of the modules. Most extensions provide

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.
+\include{doc} pulse-modules.inc
-It only supports its own built-in modules, and cannot load external
-modules written for Pulseaudio.
 
-The built-in modules can be loaded using Pulseaudio client programs, for
+# BUILT-IN MODULES
-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
 
 $(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)"

doc/dox/pulse-modules.dox

@@ -1,118 +1,8 @@
 /** \page page_pulse_modules Pulseaudio Modules
 
-PipeWire's Pulseaudio emulation implements several Pulseaudio modules.
+\include{doc} pulse-modules.inc
-It only supports its own built-in modules, and cannot load external
-modules written for Pulseaudio.
 
-# Loading modules
+# List of built-in modules:
-
-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 = [ ] }
-]
-```
-
-To list all modules currently loaded, with their arguments:
-```
-pactl list modules
-```
-
-For a short list of loaded modules:
-```
-pactl list modules short
-```
-
-Modules may be unloaded using either the module-name or index number:
-
-```
-pactl load-module <module-name> <parameters>
-pactl unload-module <module-name|index#>
-```
-
-# Common module options
-
-Most modules that create streams/devices support the following properties:
-
-## sink_name, source_name
-
-Name for the sink (resp. source). Allowed characters in the name are a-z, A-Z, numbers, period (.) and underscore (_). The length must be 1-128 characters.
-
-## format
-
-The sample format. The supported audio formats are:
-
-### PCM
- - u8: unsigned 8-bit integer
- - aLaw: A-law encoded 8-bit integer
- - uLaw: μ-law encoded 8-bit integer
- - s16le: signed 16-bit little-endian integer
- - s16be: signed 16-bit big-endian integer
- - s16, s16ne: native-endian aliases for s16le or s16be
- - s16re: reverse-endian alias for s16le or s16be
- - float32le: 32-bit little-endian float
- - float32be: 32-bit big-endian float
- - float32, float32ne: native-endian aliases for float32le or float32be
- - float32re: reverse-endian alias for float32le or float32be
- - s32le: signed 32-bit little-endian integer
- - s32be: signed 32-bit big-endian integer
- - s32, s32ne: native-endian aliases for s32le or s32be
- - s32re: reverse-endian alias for s32le or s32be
- - s24le: signed 24-bit little-endian integer (note: ALSA calls this "S24_3LE")
- - s24be: signed 24-bit big-endian integer (note: ALSA calls this "S24_3BE")
- - s24, s24ne: native-endian aliases for s24le or s24be
- - s24re: reverse-endian alias for s24le or s24be
- - s24-32le: signed 24-bit little-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_LE")
- - s24-32be: signed 24-bit big-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_BE")
- - s24-32, s24-32ne: native-endian aliases for s24-32le or s24-32be
- - s24-32re: reverse-endian alias for s24-32le or s24-32be
-
-### Compressed audio formats
-
-Below is a list of all supported compressed formats. The code at the beginning of each line is used whenever a textual identifier for a format is needed (for example in configuration files or on the command line). The formats whose identifier ends with -iec61937 have to be wrapped in IEC 61937 frames, which makes the compressed audio behave more like normal PCM audio.
-
- - ac3-iec61937: Dolby Digital (DD / AC-3 / A/52)
- - eac3-iec61937: Dolby Digital Plus (DD+ / E-AC-3)
- - mpeg-iec61937: MPEG-1 or MPEG-2 Part 3 (not MPEG-2 AAC)
- - dts-iec61937: DTS
- - mpeg2-aac-iec61937: MPEG-2 AAC (supported since PulseAudio 4.0)
- - truehd-iec61937: Dolby TrueHD (added in PulseAudio 13.0, but doesn't work yet in practice)
- - dtshd-iec61937: DTS-HD Master Audio (added in PulseAudio 13.0, but doesn't work yet in practice)
- - pcm: PCM (not a compressed format, but listed here, because pcm is one of the recognized encoding identifiers)
- - any: (special identifier for indicating that any encoding can be used)
-
-
-## rate
-
-The sample rate.
-
-##channels
-
-Number of audio channels.
-
-## channel_map
-
-A channel map. A list of comma-separated channel names. The currently defined channel names are:
-`left`, `right`, `mono`, `center`, `front-left`, `front-right`, `front-center`,
-`rear-center`, `rear-left`, `rear-right`, `lfe`, `subwoofer`, `front-left-of-center`,
-`front-right-of-center`, `side-left`, `side-right`, `aux0`, `aux1` to `aux15`, `top-center`,
-`top-front-left`, `top-front-right`, `top-front-center`, `top-rear-left`, `top-rear-right`,
-`top-rear-center`
-
-## sink_properties, source_properties
-
-Set additional properties of the sink/source. For example, you can set the description directly
-when the module is loaded by setting this parameter.
-
-```
-load-module module-alsa-sink sink_name=headphones sink_properties=device.description=Headphones
-```
-
-# List of known built-in modules:
 
 - \subpage page_pulse_module_alsa_sink
 - \subpage page_pulse_module_alsa_source

doc/dox/pulse-modules.inc

@@ -0,0 +1,111 @@
+PipeWire's Pulseaudio emulation implements several Pulseaudio modules.
+It only supports its own built-in modules, and cannot load external
+modules written for Pulseaudio.
+
+# Loading modules
+
+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 = [ ] }
+]
+```
+
+To list all modules currently loaded, with their arguments:
+```
+pactl list modules
+```
+
+For a short list of loaded modules:
+```
+pactl list modules short
+```
+
+Modules may be unloaded using either the module-name or index number:
+
+```
+pactl load-module <module-name> <parameters>
+pactl unload-module <module-name|index#>
+```
+
+# Common module options
+
+Most modules that create streams/devices support the following properties:
+
+## sink_name, source_name
+
+Name for the sink (resp. source). Allowed characters in the name are a-z, A-Z, numbers, period (.) and underscore (_). The length must be 1-128 characters.
+
+## format
+
+The sample format. The supported audio formats are:
+
+### PCM
+ - u8: unsigned 8-bit integer
+ - aLaw: A-law encoded 8-bit integer
+ - uLaw: μ-law encoded 8-bit integer
+ - s16le: signed 16-bit little-endian integer
+ - s16be: signed 16-bit big-endian integer
+ - s16, s16ne: native-endian aliases for s16le or s16be
+ - s16re: reverse-endian alias for s16le or s16be
+ - float32le: 32-bit little-endian float
+ - float32be: 32-bit big-endian float
+ - float32, float32ne: native-endian aliases for float32le or float32be
+ - float32re: reverse-endian alias for float32le or float32be
+ - s32le: signed 32-bit little-endian integer
+ - s32be: signed 32-bit big-endian integer
+ - s32, s32ne: native-endian aliases for s32le or s32be
+ - s32re: reverse-endian alias for s32le or s32be
+ - s24le: signed 24-bit little-endian integer (note: ALSA calls this "S24_3LE")
+ - s24be: signed 24-bit big-endian integer (note: ALSA calls this "S24_3BE")
+ - s24, s24ne: native-endian aliases for s24le or s24be
+ - s24re: reverse-endian alias for s24le or s24be
+ - s24-32le: signed 24-bit little-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_LE")
+ - s24-32be: signed 24-bit big-endian integer, packed into a 32-bit integer so that the 8 most significant bits are ignored (note: ALSA calls this "S24_BE")
+ - s24-32, s24-32ne: native-endian aliases for s24-32le or s24-32be
+ - s24-32re: reverse-endian alias for s24-32le or s24-32be
+
+### Compressed audio formats
+
+Below is a list of all supported compressed formats. The code at the beginning of each line is used whenever a textual identifier for a format is needed (for example in configuration files or on the command line). The formats whose identifier ends with -iec61937 have to be wrapped in IEC 61937 frames, which makes the compressed audio behave more like normal PCM audio.
+
+ - ac3-iec61937: Dolby Digital (DD / AC-3 / A/52)
+ - eac3-iec61937: Dolby Digital Plus (DD+ / E-AC-3)
+ - mpeg-iec61937: MPEG-1 or MPEG-2 Part 3 (not MPEG-2 AAC)
+ - dts-iec61937: DTS
+ - mpeg2-aac-iec61937: MPEG-2 AAC (supported since PulseAudio 4.0)
+ - truehd-iec61937: Dolby TrueHD (added in PulseAudio 13.0, but doesn't work yet in practice)
+ - dtshd-iec61937: DTS-HD Master Audio (added in PulseAudio 13.0, but doesn't work yet in practice)
+ - pcm: PCM (not a compressed format, but listed here, because pcm is one of the recognized encoding identifiers)
+ - any: (special identifier for indicating that any encoding can be used)
+
+
+## rate
+
+The sample rate.
+
+##channels
+
+Number of audio channels.
+
+## channel_map
+
+A channel map. A list of comma-separated channel names. The currently defined channel names are:
+`left`, `right`, `mono`, `center`, `front-left`, `front-right`, `front-center`,
+`rear-center`, `rear-left`, `rear-right`, `lfe`, `subwoofer`, `front-left-of-center`,
+`front-right-of-center`, `side-left`, `side-right`, `aux0`, `aux1` to `aux15`, `top-center`,
+`top-front-left`, `top-front-right`, `top-front-center`, `top-rear-left`, `top-rear-right`,
+`top-rear-center`
+
+## sink_properties, source_properties
+
+Set additional properties of the sink/source. For example, you can set the description directly
+when the module is loaded by setting this parameter.
+
+```
+load-module module-alsa-sink sink_name=headphones sink_properties=device.description=Headphones
+```

doc/examples/tutorial4.c

@@ -50,7 +50,13 @@ static void on_process(void *userdata)
 		if (data->accumulator >= M_PI_M2)
 			data->accumulator -= M_PI_M2;
 
-		val = sin(data->accumulator) * DEFAULT_VOLUME * 16767.f;
+		/* sin() gives a value between -1.0 and 1.0, we first apply
+		 * the volume and then scale with 32767.0 to get a 16 bits value
+		 * between [-32767 32767].
+		 * Another common method to convert a double to
+		 * 16 bits is to multiple by 32768.0 and then clamp to
+		 * [-32768 32767] to get the full 16 bits range. */
+		val = sin(data->accumulator) * DEFAULT_VOLUME * 32767.0;
 		for (c = 0; c < DEFAULT_CHANNELS; c++)
 			*dst++ = val;
 	}

doc/input-filter-h.sh

@@ -11,9 +11,7 @@ FILENAME="$1"
 # Add \ingroup commands for the file, for each \addgroup in it
 BASEFILE=$(echo "$FILENAME" | sed -e 's@.*src/pipewire/@pipewire/@; s@.*spa/include/spa/@spa/@; s@.*src/test/@test/@;')
 
-# shellcheck disable=SC2028 # \file is not an escape sequence
+printf "/** \\\\file\n\`%s\`\n" "$BASEFILE"
-echo "/** \file"
-echo "\`$BASEFILE\`"
 sed -n -e '/.*\\addtogroup [a-zA-Z0-9_].*/ { s/.*addtogroup /\\ingroup /; p; }' < "$FILENAME" | sort | uniq
 echo " */"
 
@@ -25,9 +23,15 @@ echo " */"
 # Ensure all macros are included (also those defined inside a struct),
 # by adding /** \ingroup XXX */ before each definition.
 # Also ensure all opaque structs get included.
+# Strip SPA_FORMAT_ARG_FUNC(1) etc. things that confuse doxygen
 sed -e 's@^\(#define .*[[:space:]]\)\(.*_method\)\((.,[[:space:]]*\)\([a-z_]\+\)\(.*)[[:space:]]*\)$@\1\2\3\4\5 /**< \\copydoc \2s.\4\n\n\\sa \2s.\4 */@;' \
     -e 's@^\(#define .*[[:space:]]\)\(.*_method\)\(_[rvs](.,[[:space:]]*\)\([a-z_]\+\)\(.*)[[:space:]]*\)$@\1\2\3\4\5 /**< \\copydoc \2s.\4\n\n\\sa \2s.\4 */@;' \
     -e '/\\addtogroup/ { h; s@.*\\addtogroup \(.*\).*@/** \\ingroup \1 */@; x; }' \
     -e '/#define \(PW\|SPA\)_[A-Z].*[^\\][ ]*$/ { x; p; x; }' \
     -e 's@^\([ ]*struct \)\([a-zA-Z0-9_]*\)\(;.*\)$@/** \\struct \2 */\n\1\2\3@;' \
+    -e 's@^[ ]*SPA_FORMAT_ARG_FUNC([0-9, ]*)@@;' \
+    -e 's@[ ]*SPA_PRINTF_FUNC([0-9, ]*);@;@;' \
+    -e 's@^[ ]*SPA_WARN_UNUSED_RESULT@ @;' \
+    -e 's@ SPA_SENTINEL;@;@;' \
+    -e 's@ SPA_UNUSED,@,@;' \
 < "$FILENAME"

doc/meson.build

@@ -14,6 +14,7 @@ doxygen_env.set('PACKAGE_URL', 'https://pipewire.org')
 doxygen_env.set('PACKAGE_BUGREPORT', 'https://gitlab.freedesktop.org/pipewire/pipewire/issues')
 doxygen_env.set('PIPEWIRE_CONFIG_DIR', pipewire_configdir)
 doxygen_env.set('PIPEWIRE_CONFDATADIR', pipewire_confdatadir)
+doxygen_env.set('SPA_PLUGINDIR', spa_plugindir)
 
 dot_found = find_program('dot', required: false).found()
 summary({'dot (used with doxygen)': dot_found}, bool_yn: true, section: 'Optional programs')
@@ -32,6 +33,7 @@ extra_docs = [
   'dox/modules.dox',
   'dox/pulse-modules.dox',
   'dox/programs/index.md',
+  'dox/config/index.md',
   'dox/internals/index.dox',
   'dox/internals/design.dox',
   'dox/internals/access.dox',
@@ -80,7 +82,14 @@ manpage_docs = [
   'dox/programs/pw-mididump.1.md',
   'dox/programs/pw-mon.1.md',
   'dox/programs/pw-profiler.1.md',
+  'dox/programs/pw-reserve.1.md',
   'dox/programs/pw-top.1.md',
+  'dox/programs/pw-v4l2.1.md',
+  'dox/programs/spa-acp-tool.1.md',
+  'dox/programs/spa-inspect.1.md',
+  'dox/programs/spa-json-dump.1.md',
+  'dox/programs/spa-monitor.1.md',
+  'dox/programs/spa-resample.1.md',
 ]
 
 manpages = []

doc/tree.dox

@@ -123,6 +123,7 @@ Support interfaces provided by host
 \}
 
 \page page_overview
+\page page_config
 \page page_programs
 \page page_modules
 \page page_pulse_modules