diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index bbf2b4ad1..fc3d0223b 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -26,6 +26,9 @@ EXAMPLE_PATH = "@top_srcdir@/src/examples" \ "@top_srcdir@/doc" EXAMPLE_PATTERNS = "*.c" +GENERATE_MAN = YES +MAN_EXTENSION = 3 + REFERENCED_BY_RELATION = NO REFERENCES_RELATION = NO IGNORE_PREFIX = pw_ \ diff --git a/doc/custom.css b/doc/custom.css index ace3e1c71..97f033f75 100644 --- a/doc/custom.css +++ b/doc/custom.css @@ -34,3 +34,7 @@ font-style: italic; font-size: medium; } + +.textblock dl.section dd { + margin-left: 2rem; +} diff --git a/doc/dox/programs/index.md b/doc/dox/programs/index.md new file mode 100644 index 000000000..4ed988aff --- /dev/null +++ b/doc/dox/programs/index.md @@ -0,0 +1,23 @@ +\page page_programs Programs + +Manual pages: + +- \subpage page_man_pipewire_1 +- \subpage page_man_pipewire_conf_5 +- \subpage page_man_pipewire-pulse_1 +- \subpage page_man_pipewire-pulse_conf_5 +- \subpage page_man_pipewire-pulse-modules_7 +- \subpage page_man_pw-cat_1 +- \subpage page_man_pw-cli_1 +- \subpage page_man_pw-config_1 +- \subpage page_man_pw-dot_1 +- \subpage page_man_pw-dump_1 +- \subpage page_man_pw-jack_1 +- \subpage page_man_pw-link_1 +- \subpage page_man_pw-loopback_1 +- \subpage page_man_pw-metadata_1 +- \subpage page_man_pw-mididump_1 +- \subpage page_man_pw-mon_1 +- \subpage page_man_pw-profiler_1 +- \subpage page_man_pw-top_1 +- \subpage page_man_libpipewire-modules_7 diff --git a/man/libpipewire-modules.7.rst.in b/doc/dox/programs/libpipewire-modules.7.md similarity index 63% rename from man/libpipewire-modules.7.rst.in rename to doc/dox/programs/libpipewire-modules.7.md index a8251d992..ae3f88be1 100644 --- a/man/libpipewire-modules.7.rst.in +++ b/doc/dox/programs/libpipewire-modules.7.md @@ -1,56 +1,44 @@ -libpipewire-modules -################### +\page page_man_libpipewire-modules_7 libpipewire-modules ----------------- PipeWire modules ----------------- -:Manual section: 7 -:Manual group: PipeWire - -DESCRIPTION -=========== +# DESCRIPTION A PipeWire module is effectively a PipeWire client running inside -``pipewire(1)`` which can host multiple modules. Usually modules are -loaded when they are listed in the configuration files. For example -the default configuration file loads several modules: - -:: +`pipewire(1)` which can host multiple modules. Usually modules are +loaded when they are listed in the configuration files. For example the +default configuration file loads several modules: context.modules = [ ... # The native communication protocol. { name = libpipewire-module-protocol-native } - + # The profile module. Allows application to access profiler # and performance data. It provides an interface that is used # by pw-top and pw-profiler. { name = libpipewire-module-profiler } - + # Allows applications to create metadata objects. It creates # a factory for Metadata objects. { name = libpipewire-module-metadata } - + # Creates a factory for making devices that run in the # context of the PipeWire server. { name = libpipewire-module-spa-device-factory } ... ] -KNOWN MODULES -============= +# KNOWN MODULES -- @LIBPIPEWIRE_MODULES@ +$(LIBPIPEWIRE_MODULES) -AUTHORS -======= +# AUTHORS -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> -SEE ALSO -======== - -``pipewire(1)``, -``pipewire.conf(5)``, +# SEE ALSO +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pipewire_conf_5 "pipewire.conf(5)" diff --git a/doc/dox/programs/pipewire-pulse-modules.7.md b/doc/dox/programs/pipewire-pulse-modules.7.md new file mode 100644 index 000000000..f31e3e07d --- /dev/null +++ b/doc/dox/programs/pipewire-pulse-modules.7.md @@ -0,0 +1,32 @@ +\page page_man_pipewire-pulse-modules_7 pipewire-pulse-modules + +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. + +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 + +$(PIPEWIRE_PULSE_MODULES) + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire-pulse_1 "pipewire-pulse(1)" diff --git a/doc/dox/programs/pipewire-pulse.1.md b/doc/dox/programs/pipewire-pulse.1.md new file mode 100644 index 000000000..90ed98f16 --- /dev/null +++ b/doc/dox/programs/pipewire-pulse.1.md @@ -0,0 +1,40 @@ +\page page_man_pipewire-pulse_1 pipewire-pulse + +The PipeWire PulseAudio replacement + +# SYNOPSIS + +**pipewire-pulse** \[*options*\] + +# DESCRIPTION + +**pipewire-pulse** starts a PulseAudio-compatible daemon that integrates +with the PipeWire media server, by running a pipewire process through a +systemd service. This daemon is a drop-in replacement for the PulseAudio +daemon. + +# OPTIONS + +\par -h | \--help +Show help. + +\par -v | \--verbose +Increase the verbosity by one level. This option may be specified +multiple times. + +\par \--version +Show version information. + +\par -c | \--config=FILE +Load the given config file (Default: pipewire-pulse.conf). + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire-pulse_conf_5 "pipewire-pulse.conf(5)", +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pipewire-pulse-modules_7 "pipewire-pulse-modules(7)" diff --git a/doc/dox/programs/pipewire-pulse.conf.5.md b/doc/dox/programs/pipewire-pulse.conf.5.md new file mode 100644 index 000000000..fe94352f3 --- /dev/null +++ b/doc/dox/programs/pipewire-pulse.conf.5.md @@ -0,0 +1,56 @@ +\page page_man_pipewire-pulse_conf_5 pipewire-pulse.conf + +The PipeWire Pulseaudio server configuration file + +# SYNOPSIS + +*$XDG_CONFIG_HOME/pipewire/pipewire-pulse.conf* + +*$(PIPEWIRE_CONFIG_DIR)/pipewire-pulse.conf* + +*$(PIPEWIRE_CONFDATADIR)/pipewire-pulse.conf* + +*$(PIPEWIRE_CONFDATADIR)/pipewire-pulse.conf.d/* + +*$(PIPEWIRE_CONFIG_DIR)/pipewire-pulse.conf.d/* + +*$XDG_CONFIG_HOME/pipewire/pipewire-pulse.conf.d/* + +# DESCRIPTION + +Configuration for PipeWire's PulseAudio-compatible daemon. + +The configuration file format is the same as for `pipewire.conf(5)`. +There are additional sections for configuring `pipewire-pulse(1)` +settings. + +# CONFIGURATION FILE SECTIONS + +\par pulse.properties +Dictionary. These properties configure the PipeWire Pulseaudio server +properties. + +\par pulse.cmd +Array of dictionaries. A set of commands to be executed on startup. + +\par pulse.rules +Array of dictionaries. A set of match rules and actions to apply to +clients. + +See \ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)" +for the detailed description. + +In addition, the general PipeWire daemon configuration sections apply, +see \ref page_man_pipewire_conf_5 "pipewire.conf(5)". + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_module_protocol_pulse "libpipewire-module-protocol-pulse(7)", +\ref page_man_pipewire_conf_5 "pipewire.conf(5)", +\ref page_man_pipewire-pulse_1 "pipewire-pulse(1)", +\ref page_man_pipewire-pulse-modules_7 "pipewire-pulse-modules(7)" diff --git a/doc/dox/programs/pipewire.1.md b/doc/dox/programs/pipewire.1.md new file mode 100644 index 000000000..9b6c389d5 --- /dev/null +++ b/doc/dox/programs/pipewire.1.md @@ -0,0 +1,44 @@ +\page page_man_pipewire_1 pipewire + +The PipeWire media server + +# SYNOPSIS + +**pipewire** \[*options*\] + +# DESCRIPTION + +PipeWire is a service that facilitates sharing of multimedia content +between devices and applications. + +The **pipewire** daemon reads a config file that is further documented +in \ref page_man_pipewire_conf_5 "pipewire.conf(5)" manual page. + +# OPTIONS + +\par -h | \--help +Show help. + +\par -v | \--verbose +Increase the verbosity by one level. This option may be specified +multiple times. + +\par \--version +Show version information. + +\par -c | \--config=FILE +Load the given config file (Default: pipewire.conf). + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pw-top_1 "pw-top(1)", +\ref page_man_pw-dump_1 "pw-dump(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", +\ref page_man_pw-cat_1 "pw-cat(1)", +\ref page_man_pw-cli_1 "pw-cli(1)", +\ref page_man_libpipewire-modules_7 "libpipewire-modules(7)" diff --git a/doc/dox/programs/pipewire.conf.5.md b/doc/dox/programs/pipewire.conf.5.md new file mode 100644 index 000000000..4abe21605 --- /dev/null +++ b/doc/dox/programs/pipewire.conf.5.md @@ -0,0 +1,102 @@ +\page page_man_pipewire_conf_5 pipewire.conf + +The PipeWire server configuration file + +# SYNOPSIS + +*$XDG_CONFIG_HOME/pipewire/pipewire.conf* + +*$(PIPEWIRE_CONFIG_DIR)/pipewire.conf* + +*$(PIPEWIRE_CONFDATADIR)/pipewire.conf* + +*$(PIPEWIRE_CONFDATADIR)/pipewire.conf.d/* + +*$(PIPEWIRE_CONFIG_DIR)/pipewire.conf.d/* + +*$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/* + +# DESCRIPTION + +PipeWire is a service that facilitates sharing of multimedia content +between devices and applications. + +On startup, the daemon reads a main configuration file to configure +itself. It executes a series of commands listed in the config file. + +The config files are loaded in the order listed in the +[SYNOPSIS](#synopsis). The environment variables `PIPEWIRE_CONFIG_DIR`, +`PIPEWIRE_CONFIG_PREFIX` and `PIPEWIRE_CONFIG_NAME` can be used to +specify an alternative config directory, subdirectory and file +respectively. + +Next to the configuration file can be a directory with the same name as +the file with a `.d/` suffix. All directories in the +[SYNOPSIS](#synopsis) directory search paths are traversed in the listed +order and the contents of the `*.conf` files inside them are appended to +the main configuration file as overrides. Object sections are merged and +array sections are appended. + +# CONFIGURATION FILE FORMAT + +The configuration file format is grouped into sections. A section is +either a dictionary, {}, or an array, \[\]. Dictionary and array entries +are separated by whitespace and may be simple value assignment, an array +or a dictionary. For example: +``` + name = value # simple assignment + + name = { key1 = value1 key2 = value2 } # a dictionary with two entries + + name = [ value1 value2 ] # an array with two entries + + name = [ { k = v1 } { k = v2 } ] # an array of dictionaries +``` + +The configuration files can be expressed in full JSON syntax but for +ease of use, a relaxed format may be used where: + +- `:` to delimit keys and values can be substuted by `=` or a space. +- \" around keys and string can be omitted as long as no special + characters are used in the strings. +- `,` to separate objects can be replaced with a whitespace character. +- `#` can be used to start a comment until the line end + +# CONFIGURATION FILE SECTIONS + +\par context.properties +Dictionary. These properties configure the PipeWire instance. + +\par context.spa-libs +Dictionary. Maps plugin features with globs to a spa library. + +\par context.modules +Array of dictionaries. Each entry in the array is a dictionary with the +*name* of the module to load, including optional *args* and *flags*. +Most modules support being loaded multiple times. + +\par context.objects +Array of dictionaries. Each entry in the array is a dictionary +containing the *factory* to create an object from and optional extra +arguments specific to that factory. + +\par context.exec +\parblock +Array of dictionaries. Each entry in the array is dictionary containing +the *path* of a program to execute on startup and optional *args*. + +This array used to contain an entry to start the session manager but +this mode of operation has since been demoted to development aid. Avoid +starting a session manager in this way in production environment. +\endparblock + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", +\ref page_man_libpipewire-modules_7 "libpipewire-modules(7)" diff --git a/doc/dox/programs/pw-cat.1.md b/doc/dox/programs/pw-cat.1.md new file mode 100644 index 000000000..4860c427f --- /dev/null +++ b/doc/dox/programs/pw-cat.1.md @@ -0,0 +1,163 @@ +\page page_man_pw-cat_1 pw-cat + +Play and record media with PipeWire + +# SYNOPSIS + +**pw-cat** \[*options*\] \[*FILE* \| -\] + +**pw-play** \[*options*\] \[*FILE* \| -\] + +**pw-record** \[*options*\] \[*FILE* \| -\] + +**pw-midiplay** \[*options*\] \[*FILE* \| -\] + +**pw-midirecord** \[*options*\] \[*FILE* \| -\] + +**pw-dsdplay** \[*options*\] \[*FILE* \| -\] + +# DESCRIPTION + +**pw-cat** is a simple tool for playing back or capturing raw or encoded +media files on a PipeWire server. It understands all audio file formats +supported by `libsndfile` for PCM capture and playback. When capturing +PCM, the filename extension is used to guess the file format with the +WAV file format as the default. + +It understands standard MIDI files for playback and recording. This tool +will not render MIDI files, it will simply make the MIDI events +available to the graph. You need a MIDI renderer such as qsynth, +timidity or a hardware MIDI rendered to hear the MIDI. + +DSD playback is supported with the DSF file format. This tool will only +work with native DSD capable hardware and will produce an error when no +such hardware was found. + +When the *FILE* is - input and output will be raw data from STDIN and +STDOUT respectively. + +# OPTIONS + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -v | \--verbose +Verbose operation. + +\par -R | \--remote=NAME +The name the *remote* instance to connect to. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -p | \--playback +Playback mode. Read data from the specified file, and play it back. If +the tool is called under the name **pw-play** or **pw-midiplay** this is +the default. + +\par -r | \--record +Recording mode. Capture data and write it to the specified file. If the +tool is called under the name **pw-record** or **pw-midirecord** this is +the default. + +\par -m | \--midi +MIDI mode. *FILE* is a MIDI file. If the tool is called under the name +**pw-midiplay** or **pw-midirecord** this is the default. Note that this +program will *not* render the MIDI events into audible samples, it will +simply provide the MIDI events in the graph. You need a separate MIDI +renderer such as qsynth, timidity or a hardware renderer to hear the +MIDI. + +\par -d | \--dsd +DSD mode. *FILE* is a DSF file. If the tool is called under the name +**pw-dsdplay** this is the default. Note that this program will *not* +render the DSD audio. You need a DSD capable device to play DSD content +or this program will exit with an error. + +\par \--media-type=VALUE +Set the media type property (default Audio/Midi depending on mode). The +media type is used by the session manager to select a suitable target to +link to. + +\par \--media-category=VALUE +Set the media category property (default Playback/Capture depending on +mode). The media type is used by the session manager to select a +suitable target to link to. + +\par \--media-role=VALUE +Set the media role property (default Music). The media type is used by +the session manager to select a suitable target to link to. + +\par \--target=VALUE +\parblock +Set a node target (default auto). The value can be: + +- **auto**: Automatically select (Default) + +- **0**: Don't try to link this node + +- \: The object.serial or the node.name of a target node +\endparblock + +\par \--latency=VALUE\[*units*\] +\parblock +Set the node latency (default 100ms) + +The latency determines the minimum amount of time it takes for a sample +to travel from application to device (playback) and from device to +application (capture). + +The latency determines the size of the buffers that the application will +be able to fill. Lower latency means smaller buffers but higher +overhead. Higher latency means larger buffers and lower overhead. + +Units can be **s** for seconds, **ms** for milliseconds, **us** for +microseconds, **ns** for nanoseconds. If no units are given, the latency +value is samples with the samplerate of the file. +\endparblock + +\par -P | \--properties=VALUE +Set extra stream properties as a JSON object. + +\par -q | \--quality=VALUE +Resampler quality. When the samplerate of the source or destination file +does not match the samplerate of the server, the data will be resampled. +Higher quality uses more CPU. Values between 0 and 15 are allowed, the +default quality is 4. + +\par \--rate=VALUE +The sample rate, default 48000. + +\par \--channels=VALUE +The number of channels, default 2. + +\par \--channel-map=VALUE +The channelmap. Possible values include: **mono**, **stereo**, +**surround-21**, **quad**, **surround-22**, **surround-40**, +**surround-31**, **surround-41**, **surround-50**, **surround-51**, +**surround-51r**, **surround-70**, **surround-71** or a comma separated +list of channel names: **FL**, **FR**, **FC**, **LFE**, **SL**, **SR**, +**FLC**, **FRC**, **RC**, **RL**, **RR**, **TC**, **TFL**, **TFC**, +**TFR**, **TRL**, **TRC**, **TRR**, **RLC**, **RRC**, **FLW**, **FRW**, +**LFE2**, **FLH**, **FCH**, **FRH**, **TFLC**, **TFRC**, **TSL**, +**TSR**, **LLFR**, **RLFE**, **BC**, **BLC**, **BRC** + +\par \--format=VALUE +The sample format to use. One of: **u8**, **s8**, **s16** (default), +**s24**, **s32**, **f32**, **f64**. + +\par \--volume=VALUE +The stream volume, default 1.000. Depending on the locale you have +configured, "," or "." may be used as a decimal separator. Check with +**locale** command. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", diff --git a/doc/dox/programs/pw-cli.1.md b/doc/dox/programs/pw-cli.1.md new file mode 100644 index 000000000..0108ef608 --- /dev/null +++ b/doc/dox/programs/pw-cli.1.md @@ -0,0 +1,189 @@ +\page page_man_pw-cli_1 pw-cli + +The PipeWire Command Line Interface + +# SYNOPSIS + +**pw-cli** \[*command*\] + +# DESCRIPTION + +Interact with a PipeWire instance. + +When a command is given, **pw-cli** will execute the command and exit + +When no command is given, **pw-cli** starts an interactive session with +the default PipeWire instance *pipewire-0*. + +Connections to other, remote instances can be made. The current instance +name is displayed at the prompt. + +Note that **pw-cli** also creates a local PipeWire instance. Some +commands operate on the current (remote) instance and some on the local +instance, such as module loading. + +Use the 'help' command to list the available commands. + +# GENERAL COMMANDS + +\par help | h +Show a quick help on the commands available. It also lists the aliases +for many commands. + +\par quit | q +Exit from **pw-cli** + +# MODULE MANAGEMENT + +Modules are loaded and unloaded in the local instance, thus the pw-cli +binary itself and can add functionality or objects to the local +instance. It is not possible in PipeWire to load modules in another +instance. + +\par load-module *name* \[*arguments...*\] +\parblock +Load a module specified by its name and arguments in the local instance. +For most modules it is OK to be loaded more than once. + +This command returns a module variable that can be used to unload the +module. + +The locally module is *not* visible in the remote instance. It is not +possible in PipeWire to load modules in a remote instance. +\endparblock + +\par unload-module *module-var* +Unload a module, specified either by its variable. + +# OBJECT INTROSPECTION + +\par list-objects +List the objects of the current instance. + +Objects are listed with their *id*, *type* and *version*. + +\par info *id* | *all* +Get information about a specific object or *all* objects. + +Requesting info about an object will also notify you of changes. + +# WORKING WITH REMOTES + +\par connect \[*remote-name*\] +\parblock +Connect to a remote instance and make this the new current instance. + +If no remote name is specified, a connection is made to the default +remote instance, usually *pipewire-0*. + +The special remote name called *internal* can be used to connect to the +local **pw-cli** PipeWire instance. + +This command returns a remote var that can be used to disconnect or +switch remotes. +\endparblock + +\par disconnect \[*remote-var*\] +\parblock +Disconnect from a *remote instance*. + +If no remote name is specified, the current instance is disconnected. +\endparblock + +\par list-remotes +List all *remote instances*. + +\par switch-remote \[*remote-var*\] +\parblock +Make the specified *remote* the current instance. + +If no remote name is specified, the first instance is made current. +\endparblock + +# NODE MANAGEMENT + +\par create-node *factory-name* \[*properties...*\] +\parblock +Create a node from a factory in the current instance. + +Properties are key=value pairs separated by whitespace. + +This command returns a *node variable*. +\endparblock + +\par export-node *node-id* \[*remote-var*\] +Export a node from the local instance to the specified instance. When no +instance is specified, the node will be exported to the current +instance. + +# DEVICE MANAGEMENT + +\par create-device *factory-name* \[*properties...*\] +\parblock +Create a device from a factory in the current instance. + +Properties are key=value pairs separated by whitespace. + +This command returns a *device variable*. +\endparblock + +# LINK MANAGEMENT + +\par create-link *node-id* *port-id* *node-id* *port-id* \[*properties...*\] +\parblock +Create a link between 2 nodes and ports. + +Port *ids* can be *-1* to automatically select an available port. + +Properties are key=value pairs separated by whitespace. + +This command returns a *link variable*. +\endparblock + +# GLOBALS MANAGEMENT + +\par destroy *object-id* +Destroy a global object. + +# PARAMETER MANAGEMENT + +\par enum-params *object-id* *param-id* +\parblock +Enumerate params of an object. + +*param-id* can also be given as the param short name. +\endparblock + +\par set-param *object-id* *param-id* *param-json* +\parblock +Set param of an object. + +*param-id* can also be given as the param short name. +\endparblock + +# PERMISSION MANAGEMENT + +\par permissions *client-id* *object-id* *permission* +\parblock +Set permissions for a client. + +*object-id* can be *-1* to set the default permissions. +\endparblock + +\par get-permissions *client-id* +Get permissions of a client. + +# COMMAND MANAGEMENT + +\par send-command *object-id* +Send a command to an object. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", diff --git a/doc/dox/programs/pw-config.1.md b/doc/dox/programs/pw-config.1.md new file mode 100644 index 000000000..898f12eb3 --- /dev/null +++ b/doc/dox/programs/pw-config.1.md @@ -0,0 +1,97 @@ +\page page_man_pw-config_1 pw-config + +Debug PipeWire Config parsing + +# SYNOPSIS + +**pw-config** \[*options*\] paths + +**pw-config** \[*options*\] list \[*SECTION*\] + +**pw-config** \[*options*\] merge *SECTION* + +# DESCRIPTION + +List config paths and config sections and display the parsed output. + +This tool can be used to get an overview of the config file that will be +parsed by the PipeWire server and clients. + +# COMMON OPTIONS + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -n | \--name=NAME +Config Name (default 'pipewire.conf') + +\par -p | \--prefix=PREFIX +Config Prefix (default '') + +\par -L | \--no-newline +Omit newlines after values + +\par -r | \--recurse +Reformat config sections recursively + +\par -N | \--no-colors +Disable color output + +\par -C | \-color\[=WHEN\] +whether to enable color support. WHEN is +*never*, *always*, or *auto* + +# LISTING PATHS + +Specify the paths command. It will display all the config files that +will be parsed and in what order. + +# LISTING CONFIG SECTIONS + +Specify the list command with an optional *SECTION* to list the +configuration fragments used for *SECTION*. Without a *SECTION*, all +sections will be listed. + +Use the -r options to reformat the sections. + +# MERGING A CONFIG SECTION + +With the merge option and a *SECTION*, pw-config will merge all config +files into a merged config section and dump the results. This will be +the section used by the client or server. + +Use the -r options to reformat the sections. + +# EXAMPLES + +\par pw-config +List all config files that will be used + +\par pw-config -n pipewire-pulse.conf +List all config files that will be used by the PipeWire pulseaudio +server. + +\par pw-config -n pipewire-pulse.conf list +List all config sections used by the PipeWire pulseaudio server + +\par pw-config -n jack.conf list context.properties +List the context.properties fragments used by the JACK clients + +\par pw-config -n jack.conf merge context.properties +List the merged context.properties used by the JACK clients + +\par pw-config -n pipewire.conf -r merge context.modules +List the merged context.modules used by the PipeWire server and reformat + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-dump_1 "pw-dump(1)", diff --git a/doc/dox/programs/pw-dot.1.md b/doc/dox/programs/pw-dot.1.md new file mode 100644 index 000000000..ab30c0d81 --- /dev/null +++ b/doc/dox/programs/pw-dot.1.md @@ -0,0 +1,56 @@ +\page page_man_pw-dot_1 pw-dot + +The PipeWire dot graph dump + +# SYNOPSIS + +**pw-dot** \[*options*\] + +# DESCRIPTION + +Create a .dot file of the PipeWire graph. + +The .dot file can then be visualized with a tool like **dotty** or +rendered to a PNG file with `dot -Tpng pw.dot -o pw.png`. + +# OPTIONS + +\par -r | \--remote=NAME +The name the remote instance to connect to. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -a | \--all +Show all object types. + +\par -s | \--smart +Show linked objects only. + +\par -d | \--detail +Show all object properties. + +\par -o FILE | \--output=FILE +Output file name (Default pw.dot). Use - for stdout. + +\par -L | \--lr +Lay the graph from left to right, instead of dot's default top to +bottom. + +\par -9 | \--90 +Lay the graph using 90-degree angles in edges. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-cli_1 "pw-cli(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", diff --git a/doc/dox/programs/pw-dump.1.md b/doc/dox/programs/pw-dump.1.md new file mode 100644 index 000000000..cf507e597 --- /dev/null +++ b/doc/dox/programs/pw-dump.1.md @@ -0,0 +1,43 @@ +\page page_man_pw-dump_1 pw-dump + +The PipeWire state dumper + +# SYNOPSIS + +**pw-dump** \[*options*\] + +# DESCRIPTION + +The *pw-dump* program produces a representation of the current PipeWire +state as JSON, including the information on nodes, devices, modules, +ports, and other objects. + +# OPTIONS + +\par -h | \--help +Show help. + +\par -r | \--remote=NAME +The name of the *remote* instance to dump. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -m | \--monitor +Monitor PipeWire state changes, and output JSON arrays describing +changes. + +\par -N | \--no-colors +Disable color output. + +\par -C | \--color=WHEN +Whether to enable color support. WHEN is `never`, `always`, or `auto`. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-cli_1 "pw-cli(1)", +\ref page_man_pw-top_1 "pw-top(1)", diff --git a/doc/dox/programs/pw-jack.1.md b/doc/dox/programs/pw-jack.1.md new file mode 100644 index 000000000..f043d2130 --- /dev/null +++ b/doc/dox/programs/pw-jack.1.md @@ -0,0 +1,45 @@ +\page page_man_pw-jack_1 pw-jack + +Use PipeWire instead of JACK + +# SYNOPSIS + +**pw-jack** \[*options*\] *COMMAND* \[*FILE*\] + +# DESCRIPTION + +**pw-jack** modifies the `LD_LIBRARY_PATH` environment variable so that +applications will load PipeWire's reimplementation of the JACK client +libraries instead of JACK's own libraries. This results in JACK clients +being redirected to PipeWire. + +If PipeWire's reimplementation of the JACK client libraries has been +installed as a system-wide replacement for JACK's own libraries, then +the whole system already behaves in that way, in which case **pw-jack** +has no practical effect. + +# 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 + +\par pw-jack sndfile-jackplay /usr/share/sounds/freedesktop/stereo/bell.oga + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +**jackd(1)**, diff --git a/doc/dox/programs/pw-link.1.md b/doc/dox/programs/pw-link.1.md new file mode 100644 index 000000000..aff53d600 --- /dev/null +++ b/doc/dox/programs/pw-link.1.md @@ -0,0 +1,135 @@ +\page page_man_pw-link_1 pw-link + +The PipeWire Link Command + +# SYNOPSIS + +**pw-link** \[*options*\] -o-l \[*out-pattern*\] \[*in-pattern*\] + +**pw-link** \[*options*\] *output* *input* + +**pw-link** \[*options*\] -d *output* *input* + +**pw-link** \[*options*\] -d *link-id* + +# DESCRIPTION + +List, create and destroy links between PipeWire ports. + +# COMMON OPTIONS + +\par -r | \--remote=NAME +The name the *remote* instance to monitor. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +# LISTING PORTS AND LINKS + +Specify one of -o, -i or -l to list the matching optional input and +output ports and their links. + +\par -o | \--output +List output ports + +\par -i | \--input +List output ports + +\par -l | \--links +List links + +\par -m | \--monitor +Monitor links and ports. **pw-link** will not exit but monitor and print +new and destroyed ports or links. + +\par -I | \--id +List IDs. Also list the unique link and port ids. + +\par -v | \--verbose +Verbose port properties. Also list the port-object-path and the +port-alias. + +# CONNECTING PORTS + +Without any list option (-i, -o or -l), the given ports will be linked. +Valid port specifications are: + +*port-id* + +As obtained with the -I option when listing ports. + +*node-name:port-name* + +As obtained when listing ports. + +*port-object-path* + +As obtained from the first alternative name for the port when listing +them with the -v option. + +*port-alias* + +As obtained from the second alternative name for the ports when listing +them with the -v option. + +Extra options when linking can be given: + +\par -L | \--linger +Linger. Will create a link that exists after **pw-link** is destroyed. +This is the default behaviour, unless the -m option is given. + +\par -P | \--passive +Passive link. A passive link will keep both nodes it links inactive +unless another non-passive link is activating the nodes. You can use +this to link a sink to a filter and have them both suspended when +nothing else is linked to either of them. + +\par -p | \--props=PROPS +Properties as JSON object. Give extra properties when creaing the link. + +# DISCONNECTING PORTS + +When the -d option is given, an existing link between port is destroyed. + +To disconnect port, a single *link-id*, as obtained when listing links +with the -I option, or two port specifications can be given. See the +connecting ports section for valid port specifications. + +\par -d | \--disconnect +Disconnect ports + +# EXAMPLES + +**pw-link** -iol + +List all port and their links. + +**pw-link** -lm + +List all links and monitor changes until **pw-link** is stopped. + +**pw-link** paplay:output_FL alsa_output.pci-0000_00_1b.0.analog-stereo:playback_FL + +Link the given output port to the input port. + +**pw-link** -lI + +List links and their Id. + +**pw-link** -d 89 + +Destroy the link with id 89. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-cli_1 "pw-cli(1)" diff --git a/doc/dox/programs/pw-loopback.1.md b/doc/dox/programs/pw-loopback.1.md new file mode 100644 index 000000000..98293430b --- /dev/null +++ b/doc/dox/programs/pw-loopback.1.md @@ -0,0 +1,67 @@ +\page page_man_pw-loopback_1 pw-loopback + +PipeWire loopback client + +# SYNOPSIS + +**pw-loopback** \[*options*\] + +# DESCRIPTION + +The *pw-loopback* program is a PipeWire client that uses the PipeWire +loopback module to create loopback nodes, with configuration given via +the command-line options. + +# OPTIONS + +\par -h | \--help +Show help. + +\par -r | \--remote=NAME +The name of the *remote* instance to connect to. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -n | \--name=NAME +Name of the loopback node + +\par -g | \--group=NAME +Name of the loopback node group + +\par -c | \--channels=NUMBER +Number of channels to provide + +\par -m | \--channel-map=MAP +Channel map (default `[ FL, FR ]`) + +\par -l | \--latency=LATENCY +Desired latency in ms + +\par -d | \--delay=DELAY +Added delay in seconds (floating point allowed) + +\par -C | \--capture=TARGET +Target device to capture from + +\par -P | \--playback=TARGET +Target device to play to + +\par \--capture-props=PROPS +Wanted properties of capture node (in JSON) + +\par \--playback-props=PROPS +Wanted properties of capture node (in JSON) + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-cat_1 "pw-cat(1)", +**pactl(1)** + +Other ways to create loopback nodes are adding the loopback module in +the configuration of a PipeWire daemon, or loading the loopback module +using Pulseaudio commands (`pactl load-module module-loopback ...`). diff --git a/doc/dox/programs/pw-metadata.1.md b/doc/dox/programs/pw-metadata.1.md new file mode 100644 index 000000000..77078de1e --- /dev/null +++ b/doc/dox/programs/pw-metadata.1.md @@ -0,0 +1,73 @@ +\page page_man_pw-metadata_1 pw-metadata + +The PipeWire metadata + +# SYNOPSIS + +**pw-metadata** \[*options*\] \[*id* \[*key* \[*value* \[*type* \] \] \] \] + +# DESCRIPTION + +Monitor, set and delete metadata on PipeWire objects. + +Metadata are key/type/value triplets attached to objects identified by +*id*. The metadata is shared between all applications binding to the +same metadata object. When an object is destroyed, all its metadata is +automatically removed. + +When no *value* is given, **pw-metadata** will query and log the +metadata matching the optional arguments *id* and *key*. Without any +arguments, all metadata is displayed. + +When *value* is given, **pw-metadata** will set the metadata for *id* +and *key* to *value* and an optional *type*. + +# OPTIONS + +\par -r | \--remote=NAME +The name the remote instance to use. If left unspecified, a connection +is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -l | \--list +List available metadata objects + +\par -m | \--monitor +Keeps running and log the changes to the metadata. + +\par -d | \--delete +Delete all metadata for *id* or for the specified *key* of object *id*. +Without any option, all metadata is removed. + +\par -n | \--name +Metadata name (Default: "default"). + +# EXAMPLES + +**pw-metadata** + +Show metadata in default name. + +**pw-metadata** -n settings 0 + +Display settings. + +**pw-metadata** -n settings 0 clock.quantum 1024 + +Change clock.quantum to 1024. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-mon_1 "pw-mon(1)", +\ref page_man_pw-cli_1 "pw-cli(1)", diff --git a/doc/dox/programs/pw-mididump.1.md b/doc/dox/programs/pw-mididump.1.md new file mode 100644 index 000000000..83b229f23 --- /dev/null +++ b/doc/dox/programs/pw-mididump.1.md @@ -0,0 +1,38 @@ +\page page_man_pw-mididump_1 pw-mididump + +The PipeWire MIDI dump + +# SYNOPSIS + +**pw-mididump** \[*options*\] \[*FILE*\] + +# DESCRIPTION + +Dump MIDI messages to stdout. + +When a MIDI file is given, the events inside the file are printed. + +When no file is given, **pw-mididump** creates a PipeWire MIDI input +stream and will print all MIDI events received on the port to stdout. + +# OPTIONS + +\par -r | \--remote=NAME +The name the remote instance to monitor. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-cat_1 "pw-cat(1)" diff --git a/doc/dox/programs/pw-mon.1.md b/doc/dox/programs/pw-mon.1.md new file mode 100644 index 000000000..6d9b63928 --- /dev/null +++ b/doc/dox/programs/pw-mon.1.md @@ -0,0 +1,36 @@ +\page page_man_pw-mon_1 pw-mon + +The PipeWire monitor + +# SYNOPSIS + +**pw-mon** \[*options*\] + +# DESCRIPTION + +Monitor objects on the PipeWire instance. + +# OPTIONS + +\par -r | \--remote=NAME +The name the *remote* instance to monitor. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -N | \--color=WHEN +Whether to use color, one of 'never', 'always', or 'auto'. The default +is 'auto'. **-N** is equivalent to **--color=never**. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)" diff --git a/doc/dox/programs/pw-profiler.1.md b/doc/dox/programs/pw-profiler.1.md new file mode 100644 index 000000000..a02e5a219 --- /dev/null +++ b/doc/dox/programs/pw-profiler.1.md @@ -0,0 +1,46 @@ +\page page_man_pw-profiler_1 pw-profiler + +The PipeWire profiler + +# SYNOPSIS + +**pw-profiler** \[*options*\] + +# DESCRIPTION + +Start profiling a PipeWire instance. + +If the server has the profiler module loaded, this program will connect +to it and log the profiler data. Profiler data contains times and +durations when processing nodes and devices started and completed. + +When this program is stopped, a set of **gnuplot** files and a script to +generate SVG files from the .plot files is generated, along with a .html +file to visualize the profiling results in a browser. + +This function uses the same data used by *pw-top*. + +# OPTIONS + +\par -r | \--remote=NAME +The name the remote instance to monitor. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -h | \--help +Show help. + +\par \--version +Show version information. + +\par -o | \--output=FILE +Profiler output name (default "profiler.log"). + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-top_1 "pw-top(1)" diff --git a/doc/dox/programs/pw-top.1.md b/doc/dox/programs/pw-top.1.md new file mode 100644 index 000000000..5460581b7 --- /dev/null +++ b/doc/dox/programs/pw-top.1.md @@ -0,0 +1,207 @@ +\page page_man_pw-top_1 pw-top + +The PipeWire process viewer + +# SYNOPSIS + +**pw-top** \[*options*\] + +# DESCRIPTION + +The *pw-top* program provides a dynamic real-time view of the pipewire +node and device statistics. + +A hierarchical view is shown of Driver nodes and follower nodes. The +Driver nodes are actively using a timer to schedule dataflow in the +followers. The followers of a driver node as shown below their driver +with a + sign in a tree-like representation. + +The columns presented are as follows: + +\par S +\parblock +Node status. + +- E = ERROR +- C = CREATING +- S = SUSPENDED +- I = IDLE +- R = RUNNING +\endparblock + +\par ID +The ID of the pipewire node/device, as found in *pw-dump* and +*pw-cli* + +\par QUANT +\parblock +The current quantum (for drivers) and the suggested quantum for +follower nodes. + +The quantum by itself needs to be divided by the RATE column to +calculate the duration of a scheduling period in fractions of a +second. + +For a QUANT of 1024 and a RATE of 48000, the duration of one period +in the graph is 1024/48000 or 21.3 milliseconds. + +Follower nodes can have a 0 QUANT field, which means that the node +does not have a suggestion for the quantum and thus uses what the +driver selected. + +The driver will use the lowest quantum of any of the followers. If +none of the followers select a quantum, the default quantum in the +pipewire configuration file will be used. + +The QUANT on the drivers usually translates directly into the number +of audio samples processed per processing cycle of the graph. + +See also + +\endparblock + +\par RATE +\parblock +The current rate (for drivers) and the suggested rate for follower +nodes. + +This is the rate at which the *graph* processes data and needs to be +combined with the QUANT value to derive the duration of a processing +cycle in the graph. + +Some nodes can have a 0 RATE, which means that they don\'t have any +rate suggestion for the graph. Nodes that suggest a rate can make +the graph switch rates if the graph is otherwise idle and the new +rate is allowed as a possible graph rate (see the pipewire +configuration file). + +The RATE on (audio) driver nodes usually also translates directly to +the samplerate used by the device. Although some devices might not +be able to operate at the given samplerate, in which case resampling +will need to be done. The negotiated samplerate with the device and +stream can be found in the FORMAT column. + +\endparblock + +\par WAIT +\parblock +The waiting time of a node is the elapsed time between when the node +is ready to start processing and when it actually started +processing. + +For Driver nodes, this is the time between when the node wakes up to +start processing the graph and when the driver (and thus also the +graph) completes a cycle. The WAIT time for driver is thus the +elapsed time processing the graph. + +For follower nodes, it is the time spent between being woken up +(when all dependencies of the node are satisfied) and when +processing starts. The WAIT time for follower nodes is thus mostly +caused by context switching. + +A value of \-\-- means that the node was not signaled. A value of ++++ means that the node was signaled but not awake. +\endparblock + +\par BUSY +\parblock +The processing time is started when the node starts processing until +it completes and wakes up the next nodes in the graph. + +A value of \-\-- means that the node was not started. A value of +++ +means that the node was started but did not complete. +\endparblock + +\par W/Q +\parblock +Ratio of WAIT / QUANT. + +The W/Q time of the driver node is a good measure of the graph load. +The running averages of the driver W/Q ratios are used as the DSP +load in other (JACK) tools. + +Values of \-\-- and +++ are copied from the WAIT column. + +\endparblock + +\par B/Q +\parblock +Ratio of BUSY / QUANT + +This is a good measure of the load of a particular driver or +follower node. + +Values of \-\-- and +++ are copied from the BUSY column. +\endparblock + +\par ERR +\parblock +Total of Xruns and Errors + +Xruns for drivers are when the graph did not complete a cycle. This +can be because a node in the graph also has an Xrun. It can also be +caused when scheduling delays cause a deadline to be missed, causing +a hardware Xrun. + +Xruns for followers are incremented when the node started processing +but did not complete before the end of the graph cycle deadline. +\endparblock + +\par FORMAT +\parblock +The format used by the driver node or the stream. This is the +hardware format negotiated with the device or stream. + +If the stream of driver has a different rate than the graph, +resampling will be done. + +For raw audio formats, the layout is \ \ +\. + +For IEC958 passthrough audio formats, the layout is IEC958 \ +\. + +For DSD formats, the layout is \ \. + +For Video formats, the layout is \ +\x\. +\endparblock + +\par NAME +\parblock +Name assigned to the device/node, as found in *pw-dump* node.name + +Names are prefixed by *+* when they are linked to a driver (entry +above with no +) +\endparblock + + +# OPTIONS + +\par -h | \--help +Show help. + +\par -b | \--batch-mode +Run in non-interactive batch mode, similar to top\'s batch mode. + +\par -n | \--iterations=NUMBER +Exit after NUMBER of batch iterations. Only used in batch mode. + +\par -r | \--remote=NAME +The name the *remote* instance to monitor. If left unspecified, a +connection is made to the default PipeWire instance. + +\par -V | \--version +Show version information. + +# AUTHORS + +The PipeWire Developers <$(PACKAGE_BUGREPORT)>; +PipeWire is available from <$(PACKAGE_URL)> + +# SEE ALSO + +\ref page_man_pipewire_1 "pipewire(1)", +\ref page_man_pw-dump_1 "pw-dump(1)", +\ref page_man_pw-cli_1 "pw-cli(1)", +\ref page_man_pw-profiler_1 "pw-profiler(1)" diff --git a/doc/input-filter.py b/doc/input-filter.py index f4c223b9c..2b64a2d65 100755 --- a/doc/input-filter.py +++ b/doc/input-filter.py @@ -18,27 +18,32 @@ import os def main(): - with open(sys.argv[1], "r") as f: + fn = sys.argv[1] + with open(fn, "r") as f: text = f.read() text = re.sub("#define.*", "", text) - m = re.search( - r"static const char[* ]*const pulse_module_options\s+=\s+(.*?\")\s*;\s*$", - text, - re.M | re.S, - ) - if m: - res = [] - for line in m.group(1).splitlines(): - m = re.match(r"\s*\"\s*([a-z0-9_]+)\s*=\s*(.*)\"\s*$", line) - if m: - name = m.group(1) - value = m.group(2).strip().strip("<>") - res.append(f"- `{name}`: {value}") + if "@pulse_module_options@" in text: + m = re.search( + r"static const char[* ]*const pulse_module_options\s+=\s+(.*?\")\s*;\s*$", + text, + re.M | re.S, + ) + if m: + res = [] + for line in m.group(1).splitlines(): + m = re.match(r"\s*\"\s*([a-z0-9_]+)\s*=\s*(.*)\"\s*$", line) + if m: + name = m.group(1) + value = m.group(2).strip().strip("<>") + res.append(f"- `{name}`: {value}") - res = "\n * ".join(res) - text = text.replace("@pulse_module_options@", res) + res = "\n * ".join(res) + text = text.replace("@pulse_module_options@", res) + + if os.path.basename(fn).startswith("module-") and fn.endswith(".c"): + text = re.sub(r"^ \* ##", r" * #", text, flags=re.M) print("/** \\privatesection */") print(text) diff --git a/doc/man-fixup.py b/doc/man-fixup.py new file mode 100755 index 000000000..758aa855e --- /dev/null +++ b/doc/man-fixup.py @@ -0,0 +1,97 @@ +#!/usr/bin/python3 +# -*- mode: python; coding: utf-8; eval: (blacken-mode); -*- +r""" +Fetch right Doxygen man file, replace dummy parts, and fixup nroff +""" +import argparse +import re +import sys +from subprocess import call +from pathlib import Path + + +def main(): + p = argparse.ArgumentParser(description=__doc__.strip()) + p.add_argument("htmldir", type=Path) + p.add_argument("page") + p.add_argument("name") + p.add_argument("section") + p.add_argument("version") + args = p.parse_args() + + page, name, section, version = args.page, args.name, args.section, args.version + + mandir = args.htmldir / ".." / "man" / "man3" + fn = mandir / f"{page}.3" + + # Doxygen < 1.9.7 names .md file output differently... + if not fn.exists(): + page2 = page.replace("page_man_", "md_doc_dox_programs_").replace("-", "_") + fn = mandir / f"{page2}.3" + else: + page2 = None + + try: + with open(fn, "r") as f: + text = f.read() + except: + print(f"ERROR: man file {fn} missing!", file=sys.stderr) + call(["ls", "-R", str(args.htmldir / ".." / "man")], stdout=sys.stderr) + raise + + text = text.replace(page, name) + if page2 is not None: + text = text.replace(page2, name) + + # Replace bad nroff header + text = re.sub( + r"^(\.TH[^\n]*)\n", + rf'.TH "{name}" {section} "{version}" "PipeWire" \\" -*- nroff -*-\n', + text, + ) + + # Fixup name field (can't be done in Doxygen, otherwise HTML looks bac) + text = re.sub( + rf"^\.SH NAME\s*\n{name} \\- {name}\s*\n\.PP\n *", + rf".SH NAME\n{name} \\- ", + text, + count=1, + flags=re.M, + ) + + # Add DESCRIPTION section if missing and NAME field has extra stuff + if not re.search(r"^\.SH DESCRIPTION\s*\n", text): + text = re.sub( + r"^(.SH NAME\s*\n[^\.].*\n)\.PP\s*\n([^\.\n ]+)", + r"\1.SH DESCRIPTION\n.PP\n\2", + text, + count=1, + flags=re.M, + ) + + # Upcase titles + def upcase(m): + return m.group(0).upper() + + text = re.sub(r"^\.SH .*?$", upcase, text, flags=re.M) + + # Replace PW_KEY_*, SPA_KEY_* by their values + def pw_key(m): + key = m.group(0) + key = key.replace("PW_KEY_", "").lower().replace("_", ".") + if key in ("protocol", "access", "client.access") or key.startswith("sec."): + return f"pipewire.{key}" + return key + + def spa_key(m): + key = m.group(0) + return key.replace("SPA_KEY_", "").lower().replace("_", ".") + + text = re.sub(r"PW_KEY_[A-Z_]+", pw_key, text, flags=re.S) + text = re.sub(r"SPA_KEY_[A-Z_]+", spa_key, text, flags=re.S) + + print(text) + + +if __name__ == "__main__": + main() diff --git a/doc/manpage.dox.in b/doc/manpage.dox.in deleted file mode 100644 index 3a92f6fbe..000000000 --- a/doc/manpage.dox.in +++ /dev/null @@ -1,7 +0,0 @@ -/** \page @pagename@ @title@ - -\brief Manual page for @title@ - -\verbinclude @filename@ - -*/ diff --git a/doc/meson.build b/doc/meson.build index efe63308b..c2949d6b1 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -1,3 +1,5 @@ +fs = import('fs') + doxyfile_conf = configuration_data() doxyfile_conf.set('PACKAGE_NAME', meson.project_name()) doxyfile_conf.set('PACKAGE_VERSION', meson.project_version()) @@ -5,6 +7,14 @@ doxyfile_conf.set('top_srcdir', meson.project_source_root()) doxyfile_conf.set('top_builddir', meson.project_build_root()) doxyfile_conf.set('output_directory', meson.current_build_dir()) +doxygen_env = environment() +doxygen_env.set('PACKAGE_NAME', meson.project_name()) +doxygen_env.set('PACKAGE_VERSION', meson.project_version()) +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) + dot_found = find_program('dot', required: false).found() summary({'dot (used with doxygen)': dot_found}, bool_yn: true, section: 'Optional programs') if dot_found @@ -21,6 +31,7 @@ extra_docs = [ 'dox/overview.dox', 'dox/modules.dox', 'dox/pulse-modules.dox', + 'dox/programs/index.md', 'dox/internals/index.dox', 'dox/internals/design.dox', 'dox/internals/access.dox', @@ -50,6 +61,37 @@ extra_docs = [ 'dox/api/spa-buffer.dox', ] +manpage_docs = [ + 'dox/programs/libpipewire-modules.7.md', + 'dox/programs/pipewire-pulse-modules.7.md', + 'dox/programs/pipewire-pulse.1.md', + 'dox/programs/pipewire-pulse.conf.5.md', + 'dox/programs/pipewire.1.md', + 'dox/programs/pipewire.conf.5.md', + 'dox/programs/pw-cat.1.md', + 'dox/programs/pw-cli.1.md', + 'dox/programs/pw-config.1.md', + 'dox/programs/pw-dot.1.md', + 'dox/programs/pw-dump.1.md', + 'dox/programs/pw-jack.1.md', + 'dox/programs/pw-link.1.md', + 'dox/programs/pw-loopback.1.md', + 'dox/programs/pw-metadata.1.md', + 'dox/programs/pw-mididump.1.md', + 'dox/programs/pw-mon.1.md', + 'dox/programs/pw-profiler.1.md', + 'dox/programs/pw-top.1.md', +] + +manpages = [] + +foreach m : manpage_docs + name = fs.stem(fs.name(m)) + pagepart = name.replace('.', '_') + manpages += [[name, f'page_man_@pagepart@']] + extra_docs += m +endforeach + inputs = [] foreach extra : extra_docs inputs += meson.project_source_root() / 'doc' / extra @@ -120,29 +162,27 @@ examples_dox = configure_file(input: 'examples.dox.in', input_dirs += [ 'doc/examples.dox' ] -man_doxygen = [] -man_subpages = [] -foreach m : manpages - manconf = configuration_data() - pagename = 'page_man_' + m.split('.rst.in').get(0).replace('.', '_').replace('-', '_') - filename = m.split('.rst.in').get(0) + '.dox' - manconf.set('pagename', pagename) - manconf.set('title', m.split('.rst.in').get(0).replace('.1','').replace('.5','')) - manconf.set('filename', meson.project_source_root() / 'man' / m) - manfile = configure_file(input: 'manpage.dox.in', - output: filename, - configuration: manconf) - man_doxygen += [manfile] - man_subpages += ['- \subpage ' + pagename] - input_dirs += [ 'doc/' + filename ] +module_manpage_list = [] +foreach m : module_sources + name = fs.stem(m) + pagepart = name.replace('-', '_') + module_manpage_list += f'\\ref page_@pagepart@ "libpipewire-@name@(7)"' + manpages += [[f'libpipewire-@name@.7', f'page_@pagepart@']] endforeach -pw_programs_dox_conf = configuration_data() -pw_programs_dox_conf.set('man_subpages', '\n'.join(man_subpages)) -pw_programs_dox = configure_file(input: 'programs.dox.in', - output: 'programs.dox', - configuration: pw_programs_dox_conf) -input_dirs += [ 'doc/programs.dox' ] +doxygen_env.set('LIBPIPEWIRE_MODULES', '
  • ' + '
  • '.join(module_manpage_list) + '
