diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 000000000..0ce80ecde --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,119 @@ +## Building + +Pipewire uses the Meson and Ninja build system to compile. You can run it +with: + +``` +$ meson build +$ cd build +$ ninja +``` + +You can see the available meson options in `meson_options.txt` file. + +If you're not familiar with these tools, the included `autogen.sh` script will +automatically run the correct `meson`/`ninja` commands, and output a Makefile. +It follows that there are two methods to build Pipewire, however both rely +on Meson and Ninja to actually perform the compilation: + +``` +$ ./autogen.sh +$ make +``` + +Provide the installation directory with the --prefix option. + +## Running + +If you want to run PipeWire without installing it on your system, there is a +script that you can run. This puts you in an environment in which PipeWire can +be run from the build directory, and ALSA, PulseAudio and JACK applications +will use the PipeWire emulation libraries automatically +in this environment. You can get into this environment with: + +``` +$ ./pw-uninstalled.sh +``` + +In most cases you would want to run the default pipewire daemon. Look +below for how to make this daemon start automatically using systemd. +If you want to run pipewire from the build directory, you can do this +by doing: + +``` +make run +``` + +This will use the default config file to configure and start the daemon. +The default config will also start pipewire-media-session, a default +example media session. + +You can also enable more debuging with the PIPEWIRE_DEBUG environment +variable like so: + +``` +PIPEWIRE_DEBUG=4 make run +``` + +You might have to stop the pipewire service/socket that might have been +started already, with: + +``` +systemctl --user stop pipewire.service +systemctl --user stop pipewire.socket +``` + +## Installing + +PipeWire comes with quite a bit of libraries and tools, use: + +``` +sudo meson install +``` + +to install everything onto the system into the specified prefix. +Some additional steps will have to be performed to integrate +with the distribution as shown below. + +### PipeWire daemon + +A correctly installed PipeWire system should have a pipewire +process and a pipewire-media-session (or alternative) process +running. PipeWire is usually started as a systemd unit using +socket activation or as a service. + +Configuration of the PipeWire daemon can be found in +/etc/pipewire/pipewire.conf. Please refer to the comments in the +config file for more information about the configuration options. + +### ALSA plugin + +The ALSA plugin is usually installed in: + +``` +/usr/lib64/alsa-lib/libasound_module_pcm_pipewire.so +``` + +There is also a config file installed in: + +``` +/usr/share/alsa/alsa.conf.d/50-pipewire.conf +``` + +The plugin will be picked up by alsa when the following files +are in /etc/alsa/conf.d/ + +``` +/etc/alsa/conf.d/50-pipewire.conf -> /usr/share/alsa/alsa.conf.d/50-pipewire.conf +/etc/alsa/conf.d/99-pipewire-default.conf +``` + +With this setup, aplay -l should list a pipewire: device that can be used as +a regular alsa device for playback and record. + +### JACK emulation + + +### PulseAudio emulation + + diff --git a/README.md b/README.md index 3c4c0f9e8..9b464c328 100644 --- a/README.md +++ b/README.md @@ -13,37 +13,127 @@ Nodes in the graph can be implemented as separate processes, communicating with sockets and exchanging multimedia content using fd passing. -## Building +## Building and installation -Pipewire uses the Meson and Ninja build system to compile. You can run it -with: +The prefered 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.md for instructions. + +## Usage + +The most important purpose of PipeWire is to run your favorite apps. + +Some application 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 distríbution 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 +PIPEWIRE_LOG=<filename> to redirect log to filename +PIPEWIRE_LATENCY=<num/denom> to configure latency +PIPEWIRE_NODE=<id> to request link to specified 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: ``` -$ meson build -$ cd build -$ ninja +$ pw-play /home/wim/data/01.\ Firepower.wav ``` -You can see the available meson options in `meson_options.txt` file. +### Running JACK applications -If you're not familiar with these tools, the included `autogen.sh` script will -automatically run the correct `meson`/`ninja` commands, and output a Makefile. -It follows that there are two methods to build Pipewire, however both rely -on Meson and Ninja to actually perform the compilation: +Depending on how the system was configured, your 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: ``` -$ ./autogen.sh -$ make +$ pw-jack <appname> ``` -## Running +If you replaced JACK with PipeWire completely, pw-jack does not have any +effect and can be ommited. -If you want to run PipeWire without installing it on your system, there is a -script that you can run. This puts you in an environment in which PipeWire can -be run from the build directory, and ALSA, PulseAudio and JACK applications -will use the PipeWire emulation libraries automatically -in this environment. You can get into this environment with: +### Running PulseAudio applications + +Depending on how the system was configured, your can either run PipeWire and +PulseAudio side-by-side or have PipeWire take over the functionality of +PulseAudio completely. We don't recommend to completely replace PulseAudio +at this point. + +Use the pw-pulse script to launch a PulseAudio application on PipeWire, like: ``` -$ ./pw-uninstalled.sh +$ pw-pulse <appname> ``` + +### Running ALSA applications + +If the PipeWire alsa module is installed, it can be seen with + +``` +$ aplay -L +``` + +Alsa application 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 like 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 + +There is currently no native graphical tool to inspect the PipeWire graph +but we recommend to use one of the excellent JACK tools, such as Carla, +catia, qjackctl,... You will not be able to see all features like the video +ports but it is a good start. + +pw-mon dumps and monitors the state of the PipeWire daemon. + +pw-dot can dump a graph of the pipeline, checkout out the help for +how to do this. + +There is a more complicated tools to inspect the state of the server +with pw-cli. This tools can be used interactively or it can execute +single commands like this to get the server information: + +``` +$ pw-cli info 0 +``` +