diff options
Diffstat (limited to '')
| -rw-r--r-- | README.md | 218 |
1 files changed, 218 insertions, 0 deletions
diff --git a/README.md b/README.md new file mode 100644 index 0000000..612f500 --- /dev/null +++ b/README.md @@ -0,0 +1,218 @@ +# 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=<level>` to increase the debug level (or use one of + `XEWIDT` for none, error, warnings, info, + debug, or trace, respectively). +* `PIPEWIRE_LOG=<filename>` to redirect log to filename +* `PIPEWIRE_LOG_SYSTEMD=false` to disable logging to systemd journal +* `PIPEWIRE_LATENCY=<num/denom>` 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=<num/denom>` to configure a rate for the graph. +* `PIPEWIRE_QUANTUM=<num/denom>` 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=<id>` 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 <appname> +``` + +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. |