From bdf96979fc2c0dc49c3da523c08a2d494fce8ae8 Mon Sep 17 00:00:00 2001 From: Pauli Virtanen Date: Sat, 9 Dec 2023 16:31:11 +0200 Subject: [PATCH] doc: include pipewire-pulse modules explanations also on man page --- doc/Doxyfile.in | 5 +- doc/dox/programs/pipewire-pulse-modules.7.md | 16 +-- doc/dox/pulse-modules.dox | 114 +------------------ doc/dox/pulse-modules.inc | 111 ++++++++++++++++++ 4 files changed, 118 insertions(+), 128 deletions(-) create mode 100644 doc/dox/pulse-modules.inc diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index fc3d0223b..5c19f0a6a 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -23,8 +23,9 @@ FILE_PATTERNS = "*.h" "*.c" RECURSIVE = YES EXAMPLE_PATH = "@top_srcdir@/src/examples" \ "@top_srcdir@/spa/examples" \ - "@top_srcdir@/doc" -EXAMPLE_PATTERNS = "*.c" + "@top_srcdir@/doc/examples" \ + "@top_srcdir@/doc/dox" +EXAMPLE_PATTERNS = "*.c" "*.inc" GENERATE_MAN = YES MAN_EXTENSION = 3 diff --git a/doc/dox/programs/pipewire-pulse-modules.7.md b/doc/dox/programs/pipewire-pulse-modules.7.md index f31e3e07d..21ef3fe30 100644 --- a/doc/dox/programs/pipewire-pulse-modules.7.md +++ b/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 \ \`. -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) diff --git a/doc/dox/pulse-modules.dox b/doc/dox/pulse-modules.dox index 6ed4d3439..2128f3ba6 100644 --- a/doc/dox/pulse-modules.dox +++ b/doc/dox/pulse-modules.dox @@ -1,118 +1,8 @@ /** \page page_pulse_modules Pulseaudio Modules -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 -# Loading modules - -The built-in modules can be loaded using Pulseaudio client programs, -for example `pactl load-module `. 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 -pactl unload-module -``` - -# 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: +# List of built-in modules: - \subpage page_pulse_module_alsa_sink - \subpage page_pulse_module_alsa_source diff --git a/doc/dox/pulse-modules.inc b/doc/dox/pulse-modules.inc new file mode 100644 index 000000000..3e54ccac8 --- /dev/null +++ b/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 `. 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 +pactl unload-module +``` + +# 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 +```