morgan/UxPlay
1
0
Fork 0
mirror of https://github.com/morgan9e/UxPlay synced 2026-04-15 00:34:05 +09:00
Code Issues Packages Projects Releases Wiki Activity

edit README

Browse Source
This commit is contained in:
fduncanh
2022-06-02 17:39:18 -04:00
parent 3d530ff15c
commit a83dc53560
3 changed files with 234 additions and 223 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
README.html
View File

@@ -11,8 +11,8 @@
<li><strong>New</strong>: Support for Raspberry Pi, with hardware video acceleration by Video4Linux2 (replacement for 32-bit-only OpenMAX, which is no longer supported by Raspberry Pi OS). (For GStreamer &lt; 1.22, a <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patch</a> to the GStreamer Video4Linux2 plugin, available in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>, is required, unless your distribution has made a backport of changes from the development version.) See <a href="https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:">success reports</a>.</li> <li><strong>New</strong>: Support for Raspberry Pi, with hardware video acceleration by Video4Linux2 (replacement for 32-bit-only OpenMAX, which is no longer supported by Raspberry Pi OS). (For GStreamer &lt; 1.22, a <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patch</a> to the GStreamer Video4Linux2 plugin, available in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>, is required, unless your distribution has made a backport of changes from the development version.) See <a href="https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:">success reports</a>.</li>
</ul> </ul>
<p>This project is a GPLv3 open source unix AirPlay2 Mirror server for Linux, macOS, and *BSD. It was initially developed by <a href="http://github.com/antimof/Uxplay">antimof</a> using code from <a href="https://github.com/FD-/RPiPlay">RPiPlay</a>, which in turn derives from <a href="https://github.com/KqsMea8/AirplayServer">AirplayServer</a>, <a href="https://github.com/juhovh/shairplay">shairplay</a>, and <a href="https://github.com/EstebanKubata/playfair">playfair</a>. (The antimof site is no longer involved in development, but periodically posts updates pulled from the new main <a href="https://github.com/FDH2/UxPlay">UxPlay site</a>).</p> <p>This project is a GPLv3 open source unix AirPlay2 Mirror server for Linux, macOS, and *BSD. It was initially developed by <a href="http://github.com/antimof/Uxplay">antimof</a> using code from <a href="https://github.com/FD-/RPiPlay">RPiPlay</a>, which in turn derives from <a href="https://github.com/KqsMea8/AirplayServer">AirplayServer</a>, <a href="https://github.com/juhovh/shairplay">shairplay</a>, and <a href="https://github.com/EstebanKubata/playfair">playfair</a>. (The antimof site is no longer involved in development, but periodically posts updates pulled from the new main <a href="https://github.com/FDH2/UxPlay">UxPlay site</a>).</p>
<p>UxPlay is tested on a number of systems, including (among others) Debian 10.11 “Buster” and 11.2 “Bullseye”, Ubuntu 20.04 and 22.04, Linux Mint 20.3, Pop!_OS 21.10 (NVIDIA edition), Rocky Linux 8.5 (a CentOS successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), FreeBSD 13.0.</p> <p>UxPlay is tested on a number of systems, including (among others) Debian 10.11 “Buster” and 11.2 “Bullseye”, Ubuntu 20.04 and 22.04, Linux Mint 20.3, Pop!_OS 21.10 (NVIDIA edition), Rocky Linux 8.6 (a CentOS successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), FreeBSD 13.1.</p>
<p>Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a window on the server display (with the possibility of sharing that window on screen-sharing applications such as Zoom) on a host running Linux, macOS, or other unix. UxPlay supports a “legacy” form of Apple’s AirPlay 2 protocol introduced in iOS 12, and some features are missing. (Details of what is publically known about Apple’s AirPlay2 protocol can be found <a href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a> and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>).</p> <p>Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a window on the server display (with the possibility of sharing that window on screen-sharing applications such as Zoom) on a host running Linux, macOS, or other unix. UxPlay supports Apple’s AirPlay 2 protocol using “Legacy Pairing”, and some features are missing. (Details of what is publically known about Apple’s AirPlay 2 protocol can be found <a href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a> and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>).</p>
<p>The UxPlay server and its client must be on the same local area network, on which a <strong>Bonjour/Zeroconf mDNS/DNS-SD server</strong> is also running (only DNS-SD “Service Discovery” service is strictly necessary, it is not necessary that the local network also be of the “.local” mDNS-based type). On Linux and BSD Unix servers, this is usually provided by <a href="https://www.avahi.org">Avahi</a>, through the avahi-daemon service, and is included in most Linux distributions (this service can also be provided by macOS, iOS or Windows servers).</p> <p>The UxPlay server and its client must be on the same local area network, on which a <strong>Bonjour/Zeroconf mDNS/DNS-SD server</strong> is also running (only DNS-SD “Service Discovery” service is strictly necessary, it is not necessary that the local network also be of the “.local” mDNS-based type). On Linux and BSD Unix servers, this is usually provided by <a href="https://www.avahi.org">Avahi</a>, through the avahi-daemon service, and is included in most Linux distributions (this service can also be provided by macOS, iOS or Windows servers).</p>
<p>Connections to the UxPlay server by iOS/MacOS clients can be initiated both in AirPlay Mirror mode (which streams lossily-compressed AAC audio while mirroring the client screen, or in the alternative AirPlay Audio mode which streams Apple Lossless (ALAC) audio without screen mirroring (the accompanying cover art in this mode is not displayed, but metadata is displayed in the terminal). <em>Switching between these two modes during an active connection is possible: in Mirror mode, close the mirror window and start an Audio mode connection, switch back by initiating a Mirror mode connection.</em></p> <p>Connections to the UxPlay server by iOS/MacOS clients can be initiated both in AirPlay Mirror mode (which streams lossily-compressed AAC audio while mirroring the client screen, or in the alternative AirPlay Audio mode which streams Apple Lossless (ALAC) audio without screen mirroring (the accompanying cover art in this mode is not displayed, but metadata is displayed in the terminal). <em>Switching between these two modes during an active connection is possible: in Mirror mode, close the mirror window and start an Audio mode connection, switch back by initiating a Mirror mode connection.</em></p>
<ul> <ul>
@@ -24,12 +24,12 @@
<li><p><strong>VAAPI for Intel and AMD integrated graphics, NVIDIA with “Nouveau” open-source driver</strong></p> <li><p><strong>VAAPI for Intel and AMD integrated graphics, NVIDIA with “Nouveau” open-source driver</strong></p>
<p>With an Intel or AMD GPU, hardware decoding with the gstreamer open-source VAAPI gstreamer plugin is preferable. The open-source “Nouveau” drivers for NVIDIA graphics are also in principle supported: see <a href="https://nouveau.freedesktop.org/VideoAcceleration.html">here</a>, but this requires VAAPI to be supplemented with firmware extracted from the proprietary NVIDIA drivers.</p></li> <p>With an Intel or AMD GPU, hardware decoding with the gstreamer open-source VAAPI gstreamer plugin is preferable. The open-source “Nouveau” drivers for NVIDIA graphics are also in principle supported: see <a href="https://nouveau.freedesktop.org/VideoAcceleration.html">here</a>, but this requires VAAPI to be supplemented with firmware extracted from the proprietary NVIDIA drivers.</p></li>
<li><p><strong>NVIDIA with proprietary drivers</strong></p> <li><p><strong>NVIDIA with proprietary drivers</strong></p>
<p>The <code>nvh264dec</code> plugin (included in gstreamer1.0-plugins-bad since GStreamer-1.18.0) can be used for accelerated video decoding on the NVIDIA GPU after NVIDIA’s CUDA driver <code>libcuda.so</code> is installed. This plugin should be used with options <code>uxplay -vd nvh264dec -vs glimagesink</code>. For GStreamer-1.16.3 or earlier, replace <code>nvh264dec</code> by the older plugin<code>nvdec</code>, which must be built by the user: See <a href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">these instructions</a>.</p></li> <p>The <code>nvh264dec</code> plugin (included in gstreamer1.0-plugins-bad since GStreamer-1.18.0) can be used for accelerated video decoding on the NVIDIA GPU after NVIDIA’s CUDA driver <code>libcuda.so</code> is installed. (This plugin should be used with options <code>uxplay -vd nvh264dec -vs glimagesink</code>.) For GStreamer-1.16.3 or earlier, replace <code>nvh264dec</code> by the older plugin <code>nvdec</code>, which must be built by the user: See <a href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">these instructions</a>.</p></li>
<li><p><strong>Video4Linux2 support for the Raspberry Pi Broadcom GPU</strong></p> <li><p><strong>Video4Linux2 support for the Raspberry Pi Broadcom GPU</strong></p>
<p>Raspberry Pi (RPi) computers can run UxPlay with software decoding of h264 video but this usually has unacceptable latency, and hardware-accelerated GPU decoding should be used. Distributions such as RPi OS (Bullseye) release have dropped support for unmaintained 32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in favor of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that allow it to work with UxPlay on RPi are now in the GStreamer development branch, and will appear in the upcoming GStreamer-1.22 release. A (partial) backport (as <code>gstreamer1.0-plugins-good-1.18.4-2+~rpt1</code>) has already appeared in RPi OS updates. Until the full update appears, or if you are using a different distribution, you can find <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patching instructions for GStreamer</a> in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>. Patches are available GStreamer releases 1.18.4 and later.</p></li> <p>Raspberry Pi (RPi) computers can run UxPlay with software decoding of h264 video but this usually has unacceptable latency, and hardware-accelerated GPU decoding should be used. Distributions such as RPi OS (Bullseye) release have recently dropped support for 32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in favor of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that allow it to work with UxPlay on RPi are now in the GStreamer development branch, and will appear in the upcoming GStreamer-1.22 release. A (partial) backport (as <code>gstreamer1.0-plugins-good-1.18.4-2+~rpt1</code>) has already appeared in RPi OS updates. Until the full update appears, or for other distributions, you can find <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patching instructions for GStreamer</a> in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a> for GStreamer 1.18.4 and later.</p></li>
</ul> </ul>
<h3 id="note-to-packagers-openssl-3.0.0-solves-gpl-v3-license-issues.">Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.</h3> <h3 id="note-to-packagers-openssl-3.0.0-solves-gpl-v3-license-issues.">Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.</h3>
<p>Some Linux distributions such as Debian do not allow distribution of compiled GPL code linked to OpenSSL-1.1.1 because its “dual OpenSSL/SSLeay” license has some incompatibilities with GPL, unless all code authors have explicitly given an “exception” to allow such linking (the historical origins of UxPlay make this impossible to obtain). Other distributions treat OpenSSL as a “System Library” which the GPL allows linking to.</p> <p>Some Linux distributions such as Debian do not allow distribution of compiled GPL code linked to OpenSSL-1.1.1 because its license has some incompatibilities with GPL code, unless all authors have given an “exception” to allow such linking (the historical origins of UxPlay make this impossible to obtain). Other distributions treat OpenSSL as a “System Library” to which the GPL allows linking.</p>
<p>For “GPL-strict” distributions, UxPlay can be built using OpenSSL- 3.0.0, which has a new <a href="https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/">GPLv3-compatible license</a>.</p> <p>For “GPL-strict” distributions, UxPlay can be built using OpenSSL- 3.0.0, which has a new <a href="https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/">GPLv3-compatible license</a>.</p>
<h1 id="getting-uxplay">Getting UxPlay:</h1> <h1 id="getting-uxplay">Getting UxPlay:</h1>
<p>Either download and unzip <a href="https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip">UxPlay-master.zip</a>, or (if git is installed): “git clone https://github.com/FDH2/UxPlay”. You can also download a recent or earlier version listed in <a href="https://github.com/FDH2/UxPlay/releases">Releases</a>.</p> <p>Either download and unzip <a href="https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip">UxPlay-master.zip</a>, or (if git is installed): “git clone https://github.com/FDH2/UxPlay”. You can also download a recent or earlier version listed in <a href="https://github.com/FDH2/UxPlay/releases">Releases</a>.</p>
@@ -37,7 +37,7 @@
<h2 id="building-uxplay-on-linux-or-bsd">Building UxPlay on Linux (or *BSD):</h2> <h2 id="building-uxplay-on-linux-or-bsd">Building UxPlay on Linux (or *BSD):</h2>
<p>(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS, see below). See <a href="#troubleshooting">Troubleshooting</a> below for help with any difficulties.</p> <p>(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS, see below). See <a href="#troubleshooting">Troubleshooting</a> below for help with any difficulties.</p>
<p>You need a C/C++ compiler (e.g. g++) with the standard development libraries installed. Debian-based systems provide a package “build-essential” for use in compiling software. You also need pkg-config: if it is not found by “<code>which pkg-config</code>”, install pkg-config or its work-alike replacement pkgconf. Also make sure that cmake&gt;=3.4.1 is installed: “<code>sudo apt-get install cmake</code>” (add <code>build-essential</code> and <code>pkg-config</code> (or <code>pkgconf</code>) to this if needed).</p> <p>You need a C/C++ compiler (e.g. g++) with the standard development libraries installed. Debian-based systems provide a package “build-essential” for use in compiling software. You also need pkg-config: if it is not found by “<code>which pkg-config</code>”, install pkg-config or its work-alike replacement pkgconf. Also make sure that cmake&gt;=3.4.1 is installed: “<code>sudo apt-get install cmake</code>” (add <code>build-essential</code> and <code>pkg-config</code> (or <code>pkgconf</code>) to this if needed).</p>
<p>Make sure that your distribution provides OpenSSL 1.1.1 or later, and libplist 2.0 or later. (This means Debian 10 “Buster”, Ubuntu 18.04 or later.) If it does not, you may need to build and install these from source (see below).</p> <p>Make sure that your distribution provides OpenSSL 1.1.1 or later, and libplist 2.0 or later. (This means Debian 10 “Buster”, Ubuntu 18.04 or later.) If it does not, you may need to build and install these from source (see instructions at the end of this README). If you have a non-standard OpenSSL installation, you may need to set the environment variable OPENSSL_ROOT_DIR (<em>e.g.</em> , “<code>export OPENSSL_ROOT_DIR=/usr/local/lib64</code>” if that is where it is installed).</p>
<p>In a terminal window, change directories to the source directory of the downloaded source code (“UxPlay-*”, “*” = “master” or the release tag for zipfile downloads, “UxPlay” for “git clone” downloads), then follow the instructions below:</p> <p>In a terminal window, change directories to the source directory of the downloaded source code (“UxPlay-*”, “*” = “master” or the release tag for zipfile downloads, “UxPlay” for “git clone” downloads), then follow the instructions below:</p>
<p><strong>Note:</strong> By default UxPlay will be built with optimization for the computer it is built on; when this is not the case, as when you are packaging for a distribution, use the cmake option <code>-DNO_MARCH_NATIVE=ON</code>.</p> <p><strong>Note:</strong> By default UxPlay will be built with optimization for the computer it is built on; when this is not the case, as when you are packaging for a distribution, use the cmake option <code>-DNO_MARCH_NATIVE=ON</code>.</p>
<ol type="1"> <ol type="1">
@@ -51,37 +51,34 @@
</ol> </ol>
<p><em>If you intend to modify the code, use a separate “build” directory: replace</em> “<code>cmake [ ] .</code>” <em>by</em> “<code>mkdir build ; cd build ; cmake [ ] ..</code>”; <em>you can then clean the build directory with</em> “<code>rm -rf build/*</code>” <em>(run from within the UxPlay source directory) without affecting the source directories which contain your modifications</em>.</p> <p><em>If you intend to modify the code, use a separate “build” directory: replace</em> “<code>cmake [ ] .</code>” <em>by</em> “<code>mkdir build ; cd build ; cmake [ ] ..</code>”; <em>you can then clean the build directory with</em> “<code>rm -rf build/*</code>” <em>(run from within the UxPlay source directory) without affecting the source directories which contain your modifications</em>.</p>
<p>The above script installs the executable file “<code>uxplay</code>” to <code>/usr/local/bin</code>, (and installs a manpage to somewhere like <code>/usr/local/share/man/man1</code> and README files to somewhere like <code>/usr/local/share/doc/uxplay</code>). It can also be found in the build directory after the build processs.</p> <p>The above script installs the executable file “<code>uxplay</code>” to <code>/usr/local/bin</code>, (and installs a manpage to somewhere like <code>/usr/local/share/man/man1</code> and README files to somewhere like <code>/usr/local/share/doc/uxplay</code>). It can also be found in the build directory after the build processs.</p>
<p><strong>Finally, run uxplay in a terminal window</strong>. If it is not seen by the iOS client’s drop-down “Screen Mirroring” panel, check that your DNS-SD server (usually avahi-daemon) is running: do this in a terminal window with <code>systemctl status avahi-daemon</code>. If this shows the avahi-daemon is not running, control it with <code>sudo systemctl [start,stop,enable,disable] avahi-daemon</code> (or avahi-daemon.service). If UxPlay is seen, but the client fails to connect when it is selected, there may be a firewall on the server that prevents UxPlay from receiving client connection requests unless some network ports are opened. See <a href="#troubleshooting">Troubleshooting</a> below for help with this or other problems.</p> <p><strong>Finally, run uxplay in a terminal window</strong>. Use Ctrl-C (or close the window) to terminate it when done. If it is not seen by the iOS client’s drop-down “Screen Mirroring” panel, check that your DNS-SD server (usually avahi-daemon) is running: do this in a terminal window with <code>systemctl status avahi-daemon</code>. If this shows the avahi-daemon is not running, control it with <code>sudo systemctl [start,stop,enable,disable] avahi-daemon</code> (or avahi-daemon.service). If UxPlay is seen, but the client fails to connect when it is selected, there may be a firewall on the server that prevents UxPlay from receiving client connection requests unless some network ports are opened. See <a href="#troubleshooting">Troubleshooting</a> below for help with this or other problems.</p>
<p>One common problem involves GStreamer attempting to use incorrectly-configured or absent accelerated hardware h264 video decoding (e.g., VAAPI). Try “<code>uxplay -avdec</code>” to force software video decoding; if this works you can then try to fix accelerated hardware video decoding if you need it. See <a href="#usage">Usage</a> for more run-time options.</p> <p>One common problem involves GStreamer attempting to use incorrectly-configured or absent accelerated hardware h264 video decoding (e.g., VAAPI). Try “<code>uxplay -avdec</code>” to force software video decoding; if this works you can then try to fix accelerated hardware video decoding if you need it. See <a href="#usage">Usage</a> for more run-time options.</p>
<p><strong>Raspberry Pi</strong>: For GStreamer-1.20 or earlier, see <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patching instructions for GStreamer</a>. If “<code>uxplay</code>” by itself does not work, use “<code>uxplay -v4l2</code>” (or use “<code>-rpi</code>” as a synonym for “<code>-v4l2</code>”) on your desktop X11 system, and optionally specify a videosink with “<code>-vs ..</code>”; use “<code>uxplay -rpiwl</code>” as a synonym for “<code>-v4l2 -vs waylandsink</code>” on a desktop system with Wayland (this applies to Ubuntu). On a system without X11 that uses framebuffer video (such as RPi OS Bullseye “Lite”) use “<code>uxplay -rpifb</code>” as a synonym for “<code>uxplay -v4l2 -vs kmssink</code>”. You can test UxPlay with software-only video decoding using option <code>-avdec</code>.</p> <p><strong>Raspberry Pi</strong>: GStreamer-1.18.4 or later required for hardware video decoding; for 1.20 or earlier, also see <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patching instructions for GStreamer</a>. If “<code>uxplay</code>” by itself does not work, use “<code>uxplay -v4l2</code>” (or use “<code>-rpi</code>” as a synonym for “<code>-v4l2</code>”) on your desktop X11 system, and optionally specify a videosink with “<code>-vs ..</code>”; use “<code>uxplay -rpiwl</code>” as a synonym for “<code>-v4l2 -vs waylandsink</code>” on a desktop system with Wayland (this applies to recent Ubuntu). On a system without X11 that uses framebuffer video (such as RPi OS Bullseye “Lite”) use “<code>uxplay -rpifb</code>” as a synonym for “<code>uxplay -v4l2 -vs kmssink</code>”. You can test UxPlay with software-only video decoding using option <code>-avdec</code>.</p>
<ul> <ul>
<li><p><strong>Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma Linux):</strong> (sudo yum install) openssl-devel libplist-devel avahi-compat-libdns_sd-devel (some from the “PowerTools” add-on repository) (+libX11-devel for ZOOMFIX). The required GStreamer packages (some from <a href="https://rpmfusion.org">rpmfusion.org</a>) are: gstreamer1-devel gstreamer1-plugins-base-devel gstreamer1-libav gstreamer1-plugins-bad-free (+ gstreamer1-vaapi for intel graphics).</p></li> <li><p><strong>Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma Linux):</strong> (sudo yum install) openssl-devel libplist-devel avahi-compat-libdns_sd-devel (some from the “PowerTools” add-on repository) (+libX11-devel for ZOOMFIX). The required GStreamer packages (some from <a href="https://rpmfusion.org">rpmfusion.org</a>) are: gstreamer1-devel gstreamer1-plugins-base-devel gstreamer1-libav gstreamer1-plugins-bad-free (+ gstreamer1-vaapi for intel graphics).</p></li>
<li><p><strong>OpenSUSE:</strong> (sudo zypper install) libopenssl-devel libplist-devel avahi-compat-mDNSResponder-devel (+ libX11-devel for ZOOMFIX). The required GStreamer packages (you may need to use versions from <a href="https://ftp.gwdg.de/pub/linux/misc/packman/suse/">Packman</a>) are: gstreamer-devel gstreamer-plugins-base-devel gstreamer-plugins-libav gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel graphics).</p></li> <li><p><strong>OpenSUSE:</strong> (sudo zypper install) libopenssl-devel libplist-devel avahi-compat-mDNSResponder-devel (+ libX11-devel for ZOOMFIX). The required GStreamer packages (you may need to use versions from <a href="https://ftp.gwdg.de/pub/linux/misc/packman/suse/">Packman</a>) are: gstreamer-devel gstreamer-plugins-base-devel gstreamer-plugins-libav gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel graphics).</p></li>
<li><p><strong>Arch Linux</strong> (sudo pacman -Syu) openssl libplist avahi gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav (+ gstreamer-vaapi for Intel graphics). (<strong>Also available as a package in AUR</strong>).</p></li> <li><p><strong>Arch Linux</strong> (sudo pacman -Syu) openssl libplist avahi gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav (+ gstreamer-vaapi for Intel graphics). (<strong>Also available as a package in AUR</strong>).</p></li>
<li><p><strong>FreeBSD:</strong> (sudo pkg install) libplist gstreamer1, gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk, gl, vulkan, pulse …), (+ gstreamer1-vaapi for Intel graphics). Either avahi-libdns or mDNSResponder must also be installed to provide the dns_sd library. OpenSSL is already installed as a System Library. “ZOOMFIX” is untested; don’t try to use it on FreeBSD unless you need it.</p></li> <li><p><strong>FreeBSD:</strong> (sudo pkg install) libplist gstreamer1, gstreamer1-libav, gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk, gl, vulkan, pulse …), (+ gstreamer1-vaapi for Intel graphics). Either avahi-libdns or mDNSResponder must also be installed to provide the dns_sd library. OpenSSL is already installed as a System Library. “ZOOMFIX” is untested; don’t try to use it on FreeBSD unless you need it.</p></li>
</ul> </ul>
<h3 id="building-openssl-1.1.1-from-source.">Building OpenSSL &gt;= 1.1.1 from source.</h3> <h2 id="building-uxplay-on-macos-intel-x86_64-and-apple-silicon-m1-macs">Building UxPlay on macOS: <strong>(Intel X86_64 and “Apple Silicon” M1 Macs)</strong></h2>
<p>If you need to do this, note that you may be able to use a newer version (OpenSSL-3.0.1 is known to work). You will need the standard development toolset (autoconf, automake, libtool). Download the source code from <a href="https://www.openssl.org/source/">https://www.openssl.org/source/</a>. Install the downloaded openssl by opening a terminal in your Downloads directory, and unpacking the source distribution: (“tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1”). Then build/install with “./config ; make ; sudo make install_dev”. This will typically install the needed library <code>libcrypto.*</code>, either in /usr/local/lib or /usr/local/lib64. <em>(Ignore the following for builds on MacOS:)</em> Assuming the library was placed in /usr/local/lib64, you must “export OPENSSL_ROOT_DIR=/usr/local/lib64” before running cmake. On some systems like Debian or Ubuntu, you may also need to add a missing entry <code>/usr/local/lib64</code> in /etc/ld.so.conf (or place a file containing “/usr/local/lib64/libcrypto.so” in /etc/ld.so.conf.d) and then run “sudo ldconfig”.</p>
<h3 id="bulding-libplist-2.0.0-from-source.">Bulding libplist &gt;= 2.0.0 from source.</h3>
<p><em>(Note: on Debian 9 “Stretch” or Ubuntu 16.04 LTS editions, you can avoid this step by installing libplist-dev and libplist3 from Debian 10 or Ubuntu 18.04.)</em> As well as the usual build tools (autoconf, automake, libtool), you may need to also install some libpython*-dev package. Download the latest source from <a href="https://github.com/libimobiledevice/libplist">https://github.com/libimobiledevice/libplist</a>: get <a href="https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip">libplist-master.zip</a>, then (“unzip libplist-master.zip ; cd libplist-master”), build/install (“./autogen.sh ; make ; sudo make install”). This will probably install libplist-2.0.* in /usr/local/lib. <em>(Ignore the following for builds on MacOS:)</em> On some systems like Debian or Ubuntu, you may also need to add a missing entry <code>/usr/local/lib</code> in /etc/ld.so.conf (or place a file containing “/usr/local/lib/libplist-2.0.so” in /etc/ld.so.conf.d) and then run “sudo ldconfig”.</p>
<h2 id="building-uxplay-on-macos-now-tested-on-both-intel-x86_64-and-apple-silicon-m1-macs">Building UxPlay on macOS: <strong>(Now tested on both Intel X86_64 and “Apple Silicon” M1 Macs)</strong></h2>
<p><em>Note: A native AirPlay Server feature is included in macOS 12 Monterey, but is restricted to recent hardware. UxPlay can run on older macOS systems that will not be able to run Monterey, or can run Monterey but not AirPlay.</em></p> <p><em>Note: A native AirPlay Server feature is included in macOS 12 Monterey, but is restricted to recent hardware. UxPlay can run on older macOS systems that will not be able to run Monterey, or can run Monterey but not AirPlay.</em></p>
<p>These instructions for macOS asssume that the Xcode command-line developer tools are installed (if Xcode is installed, open the Terminal, type “sudo xcode-select –install” and accept the conditions).</p> <p>These instructions for macOS asssume that the Xcode command-line developer tools are installed (if Xcode is installed, open the Terminal, type “sudo xcode-select –install” and accept the conditions).</p>
<p>It is also assumed that CMake &gt;= 3.13 is installed: this can be done with package managers <a href="http://www.macports.org">MacPorts</a>, <a href="http://finkproject.org">Fink</a> or <a href="http://brew.sh">Homebrew</a>, or by a download from <a href="https://cmake.org/download/">https://cmake.org/download/</a>.</p> <p>It is also assumed that CMake &gt;= 3.13 is installed: this can be done with package managers <a href="http://www.macports.org">MacPorts</a>, <a href="http://finkproject.org">Fink</a> or <a href="http://brew.sh">Homebrew</a>, or by a download from <a href="https://cmake.org/download/">https://cmake.org/download/</a>.</p>
<p>First get the latest macOS release of GStreamer-1.0 from <a href="https://gstreamer.freedesktop.org/download/">https://gstreamer.freedesktop.org/download/</a>. Install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.2. install <code>gstreamer-1.0-1.20.2-universal.pkg</code> and <code>gstreamer-1.0-devel-1.20.2-universal.pkg</code>. (If you have an Intel-architecture Mac, and have problems with the “universal” packages, you can also use <code>gstreamer-1.0-1.18.6-x86_64.pkg</code> and <code>gstreamer-1.0-devel-1.18.6-x86_64.pkg</code>.) Click on them to install (they install to /Library/FrameWorks/GStreamer.framework). It is recommended you use GStreamer.framework rather than install Gstreamer with Homebrew or MacPorts (see later).</p> <p>First install OpenSSL and libplist: static versions of these libaries will be used, so they can be uninstalled after UxPlay is built. These are available in MacPorts and Homebrew, or they can easily be built from source (see instructions at the end of this README; this requires development tools autoconf, automake, libtool, which can be installed using MacPorts, HomeBrew, or Fink).</p>
<p>Next install OpenSSL and libplist: these can be built from source (see above), in which case you may need to install the standard development tools autoconf, automake, libtool, which can be done with MacPorts, HomeBrew, or Fink. Only the static forms of the two libraries will used for the macOS build, so you can uninstall them (“sudo make uninstall”) after you have built UxPlay. It may be easier to get them using MacPorts “sudo port install openssl libplist-devel” or Homebrew “brew install openssl libplist” (but not Fink). if you don’t have MacPorts or Homebrew installed, you can just install one of them before building uxplay, and uninstall afterwards if it is not wanted.</p> <p>Next get the latest macOS release of GStreamer-1.0.</p>
<ul>
<li>recommended: install the “official” GStreamer release for macOS from <a href="https://gstreamer.freedesktop.org/download/">https://gstreamer.freedesktop.org/download/</a>. The alternative is to install it from Homebrew (MacPorts also supplies it, but compiled to use X11).</li>
</ul>
<p><strong>For the “official” release</strong>: install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.2. install <code>gstreamer-1.0-1.20.2-universal.pkg</code> and <code>gstreamer-1.0-devel-1.20.2-universal.pkg</code>. (If you have an Intel-architecture Mac, and have problems with the “universal” packages, you can also use <code>gstreamer-1.0-1.18.6-x86_64.pkg</code> and <code>gstreamer-1.0-devel-1.18.6-x86_64.pkg</code>.) Click on them to install (they install to /Library/FrameWorks/GStreamer.framework).</p>
<p><strong>For Homebrew</strong>: pkgconfig is needed (“brew install pkgconfig”). Then “brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav”. This appears to be functionally equivalent to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. <strong>You may need to set the environment variable GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0 to point to the Homebrew GStreamer installation.</strong></p>
<p>Finally, build and install uxplay (without ZOOMFIX): open a terminal and change into the UxPlay source directory (“UxPlay-master” for zipfile downloads, “UxPlay” for “git clone” downloads) and build/install with “cmake . ; make ; sudo make install” (same as for Linux).</p> <p>Finally, build and install uxplay (without ZOOMFIX): open a terminal and change into the UxPlay source directory (“UxPlay-master” for zipfile downloads, “UxPlay” for “git clone” downloads) and build/install with “cmake . ; make ; sudo make install” (same as for Linux).</p>
<ul> <ul>
<li><p>On macOS with this installation of GStreamer, the only videosinks available seem to be glimagesink (default choice made by autovideosink) and osxvideosink. (It seems that vaapisink is not supported on macOS). The window title does not show the Airplay server name, but the window is visible to screen-sharing apps (e.g., Zoom). The only available audiosink seems to be osxaudiosink.</p></li> <li><p>On macOS with this installation of GStreamer, the only videosinks available seem to be glimagesink (default choice made by autovideosink) and osxvideosink. The window title does not show the Airplay server name, but the window is visible to screen-sharing apps (e.g., Zoom). The only available audiosink seems to be osxaudiosink.</p></li>
<li><p>On macOS, the option -t <em>timeout</em> is currently suppressed, and the option -nc is always used, whether or not it is selected. This is a workaround until a problem with GStreamer videosinks on macOS is fixed: if the GStreamer pipeline is destroyed while the mirror window is still open, a segfault occurs.</p></li> <li><p>The option -t <em>timeout</em> is currently suppressed, and the option -nc is always used, whether or not it is selected. This is a workaround for a problem with GStreamer videosinks on macOS: if the GStreamer pipeline is destroyed while the mirror window is still open, a segfault occurs.</p></li>
<li><p>In the case of glimagesink, the resolution settings “-s wxh” do not affect the (small) initial OpenGL mirror window size, but the window can be expanded using the mouse or trackpad. In contrast, a window created with “-vs osxvideosink” is initially big, but has the wrong aspect ratio (stretched image); in this case the aspect ratio changes when the window width is changed by dragging its side.</p></li> <li><p>In the case of glimagesink, the resolution settings “-s wxh” do not affect the (small) initial OpenGL mirror window size, but the window can be expanded using the mouse or trackpad. In contrast, a window created with “-vs osxvideosink” is initially big, but has the wrong aspect ratio (stretched image); in this case the aspect ratio changes when the window width is changed by dragging its side.</p></li>
</ul> </ul>
<p><strong><em>Other ways (Homebrew, MacPorts) to install GStreamer on macOS (not recommended):</em></strong></p> <p><strong><em>Using GStreamer installed from MacPorts (not recommended):</em></strong></p>
<p>First make sure that pkgconfig is installed (Homebrew: “brew install pkgconfig” ; MacPorts: “sudo port install pkgconfig” ).</p> <p>To install: “sudo port install pkgconfig”; “sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav”. <strong>The MacPorts GStreamer is built to use X11</strong>, so uxplay must be run from an XQuartz terminal, can use ZOOMFIX, and needs option “-vs ximagesink”. On an unibody (non-retina) MacBook Pro, the default resolution wxh = 1920x1080 was too large, but using option “-s 800x600” worked. The MacPorts GStreamer pipeline seems fragile against attempts to change the X11 window size, or to rotations that switch a connected client between portrait and landscape mode while uxplay is running. Using the MacPorts X11 GStreamer seems only possible if the image size is left unchanged from the initial “-s wxh” setting (also use the iPad/iPhone setting that locks the screen orientation against switching between portrait and landscape mode as the device is rotated).</p>
<ol type="a">
<li><p>with Homebrew: “brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav”. This appears to be functionally equivalent to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies. <strong>You may need to set the environment variable GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0 to point to the Homebrew GStreamer installation.</strong></p></li>
<li><p>with MacPorts: “sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav”. <strong>The MacPorts GStreamer is built to use X11</strong>, so uxplay must be run from an XQuartz terminal, can use ZOOMFIX, and needs option “-vs ximagesink”. On an older unibody MacBook Pro, the default resolution wxh = 1920x1080 was too large for the non-retina display, but using option “-s 800x600” worked; However, the GStreamer pipeline is fragile against attempts to change the X11 window size, or to rotations that switch a connected client between portrait and landscape mode while uxplay is running. Using the MacPorts X11 GStreamer is only viable if the image size is left unchanged from the initial “-s wxh” setting (also use the iPad/iPhone setting that locks the screen orientation against switching between portrait and landscape mode as the device is rotated).</p></li>
</ol>
<h1 id="usage">Usage</h1> <h1 id="usage">Usage</h1>
<p>Options:</p> <p>Options:</p>
<p><strong>-p</strong> allows you to select the network ports used by UxPlay (these need to be opened if the server is behind a firewall). By itself, -p sets “legacy” ports TCP 7100, 7000, 7001, UDP 6000, 6001, 7011. -p n (e.g. -p 35000) sets TCP and UDP ports n, n+1, n+2. -p n1,n2,n3 (comma-separated values) sets each port separately; -p n1,n2 sets ports n1,n2,n2+1. -p tcp n or -p udp n sets just the TCP or UDP ports. Ports must be in the range [1024-65535].</p> <p><strong>-p</strong> allows you to select the network ports used by UxPlay (these need to be opened if the server is behind a firewall). By itself, -p sets “legacy” ports TCP 7100, 7000, 7001, UDP 6000, 6001, 7011. -p n (e.g. -p 35000) sets TCP and UDP ports n, n+1, n+2. -p n1,n2,n3 (comma-separated values) sets each port separately; -p n1,n2 sets ports n1,n2,n2+1. -p tcp n or -p udp n sets just the TCP or UDP ports. Ports must be in the range [1024-65535].</p>
@@ -175,6 +172,12 @@
<p>A workaround is to manually make the X11 window visible to screen-sharing apps with the X11 utility xdotool, if it is installed, with: <code>xdotool selectwindow set_window --name &lt;name&gt;</code> (where <code>&lt;name&gt;</code> is your choice of name), and then select the uxplay window by clicking on it with the mouse.</p> <p>A workaround is to manually make the X11 window visible to screen-sharing apps with the X11 utility xdotool, if it is installed, with: <code>xdotool selectwindow set_window --name &lt;name&gt;</code> (where <code>&lt;name&gt;</code> is your choice of name), and then select the uxplay window by clicking on it with the mouse.</p>
<p>However, if “<code>cmake -DZOOMFIX=ON .</code>” is run before compiling, the mirrored window is visible to screen-sharing applications, without this procedure. To compile with ZOOMFIX=ON, the X11 development libraries must be installed. (Without ZOOMFIX, UxPlay has no dependence on X11).</p> <p>However, if “<code>cmake -DZOOMFIX=ON .</code>” is run before compiling, the mirrored window is visible to screen-sharing applications, without this procedure. To compile with ZOOMFIX=ON, the X11 development libraries must be installed. (Without ZOOMFIX, UxPlay has no dependence on X11).</p>
<p><strong>ZOOMFIX is not needed in GStreamer-1.20 or later.</strong> Thanks to David Ventura https://github.com/DavidVentura/UxPlay for the fix and also for getting a fix into gstreamer-1.20.</p> <p><strong>ZOOMFIX is not needed in GStreamer-1.20 or later.</strong> Thanks to David Ventura https://github.com/DavidVentura/UxPlay for the fix and also for getting a fix into gstreamer-1.20.</p>
<h3 id="building-openssl-1.1.1-from-source.">Building OpenSSL &gt;= 1.1.1 from source.</h3>
<p>If you need to do this, note that you may be able to use a newer version (OpenSSL-3.0.1 is known to work). You will need the standard development toolset (autoconf, automake, libtool). Download the source code from <a href="https://www.openssl.org/source/">https://www.openssl.org/source/</a>. Install the downloaded openssl by opening a terminal in your Downloads directory, and unpacking the source distribution: (“tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1”). Then build/install with “./config ; make ; sudo make install_dev”. This will typically install the needed library <code>libcrypto.*</code>, either in /usr/local/lib or /usr/local/lib64.</p>
<p><em>(Ignore the following for builds on MacOS:)</em> On some systems like Debian or Ubuntu, you may also need to add a missing entry <code>/usr/local/lib64</code> in /etc/ld.so.conf (or place a file containing “/usr/local/lib64/libcrypto.so” in /etc/ld.so.conf.d) and then run “sudo ldconfig”.</p>
<h3 id="building-libplist-2.0.0-from-source.">Building libplist &gt;= 2.0.0 from source.</h3>
<p><em>(Note: on Debian 9 “Stretch” or Ubuntu 16.04 LTS editions, you can avoid this step by installing libplist-dev and libplist3 from Debian 10 or Ubuntu 18.04.)</em> As well as the usual build tools (autoconf, automake, libtool), you may need to also install some libpython*-dev package. Download the latest source from <a href="https://github.com/libimobiledevice/libplist">https://github.com/libimobiledevice/libplist</a>: get <a href="https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip">libplist-master.zip</a>, then (“unzip libplist-master.zip ; cd libplist-master”), build/install (“./autogen.sh ; make ; sudo make install”). This will probably install libplist-2.0.* in /usr/local/lib.</p>
<p><em>(Ignore the following for builds on MacOS:)</em> On some systems like Debian or Ubuntu, you may also need to add a missing entry <code>/usr/local/lib</code> in /etc/ld.so.conf (or place a file containing “/usr/local/lib/libplist-2.0.so” in /etc/ld.so.conf.d) and then run “sudo ldconfig”.</p>
<h1 id="disclaimer">Disclaimer</h1> <h1 id="disclaimer">Disclaimer</h1>
<p>All the resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to.</p> <p>All the resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to.</p>
<p>This project makes use of a third-party GPL library for handling FairPlay. The legal status of that library is unclear. Should you be a representative of Apple and have any objections against the legality of the library and its use in this project, please contact me and I’ll take the appropriate steps.</p> <p>This project makes use of a third-party GPL library for handling FairPlay. The legal status of that library is unclear. Should you be a representative of Apple and have any objections against the legality of the library and its use in this project, please contact me and I’ll take the appropriate steps.</p>

165
README.md
View File

@@ -41,15 +41,14 @@ main [UxPlay site](https://github.com/FDH2/UxPlay)).
UxPlay is tested on a number of systems, including (among others) Debian 10.11 "Buster" and 11.2 "Bullseye", Ubuntu 20.04 and 22.04, UxPlay is tested on a number of systems, including (among others) Debian 10.11 "Buster" and 11.2 "Bullseye", Ubuntu 20.04 and 22.04,
Linux Mint 20.3, Pop!\_OS 21.10 (NVIDIA edition), Linux Mint 20.3, Pop!\_OS 21.10 (NVIDIA edition),
Rocky Linux 8.5 (a CentOS successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), FreeBSD 13.0. Rocky Linux 8.6 (a CentOS successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), FreeBSD 13.1.
Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients
(iPhones, iPads, MacBooks) in a window (iPhones, iPads, MacBooks) in a window
on the server display (with the possibility of on the server display (with the possibility of
sharing that window on screen-sharing applications such as Zoom) sharing that window on screen-sharing applications such as Zoom)
on a host running Linux, macOS, or other unix. UxPlay supports a "legacy" form of Apple's AirPlay 2 protocol introduced on a host running Linux, macOS, or other unix. UxPlay supports Apple's AirPlay 2 protocol using "Legacy Pairing", and some features are missing.
in iOS 12, and some features are missing. (Details of what is publically known about Apple's AirPlay 2 protocol can be found
(Details of what is publically known about Apple's AirPlay2 protocol can be found
[here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol) and [here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol) and
[here](https://emanuelecozzi.net/docs/airplay2)). [here](https://emanuelecozzi.net/docs/airplay2)).
@@ -98,9 +97,9 @@ h264 decoders if available; if not, software decoding is used.
(included in gstreamer1.0-plugins-bad since GStreamer-1.18.0) (included in gstreamer1.0-plugins-bad since GStreamer-1.18.0)
can be used for accelerated video decoding on the NVIDIA GPU after can be used for accelerated video decoding on the NVIDIA GPU after
NVIDIA's CUDA driver `libcuda.so` is installed. NVIDIA's CUDA driver `libcuda.so` is installed.
This plugin should be used with options (This plugin should be used with options
`uxplay -vd nvh264dec -vs glimagesink`. For GStreamer-1.16.3 `uxplay -vd nvh264dec -vs glimagesink`.) For GStreamer-1.16.3
or earlier, replace `nvh264dec` by the older plugin`nvdec`, which or earlier, replace `nvh264dec` by the older plugin `nvdec`, which
must be built by the user: must be built by the user:
See [these instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins). See [these instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
@@ -110,24 +109,23 @@ h264 decoders if available; if not, software decoding is used.
of h264 video but this of h264 video but this
usually has unacceptable latency, and hardware-accelerated GPU decoding usually has unacceptable latency, and hardware-accelerated GPU decoding
should be used. Distributions such as RPi OS (Bullseye) release have should be used. Distributions such as RPi OS (Bullseye) release have
dropped support for unmaintained 32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in recently dropped support for 32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in
favor of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that allow it to favor of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that allow it to
work with UxPlay on RPi are now in the GStreamer development work with UxPlay on RPi are now in the GStreamer development
branch, and will appear in the upcoming GStreamer-1.22 release. branch, and will appear in the upcoming GStreamer-1.22 release.
A (partial) backport (as `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`) A (partial) backport (as `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`)
has already appeared in RPi OS updates. Until the full update has already appeared in RPi OS updates. Until the full update
appears, or if you are using a different distribution, you can find appears, or for other distributions, you can find
[patching instructions for GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) [patching instructions for GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki). Patches in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki) for GStreamer 1.18.4 and later.
are available GStreamer releases 1.18.4 and later.
### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues. ### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.
Some Linux distributions such as Debian do not allow distribution of compiled Some Linux distributions such as Debian do not allow distribution of compiled
GPL code linked to OpenSSL-1.1.1 because its "dual OpenSSL/SSLeay" license GPL code linked to OpenSSL-1.1.1 because its license
has some incompatibilities with GPL, unless all code authors have explicitly has some incompatibilities with GPL code, unless all authors have
given an "exception" to allow such linking (the historical origins of UxPlay given an "exception" to allow such linking (the historical origins of UxPlay
make this impossible to obtain). Other distributions make this impossible to obtain). Other distributions
treat OpenSSL as a "System Library" which the GPL allows linking to. treat OpenSSL as a "System Library" to which the GPL allows linking.
For "GPL-strict" distributions, UxPlay can be built using OpenSSL- 3.0.0, For "GPL-strict" distributions, UxPlay can be built using OpenSSL- 3.0.0,
which has a new [GPLv3-compatible license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/). which has a new [GPLv3-compatible license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/).
@@ -161,7 +159,9 @@ pkgconf. Also make sure that cmake>=3.4.1 is installed:
Make sure that your distribution provides OpenSSL 1.1.1 or later, and Make sure that your distribution provides OpenSSL 1.1.1 or later, and
libplist 2.0 or later. (This means Debian 10 "Buster", Ubuntu 18.04 or libplist 2.0 or later. (This means Debian 10 "Buster", Ubuntu 18.04 or
later.) If it does not, you may need to build and install these from later.) If it does not, you may need to build and install these from
source (see below). source (see instructions at the end of this README). If you have a non-standard OpenSSL
installation, you may need to set the environment variable OPENSSL_ROOT_DIR
(_e.g._ , "`export OPENSSL_ROOT_DIR=/usr/local/lib64`" if that is where it is installed).
In a terminal window, change directories to the source directory of the In a terminal window, change directories to the source directory of the
downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag for downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag for
@@ -207,7 +207,7 @@ files to somewhere like `/usr/local/share/doc/uxplay`).
It can also be found in the build directory after the build It can also be found in the build directory after the build
processs. processs.
**Finally, run uxplay in a terminal window**. If it is not seen by the **Finally, run uxplay in a terminal window**. Use Ctrl-C (or close the window) to terminate it when done. If it is not seen by the
iOS client's drop-down "Screen Mirroring" panel, check that your DNS-SD iOS client's drop-down "Screen Mirroring" panel, check that your DNS-SD
server (usually avahi-daemon) is running: do this in a terminal window server (usually avahi-daemon) is running: do this in a terminal window
with ```systemctl status avahi-daemon```. with ```systemctl status avahi-daemon```.
@@ -226,13 +226,13 @@ Try "`uxplay -avdec`" to force software video decoding; if this works you can
then try to fix accelerated hardware video decoding if you need it. then try to fix accelerated hardware video decoding if you need it.
See [Usage](#usage) for more run-time options. See [Usage](#usage) for more run-time options.
**Raspberry Pi**: For GStreamer-1.20 or earlier, see **Raspberry Pi**: GStreamer-1.18.4 or later required for hardware video decoding; for 1.20 or earlier, also see
[patching instructions for GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches). [patching instructions for GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
If "`uxplay`" by itself does not work, If "`uxplay`" by itself does not work,
use "`uxplay -v4l2`" (or use "``-rpi ``" as a synonym for "```-v4l2```") use "`uxplay -v4l2`" (or use "``-rpi ``" as a synonym for "```-v4l2```")
on your desktop X11 system, and optionally specify a videosink with "`-vs ..`"; on your desktop X11 system, and optionally specify a videosink with "`-vs ..`";
use "``uxplay -rpiwl``" as a synonym for "`-v4l2 -vs waylandsink`" on a use "``uxplay -rpiwl``" as a synonym for "`-v4l2 -vs waylandsink`" on a
desktop system with Wayland (this applies to Ubuntu). On a system desktop system with Wayland (this applies to recent Ubuntu). On a system
without X11 that uses framebuffer video (such as RPi OS Bullseye "Lite") without X11 that uses framebuffer video (such as RPi OS Bullseye "Lite")
use "`uxplay -rpifb`" as a synonym for "`uxplay -v4l2 -vs kmssink`". You can test UxPlay use "`uxplay -rpifb`" as a synonym for "`uxplay -v4l2 -vs kmssink`". You can test UxPlay
with software-only video decoding using option `-avdec`. with software-only video decoding using option `-avdec`.
@@ -257,46 +257,13 @@ for Intel graphics). (**Also available as a package in AUR**).
Either avahi-libdns or mDNSResponder must also be installed to provide the dns_sd library. Either avahi-libdns or mDNSResponder must also be installed to provide the dns_sd library.
OpenSSL is already installed as a System Library. "ZOOMFIX" is untested; don't try to use it on FreeBSD unless you need it. OpenSSL is already installed as a System Library. "ZOOMFIX" is untested; don't try to use it on FreeBSD unless you need it.
### Building OpenSSL >= 1.1.1 from source.
If you need to do this, note that you may be able to use a newer version (OpenSSL-3.0.1 is known to work). ## Building UxPlay on macOS: **(Intel X86_64 and "Apple Silicon" M1 Macs)**
You will need the standard development toolset (autoconf, automake, libtool).
Download the source code from
[https://www.openssl.org/source/](https://www.openssl.org/source/).
Install the downloaded
openssl by opening a terminal in your Downloads directory, and unpacking the source distribution:
("tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1"). Then build/install with
"./config ; make ; sudo make install_dev". This will typically install the needed library ```libcrypto.*```,
either in /usr/local/lib or /usr/local/lib64.
_(Ignore the following for builds on MacOS:)_
Assuming the library was placed in /usr/local/lib64, you must
"export OPENSSL_ROOT_DIR=/usr/local/lib64" before running cmake.
On some systems like
Debian or Ubuntu, you may also need to add a missing entry ```/usr/local/lib64```
in /etc/ld.so.conf (or place a file containing "/usr/local/lib64/libcrypto.so" in /etc/ld.so.conf.d)
and then run "sudo ldconfig".
### Bulding libplist >= 2.0.0 from source.
_(Note: on Debian 9 "Stretch" or Ubuntu 16.04 LTS editions, you can avoid this step by installing libplist-dev
and libplist3 from Debian 10 or Ubuntu 18.04.)_
As well as the usual build tools (autoconf, automake, libtool), you
may need to also install some libpython\*-dev package. Download the latest source
from [https://github.com/libimobiledevice/libplist](https://github.com/libimobiledevice/libplist): get
[libplist-master.zip](https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip), then
("unzip libplist-master.zip ; cd libplist-master"), build/install
("./autogen.sh ; make ; sudo make install"). This will probably install libplist-2.0.* in /usr/local/lib.
_(Ignore the following for builds on MacOS:)_ On some systems like
Debian or Ubuntu, you may also need to add a missing entry ```/usr/local/lib```
in /etc/ld.so.conf (or place a file containing "/usr/local/lib/libplist-2.0.so" in /etc/ld.so.conf.d)
and then run "sudo ldconfig".
## Building UxPlay on macOS: **(Now tested on both Intel X86_64 and "Apple Silicon" M1 Macs)**
_Note: A native AirPlay Server feature is included in macOS 12 Monterey, but is restricted to recent hardware. _Note: A native AirPlay Server feature is included in macOS 12 Monterey, but is restricted to recent hardware.
UxPlay can run on older macOS systems that will not be able to run Monterey, or can run Monterey but not AirPlay._ UxPlay can run on older macOS systems that will not be able to run Monterey, or can run Monterey but not AirPlay._
These instructions for macOS asssume that the Xcode command-line developer tools are installed (if Xcode is These instructions for macOS asssume that the Xcode command-line developer tools are installed (if Xcode is
installed, open the Terminal, type "sudo xcode-select --install" and accept the conditions). installed, open the Terminal, type "sudo xcode-select --install" and accept the conditions).
It is also assumed that CMake >= 3.13 is installed: It is also assumed that CMake >= 3.13 is installed:
@@ -304,35 +271,44 @@ this can be done with package managers [MacPorts](http://www.macports.org),
[Fink](http://finkproject.org) or [Homebrew](http://brew.sh), or by a download from [Fink](http://finkproject.org) or [Homebrew](http://brew.sh), or by a download from
[https://cmake.org/download/](https://cmake.org/download/). [https://cmake.org/download/](https://cmake.org/download/).
First install OpenSSL and libplist: static versions of these libaries will be used, so they can be uninstalled after UxPlay is built.
These are available in MacPorts and Homebrew, or they can easily be built from source (see instructions at the end of this README; this
requires development tools autoconf, automake, libtool, which can be installed using MacPorts, HomeBrew, or Fink).
First get the latest macOS release of GStreamer-1.0
from [https://gstreamer.freedesktop.org/download/](https://gstreamer.freedesktop.org/download/). Next get the latest macOS release of GStreamer-1.0.
Install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.2.
* recommended: install the "official" GStreamer release for macOS
from [https://gstreamer.freedesktop.org/download/](https://gstreamer.freedesktop.org/download/). The alternative is to install it from Homebrew
(MacPorts also supplies it, but compiled to use X11).
**For the "official" release**: install both the macOS runtime and development installer packages. Assuming that the latest release is 1.20.2.
install `gstreamer-1.0-1.20.2-universal.pkg` and ``gstreamer-1.0-devel-1.20.2-universal.pkg``. (If install `gstreamer-1.0-1.20.2-universal.pkg` and ``gstreamer-1.0-devel-1.20.2-universal.pkg``. (If
you have an Intel-architecture Mac, and have problems with the "universal" packages, you can also you have an Intel-architecture Mac, and have problems with the "universal" packages, you can also
use `gstreamer-1.0-1.18.6-x86_64.pkg` and ``gstreamer-1.0-devel-1.18.6-x86_64.pkg``.) Click on them to use `gstreamer-1.0-1.18.6-x86_64.pkg` and ``gstreamer-1.0-devel-1.18.6-x86_64.pkg``.) Click on them to
install (they install to /Library/FrameWorks/GStreamer.framework). install (they install to /Library/FrameWorks/GStreamer.framework).
It is recommended you use GStreamer.framework rather than install Gstreamer with Homebrew or MacPorts (see later).
Next install OpenSSL and libplist: these can be built from source (see above), in which case you may need to install
the standard development tools autoconf, automake, libtool, which can be done with MacPorts, HomeBrew, or Fink.
Only the static forms of the two libraries will used for the macOS build, so you can uninstall them ("sudo **For Homebrew**: pkgconfig is needed ("brew install pkgconfig").
make uninstall") after you have built UxPlay. It may be easier to get them using Then
MacPorts "sudo port install openssl libplist-devel" or Homebrew "brew install openssl libplist" (but not Fink). "brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav". This appears to be functionally equivalent
if you don't have MacPorts or Homebrew installed, you can just install to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies.
one of them before building uxplay, and uninstall afterwards if it is not wanted. **You may need to set the environment variable GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0 to point to the Homebrew GStreamer installation.**
Finally, build and install uxplay (without ZOOMFIX): open a terminal and change into the UxPlay source directory Finally, build and install uxplay (without ZOOMFIX): open a terminal and change into the UxPlay source directory
("UxPlay-master" for zipfile downloads, "UxPlay" for "git clone" downloads) and build/install with ("UxPlay-master" for zipfile downloads, "UxPlay" for "git clone" downloads) and build/install with
"cmake . ; make ; sudo make install " (same as for Linux). "cmake . ; make ; sudo make install " (same as for Linux).
* On macOS with this installation of GStreamer, the only videosinks available seem to be glimagesink (default choice made by * On macOS with this installation of GStreamer, the only videosinks available seem to be glimagesink (default choice made by
autovideosink) and osxvideosink. (It seems that vaapisink is not supported autovideosink) and osxvideosink. The window title does not show the Airplay server name, but the window is visible to
on macOS). The window title does not show the Airplay server name, but the window is visible to
screen-sharing apps (e.g., Zoom). The only available audiosink seems to be osxaudiosink. screen-sharing apps (e.g., Zoom). The only available audiosink seems to be osxaudiosink.
* On macOS, the option -t _timeout_ is currently suppressed, and the option -nc is always used, whether or not it is selected. * The option -t _timeout_ is currently suppressed, and the option -nc is always used, whether or not it is selected.
This is a workaround until a problem with GStreamer videosinks on macOS is fixed: This is a workaround for a problem with GStreamer videosinks on macOS:
if the GStreamer pipeline is destroyed while the mirror window is still open, a segfault occurs. if the GStreamer pipeline is destroyed while the mirror window is still open, a segfault occurs.
* In the case of glimagesink, the resolution settings "-s wxh" do not affect * In the case of glimagesink, the resolution settings "-s wxh" do not affect
@@ -341,20 +317,14 @@ Finally, build and install uxplay (without ZOOMFIX): open a terminal and change
in this case the aspect ratio changes when the window width is changed by dragging its side. in this case the aspect ratio changes when the window width is changed by dragging its side.
***Other ways (Homebrew, MacPorts) to install GStreamer on macOS (not recommended):*** ***Using GStreamer installed from MacPorts (not recommended):***
First make sure that pkgconfig is installed (Homebrew: "brew install pkgconfig" ; MacPorts: "sudo port install pkgconfig" ). To install: "sudo port install pkgconfig"; "sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav".
(a) with Homebrew: "brew install gst-plugins-base gst-plugins-good gst-plugins-bad gst-libav". This appears to be functionally equivalent
to using GStreamer.framework, but causes a large number of extra packages to be installed by Homebrew as dependencies.
**You may need to set the environment variable GST_PLUGIN_PATH=/usr/local/lib/gstreamer-1.0 to point to the Homebrew GStreamer installation.**
(b) with MacPorts: "sudo port install gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad gstreamer1-gst-libav".
**The MacPorts GStreamer is built to use X11**, so uxplay must be run from an XQuartz terminal, can use ZOOMFIX, and needs **The MacPorts GStreamer is built to use X11**, so uxplay must be run from an XQuartz terminal, can use ZOOMFIX, and needs
option "-vs ximagesink". On an older unibody MacBook Pro, the default resolution wxh = 1920x1080 was too large for option "-vs ximagesink". On an unibody (non-retina) MacBook Pro, the default resolution wxh = 1920x1080 was too large,
the non-retina display, but using option "-s 800x600" worked; However, the GStreamer pipeline is fragile against attempts to change but using option "-s 800x600" worked. The MacPorts GStreamer pipeline seems fragile against attempts to change
the X11 window size, or to rotations that switch a connected client between portrait and landscape mode while uxplay is running. the X11 window size, or to rotations that switch a connected client between portrait and landscape mode while uxplay is running.
Using the MacPorts X11 GStreamer is only viable if the image size is left unchanged from the initial "-s wxh" setting Using the MacPorts X11 GStreamer seems only possible if the image size is left unchanged from the initial "-s wxh" setting
(also use the iPad/iPhone setting that locks the screen orientation against switching between portrait and landscape mode (also use the iPad/iPhone setting that locks the screen orientation against switching between portrait and landscape mode
as the device is rotated). as the device is rotated).
@@ -758,6 +728,43 @@ Thanks to David Ventura
https://github.com/DavidVentura/UxPlay for the fix and also for getting a fix into gstreamer-1.20. https://github.com/DavidVentura/UxPlay for the fix and also for getting a fix into gstreamer-1.20.
### Building OpenSSL >= 1.1.1 from source.
If you need to do this, note that you may be able to use a newer version (OpenSSL-3.0.1 is known to work).
You will need the standard development toolset (autoconf, automake, libtool).
Download the source code from
[https://www.openssl.org/source/](https://www.openssl.org/source/).
Install the downloaded
openssl by opening a terminal in your Downloads directory, and unpacking the source distribution:
("tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1"). Then build/install with
"./config ; make ; sudo make install_dev". This will typically install the needed library ```libcrypto.*```,
either in /usr/local/lib or /usr/local/lib64.
_(Ignore the following for builds on MacOS:)_
On some systems like
Debian or Ubuntu, you may also need to add a missing entry ```/usr/local/lib64```
in /etc/ld.so.conf (or place a file containing "/usr/local/lib64/libcrypto.so" in /etc/ld.so.conf.d)
and then run "sudo ldconfig".
### Building libplist >= 2.0.0 from source.
_(Note: on Debian 9 "Stretch" or Ubuntu 16.04 LTS editions, you can avoid this step by installing libplist-dev
and libplist3 from Debian 10 or Ubuntu 18.04.)_
As well as the usual build tools (autoconf, automake, libtool), you
may need to also install some libpython\*-dev package. Download the latest source
from [https://github.com/libimobiledevice/libplist](https://github.com/libimobiledevice/libplist): get
[libplist-master.zip](https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip), then
("unzip libplist-master.zip ; cd libplist-master"), build/install
("./autogen.sh ; make ; sudo make install"). This will probably install libplist-2.0.* in /usr/local/lib.
_(Ignore the following for builds on MacOS:)_ On some systems like
Debian or Ubuntu, you may also need to add a missing entry ```/usr/local/lib```
in /etc/ld.so.conf (or place a file containing "/usr/local/lib/libplist-2.0.so" in /etc/ld.so.conf.d)
and then run "sudo ldconfig".
# Disclaimer # Disclaimer
All the resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to. All the resources in this repository are written using only freely available information from the internet. The code and related resources are meant for educational purposes only. It is the responsibility of the user to make sure all local laws are adhered to.

243
README.txt
View File

@@ -43,17 +43,17 @@ pulled from the new main [UxPlay site](https://github.com/FDH2/UxPlay)).
UxPlay is tested on a number of systems, including (among others) Debian UxPlay is tested on a number of systems, including (among others) Debian
10.11 "Buster" and 11.2 "Bullseye", Ubuntu 20.04 and 22.04, Linux Mint 10.11 "Buster" and 11.2 "Bullseye", Ubuntu 20.04 and 22.04, Linux Mint
20.3, Pop!\_OS 21.10 (NVIDIA edition), Rocky Linux 8.5 (a CentOS 20.3, Pop!\_OS 21.10 (NVIDIA edition), Rocky Linux 8.6 (a CentOS
successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1), successor), OpenSUSE 15.3, Arch Linux 5.16.8, macOS 12.3 (Intel and M1),
FreeBSD 13.0. FreeBSD 13.1.
Its main use is to act like an AppleTV for screen-mirroring (with audio) Its main use is to act like an AppleTV for screen-mirroring (with audio)
of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a window on of iOS/iPadOS/macOS clients (iPhones, iPads, MacBooks) in a window on
the server display (with the possibility of sharing that window on the server display (with the possibility of sharing that window on
screen-sharing applications such as Zoom) on a host running Linux, screen-sharing applications such as Zoom) on a host running Linux,
macOS, or other unix. UxPlay supports a "legacy" form of Apple's AirPlay macOS, or other unix. UxPlay supports Apple's AirPlay 2 protocol using
2 protocol introduced in iOS 12, and some features are missing. (Details "Legacy Pairing", and some features are missing. (Details of what is
of what is publically known about Apple's AirPlay2 protocol can be found publically known about Apple's AirPlay 2 protocol can be found
[here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol) [here](https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol)
and [here](https://emanuelecozzi.net/docs/airplay2)). and [here](https://emanuelecozzi.net/docs/airplay2)).
@@ -108,9 +108,9 @@ used.
The `nvh264dec` plugin (included in gstreamer1.0-plugins-bad since The `nvh264dec` plugin (included in gstreamer1.0-plugins-bad since
GStreamer-1.18.0) can be used for accelerated video decoding on the GStreamer-1.18.0) can be used for accelerated video decoding on the
NVIDIA GPU after NVIDIA's CUDA driver `libcuda.so` is installed. NVIDIA GPU after NVIDIA's CUDA driver `libcuda.so` is installed.
This plugin should be used with options (This plugin should be used with options
`uxplay -vd nvh264dec -vs glimagesink`. For GStreamer-1.16.3 or `uxplay -vd nvh264dec -vs glimagesink`.) For GStreamer-1.16.3 or
earlier, replace `nvh264dec` by the older plugin`nvdec`, which must earlier, replace `nvh264dec` by the older plugin `nvdec`, which must
be built by the user: See [these be built by the user: See [these
instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins). instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
@@ -119,28 +119,27 @@ used.
Raspberry Pi (RPi) computers can run UxPlay with software decoding Raspberry Pi (RPi) computers can run UxPlay with software decoding
of h264 video but this usually has unacceptable latency, and of h264 video but this usually has unacceptable latency, and
hardware-accelerated GPU decoding should be used. Distributions such hardware-accelerated GPU decoding should be used. Distributions such
as RPi OS (Bullseye) release have dropped support for unmaintained as RPi OS (Bullseye) release have recently dropped support for
32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in favor 32-bit-only OpenMax (omx) GPU decoding (used by RPiPlay), in favor
of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that of Video4Linux2 (v4l2). Fixes to the GStreamer v4l2 plugin that
allow it to work with UxPlay on RPi are now in the GStreamer allow it to work with UxPlay on RPi are now in the GStreamer
development branch, and will appear in the upcoming GStreamer-1.22 development branch, and will appear in the upcoming GStreamer-1.22
release. A (partial) backport (as release. A (partial) backport (as
`gstreamer1.0-plugins-good-1.18.4-2+~rpt1`) has already appeared in `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`) has already appeared in
RPi OS updates. Until the full update appears, or if you are using a RPi OS updates. Until the full update appears, or for other
different distribution, you can find [patching instructions for distributions, you can find [patching instructions for
GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki). Patches in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki) for
are available GStreamer releases 1.18.4 and later. GStreamer 1.18.4 and later.
### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues. ### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.
Some Linux distributions such as Debian do not allow distribution of Some Linux distributions such as Debian do not allow distribution of
compiled GPL code linked to OpenSSL-1.1.1 because its "dual compiled GPL code linked to OpenSSL-1.1.1 because its license has some
OpenSSL/SSLeay" license has some incompatibilities with GPL, unless all incompatibilities with GPL code, unless all authors have given an
code authors have explicitly given an "exception" to allow such linking "exception" to allow such linking (the historical origins of UxPlay make
(the historical origins of UxPlay make this impossible to obtain). Other this impossible to obtain). Other distributions treat OpenSSL as a
distributions treat OpenSSL as a "System Library" which the GPL allows "System Library" to which the GPL allows linking.
linking to.
For "GPL-strict" distributions, UxPlay can be built using OpenSSL- For "GPL-strict" distributions, UxPlay can be built using OpenSSL-
3.0.0, which has a new [GPLv3-compatible 3.0.0, which has a new [GPLv3-compatible
@@ -178,7 +177,11 @@ cmake\>=3.4.1 is installed: "`sudo apt-get install cmake`" (add
Make sure that your distribution provides OpenSSL 1.1.1 or later, and Make sure that your distribution provides OpenSSL 1.1.1 or later, and
libplist 2.0 or later. (This means Debian 10 "Buster", Ubuntu 18.04 or libplist 2.0 or later. (This means Debian 10 "Buster", Ubuntu 18.04 or
later.) If it does not, you may need to build and install these from later.) If it does not, you may need to build and install these from
source (see below). source (see instructions at the end of this README). If you have a
non-standard OpenSSL installation, you may need to set the environment
variable OPENSSL\_ROOT\_DIR (*e.g.* ,
"`export OPENSSL_ROOT_DIR=/usr/local/lib64`" if that is where it is
installed).
In a terminal window, change directories to the source directory of the In a terminal window, change directories to the source directory of the
downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag
@@ -229,11 +232,12 @@ The above script installs the executable file "`uxplay`" to
`/usr/local/share/doc/uxplay`). It can also be found in the build `/usr/local/share/doc/uxplay`). It can also be found in the build
directory after the build processs. directory after the build processs.
**Finally, run uxplay in a terminal window**. If it is not seen by the **Finally, run uxplay in a terminal window**. Use Ctrl-C (or close the
iOS client's drop-down "Screen Mirroring" panel, check that your DNS-SD window) to terminate it when done. If it is not seen by the iOS client's
server (usually avahi-daemon) is running: do this in a terminal window drop-down "Screen Mirroring" panel, check that your DNS-SD server
with `systemctl status avahi-daemon`. If this shows the avahi-daemon is (usually avahi-daemon) is running: do this in a terminal window with
not running, control it with `systemctl status avahi-daemon`. If this shows the avahi-daemon is not
running, control it with
`sudo systemctl [start,stop,enable,disable] avahi-daemon` (or `sudo systemctl [start,stop,enable,disable] avahi-daemon` (or
avahi-daemon.service). If UxPlay is seen, but the client fails to avahi-daemon.service). If UxPlay is seen, but the client fails to
connect when it is selected, there may be a firewall on the server that connect when it is selected, there may be a firewall on the server that
@@ -248,16 +252,16 @@ decoding; if this works you can then try to fix accelerated hardware
video decoding if you need it. See [Usage](#usage) for more run-time video decoding if you need it. See [Usage](#usage) for more run-time
options. options.
**Raspberry Pi**: For GStreamer-1.20 or earlier, see [patching **Raspberry Pi**: GStreamer-1.18.4 or later required for hardware video
instructions for decoding; for 1.20 or earlier, also see [patching instructions for
GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches). GStreamer](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches).
If "`uxplay`" by itself does not work, use "`uxplay -v4l2`" (or use If "`uxplay`" by itself does not work, use "`uxplay -v4l2`" (or use
"`-rpi`" as a synonym for "`-v4l2`") on your desktop X11 system, and "`-rpi`" as a synonym for "`-v4l2`") on your desktop X11 system, and
optionally specify a videosink with "`-vs ..`"; use "`uxplay -rpiwl`" as optionally specify a videosink with "`-vs ..`"; use "`uxplay -rpiwl`" as
a synonym for "`-v4l2 -vs waylandsink`" on a desktop system with Wayland a synonym for "`-v4l2 -vs waylandsink`" on a desktop system with Wayland
(this applies to Ubuntu). On a system without X11 that uses framebuffer (this applies to recent Ubuntu). On a system without X11 that uses
video (such as RPi OS Bullseye "Lite") use "`uxplay -rpifb`" as a framebuffer video (such as RPi OS Bullseye "Lite") use "`uxplay -rpifb`"
synonym for "`uxplay -v4l2 -vs kmssink`". You can test UxPlay with as a synonym for "`uxplay -v4l2 -vs kmssink`". You can test UxPlay with
software-only video decoding using option `-avdec`. software-only video decoding using option `-avdec`.
- **Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma - **Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma
@@ -289,43 +293,8 @@ software-only video decoding using option `-avdec`.
installed as a System Library. "ZOOMFIX" is untested; don't try to installed as a System Library. "ZOOMFIX" is untested; don't try to
use it on FreeBSD unless you need it. use it on FreeBSD unless you need it.
### Building OpenSSL \>= 1.1.1 from source. Building UxPlay on macOS: **(Intel X86\_64 and "Apple Silicon" M1 Macs)**
-------------------------------------------------------------------------
If you need to do this, note that you may be able to use a newer version
(OpenSSL-3.0.1 is known to work). You will need the standard development
toolset (autoconf, automake, libtool). Download the source code from
<https://www.openssl.org/source/>. Install the downloaded openssl by
opening a terminal in your Downloads directory, and unpacking the source
distribution: ("tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1").
Then build/install with "./config ; make ; sudo make install\_dev". This
will typically install the needed library `libcrypto.*`, either in
/usr/local/lib or /usr/local/lib64. *(Ignore the following for builds on
MacOS:)* Assuming the library was placed in /usr/local/lib64, you must
"export OPENSSL\_ROOT\_DIR=/usr/local/lib64" before running cmake. On
some systems like Debian or Ubuntu, you may also need to add a missing
entry `/usr/local/lib64` in /etc/ld.so.conf (or place a file containing
"/usr/local/lib64/libcrypto.so" in /etc/ld.so.conf.d) and then run "sudo
ldconfig".
### Bulding libplist \>= 2.0.0 from source.
*(Note: on Debian 9 "Stretch" or Ubuntu 16.04 LTS editions, you can
avoid this step by installing libplist-dev and libplist3 from Debian 10
or Ubuntu 18.04.)* As well as the usual build tools (autoconf, automake,
libtool), you may need to also install some libpython\*-dev package.
Download the latest source from
<https://github.com/libimobiledevice/libplist>: get
[libplist-master.zip](https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip),
then ("unzip libplist-master.zip ; cd libplist-master"), build/install
("./autogen.sh ; make ; sudo make install"). This will probably install
libplist-2.0.\* in /usr/local/lib. *(Ignore the following for builds on
MacOS:)* On some systems like Debian or Ubuntu, you may also need to add
a missing entry `/usr/local/lib` in /etc/ld.so.conf (or place a file
containing "/usr/local/lib/libplist-2.0.so" in /etc/ld.so.conf.d) and
then run "sudo ldconfig".
Building UxPlay on macOS: **(Now tested on both Intel X86\_64 and "Apple Silicon" M1 Macs)**
--------------------------------------------------------------------------------------------
*Note: A native AirPlay Server feature is included in macOS 12 Monterey, *Note: A native AirPlay Server feature is included in macOS 12 Monterey,
but is restricted to recent hardware. UxPlay can run on older macOS but is restricted to recent hardware. UxPlay can run on older macOS
@@ -341,28 +310,36 @@ with package managers [MacPorts](http://www.macports.org),
[Fink](http://finkproject.org) or [Homebrew](http://brew.sh), or by a [Fink](http://finkproject.org) or [Homebrew](http://brew.sh), or by a
download from <https://cmake.org/download/>. download from <https://cmake.org/download/>.
First get the latest macOS release of GStreamer-1.0 from First install OpenSSL and libplist: static versions of these libaries
<https://gstreamer.freedesktop.org/download/>. Install both the macOS will be used, so they can be uninstalled after UxPlay is built. These
runtime and development installer packages. Assuming that the latest are available in MacPorts and Homebrew, or they can easily be built from
release is 1.20.2. install `gstreamer-1.0-1.20.2-universal.pkg` and source (see instructions at the end of this README; this requires
development tools autoconf, automake, libtool, which can be installed
using MacPorts, HomeBrew, or Fink).
Next get the latest macOS release of GStreamer-1.0.
- recommended: install the "official" GStreamer release for macOS from
<https://gstreamer.freedesktop.org/download/>. The alternative is to
install it from Homebrew (MacPorts also supplies it, but compiled to
use X11).
**For the "official" release**: install both the macOS runtime and
development installer packages. Assuming that the latest release is
1.20.2. install `gstreamer-1.0-1.20.2-universal.pkg` and
`gstreamer-1.0-devel-1.20.2-universal.pkg`. (If you have an `gstreamer-1.0-devel-1.20.2-universal.pkg`. (If you have an
Intel-architecture Mac, and have problems with the "universal" packages, Intel-architecture Mac, and have problems with the "universal" packages,
you can also use `gstreamer-1.0-1.18.6-x86_64.pkg` and you can also use `gstreamer-1.0-1.18.6-x86_64.pkg` and
`gstreamer-1.0-devel-1.18.6-x86_64.pkg`.) Click on them to install (they `gstreamer-1.0-devel-1.18.6-x86_64.pkg`.) Click on them to install (they
install to /Library/FrameWorks/GStreamer.framework). It is recommended install to /Library/FrameWorks/GStreamer.framework).
you use GStreamer.framework rather than install Gstreamer with Homebrew
or MacPorts (see later).
Next install OpenSSL and libplist: these can be built from source (see **For Homebrew**: pkgconfig is needed ("brew install pkgconfig"). Then
above), in which case you may need to install the standard development "brew install gst-plugins-base gst-plugins-good gst-plugins-bad
tools autoconf, automake, libtool, which can be done with MacPorts, gst-libav". This appears to be functionally equivalent to using
HomeBrew, or Fink. Only the static forms of the two libraries will used GStreamer.framework, but causes a large number of extra packages to be
for the macOS build, so you can uninstall them ("sudo make uninstall") installed by Homebrew as dependencies. **You may need to set the
after you have built UxPlay. It may be easier to get them using MacPorts environment variable GST\_PLUGIN\_PATH=/usr/local/lib/gstreamer-1.0 to
"sudo port install openssl libplist-devel" or Homebrew "brew install point to the Homebrew GStreamer installation.**
openssl libplist" (but not Fink). if you don't have MacPorts or Homebrew
installed, you can just install one of them before building uxplay, and
uninstall afterwards if it is not wanted.
Finally, build and install uxplay (without ZOOMFIX): open a terminal and Finally, build and install uxplay (without ZOOMFIX): open a terminal and
change into the UxPlay source directory ("UxPlay-master" for zipfile change into the UxPlay source directory ("UxPlay-master" for zipfile
@@ -371,16 +348,16 @@ downloads, "UxPlay" for "git clone" downloads) and build/install with
- On macOS with this installation of GStreamer, the only videosinks - On macOS with this installation of GStreamer, the only videosinks
available seem to be glimagesink (default choice made by available seem to be glimagesink (default choice made by
autovideosink) and osxvideosink. (It seems that vaapisink is not autovideosink) and osxvideosink. The window title does not show the
supported on macOS). The window title does not show the Airplay Airplay server name, but the window is visible to screen-sharing
server name, but the window is visible to screen-sharing apps (e.g., apps (e.g., Zoom). The only available audiosink seems to be
Zoom). The only available audiosink seems to be osxaudiosink. osxaudiosink.
- On macOS, the option -t *timeout* is currently suppressed, and the - The option -t *timeout* is currently suppressed, and the option -nc
option -nc is always used, whether or not it is selected. This is a is always used, whether or not it is selected. This is a workaround
workaround until a problem with GStreamer videosinks on macOS is for a problem with GStreamer videosinks on macOS: if the GStreamer
fixed: if the GStreamer pipeline is destroyed while the mirror pipeline is destroyed while the mirror window is still open, a
window is still open, a segfault occurs. segfault occurs.
- In the case of glimagesink, the resolution settings "-s wxh" do not - In the case of glimagesink, the resolution settings "-s wxh" do not
affect the (small) initial OpenGL mirror window size, but the window affect the (small) initial OpenGL mirror window size, but the window
@@ -389,35 +366,22 @@ downloads, "UxPlay" for "git clone" downloads) and build/install with
aspect ratio (stretched image); in this case the aspect ratio aspect ratio (stretched image); in this case the aspect ratio
changes when the window width is changed by dragging its side. changes when the window width is changed by dragging its side.
***Other ways (Homebrew, MacPorts) to install GStreamer on macOS (not ***Using GStreamer installed from MacPorts (not recommended):***
recommended):***
First make sure that pkgconfig is installed (Homebrew: "brew install To install: "sudo port install pkgconfig"; "sudo port install
pkgconfig" ; MacPorts: "sudo port install pkgconfig" ). gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good
gstreamer1-gst-plugins-bad gstreamer1-gst-libav". **The MacPorts
(a) with Homebrew: "brew install gst-plugins-base gst-plugins-good GStreamer is built to use X11**, so uxplay must be run from an XQuartz
gst-plugins-bad gst-libav". This appears to be functionally terminal, can use ZOOMFIX, and needs option "-vs ximagesink". On an
equivalent to using GStreamer.framework, but causes a large number unibody (non-retina) MacBook Pro, the default resolution wxh = 1920x1080
of extra packages to be installed by Homebrew as dependencies. **You was too large, but using option "-s 800x600" worked. The MacPorts
may need to set the environment variable GStreamer pipeline seems fragile against attempts to change the X11
GST\_PLUGIN\_PATH=/usr/local/lib/gstreamer-1.0 to point to the window size, or to rotations that switch a connected client between
Homebrew GStreamer installation.** portrait and landscape mode while uxplay is running. Using the MacPorts
X11 GStreamer seems only possible if the image size is left unchanged
(b) with MacPorts: "sudo port install gstreamer1-gst-plugins-base from the initial "-s wxh" setting (also use the iPad/iPhone setting that
gstreamer1-gst-plugins-good gstreamer1-gst-plugins-bad locks the screen orientation against switching between portrait and
gstreamer1-gst-libav". **The MacPorts GStreamer is built to use landscape mode as the device is rotated).
X11**, so uxplay must be run from an XQuartz terminal, can use
ZOOMFIX, and needs option "-vs ximagesink". On an older unibody
MacBook Pro, the default resolution wxh = 1920x1080 was too large
for the non-retina display, but using option "-s 800x600" worked;
However, the GStreamer pipeline is fragile against attempts to
change the X11 window size, or to rotations that switch a connected
client between portrait and landscape mode while uxplay is running.
Using the MacPorts X11 GStreamer is only viable if the image size is
left unchanged from the initial "-s wxh" setting (also use the
iPad/iPhone setting that locks the screen orientation against
switching between portrait and landscape mode as the device is
rotated).
Usage Usage
===== =====
@@ -925,6 +889,43 @@ must be installed. (Without ZOOMFIX, UxPlay has no dependence on X11).
Ventura https://github.com/DavidVentura/UxPlay for the fix and also for Ventura https://github.com/DavidVentura/UxPlay for the fix and also for
getting a fix into gstreamer-1.20. getting a fix into gstreamer-1.20.
### Building OpenSSL \>= 1.1.1 from source.
If you need to do this, note that you may be able to use a newer version
(OpenSSL-3.0.1 is known to work). You will need the standard development
toolset (autoconf, automake, libtool). Download the source code from
<https://www.openssl.org/source/>. Install the downloaded openssl by
opening a terminal in your Downloads directory, and unpacking the source
distribution: ("tar -xvzf openssl-3.0.1.tar.gz ; cd openssl-3.0.1").
Then build/install with "./config ; make ; sudo make install\_dev". This
will typically install the needed library `libcrypto.*`, either in
/usr/local/lib or /usr/local/lib64.
*(Ignore the following for builds on MacOS:)* On some systems like
Debian or Ubuntu, you may also need to add a missing entry
`/usr/local/lib64` in /etc/ld.so.conf (or place a file containing
"/usr/local/lib64/libcrypto.so" in /etc/ld.so.conf.d) and then run "sudo
ldconfig".
### Building libplist \>= 2.0.0 from source.
*(Note: on Debian 9 "Stretch" or Ubuntu 16.04 LTS editions, you can
avoid this step by installing libplist-dev and libplist3 from Debian 10
or Ubuntu 18.04.)* As well as the usual build tools (autoconf, automake,
libtool), you may need to also install some libpython\*-dev package.
Download the latest source from
<https://github.com/libimobiledevice/libplist>: get
[libplist-master.zip](https://github.com/libimobiledevice/libplist/archive/refs/heads/master.zip),
then ("unzip libplist-master.zip ; cd libplist-master"), build/install
("./autogen.sh ; make ; sudo make install"). This will probably install
libplist-2.0.\* in /usr/local/lib.
*(Ignore the following for builds on MacOS:)* On some systems like
Debian or Ubuntu, you may also need to add a missing entry
`/usr/local/lib` in /etc/ld.so.conf (or place a file containing
"/usr/local/lib/libplist-2.0.so" in /etc/ld.so.conf.d) and then run
"sudo ldconfig".
Disclaimer Disclaimer
========== ==========