') + +pulse_module_manpage_list = [] +foreach m : pipewire_module_protocol_pulse_sources + name = fs.stem(fs.name(m)) + if m.contains('/modules/') and name.startswith('module-') + pagepart = name.replace('-', '_') + pulse_module_manpage_list += f'\\ref page_pulse_@pagepart@ "pipewire-pulse-@name@(7)"' + manpages += [[f'pipewire-pulse-@name@.7', f'page_pulse_@pagepart@']] + endif +endforeach + +doxygen_env.set('PIPEWIRE_PULSE_MODULES', '
  • ' + '
  • '.join(pulse_module_manpage_list) + '
') doxygen_layout = meson.project_source_root() / 'doc' / 'DoxygenLayout.xml' doxygen_filter_c = meson.project_source_root() / 'doc' / 'input-filter.py' @@ -165,53 +205,31 @@ if docdir == '' endif html_target = custom_target('pipewire-docs', - input: [ doxyfile, doxygen_layout, examples_dox, pw_programs_dox, doxygen_filter_c, doxygen_filter_h ] + inputs + cssfiles + man_doxygen, + input: [ doxyfile, doxygen_layout, examples_dox, doxygen_filter_c, doxygen_filter_h ] + inputs + cssfiles, output: [ 'html' ], command: [ doxygen, doxyfile ], + env: doxygen_env, install: true, install_dir: docdir) -if generate_extra_manpages - module_man_rst_py = meson.project_source_root() / 'doc' / 'module-man-rst.py' - module_man_defines = [] - foreach m : manpage_conf.keys() - if m != 'LIBPIPEWIRE_MODULES' - module_man_defines += ['-D', m, manpage_conf.get(m)] - endif - endforeach +man_fixup = files('man-fixup.py') - module_manpage_names = [] - foreach m : module_sources - name = m.split('.c').get(0) - file = f'libpipewire-@name@.7' - module_manpage_names += [[name, file]] - endforeach - foreach m : pipewire_module_protocol_pulse_sources - name = m.split('/').get(-1).split('.c').get(0) - if m.contains('/modules/') and name.startswith('module-') - name = f'pulse-@name@' - file = f'pipewire-@name@.7' - module_manpage_names += [[name, file]] - endif - endforeach +manfiles = [] - foreach item : module_manpage_names - name = item.get(0) - file = item.get(1) +foreach m : manpages + file = m.get(0) + page = m.get(1) + name = fs.stem(file) + section = file.split('.').get(-1) - rst = custom_target(file + '.rst', - command : [python, module_man_rst_py, pandoc, name, '@INPUT@' ] + module_man_defines, - input : [ html_target ], - depend_files : [ module_man_rst_py ], - output : file + '.rst', - capture : true - ) - custom_target(file, - output : file, - input : rst, - command : [rst2man, '@INPUT@', '@OUTPUT@'], - install : true, - install_dir : get_option('mandir') / 'man7') - endforeach -endif + manfiles += custom_target(file, + command : [ python, man_fixup, '@INPUT@', page, name, section, meson.project_version() ], + output : file, + input : html_target, + depend_files : [ man_fixup ], + capture : true, + install : true, + install_dir : get_option('mandir') / 'man' + section + ) +endforeach diff --git a/doc/module-man-rst.py b/doc/module-man-rst.py deleted file mode 100644 index c4a84594d..000000000 --- a/doc/module-man-rst.py +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/python3 -# -*- mode: python; coding: utf-8; eval: (blacken-mode); -*- -""" -Convert Doxygen HTML documentation for a PipeWire module to RST. -""" -import argparse -import html, html.parser -import re -from pathlib import Path -from subprocess import check_output - -TEMPLATE = """ -{name} -{name_underline} - -{subtitle_underline} -{subtitle} -{subtitle_underline} - -:Manual section: 7 -:Manual group: PipeWire - -DESCRIPTION ------------ - -{content} - -AUTHORS -------- - -The PipeWire Developers <{PACKAGE_BUGREPORT}>; -PipeWire is available from {PACKAGE_URL} - -SEE ALSO --------- - -{seealso} -""" - - -def main(): - p = argparse.ArgumentParser(description=__doc__.strip()) - p.add_argument( - "-D", - "--define", - nargs=2, - action="append", - dest="define", - default=[], - ) - p.add_argument("pandoc") - p.add_argument("module") - p.add_argument("htmldir", type=Path) - args = p.parse_args() - - page = args.module.lower().replace("-", "_") - src = args.htmldir / f"page_{page}.html" - - # Pick content block only - parser = DoxyParser() - with open(src, "r") as f: - parser.feed(f.read()) - data = "".join(parser.content) - - # Produce output - content = check_output( - [args.pandoc, "-f", "html", "-t", "rst"], input=data, encoding="utf-8" - ) - - if not content.strip() or content.lower().startswith("module name\n-----"): - content = "Undocumented.\n\n" + content - - if args.module.startswith("pulse-"): - name = re.sub(r"^pulse-module-", "module-", args.module) - seealso = "``pipewire-pulse(1)``, ``pipewire-pulse-modules(7)``" - subtitle = "PipeWire Pulseaudio module" - else: - name = f"libpipewire-{args.module}" - seealso = "``pipewire(1)``, ``pipewire.conf(5)``, ``libpipewire-modules(7)``" - subtitle = "PipeWire module" - - env = dict( - content=content, - name=name, - name_underline="#" * len(name), - subtitle=subtitle, - subtitle_underline="-" * len(subtitle), - seealso=seealso, - ) - - for k, v in args.define: - env[k] = v - - print(TEMPLATE.format(**env)) - - -def replace_pw_key(key): - key = key.lower().replace("_", ".") - if key in ("protocol", "access", "client.access") or key.startswith("sec."): - return f"pipewire.{key}" - return key - - -class DoxyParser(html.parser.HTMLParser): - """ - Capture div.textblock, and: - - Convert div.fragment to pre - - Convert a[@href="page_module_XXX.html"] to libpipewire-module-xxx(7) - """ - - def __init__(self): - super().__init__() - self.content = [] - self.stack = [] - - def feed(self, data): - try: - super().feed(data) - except EOFError: - pass - - def handle_starttag(self, tag, attrs): - attrs = dict(attrs) - - if self.stack: - if self.stack[-1] is None: - self.stack.append(None) - return - - if tag == "div" and attrs.get("class") == "fragment": - tag = "pre" - attrs = dict() - elif tag == "a" and attrs.get("href").startswith("page_module_"): - module = attrs["href"].replace("page_module_", "libpipewire-module-") - module = module.replace(".html", "").replace("_", "-") - self.content.append(f"{module}(7)") - self.stack.append(None) - return - - attrstr = " ".join(f'{k}="{html.escape(v)}"' for k, v in attrs.items()) - self.content.append(f"<{tag} {attrstr}>") - self.stack.append(tag) - elif tag == "div" and attrs.get("class") == "textblock": - self.stack.append(tag) - - def handle_endtag(self, tag): - if len(self.stack) == 1: - raise EOFError() - elif self.stack: - otag = self.stack.pop() - if otag is not None: - self.content.append(f"") - - def handle_data(self, data): - if self.stack and self.stack[-1] is not None: - if self.stack[-1] == "a": - m = re.match(r"^(PW|SPA)_KEY_([A-Z_]+)$", data) - if m: - data = replace_pw_key(m.group(2)) - - self.content.append(html.escape(data)) - - -if __name__ == "__main__": - main() diff --git a/doc/programs.dox.in b/doc/programs.dox.in deleted file mode 100644 index 1320abf0f..000000000 --- a/doc/programs.dox.in +++ /dev/null @@ -1,7 +0,0 @@ -/** \page page_programs Programs - -Manual pages: - -@man_subpages@ - -*/ diff --git a/man/meson.build b/man/meson.build deleted file mode 100644 index 5ea191e66..000000000 --- a/man/meson.build +++ /dev/null @@ -1,68 +0,0 @@ -manpage_conf = configuration_data() -manpage_conf.set('PACKAGE_NAME', meson.project_name()) -manpage_conf.set('PACKAGE_VERSION', meson.project_version()) -manpage_conf.set('PACKAGE_URL', 'https://pipewire.org') -manpage_conf.set('PACKAGE_BUGREPORT', 'https://gitlab.freedesktop.org/pipewire/pipewire/issues') -manpage_conf.set('PIPEWIRE_CONFIG_DIR', pipewire_configdir) -manpage_conf.set('PIPEWIRE_CONFDATADIR', pipewire_confdatadir) - -module_manpage_list = [] -foreach m : module_sources - name = m.split('.c').get(0) - module_manpage_list += f'``libpipewire-' + name + '(7)``' -endforeach - -manpage_conf.set('LIBPIPEWIRE_MODULES', '\n- '.join(module_manpage_list)) - -pulse_module_manpage_list = [] -foreach m : pipewire_module_protocol_pulse_sources - name = m.split('/').get(-1).split('.c').get(0) - if m.contains('/modules/') and name.startswith('module-') - pulse_module_manpage_list += f'``pipewire-pulse-@name@(7)``' - endif -endforeach - -manpage_conf.set('PIPEWIRE_PULSE_MODULES', '\n- '.join(pulse_module_manpage_list)) - -manpages = [ - 'pipewire.1.rst.in', - 'pipewire-pulse.1.rst.in', - 'pipewire.conf.5.rst.in', - 'pipewire-pulse.conf.5.rst.in', - 'pw-cat.1.rst.in', - 'pw-cli.1.rst.in', - 'pw-config.1.rst.in', - 'pw-dot.1.rst.in', - 'pw-dump.1.rst.in', - 'pw-link.1.rst.in', - 'pw-loopback.1.rst.in', - 'pw-metadata.1.rst.in', - 'pw-mididump.1.rst.in', - 'pw-mon.1.rst.in', - 'pw-profiler.1.rst.in', - 'pw-top.1.rst.in', - 'libpipewire-modules.7.rst.in', - 'pipewire-pulse-modules.7.rst.in', -] - -if get_option('pipewire-jack').allowed() - manpages += 'pw-jack.1.rst.in' -endif - -if not generate_manpages - subdir_done() -endif - -foreach m : manpages - file = m.split('.rst.in').get(0) - rst = configure_file(input : m, - output : file + '.rst', - configuration : manpage_conf) - section = file.split('.').get(-1) - custom_target(file + '.target', - output : file, - input : rst, - command : [rst2man, '@INPUT@', '@OUTPUT@'], - install : true, - install_dir : get_option('mandir') / 'man' + section) -endforeach diff --git a/man/pipewire-pulse-modules.7.rst.in b/man/pipewire-pulse-modules.7.rst.in deleted file mode 100644 index 5093684b3..000000000 --- a/man/pipewire-pulse-modules.7.rst.in +++ /dev/null @@ -1,43 +0,0 @@ -pipewire-pulse-modules -###################### - ---------------------------- -PipeWire Pulseaudio modules ---------------------------- - -:Manual section: 7 -:Manual group: PipeWire - -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. - -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 -============= - -- @PIPEWIRE_PULSE_MODULES@ - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire-pulse(1)``, diff --git a/man/pipewire-pulse.1.rst.in b/man/pipewire-pulse.1.rst.in deleted file mode 100644 index 43768b06a..000000000 --- a/man/pipewire-pulse.1.rst.in +++ /dev/null @@ -1,50 +0,0 @@ -pipewire-pulse -############## - ------------------------------------ -The PipeWire PulseAudio replacement ------------------------------------ - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pipewire-pulse** [*options*] - -DESCRIPTION -=========== - -**pipewire-pulse** starts a PulseAudio-compatible daemon that integrates with -the PipeWire media server, by running a pipewire process through a systemd -service. This daemon is a drop-in replacement for the PulseAudio daemon. - -OPTIONS -======= - --h | --help - Show help. - --v | --verbose - Increase the verbosity by one level. This option may be specified multiple - times. - ---version - Show version information. - --c | --config=FILE - Load the given config file (Default: pipewire-pulse.conf). - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; -PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire-pulse.conf(5)``, -``pipewire(1)``, -``pipewire-pulse-modules(7)`` diff --git a/man/pipewire-pulse.conf.5.rst.in b/man/pipewire-pulse.conf.5.rst.in deleted file mode 100644 index 73f571268..000000000 --- a/man/pipewire-pulse.conf.5.rst.in +++ /dev/null @@ -1,66 +0,0 @@ -pipewire-pulse.conf -################### - -------------------------------------------------- -The PipeWire Pulseaudio server configuration file -------------------------------------------------- - -:Manual section: 5 -:Manual group: File Formats Manual - -.. _synopsis: - -SYNOPSIS -======== - -*$XDG_CONFIG_HOME/pipewire/pipewire-pulse.conf* - -*@PIPEWIRE_CONFIG_DIR@/pipewire-pulse.conf* - -*@PIPEWIRE_CONFDATADIR@/pipewire-pulse.conf* - -*@PIPEWIRE_CONFDATADIR@/pipewire-pulse.conf.d/* - -*@PIPEWIRE_CONFIG_DIR@/pipewire-pulse.conf.d/* - -*$XDG_CONFIG_HOME/pipewire/pipewire-pulse.conf.d/* - -DESCRIPTION -=========== - -Configuration for PipeWire's PulseAudio-compatible daemon. - -The configuration file format is the same as for ``pipewire.conf(5)``. -There are additional sections for configuring ``pipewire-pulse(1)`` -settings. - - -CONFIGURATION FILE SECTIONS -=========================== - -pulse.properties - Dictionary. These properties configure the PipeWire Pulseaudio server properties. - -pulse.cmd - Array of dictionaries. A set of commands to be executed on startup. - -pulse.rules - Array of dictionaries. A set of match rules and actions to apply to clients. - -See ``libpipewire-module-protocol-pulse(7)`` for the detailed description. - -In addition, the general PipeWire daemon configuration sections apply, -see ``pipewire.conf(5)``. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``libpipewire-module-protocol-pulse(7)``, -``pipewire.conf(5)``, -``pipewire-pulse(1)``, -``pipewire-pulse-modules(7)``, diff --git a/man/pipewire.1.rst.in b/man/pipewire.1.rst.in deleted file mode 100644 index 8f5aebd04..000000000 --- a/man/pipewire.1.rst.in +++ /dev/null @@ -1,55 +0,0 @@ -pipewire -######## - -------------------------- -The PipeWire media server -------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pipewire** [*options*] - -DESCRIPTION -=========== - -PipeWire is a service that facilitates sharing of multimedia content -between devices and applications. - -The **pipewire** daemon reads a config file that is further documented in -``pipewire.conf(5)`` manual page. - -OPTIONS -======= - --h | --help - Show help. - --v | --verbose - Increase the verbosity by one level. This option may be specified multiple - times. - ---version - Show version information. - --c | --config=FILE - Load the given config file (Default: pipewire.conf). - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; -PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pw-top(1)``, -``pw-dump(1)``, -``pw-mon(1)``, -``pw-cat(1)``, -``pw-cli(1)``, -``libpipewire-modules(7)``, diff --git a/man/pipewire.conf.5.rst.in b/man/pipewire.conf.5.rst.in deleted file mode 100644 index d5d39c258..000000000 --- a/man/pipewire.conf.5.rst.in +++ /dev/null @@ -1,113 +0,0 @@ -pipewire.conf -############# - --------------------------------------- -The PipeWire server configuration file --------------------------------------- - -:Manual section: 5 -:Manual group: File Formats Manual - -.. _synopsis: - -SYNOPSIS -======== - -*$XDG_CONFIG_HOME/pipewire/pipewire.conf* - -*@PIPEWIRE_CONFIG_DIR@/pipewire.conf* - -*@PIPEWIRE_CONFDATADIR@/pipewire.conf* - -*@PIPEWIRE_CONFDATADIR@/pipewire.conf.d/* - -*@PIPEWIRE_CONFIG_DIR@/pipewire.conf.d/* - -*$XDG_CONFIG_HOME/pipewire/pipewire.conf.d/* - -DESCRIPTION -=========== - -PipeWire is a service that facilitates sharing of multimedia content -between devices and applications. - -On startup, the daemon reads a main configuration file to configure -itself. It executes a series of commands listed in the config -file. - -The config files are loaded in the order listed in the SYNOPSIS_. -The environment variables ``PIPEWIRE_CONFIG_DIR``, ``PIPEWIRE_CONFIG_PREFIX`` -and ``PIPEWIRE_CONFIG_NAME`` can be used to specify an alternative config -directory, subdirectory and file respectively. - -Next to the configuration file can be a directory with the same name as -the file with a ``.d/`` suffix. All directories in the SYNOPSIS_ directory -search paths are traversed in the listed order and the contents of the -``*.conf`` files inside them are appended to the main configuration file -as overrides. Object sections are merged and array sections are appended. - - -CONFIGURATION FILE FORMAT -========================= - -The configuration file format is grouped into sections. A section -is either a dictionary, {}, or an array, []. Dictionary and array -entries are separated by whitespace and may be simple value -assignment, an array or a dictionary. For example: - -name = value # simple assignment - -name = { key1 = value1 key2 = value2 } # a dictionary with two -entries - -name = [ value1 value2 ] # an array with two entries - -name = [ { k = v1 } { k = v2 } ] # an array of dictionaries - - -The configuration files can be expressed in full JSON syntax but for ease -of use, a relaxed format may be used where: - - * ``:`` to delimit keys and values can be substuted by ``=`` or a space. - * ``"`` around keys and string can be omitted as long as no special characters are used in the strings. - * ``,`` to separate objects can be replaced with a whitespace character. - * ``#`` can be used to start a comment until the line end - - -CONFIGURATION FILE SECTIONS -=========================== - -context.properties - Dictionary. These properties configure the PipeWire instance. - -context.spa-libs - Dictionary. Maps plugin features with globs to a spa library. - -context.modules - Array of dictionaries. Each entry in the array is a dictionary with the *name* of the module to load, - including optional *args* and *flags*. Most modules support being loaded - multiple times. - -context.objects - Array of dictionaries. Each entry in the array is a dictionary containing the *factory* to create an - object from and optional extra arguments specific to that factory. - -context.exec - Array of dictionaries. Each entry in the array is dictionary containing the *path* of a program to - execute on startup and optional *args*. - - This array used to contain an entry to start the session manager but this mode - of operation has since been demoted to development aid. Avoid starting a - session manager in this way in production environment. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-mon(1)``, -``libpipewire-modules(7)``, diff --git a/man/pw-cat.1.rst.in b/man/pw-cat.1.rst.in deleted file mode 100644 index 87d4ab6c5..000000000 --- a/man/pw-cat.1.rst.in +++ /dev/null @@ -1,176 +0,0 @@ -pw-cat -###### - ------------------------------------ -Play and record media with PipeWire ------------------------------------ - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-cat** [*options*] [*FILE* \| -] -| **pw-play** [*options*] [*FILE* \| -] -| **pw-record** [*options*] [*FILE* \| -] -| **pw-midiplay** [*options*] [*FILE* \| -] -| **pw-midirecord** [*options*] [*FILE* \| -] -| **pw-dsdplay** [*options*] [*FILE* \| -] - -DESCRIPTION -=========== - -**pw-cat** is a simple tool for playing back or -capturing raw or encoded media files on a PipeWire -server. It understands all audio file formats supported by -``libsndfile`` for PCM capture and playback. When capturing PCM, the filename -extension is used to guess the file format with the WAV file format as -the default. - -It understands standard MIDI files for playback and recording. This tool -will not render MIDI files, it will simply make the MIDI events available -to the graph. You need a MIDI renderer such as qsynth, timidity or a hardware -MIDI rendered to hear the MIDI. - -DSD playback is supported with the DSF file format. This tool will only work -with native DSD capable hardware and will produce an error when no such -hardware was found. - -When the *FILE* is - input and output will be raw data from STDIN and -STDOUT respectively. - -OPTIONS -======= - --h | --help - Show help. - ---version - Show version information. - --v | --verbose - Verbose operation. - --R | --remote=NAME - The name the *remote* instance to connect to. If left unspecified, - a connection is made to the default PipeWire instance. - --p | --playback - Playback mode. Read data from the specified file, and play it back. If the tool - is called under the name **pw-play** or **pw-midiplay** this is the default. - --r | --record - Recording mode. Capture data and write it to the specified file. If the tool is - called under the name **pw-record** or **pw-midirecord** this is the default. - --m | --midi - MIDI mode. *FILE* is a MIDI file. If the tool is called under the name - **pw-midiplay** or **pw-midirecord** this is the default. - Note that this program will *not* render the MIDI events into audible samples, - it will simply provide the MIDI events in the graph. You need a separate - MIDI renderer such as qsynth, timidity or a hardware renderer to hear the MIDI. - --d | --dsd - DSD mode. *FILE* is a DSF file. If the tool is called under the name - **pw-dsdplay** this is the default. - Note that this program will *not* render the DSD audio. You need a DSD capable - device to play DSD content or this program will exit with an error. - ---media-type=VALUE - Set the media type property (default Audio/Midi depending on mode). - The media type is used by the session manager to select a suitable target - to link to. - ---media-category=VALUE - Set the media category property (default Playback/Capture depending on mode). - The media type is used by the session manager to select a suitable target - to link to. - ---media-role=VALUE - Set the media role property (default Music). - The media type is used by the session manager to select a suitable target - to link to. - ---target=VALUE - Set a node target (default auto). The value can be: - - auto - Automatically select (Default) - - 0 - Don't try to link this node - - - The object.serial or the node.name of a target node - ---latency=VALUE[*units*] - Set the node latency (default 100ms) - - The latency determines the minimum amount of time it takes - for a sample to travel from application to device (playback) and - from device to application (capture). - - The latency determines the size of the buffers that the - application will be able to fill. Lower latency means smaller - buffers but higher overhead. Higher latency means larger buffers - and lower overhead. - - Units can be **s** for seconds, **ms** for milliseconds, - **us** for microseconds, **ns** for nanoseconds. - If no units are given, the latency value is samples with the samplerate - of the file. - --P | --properties=VALUE - Set extra stream properties as a JSON object. - --q | --quality=VALUE - Resampler quality. When the samplerate of the source or - destination file does not match the samplerate of the server, the - data will be resampled. Higher quality uses more CPU. Values between 0 and 15 are - allowed, the default quality is 4. - ---rate=VALUE - The sample rate, default 48000. - ---channels=VALUE - The number of channels, default 2. - ---channel-map=VALUE - The channelmap. Possible values include: - **mono**, **stereo**, **surround-21**, - **quad**, **surround-22**, **surround-40**, - **surround-31**, **surround-41**, - **surround-50**, **surround-51**, - **surround-51r**, **surround-70**, - **surround-71** or a comma separated list of channel names: - **FL**, **FR**, **FC**, **LFE**, - **SL**, **SR**, **FLC**, **FRC**, - **RC**, **RL**, **RR**, **TC**, - **TFL**, **TFC**, **TFR**, **TRL**, - **TRC**, **TRR**, **RLC**, **RRC**, - **FLW**, **FRW**, **LFE2**, **FLH**, - **FCH**, **FRH**, **TFLC**, **TFRC**, - **TSL**, **TSR**, **LLFR**, **RLFE**, - **BC**, **BLC**, **BRC** - ---format=VALUE - The sample format to use. One of: - **u8**, **s8**, **s16** (default), **s24**, **s32**, - **f32**, **f64**. - ---volume=VALUE - The stream volume, default 1.000. - Depending on the locale you have configured, "," or "." may be - used as a decimal separator. Check with **locale** command. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``PipeWire(1)``, -``pw-mon(1)``, diff --git a/man/pw-cli.1.rst.in b/man/pw-cli.1.rst.in deleted file mode 100644 index 31a5acb9e..000000000 --- a/man/pw-cli.1.rst.in +++ /dev/null @@ -1,195 +0,0 @@ -pw-cli -###### - ------------------------------------ -The PipeWire Command Line Interface ------------------------------------ - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-cli** [*command*] - -DESCRIPTION -=========== - -Interact with a PipeWire instance. - -When a command is given, **pw-cli** -will execute the command and exit - -When no command is given, **pw-cli** -starts an interactive session with the default PipeWire instance -*pipewire-0*. - -Connections to other, remote instances can be made. The current instance -name is displayed at the prompt. - -Note that **pw-cli** also creates a local PipeWire instance. Some commands -operate on the current (remote) instance and some on the local instance, such -as module loading. - -Use the 'help' command to list the available commands. - -GENERAL COMMANDS -================ - -help | h - Show a quick help on the commands available. It also lists the aliases - for many commands. - -quit | q - Exit from **pw-cli** - -MODULE MANAGEMENT -================= - -| Modules are loaded and unloaded in the local instance, thus the pw-cli -| binary itself and can add functionality or objects to the local -| instance. It is not possible in PipeWire to load modules in another -| instance. - -load-module *name* [*arguments...*] - Load a module specified by its name and arguments in the local instance. - For most modules it is OK to be loaded more than once. - - This command returns a module variable that can be used - to unload the module. - - The locally module is *not* visible in the remote instance. It is not - possible in PipeWire to load modules in a remote instance. - -unload-module *module-var* - Unload a module, specified either by its variable. - -OBJECT INTROSPECTION -==================== - -list-objects - List the objects of the current instance. - - Objects are listed with their *id*, *type* and *version*. - -info *id* | *all* - Get information about a specific object or *all* objects. - - Requesting info about an object will also notify you of changes. - -WORKING WITH REMOTES -==================== - -connect [*remote-name*] - Connect to a remote instance and make this the new current - instance. - - If no remote name is specified, a connection is made to - the default remote instance, usually *pipewire-0*. - - The special remote name called *internal* can be used to connect to - the local **pw-cli** PipeWire instance. - - This command returns a remote var that can be used to disconnect or - switch remotes. - -disconnect [*remote-var*] - Disconnect from a *remote instance*. - - If no remote name is specified, the current instance is disconnected. - -list-remotes - List all *remote instances*. - -switch-remote [*remote-var*] - Make the specified *remote* the current instance. - - If no remote name is specified, the first instance is made current. - -NODE MANAGEMENT -=============== - -create-node *factory-name* [*properties...*] - Create a node from a factory in the current instance. - - Properties are key=value pairs separated by whitespace. - - This command returns a *node variable*. - -export-node *node-id* [*remote-var*] - Export a node from the local instance to the specified instance. - When no instance is specified, the node will be exported to the current - instance. - -DEVICE MANAGEMENT -================= - -create-device *factory-name* [*properties...*] - Create a device from a factory in the current instance. - - Properties are key=value pairs separated by whitespace. - - This command returns a *device variable*. - - -LINK MANAGEMENT -=============== - -create-link *node-id* *port-id* *node-id* *port-id* [*properties...*] - Create a link between 2 nodes and ports. - - Port *ids* can be *-1* to automatically select an available port. - - Properties are key=value pairs separated by whitespace. - - This command returns a *link variable*. - -GLOBALS MANAGEMENT -================== - -destroy *object-id* - Destroy a global object. - - -PARAMETER MANAGEMENT -==================== - -enum-params *object-id* *param-id* - Enumerate params of an object. - - *param-id* can also be given as the param short name. - -set-param *object-id* *param-id* *param-json* - Set param of an object. - - *param-id* can also be given as the param short name. - -PERMISSION MANAGEMENT -===================== - -permissions *client-id* *object-id* *permission* - Set permissions for a client. - - *object-id* can be *-1* to set the default permissions. - -get-permissions *client-id* - Get permissions of a client. - - -COMMAND MANAGEMENT -================== - -send-command *object-id* - Send a command to an object. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-mon(1)``, diff --git a/man/pw-config.1.rst.in b/man/pw-config.1.rst.in deleted file mode 100644 index a3df2dbf8..000000000 --- a/man/pw-config.1.rst.in +++ /dev/null @@ -1,110 +0,0 @@ -pw-config -######### - ------------------------------ -Debug PipeWire Config parsing ------------------------------ - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-config** [*options*] paths - -| **pw-config** [*options*] list [*SECTION*] - -| **pw-config** [*options*] merge *SECTION* - -DESCRIPTION -=========== - -List config paths and config sections and display the parsed -output. - -This tool can be used to get an overview of the config file that will be -parsed by the PipeWire server and clients. - -COMMON OPTIONS -============== - --h | --help - Show help. - ---version - Show version information. - --n | --name=NAME - Config Name (default 'pipewire.conf') - --p | --prefix=PREFIX - Config Prefix (default '') - --L | --no-newline - Omit newlines after values - --r | --recurse - Reformat config sections recursively - --N | --no-colors - Disable color output - --C | --color[=WHEN] - whether to enable color support. WHEN is `never`, `always`, or `auto` - -LISTING PATHS -============= - -Specify the paths command. It will display all the config files that will -be parsed and in what order. - -LISTING CONFIG SECTIONS -======================= - -Specify the list command with an optional *SECTION* to list the configuration -fragments used for *SECTION*. Without a *SECTION*, all sections will be -listed. - -Use the -r options to reformat the sections. - -MERGING A CONFIG SECTION -======================== - -With the merge option and a *SECTION*, pw-config will merge all config files into -a merged config section and dump the results. This will be the section used by -the client or server. - -Use the -r options to reformat the sections. - -EXAMPLES -======== - -**pw-config** - List all config files that will be used - -**pw-config** -n pipewire-pulse.conf - List all config files that will be used by the PipeWire pulseaudio server. - -**pw-config** -n pipewire-pulse.conf list - List all config sections used by the PipeWire pulseaudio server - -**pw-config** -n jack.conf list context.properties - List the context.properties fragments used by the JACK clients - -**pw-config** -n jack.conf merge context.properties - List the merged context.properties used by the JACK clients - -**pw-config** -n pipewire.conf -r merge context.modules - List the merged context.modules used by the PipeWire server and reformat - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-dump(1)``, diff --git a/man/pw-dot.1.rst.in b/man/pw-dot.1.rst.in deleted file mode 100644 index 459953982..000000000 --- a/man/pw-dot.1.rst.in +++ /dev/null @@ -1,65 +0,0 @@ -pw-dot -###### - ---------------------------- -The PipeWire dot graph dump ---------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-dot** [*options*] - -DESCRIPTION -=========== - -Create a .dot file of the PipeWire graph. - -The .dot file can then be visualized with a tool like **dotty** -or rendered to a PNG file with ``dot -Tpng pw.dot -o pw.png``. - -OPTIONS -======= - --r | --remote=NAME - The name the remote instance to connect to. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - --a | --all - Show all object types. - --s | --smart - Show linked objects only. - --d | --detail - Show all object properties. - --o FILE | --output=FILE - Output file name (Default pw.dot). Use - for stdout. - --L | --lr - Lay the graph from left to right, instead of dot's default top to bottom. - --9 | --90 - Lay the graph using 90-degree angles in edges. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-cli(1)``, -``pw-mon(1)``, diff --git a/man/pw-dump.1.rst.in b/man/pw-dump.1.rst.in deleted file mode 100644 index 5b11ee30b..000000000 --- a/man/pw-dump.1.rst.in +++ /dev/null @@ -1,54 +0,0 @@ -pw-dump -####### - -------------------------- -The PipeWire state dumper -------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-dump** [*options*] - -DESCRIPTION -=========== - -The *pw-dump* program produces a representation of the current -PipeWire state as JSON, including the information on nodes, devices, -modules, ports, and other objects. - -OPTIONS -======= - --h | --help - Show help. - --r | --remote=NAME - The name of the *remote* instance to dump. If left unspecified, - a connection is made to the default PipeWire instance. - --m | --monitor - Monitor PipeWire state changes, and output JSON arrays describing changes. - --N | --no-colors - Disable color output. - --C | --color=WHEN - Whether to enable color support. WHEN is ``never``, ``always``, or ``auto``. - - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-cli(1)``, -``pw-top(1)``, - diff --git a/man/pw-jack.1.rst.in b/man/pw-jack.1.rst.in deleted file mode 100644 index 0781b3d7b..000000000 --- a/man/pw-jack.1.rst.in +++ /dev/null @@ -1,65 +0,0 @@ -pw-jack -####### - ----------------------------- -Use PipeWire instead of JACK ----------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-jack** [*options*] *COMMAND* [*FILE*] - -DESCRIPTION -=========== - -**pw-jack** modifies the ``LD_LIBRARY_PATH`` environment -variable so that applications will load PipeWire's reimplementation -of the JACK client libraries instead of JACK's own -libraries. This results in JACK clients being redirected to -PipeWire. - -If PipeWire's reimplementation of the JACK client libraries -has been installed as a system-wide replacement for JACK's -own libraries, then the whole system already behaves in that way, -in which case **pw-jack** has no practical effect. - -OPTIONS -======= - --h - Show help. - --r NAME - The name of the remote instance to connect to. If left - unspecified, a connection is made to the default PipeWire - instance. - --v - Verbose operation. - -EXAMPLES -======== - -| **pw-jack** sndfile-jackplay /usr/share/sounds/freedesktop/stereo/bell.oga - -NOTES -===== - -Using PipeWire for audio is currently considered to be -experimental. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; -PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``jackd(1)``, diff --git a/man/pw-link.1.rst.in b/man/pw-link.1.rst.in deleted file mode 100644 index 7d1001c58..000000000 --- a/man/pw-link.1.rst.in +++ /dev/null @@ -1,139 +0,0 @@ -pw-link -####### - -------------------------- -The PipeWire Link Command -------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-link** [*options*] -o|-i|-l [*out-pattern*] [*in-pattern*] - -| **pw-link** [*options*] *output* *input* - -| **pw-link** [*options*] -d *output* *input* - -| **pw-link** [*options*] -d *link-id* - -DESCRIPTION -=========== - -List, create and destroy links between PipeWire ports. - -COMMON OPTIONS -============== - --r | --remote=NAME - The name the *remote* instance to monitor. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - -LISTING PORTS AND LINKS -======================= - -Specify one of -o, -i or -l to list the matching optional input and -output ports and their links. - --o | --output - List output ports - --i | --input - List output ports - --l | --links - List links - --m | --monitor - Monitor links and ports. **pw-link** will not exit but monitor and - print new and destroyed ports or links. - --I | --id - List IDs. Also list the unique link and port ids. - --v | --verbose - Verbose port properties. Also list the port-object-path and the port-alias. - -CONNECTING PORTS -================ - -Without any list option (-i, -o or -l), the given ports will be linked. -Valid port specifications are: - -*port-id* - As obtained with the -I option when listing ports. - -*node-name:port-name* - As obtained when listing ports. - -*port-object-path* - As obtained from the first alternative name for the port when listing - them with the -v option. - -*port-alias* - As obtained from the second alternative name for the ports when listing - them with the -v option. - -Extra options when linking can be given: - --L | --linger - Linger. Will create a link that exists after **pw-link** is destroyed. - This is the default behaviour, unless the -m option is given. - --P | --passive - Passive link. A passive link will keep both nodes it links inactive - unless another non-passive link is activating the nodes. You can use this - to link a sink to a filter and have them both suspended when nothing else - is linked to either of them. - --p | --props=PROPS - Properties as JSON object. Give extra properties when creaing the link. - -DISCONNECTING PORTS -=================== - -When the -d option is given, an existing link between port is destroyed. - -To disconnect port, a single *link-id*, as obtained when listing links with -the -I option, or two port specifications can be given. See the connecting -ports section for valid port specifications. - --d | --disconnect - Disconnect ports - -EXAMPLES -======== - -**pw-link** -iol - List all port and their links. - -**pw-link** -lm - List all links and monitor changes until **pw-link** is stopped. - -**pw-link** paplay:output_FL alsa_output.pci-0000_00_1b.0.analog-stereo:playback_FL - Link the given output port to the input port. - -**pw-link** -lI - List links and their Id. - -**pw-link** -d 89 - Destroy the link with id 89. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-cli(1)``, diff --git a/man/pw-loopback.1.rst.in b/man/pw-loopback.1.rst.in deleted file mode 100644 index 0008c305b..000000000 --- a/man/pw-loopback.1.rst.in +++ /dev/null @@ -1,79 +0,0 @@ -pw-loopback -########### - ------------------------- -PipeWire loopback client ------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-loopback** [*options*] - -DESCRIPTION -=========== - -The *pw-loopback* program is a PipeWire client that uses the PipeWire -loopback module to create loopback nodes, with configuration given via -the command-line options. - -OPTIONS -======= - --h | --help - Show help. - --r | --remote=NAME - The name of the *remote* instance to connect to. If left unspecified, - a connection is made to the default PipeWire instance. - --n | --name=NAME - Name of the loopback node - --g | --group=NAME - Name of the loopback node group - --c | --channels=NUMBER - Number of channels to provide - --m | --channel-map=MAP - Channel map (default ``[ FL, FR ]``) - --l | --latency=LATENCY - Desired latency in ms - --d | --delay=DELAY - Added delay in seconds (floating point allowed) - --C | --capture=TARGET - Target device to capture from - --P | --playback=TARGET - Target device to play to - ---capture-props=PROPS - - Wanted properties of capture node (in JSON) - ---playback-props=PROPS - - Wanted properties of capture node (in JSON) - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-cat(1)``, -``pactl(1)`` - -Other ways to create loopback nodes are adding the loopback module in -the configuration of a PipeWire daemon, or loading the loopback module -using Pulseaudio commands (``pactl load-module module-loopback ...``). diff --git a/man/pw-metadata.1.rst.in b/man/pw-metadata.1.rst.in deleted file mode 100644 index 32f9c5117..000000000 --- a/man/pw-metadata.1.rst.in +++ /dev/null @@ -1,82 +0,0 @@ -pw-metadata -########### - ---------------------- -The PipeWire metadata ---------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-metadata** [*options*] [*id* [*key* [*value* [*type* ] ] ] ] - -DESCRIPTION -=========== - -Monitor, set and delete metadata on PipeWire objects. - -Metadata are key/type/value triplets attached to objects identified -by *id*. The metadata is shared between all applications -binding to the same metadata object. When an object is destroyed, all its -metadata is automatically removed. - -When no *value* is given, **pw-metadata** will query and -log the metadata matching the optional arguments *id* -and *key*. Without any arguments, all metadata is displayed. - -When *value* is given, **pw-metadata** will set the -metadata for *id* and *key* to *value* and -an optional *type*. - -OPTIONS -======= - --r | --remote=NAME - The name the remote instance to use. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - --l | --list - List available metadata objects - --m | --monitor - Keeps running and log the changes to the metadata. - --d | --delete - Delete all metadata for *id* or for the specified *key* of object *id*. - Without any option, all metadata is removed. - --n | --name - Metadata name (Default: "default"). - -EXAMPLES -======== - -**pw-metadata** - Show metadata in default name. - -**pw-metadata** -n settings 0 - Display settings. - -**pw-metadata** -n settings 0 clock.quantum 1024 - Change clock.quantum to 1024. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-mon(1)``, -``pw-cli(1)``, diff --git a/man/pw-mididump.1.rst.in b/man/pw-mididump.1.rst.in deleted file mode 100644 index bb56ec673..000000000 --- a/man/pw-mididump.1.rst.in +++ /dev/null @@ -1,49 +0,0 @@ -pw-mididump -########### - ----------------------- -The PipeWire MIDI dump ----------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-mididump** [*options*] [*FILE*] - -DESCRIPTION -=========== - -Dump MIDI messages to stdout. - -When a MIDI file is given, the events inside the file are printed. - -When no file is given, **pw-mididump** creates a PipeWire -MIDI input stream and will print all MIDI events received on the port to -stdout. - -OPTIONS -======= - --r | --remote=NAME - The name the remote instance to monitor. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-cat(1)``, diff --git a/man/pw-mon.1.rst.in b/man/pw-mon.1.rst.in deleted file mode 100644 index 775de0a4e..000000000 --- a/man/pw-mon.1.rst.in +++ /dev/null @@ -1,46 +0,0 @@ -pw-mon -###### - --------------------- -The PipeWire monitor --------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-mon** [*options*] - -DESCRIPTION -=========== - -Monitor objects on the PipeWire instance. - -OPTIONS -======= - --r | --remote=NAME - The name the *remote* instance to monitor. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - --N | --color=WHEN - Whether to use color, one of 'never', 'always', or 'auto'. The - default is 'auto'. **-N** is equivalent to **--color=never**. - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, diff --git a/man/pw-profiler.1.rst.in b/man/pw-profiler.1.rst.in deleted file mode 100644 index 6fb57c8eb..000000000 --- a/man/pw-profiler.1.rst.in +++ /dev/null @@ -1,57 +0,0 @@ -pw-profiler -########### - ---------------------- -The PipeWire profiler ---------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-profiler** [*options*] - -DESCRIPTION -=========== - -Start profiling a PipeWire instance. - -If the server has the profiler module loaded, this program will -connect to it and log the profiler data. Profiler data contains -times and durations when processing nodes and devices started and -completed. - -When this program is stopped, a set of **gnuplot** files and a script to generate -SVG files from the .plot files is generated, along with a .html file to -visualize the profiling results in a browser. - -This function uses the same data used by *pw-top*. - -OPTIONS -======= - --r | --remote=NAME - The name the remote instance to monitor. If left unspecified, - a connection is made to the default PipeWire instance. - --h | --help - Show help. - ---version - Show version information. - --o | --output=FILE - Profiler output name (default "profiler.log"). - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-top(1)``, diff --git a/man/pw-top.1.rst.in b/man/pw-top.1.rst.in deleted file mode 100644 index 0320a2752..000000000 --- a/man/pw-top.1.rst.in +++ /dev/null @@ -1,184 +0,0 @@ -pw-top -###### - ---------------------------- -The PipeWire process viewer ---------------------------- - -:Manual section: 1 -:Manual group: General Commands Manual - -SYNOPSIS -======== - -| **pw-top** [*options*] - -DESCRIPTION -=========== - -The *pw-top* program provides a dynamic real-time view of the pipewire -node and device statistics. - -A hierarchical view is shown of Driver nodes and follower nodes. The Driver -nodes are actively using a timer to schedule dataflow in the followers. The -followers of a driver node as shown below their driver with a + sign in -a tree-like representation. - -The columns presented are as follows: - -S - Node status. - E = ERROR - C = CREATING - S = SUSPENDED - I = IDLE - R = RUNNING - -ID - The ID of the pipewire node/device, as found in *pw-dump* and *pw-cli* - -QUANT - The current quantum (for drivers) and the suggested quantum for follower - nodes. - - The quantum by itself needs to be divided by the RATE column to calculate - the duration of a scheduling period in fractions of a second. - - For a QUANT of 1024 and a RATE of 48000, the duration of one period in the - graph is 1024/48000 or 21.3 milliseconds. - - Follower nodes can have a 0 QUANT field, which means that the node does not - have a suggestion for the quantum and thus uses what the driver selected. - - The driver will use the lowest quantum of any of the followers. If none of - the followers select a quantum, the default quantum in the pipewire configuration - file will be used. - - The QUANT on the drivers usually translates directly into the number of audio - samples processed per processing cycle of the graph. - - See also https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/FAQ#pipewire-buffering-explained - -RATE - The current rate (for drivers) and the suggested rate for follower - nodes. - - This is the rate at which the *graph* processes data and needs to be combined with - the QUANT value to derive the duration of a processing cycle in the graph. - - Some nodes can have a 0 RATE, which means that they don't have any rate - suggestion for the graph. Nodes that suggest a rate can make the graph switch - rates if the graph is otherwise idle and the new rate is allowed as - a possible graph rate (see the pipewire configuration file). - - The RATE on (audio) driver nodes usually also translates directly to the - samplerate used by the device. Although some devices might not be able to - operate at the given samplerate, in which case resampling will need to be - done. The negotiated samplerate with the device and stream can be found in - the FORMAT column. - -WAIT - The waiting time of a node is the elapsed time between when the node - is ready to start processing and when it actually started processing. - - For Driver nodes, this is the time between when the node wakes up to - start processing the graph and when the driver (and thus also the graph) - completes a cycle. The WAIT time for driver is thus the elapsed time - processing the graph. - - For follower nodes, it is the time spent between being woken up (when all - dependencies of the node are satisfied) and when processing starts. The - WAIT time for follower nodes is thus mostly caused by context switching. - - A value of --- means that the node was not signaled. A value of +++ - means that the node was signaled but not awake. - -BUSY - The processing time is started when the node starts processing until it - completes and wakes up the next nodes in the graph. - - A value of --- means that the node was not started. A value of +++ - means that the node was started but did not complete. - -W/Q - Ratio of WAIT / QUANT. - - The W/Q time of the driver node is a good measure of the graph - load. The running averages of the driver W/Q ratios are used as the DSP - load in other (JACK) tools. - - Values of --- and +++ are copied from the WAIT column. - -B/Q - Ratio of BUSY / QUANT - - This is a good measure of the load of a particular driver or follower - node. - - Values of --- and +++ are copied from the BUSY column. - -ERR - Total of Xruns and Errors - - Xruns for drivers are when the graph did not complete a cycle. This can - be because a node in the graph also has an Xrun. It can also be caused when - scheduling delays cause a deadline to be missed, causing a hardware - Xrun. - - Xruns for followers are incremented when the node started processing but - did not complete before the end of the graph cycle deadline. - -FORMAT - The format used by the driver node or the stream. This is the hardware format - negotiated with the device or stream. - - If the stream of driver has a different rate than the graph, resampling will - be done. - - For raw audio formats, the layout is . - - For IEC958 passthrough audio formats, the layout is IEC958 . - - For DSD formats, the layout is . - - For Video formats, the layout is x. - -NAME - Name assigned to the device/node, as found in *pw-dump* node.name - - Names are prefixed by *+* when they are linked to a driver (entry above with no +) - - -OPTIONS -======= - --h | --help - Show help. - --b | --batch-mode - Run in non-interactive batch mode, similar to top's batch mode. - --n | --iterations=NUMBER - Exit after NUMBER of batch iterations. Only used in batch mode. - --r | --remote=NAME - The name the *remote* instance to monitor. If left unspecified, - a connection is made to the default PipeWire instance. - --V | --version - Show version information. - - -AUTHORS -======= - -The PipeWire Developers <@PACKAGE_BUGREPORT@>; PipeWire is available from @PACKAGE_URL@ - -SEE ALSO -======== - -``pipewire(1)``, -``pw-dump(1)``, -``pw-cli(1)``, -``pw-profiler(1)``, - diff --git a/meson.build b/meson.build index 6f5d58971..6bf25eef5 100644 --- a/meson.build +++ b/meson.build @@ -485,36 +485,17 @@ if alsa_dep.found() subdir('pipewire-alsa/tests') endif -generate_manpages = false -if get_option('man').allowed() - rst2man = find_program('rst2man', required: false) - if not rst2man.found() - rst2man = find_program('rst2man.py', required: get_option('man')) - endif - if rst2man.found() - generate_manpages = true - endif -endif - -summary({'Manpage generation': generate_manpages}, bool_yn: true) -subdir('man') - doxygen = find_program('doxygen', required : get_option('docs')) pymod = import('python') python = pymod.find_installation('python3', required: get_option('docs')) +generate_docs = doxygen.found() and python.found() -generate_extra_manpages = false - -if doxygen.found() and python.found() - if generate_manpages - pandoc = find_program('pandoc', required: get_option('man-extra')) - generate_extra_manpages = pandoc.found() - endif - +if generate_docs subdir('doc') endif -summary({'Extra manpage generation': generate_extra_manpages}, bool_yn: true) +summary({'Documentation and man pages ': generate_docs}, bool_yn: true) + setenv = find_program('pw-uninstalled.sh') run_target('pw-uninstalled', diff --git a/meson_options.txt b/meson_options.txt index 38ba24020..713e253f7 100644 --- a/meson_options.txt +++ b/meson_options.txt @@ -9,14 +9,6 @@ option('examples', description: 'Build examples', type: 'feature', value: 'enabled') -option('man', - description: 'Build manpages', - type: 'feature', - value: 'auto') -option('man-extra', - description: 'Build extra manpages', - type: 'feature', - value: 'auto') option('tests', description: 'Build tests', type: 'feature',