diff --git a/README.md b/README.md new file mode 100644 index 0000000..ca4aa91 --- /dev/null +++ b/README.md @@ -0,0 +1,169 @@ +A GStreamer plugin that provides an `airplaysrc` element for receiving video +streamed from Apple devices using the AirPlay protocol. Audio is currently not +supported. + +## Installation + +See [below](#building) for build instructions. Once you have the file `libgstairplay.so`, +you must let GStreamer find it. Possibilities include: + +* Placing the `libgstairplay.so` file in `~/.local/share/gstreamer-1.0/plugins`. +* Using the `--gst-plugin-path` option with `gst-launch` (for example `gst-launch-1.0 --gst-plugin-path=~/my-gst-plugins` airplaysrc ! ...`, see below for complete pipelines). +* Add the directory containing the plugin to the `GST_PLUGIN_PATH` environment variable. + +## Usage + +The `airplaysrc` element can be used like other video sources in GStreamer +pipelines. Examples are shown below. + +Typical use will require the following packages (tested on Ubuntu 20.04): + +``` +gstreamer1.0-tools +gstreamer1.0-plugins-good +gstreamer1.0-plugins-bad +gstreamer1.0-libav +libavahi-compat-libdnssd1 +libplist3 +``` + +### Showing the video in a window + +The `gst-launch` tool can be used to run a pipeline that shows the video stream +in a new window: + +``` +gst-launch-1.0 airplaysrc ! queue ! h264parse ! avdec_h264 max-threads=1 ! autovideosink +``` + +Explanation: the video stream is received in the H.264 format. The stream must +be parsed (`h264parse`) and decoded (`avdec_h264`) before showing in a window +(`autovideosink`). The `queue` element adds some buffering. The `max-threads=1` +decoding option can help reduce latency. + +### Using as a source in OBS Studio + +The `airplaysrc` element can be used with the [OBS GStreamer +plugin](https://github.com/fzwoch/obs-gstreamer) to configure an OBS source +that shows the AirPlay video stream: + +1. Install the OBS Gstreamer plugin. After compiling, I put the file `obs-gstreamer.so` in the directory `~/.config/obs-studio/plugins/obs-gstreamer/bin/64bit/`. +1. In your OBS scene, add a "GStreamer Source" +1. Set the pipeline parameter, using `airplaysrc` as first element. I use the following: + + airplaysrc ! queue ! h264parse ! avdec_h264 max-threads=1 ! videoconvert ! videoscale ! video. + +1. For best results, set the canvas and output sizes to the resolution of the AirPlay stream. + +### Using as a Linux camera device + +Using the [v4l2loopback](https://github.com/umlaeute/v4l2loopback) kernel +module, you can expose the AirPlay video stream as a camera device in Linux. + +1. Install the `v4l2loopback` module. Your distribution might have it as a package, for example `v4l2loopback-dkms` in Ubuntu 20.04. +1. Load the module with appropriate options. I use the following: + + sudo modprobe v4l2loopback devices=1 video_nr=10 card_label="AirPlay Cam" exclusive_caps=1 max_buffers=3 + + This creates a virtual camera with name "AirPlay Cam" and device `/dev/video10`. + +1. Start a GStreamer pipeline that feeds the AirPlay stream to the video device: + + gst-launch-1.0 -v airplaysrc ! queue ! h264parse ! avdec_h264 max-threads=1 ! videoconvert ! videoscale ! v4l2sink device=/dev/video10 + +Once you start streaming from the Apple device, you should see "AirPlay Cam" in the list of cameras on your computer. + +## Troubleshooting + +Call `gst-inspect-1.0 libgstairplay.so` (giving the path where the +`libgstairplay.so` file is located) to check for problems such as missing +libraries. For example if it says `libplist.so.3: cannot open shared object +file: No such file or directory`, you can fix it by installing the `libplist3` +package (on Ubuntu 20.04 at least). + +If you get an uninformative error message such as `Could not load plugin file: +File "libgstairplay.so" appears to be a GStreamer plugin, but it failed to +initialize`, try running again with `GST_DEBUG=4 gst-inspect-1.0 +build/libgstairplay.so`. + +## Building + +First install the build dependencies. The following packages are needed on +Ubuntu 20.04: + +``` +git +gcc +pkg-config +cmake +gstreamer1.0-tools +libgstreamer1.0-dev +libgstreamer-plugins-base1.0-dev +libavahi-compat-libdnssd-dev +libplist-dev +libssl-dev +meson +ninja-build +``` + +Then clone and build RPiPlay. The fork at https://github.com/knuesel/RPiPlay is +currently required. I use the following commands: + +``` +git clone https://github.com/knuesel/RPiPlay +cd RPiPlay +mkdir -p build install +cd build +cmake -DCMAKE_INSTALL_PREFIX=../install .. +make install +``` + +Then clone and build this project. I use the following: + +``` +cd ../.. # Get out of the RPiPlay directory +export PKG_CONFIG_PATH=$PKG_CONFIG_PATH:$PWD/RPiPlay/install/lib/pkgconfig +git clone https://github.com/knuesel/gst-airplay +cd gst-airplay +meson build +ninja -C build +``` + +You should now have the compiled plugin `libgstairplay.so` in the `build` +directory. To check that it is a valid GStreamer plugin, run: + +``` +gst-inspect-1.0 build/libgstairplay.so +``` + +This should display something such as + +``` +Plugin Details: + Name airplay + Description receive video through Apple AirPlay + Filename build/libgstairplay.so + Version 0.1 + License GPL + Source module gst-airplay-plugin + Binary package GStreamer airplay Plug-ins + Origin URL https://github.com/knuesel/gst-airplay + + airplaysrc: AirPlay source + + 1 features: + +-- 1 elements +``` + +If you get an error message, see the [troubleshooting](#troubleshooting) section. + +## Credits + +The pluging code is based on +[gst-template](https://gitlab.freedesktop.org/gstreamer/gst-template/) and uses +the AirPlay implementation from [RPiPlay](https://github.com/FD-/RPiPlay). + +## License + +The plugin makes use of [RPiPlay](https://github.com/FD-/RPiPlay) so it is +licensed under the GNU GPL 3.0.