From be25be14946a9625b33c59dbd82853bab2ddaa51 Mon Sep 17 00:00:00 2001 From: Nedko Arnaudov Date: Sun, 28 May 2023 18:44:56 +0300 Subject: [PATCH] replace PipeWire's README with one for SPA --- README.adoc | 70 +++++++++++++++++ README.md | 218 ---------------------------------------------------- 2 files changed, 70 insertions(+), 218 deletions(-) create mode 100644 README.adoc delete mode 100644 README.md diff --git a/README.adoc b/README.adoc new file mode 100644 index 000000000..4024cd923 --- /dev/null +++ b/README.adoc @@ -0,0 +1,70 @@ +== Project overview +This is project of maintaining https://docs.pipewire.org/page_spa.html[PipeWire's SPA] as SPA-only SDK codebase. + +== SPA (Simple Plugin API) + +SPA (Simple Plugin API) is an extensible API to implement all kinds of plugins. + +It is inspired by many other plugin APIs, mostly LV2 and GStreamer. SPA provides two parts: + + * A header-only API with no external dependencies. + * A set of support libraries ("plugins") for commonly used functionality. + +The usual approach is that PipeWire and PipeWire clients can use the header-only functions to interact with the plugins. Those plugins are usually loaded at runtime (through dlopen(3)). + +== Motivation + +SPA was designed with the following goals in mind: + + * No dependencies, SPA is shipped as a set of header files that have no dependencies except for the standard C library. + * Very efficient both in space and in time. + * Very configurable and usable in many different environments. All aspects of the plugin environment can be configured and changed, like logging, poll loops, system calls, etc. + * Consistent API. + * Extensible; new API can be added with minimal effort, existing API can be updated and versioned. + +The original user of SPA is PipeWire, which uses SPA to implement the low-level multimedia processing plugins, device detection, mainloops, CPU detection, logging, among other things. SPA however can be used outside of PipeWire with minimal problems. + +== The SPA Header-Only API + +A very simple example on how SPA headers work are the Utilities, a set of utilities commonly required by C projects. SPA functions use the spa_ namespace and are easy to identify. + +.spa-test.c +[source,C] +---- +/* cc $(pkg-config --cflags libspa-0.2) -o spa-test spa-test.c */ + +#include +#include + +int main(int argc, char **argv) { + uint32_t val; + + if (spa_atoi32(argv[1], &val, 16)) + printf("argv[1] is hex %#x\n", val); + else + printf("argv[1] is not a hex number\n"); + + return 0; +} +---- + +== SPA Plugins + +SPA plugins are shared libraries (.so files) that can be loaded at runtime. Each library provides one or more "factories", each of which may implement several "interfaces". Code that uses SPA plugins then uses those interfaces (through SPA header files) to interact with the plugin. + +For example, the PipeWire daemon can load the normal printf-based logger or a systemd journal-based logger. Both of those provide the Log interface and once instantiated, PipeWire no longer has to differentiate between the two logging facilities. + +Please see SPA Plugins for the details on how to use SPA plugins. + +== Source code +Git repositories: + + * https://gitea.ladish.org/LADI/spa[SPA Gitea @ LADI project] + * https://github.com/LADI/spa[LADI project github for SPA] + +== Contact +For LADI specific issues, submit issues or pull request to LADI project. +For related discussions, you are invited to join +link:https://libera.chat/[Libera.Chat] channel #ladi + +IMPORTANT: Do not submit LADI specific issues to PipeWire project. diff --git a/README.md b/README.md deleted file mode 100644 index 612f500e7..000000000 --- a/README.md +++ /dev/null @@ -1,218 +0,0 @@ -# PipeWire - -[PipeWire](https://pipewire.org) is a server and user space API to -deal with multimedia pipelines. This includes: - - - Making available sources of video (such as from a capture devices or - application provided streams) and multiplexing this with - clients. - - Accessing sources of video for consumption. - - Generating graphs for audio and video processing. - -Nodes in the graph can be implemented as separate processes, -communicating with sockets and exchanging multimedia content using fd -passing. - -## Building and installation - -The preferred way to install PipeWire is to install it with your -distribution package system. This ensures PipeWire is integrated -into the rest of your system for the best experience. - -If you want to build and install PipeWire yourself, refer to -[install](INSTALL.md) for instructions. - -## Usage - -The most important purpose of PipeWire is to run your favorite apps. - -Some applications use the native PipeWire API, such as most compositors -(gnome-shell, wayland, ...) to implement screen sharing. These apps will -just work automatically. - -Most audio applications can use either ALSA, JACK or PulseAudio as a -backend. PipeWire provides support for all 3 backends. Depending on how -your distribution has configured things this should just work automatically -or with the provided scripts shown below. - -PipeWire can use environment variables to control the behaviour of -applications: - -* `PIPEWIRE_DEBUG=` to increase the debug level (or use one of - `XEWIDT` for none, error, warnings, info, - debug, or trace, respectively). -* `PIPEWIRE_LOG=` to redirect log to filename -* `PIPEWIRE_LOG_SYSTEMD=false` to disable logging to systemd journal -* `PIPEWIRE_LATENCY=` to configure latency as a fraction. 10/1000 - configures a 10ms latency. Usually this is - expressed as a fraction of the samplerate, - like 256/48000, which uses 256 samples at a - samplerate of 48KHz for a latency of 5.33ms. - This function does not attempt to configure - the samplerate. -* `PIPEWIRE_RATE=` to configure a rate for the graph. -* `PIPEWIRE_QUANTUM=` to configure latency as a fraction and a - samplerate. This function will attempt to change - the graph samplerate to `denom` and use the - specified `num` as the buffer size. -* `PIPEWIRE_NODE=` to request a link to the specified node. The - id can be a node.name or object.serial of the target node. - -### Using tools - -`pw-cat` can be used to play and record audio and midi. Use `pw-cat -h` to get -some more help. There are some aliases like `pw-play` and `pw-record` to make -things easier: - -``` -$ pw-play /home/wim/data/01.\ Firepower.wav -``` - -### Running JACK applications - -Depending on how the system was configured, you can either run PipeWire and -JACK side-by-side or have PipeWire take over the functionality of JACK -completely. - -In dual mode, JACK apps will by default use the JACK server. To direct a JACK -app to PipeWire, you can use the `pw-jack` script like this: - -``` -$ pw-jack -``` - -If you replaced JACK with PipeWire completely, `pw-jack` does not have any -effect and can be omitted. - -JACK applications will automatically use the buffer-size chosen by the -server. You can force a maximum buffer size (latency) by setting the -`PIPEWIRE_LATENCY` environment variable like so: - -``` -PIPEWIRE_LATENCY=128/48000 jack_simple_client -``` -Requests the `jack_simple_client` to run with a buffer of 128 or -less samples. - - -### Running PulseAudio applications - -PipeWire can run a PulseAudio compatible replacement server. You can't -use both servers at the same time. Usually your package manager will -make the server conflict so that you can only install one or the -other. - -PulseAudio applications still use the regular PulseAudio client -libraries and you don't need to do anything else than change the -server implementation. - -A successful swap of the server can be verified by checking the -output of - -``` -pactl info -``` -It should include the string: -``` -... -Server Name: PulseAudio (on PipeWire 0.3.x) -... -``` - -You can use pavucontrol to change profiles and ports, change volumes -or redirect streams, just like with PulseAudio. - - -### Running ALSA applications - -If the PipeWire alsa module is installed, it can be seen with - -``` -$ aplay -L -``` - -ALSA applications can then use the `pipewire:` device to use PipeWire -as the audio system. - -### Running GStreamer applications - -PipeWire includes 2 GStreamer elements called `pipewiresrc` and -`pipewiresink`. They can be used in pipelines such as this: - -``` -$ gst-launch-1.0 pipewiresrc ! videoconvert ! autovideosink -``` - -Or to play a beeping sound: - -``` -$ gst-launch-1.0 audiotestsrc ! pipewiresink -``` - -PipeWire provides a device monitor as well so that - -``` -$ gst-device-monitor-1.0 -``` - -shows the PipeWire devices and applications like cheese will -automatically use the PipeWire video source when possible. - -### Inspecting the PipeWire state - -To inspect and manipulate the PipeWire graph via GUI, you can use [Helvum](https://gitlab.freedesktop.org/ryuukyu/helvum). - -Alternatively, you can use use one of the excellent JACK tools, such as `Carla`, -`catia`, `qjackctl`, ... -However, you will not be able to see all features like the video -ports. - -`pw-mon` dumps and monitors the state of the PipeWire daemon. - -`pw-dot` can dump a graph of the pipeline, check out the help for -how to do this. - -`pw-top` monitors the real-time status of the graph. This is handy to -find out what clients are running and how much DSP resources they -use. - -`pw-dump` dumps the state of the PipeWire daemon in JSON format. This -can be used to find out the properties and parameters of the objects -in the PipeWire daemon. - -There is a more complicated tool to inspect the state of the server -with `pw-cli`. This tool can be used interactively or it can execute -single commands like this to get the server information: - -``` -$ pw-cli info 0 -``` - -## Documentation - -Find tutorials and design documentation [here](doc/index.dox). - -The (incomplete) autogenerated API docs are [here](https://docs.pipewire.org). - -The Wiki can be found [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home) - -## Contributing - -PipeWire is Free Software and is developed in the open. It is mostly -licensed under the [MIT license](COPYING). Check [LICENSE](LICENSE) for -more details about the exceptions. - -Contributors are encouraged to submit merge requests or file bugs on -[gitlab](https://gitlab.freedesktop.org/pipewire). - -Join us on IRC at #pipewire on [OFTC](https://www.oftc.net/). - -We adhere to the Contributor Covenant for our [code of conduct](CODE_OF_CONDUCT.md). - -[Donate using Liberapay](https://liberapay.com/PipeWire/donate). - -## Getting help - -You can ask for help on the IRC channel (see above). You can also ask -questions by [raising](https://gitlab.freedesktop.org/pipewire/pipewire/-/issues/new) -a gitlab issue.