Update docs a bit

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
+
+

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
+The prefered way to install PipeWire is to install it with your
-with:
+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
+$ pw-play /home/wim/data/01.\ Firepower.wav
-$ cd build
-$ ninja
 ```
 
-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
+Depending on how the system was configured, your can either run PipeWire and
-automatically run the correct `meson`/`ninja` commands, and output a Makefile.
+JACK side-by-side or have PipeWire take over the functionality of JACK
-It follows that there are two methods to build Pipewire, however both rely
+completely.
-on Meson and Ninja to actually perform the compilation:
+
+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
+$ pw-jack <appname>
-$ make
 ```
 
-## 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
+### Running PulseAudio applications
-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
+Depending on how the system was configured, your can either run PipeWire and
-will use the PipeWire emulation libraries automatically
+PulseAudio side-by-side or have PipeWire take over the functionality of
-in this environment. You can get into this environment with:
+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
+```
+