You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

202 lines
6.1 KiB

2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
  1. # PipeWire
  2. [PipeWire](https://pipewire.org) is a server and user space API to
  3. deal with multimedia pipelines. This includes:
  4. - Making available sources of video (such as from a capture devices or
  5. application provided streams) and multiplexing this with
  6. clients.
  7. - Accessing sources of video for consumption.
  8. - Generating graphs for audio and video processing.
  9. Nodes in the graph can be implemented as separate processes,
  10. communicating with sockets and exchanging multimedia content using fd
  11. passing.
  12. ## Building and installation
  13. The preferred way to install PipeWire is to install it with your
  14. distribution package system. This ensures PipeWire is integrated
  15. into the rest of your system for the best experience.
  16. If you want to build and install PipeWire yourself, refer to
  17. [install](INSTALL.md) for instructions.
  18. ## Usage
  19. The most important purpose of PipeWire is to run your favorite apps.
  20. Some applications use the native PipeWire API, such as most compositors
  21. (gnome-shell, wayland, ...) to implement screen sharing. These apps will
  22. just work automatically.
  23. Most audio applications can use either ALSA, JACK or PulseAudio as a
  24. backend. PipeWire provides support for all 3 backends. Depending on how
  25. your distribution has configured things this should just work automatically
  26. or with the provided scripts shown below.
  27. PipeWire can use environment variables to control the behaviour of
  28. applications:
  29. * `PIPEWIRE_DEBUG=<level>` to increase the debug level
  30. * `PIPEWIRE_LOG=<filename>` to redirect log to filename
  31. * `PIPEWIRE_LOG_SYSTEMD=false` to disable logging to systemd journal
  32. * `PIPEWIRE_LATENCY=<num/denom>` to configure latency as a fraction. 10/1000
  33. configures a 10ms latency. Usually this is
  34. expressed as a fraction of the samplerate,
  35. like 256/48000, which uses 256 samples at a
  36. samplerate of 48KHz for a latency of 5.33ms.
  37. * `PIPEWIRE_NODE=<id>` to request a link to the specified node
  38. ### Using tools
  39. `pw-cat` can be used to play and record audio and midi. Use `pw-cat -h` to get
  40. some more help. There are some aliases like `pw-play` and `pw-record` to make
  41. things easier:
  42. ```
  43. $ pw-play /home/wim/data/01.\ Firepower.wav
  44. ```
  45. ### Running JACK applications
  46. Depending on how the system was configured, you can either run PipeWire and
  47. JACK side-by-side or have PipeWire take over the functionality of JACK
  48. completely.
  49. In dual mode, JACK apps will by default use the JACK server. To direct a JACK
  50. app to PipeWire, you can use the `pw-jack` script like this:
  51. ```
  52. $ pw-jack <appname>
  53. ```
  54. If you replaced JACK with PipeWire completely, `pw-jack` does not have any
  55. effect and can be omitted.
  56. JACK applications will automatically use the buffer-size chosen by the
  57. server. You can force a maximum buffer size (latency) by setting the
  58. `PIPEWIRE_LATENCY` environment variable like so:
  59. ```
  60. PIPEWIRE_LATENCY=128/48000 jack_simple_client
  61. ```
  62. Requests the `jack_simple_client` to run with a buffer of 128 or
  63. less samples.
  64. ### Running PulseAudio applications
  65. PipeWire can run a PulseAudio compatible replacement server. You can't
  66. use both servers at the same time. Usually your package manager will
  67. make the server conflict so that you can only install one or the
  68. other.
  69. PulseAudio applications still use the regular PulseAudio client
  70. libraries and you don't need to do anything else than change the
  71. server implementation.
  72. A successful swap of the server can be verified by checking the
  73. output of
  74. ```
  75. pactl info
  76. ```
  77. It should include the string:
  78. ```
  79. ...
  80. Server Name: PulseAudio (on PipeWire 0.3.x)
  81. ...
  82. ```
  83. You can use pavucontrol to change profiles and ports, change volumes
  84. or redirect streams, just like with PulseAudio.
  85. ### Running ALSA applications
  86. If the PipeWire alsa module is installed, it can be seen with
  87. ```
  88. $ aplay -L
  89. ```
  90. ALSA applications can then use the `pipewire:` device to use PipeWire
  91. as the audio system.
  92. ### Running GStreamer applications
  93. PipeWire includes 2 GStreamer elements called `pipewiresrc` and
  94. `pipewiresink`. They can be used in pipelines such as this:
  95. ```
  96. $ gst-launch-1.0 pipewiresrc ! videoconvert ! autovideosink
  97. ```
  98. Or to play a beeping sound:
  99. ```
  100. $ gst-launch-1.0 audiotestsrc ! pipewiresink
  101. ```
  102. PipeWire provides a device monitor as well so that
  103. ```
  104. $ gst-device-monitor-1.0
  105. ```
  106. shows the PipeWire devices and applications like cheese will
  107. automatically use the PipeWire video source when possible.
  108. ### Inspecting the PipeWire state
  109. To inspect and manipulate the PipeWire graph via GUI, you can use [Helvum](https://gitlab.freedesktop.org/ryuukyu/helvum).
  110. Alternatively, you can use use one of the excellent JACK tools, such as `Carla`,
  111. `catia`, `qjackctl`, ...
  112. However, you will not be able to see all features like the video
  113. ports.
  114. `pw-mon` dumps and monitors the state of the PipeWire daemon.
  115. `pw-dot` can dump a graph of the pipeline, check out the help for
  116. how to do this.
  117. `pw-top` monitors the real-time status of the graph. This is handy to
  118. find out what clients are running and how much DSP resources they
  119. use.
  120. `pw-dump` dumps the state of the PipeWire daemon in JSON format. This
  121. can be used to find out the properties and parameters of the objects
  122. in the PipeWire daemon.
  123. There is a more complicated tool to inspect the state of the server
  124. with `pw-cli`. This tool can be used interactively or it can execute
  125. single commands like this to get the server information:
  126. ```
  127. $ pw-cli info 0
  128. ```
  129. ## Documentation
  130. Find tutorials and design documentation [here](doc/index.md).
  131. The (incomplete) autogenerated API docs are [here](https://docs.pipewire.org).
  132. The Wiki can be found [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/wikis/home)
  133. ## Contributing
  134. PipeWire is Free Software and is developed in the open. It is mostly
  135. licensed under the [MIT license](COPYING). Check [LICENSE](LICENSE) for
  136. more details about the exceptions.
  137. Contributors are encouraged to submit merge requests or file bugs on
  138. [gitlab](https://gitlab.freedesktop.org/pipewire).
  139. Join us on IRC at #pipewire on [OFTC](https://www.oftc.net/).
  140. We adhere to the Contributor Covenant for our [code of conduct](CODE_OF_CONDUCT.md).
  141. [Donate using Liberapay](https://liberapay.com/PipeWire/donate).