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

README edits

Browse Source
This commit is contained in:
fduncanh
2022-05-27 15:13:28 -04:00
parent bdf4037cf2
commit e21fd70c59
3 changed files with 175 additions and 115 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
README.html
View File

@@ -1,5 +1,5 @@
<h1 id="uxplay-1.52-airplayairplay-mirror-server-for-linux-macos-and-unix.">UxPlay 1.52: AirPlay/AirPlay-Mirror server for Linux, macOS, and Unix.</h1>
<h3 id="now-developed-at-github-site-httpsgithub.comfdh2uxplay-where-user-issues-should-be-posted.">Now developed at GitHub site <a href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a> (where user issues should be posted).</h3>
<h3 id="now-developed-at-a-new-github-site-httpsgithub.comfdh2uxplay-where-user-issues-should-be-posted.">Now developed at a new GitHub site <a href="https://github.com/FDH2/UxPlay">https://github.com/FDH2/UxPlay</a> (where user issues should be posted).</h3>
<p>Highlights:</p>
<ul>
<li>GPLv3, open source.</li>
@@ -8,24 +8,24 @@
<li>Support for older 32-bit iOS clients (such as iPad 2nd gen, iPhone 4S, when upgraded to iOS 9.3.5 or later), and a Windows AirPlay-client emulator, AirMyPC.</li>
<li>Uses GStreamer, with options to select different output “videosinks” and “audiosinks”.</li>
<li>Support for server behind a firewall.</li>
<li><strong>New</strong>: Support for Raspberry Pi, with hardware video acceleration by Video4Linux2 (replacement for OpenMAX, which is no longer supplied in Raspberry Pi OS) (may require a <a href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patch</a> to the GStreamer Video4Linux2 plugin.) 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 supplied in 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>
<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 mainly inactive, but periodically posts updates pulled from the <a href="https://github.com/FDH2/UxPlay">main 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 21.10, Linux Mint 20.2, 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>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>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 Mirror protocol introduced in iOS 12; client devices running iOS/iPadOS 9.3.5 or later are supported, as is a (non-free) Windows-based AirPlay-client software emulator, AirMyPC. (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>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> <strong>Note that Apple DRM (as in Apple TV app content on the client) cannot be decrypted by UxPlay, and (unlike with a true AppleTV), the client cannot run a http connection on the server instead of streaming content from one on the client.</strong></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> <strong>Note that Apple DRM (as found in Apple TV app content on the client) cannot be decrypted by UxPlay, and (unlike a true AppleTV), the UxPlay server does not allow the Apple client to directly run a http connection on the server instead of streaming content from the http conection on the client.</strong></p>
<h3 id="possibility-for-using-hardware-accelerated-h264-video-decoding-if-available.">Possibility for using hardware-accelerated h264 video-decoding, if available.</h3>
<p>UxPlay uses <a href="https://gstreamer.freedesktop.org">GStreamer</a> Plugins for rendering audio and video, This means that video and audio are supported “out of the box”, using a choice of plugins. AirPlay streams video in h264 format: gstreamer decoding is plugin agnostic, and uses accelerated GPU hardware h264 decoders if available; if not, software decoding is used.</p>
<p>For systems with Intel or AMD integrated graphics, hardware GPU decoding with the gstreamer VAAPI plugin is preferable. VAAPI is open-source, and in addition to Intel and AMD graphics, the open-source “Nouveau” drivers for NVIDIA graphics are also in principle supported: see <a href="https://nouveau.freedesktop.org/VideoAcceleration.html">here</a>, which requires VAAPI to be supplemented with firmware extracted from the proprietary NVIDIA drivers.</p>
<p>For NVIDIA graphics with the proprietary drivers, 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, the plugin is called <code>nvdec</code>, and must be built by the user: see <a href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">these instructions</a>. This older form of the plugin should be used with the <code>-vd nvdec -vs glimagesink</code> uxplay options.</p>
<p>For NVIDIA graphics with the proprietary drivers, 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, the plugin is called <code>nvdec</code>, and must be built by the user: see <a href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">these instructions</a>. This older form of the NVIDIA plugin should be used with the <code>-vd nvdec -vs glimagesink</code> uxplay options.</p>
<ul>
<li><p><strong>GPU Support for Raspberry Pi</strong></p>
<p>Raspberry Pi (RPi) computers can run UxPlay with software decoding of h264 video (by adding <code>-avdec</code> to the uxplay options) but this usually has unacceptable latency, and hardware-accelerated decoding by the Pi’s built-in Broadcom GPU should be used. RPi OS (Bullseye) has abandoned the omx (OpenMAX) driver used till now for this by <a href="http://github.com/FD-/RPiPlay">RPiPlay</a>, in favor of v4l2 (Video4Linux2). The GStreamer Video4Linux2 plugin only works with UxPlay since GStreamer-1.21.0.0 on the development branch, but a (partial) backport (as <code>gstreamer1.0-plugins-good-1.18.4-2+~rpt1</code>) for RPi OS (Bullseye) has already appeared in current updates. Until the promised 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</a> in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>. Patches for GStreamer-1.18.5 (used in Ubuntu 21.10 for RPi) and GStreamer-1.20.1 (used in Manjaro for RPi) are also available. On “Desktop” operating systems with X11, use <code>uxplay -v4l2</code> (or use <code>-rpi</code> as a synonym), 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. On a system without X11 with framebuffer video (such as RPi OS Bullseye “Lite”) use <code>uxplay -rpifb</code> as a synonym for “<code>uxplay -v4l2 -vs kmssink</code>”.</p></li>
<p>Raspberry Pi (RPi) computers can run UxPlay with software decoding of h264 video (by adding <code>-avdec</code> to the uxplay options) but this usually has unacceptable latency, and hardware-accelerated decoding by the Pi’s built-in Broadcom GPU should be used. RPi OS (Bullseye) has abandoned the omx (OpenMAX) driver used till now for this by <a href="http://github.com/FD-/RPiPlay">RPiPlay</a>, in favor of v4l2 (Video4Linux2). A GStreamer Video4Linux2 plugin that works with UxPlay is now in the GStreamer-1.21.0.0 development branch, and will only be available in the forthcoming GStreamer-1.22 release ,but a (partial) backport (as <code>gstreamer1.0-plugins-good-1.18.4-2+~rpt1</code>) for RPi OS (Bullseye) has already appeared in its current updates. Until the promised 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</a> in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay Wiki</a>. Patches for GStreamer-1.18.5 (used in Ubuntu 21.10 for RPi) and GStreamer-1.20.1 (used in Ubuntu 22.04 and Manjaro for RPi) are also available. On “Desktop” operating systems with X11, if just using <code>uxplay</code> does not work well, use <code>uxplay -v4l2</code> (or use <code>-rpi</code> as a synonym), 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>”.</p></li>
</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>
<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>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 anew <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>
<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>*Current UxPlay is also a pull request on the original site https://github.com/antimof/UxPlay ; that original project is inactive, but the pull requests are now being periodically merged with the antimof tree (thank you antimof!).</p>
@@ -46,7 +46,7 @@
</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>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. See <a href="#usage">Usage</a> for run-time options.</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. 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 run-time options.</p>
<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>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>
@@ -139,7 +139,7 @@
<p>This triggers an unending stream of error messages, and means that the audio decryption key (also used in video decryption) was not correctly extracted from data sent by the client. This should not happen for iOS 9.3 or later clients. However, if a client uses the same older version of the protocol that is used by the Windows-based AirPlay client emulator <em>AirMyPC</em>, the protocol can be switched to the older version by the setting <code>OLD_PROTOCOL_CLIENT_USER_AGENT_LIST</code> in lib/global.h. UxPlay reports the client’s “User Agent” string when it connects. If some other client also fails to decrypt all audio and video, try adding its “User Agent” string in place of “xxx” in the entry “AirMyPC/2.0;xxx” in global.h and rebuild uxplay.</p>
<p>Note that Uxplay declares itself to be an AppleTV3,2 with a sourceVersion 220.68; this can also be changed in global.h. It had been thought that it was necessary for UxPlay to claim to be an older 32 bit AppleTV model that cannot run modern 64bit tvOS, in order for the client to use a “legacy” protocol for pairing with the server (see the <em>“Notes on AirPlay protocol versions”</em> at the end of this README). However, UxPlay still works if it declares itself as an AppleTV6,2 with sourceVersion 380.20.1 (an AppleTV 4K 1st gen, introduced 2017, running tvOS 12.2.1); it seems that the use of “legacy” protocol just requires bit 27 (listed as “SupportsLegacyPairing”) of the “features” plist code (reported to the client by the AirPlay server) to be set.</p>
<h1 id="changelog">ChangeLog</h1>
<p>1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted streaming debug output (readable aligned timestamps with decimal points in seconds). Eliminate memory leaks (found by valgrind).</p>
<p>1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted streaming debug output (readable aligned timestamps with decimal points in seconds). Eliminate memory leaks (found by valgrind). Support for display of ALAC (audio-only) metadata (soundtrack artist names, titles etc.) in the uxplay terminal.</p>
<p>1.51 2022-04-24 Reworked options forVideo4Linux2 support (new option -v4l2) and short options -rpi, -rpifb, -rpiwl as synonyms for -v4l2, -v4l2 -vs kmssink, and -v4l2 -vs waylandsink. Reverted a change from 1.48 that broke reconnection after “Stop Mirroring” is sent by client.</p>
<p>1.50 2022-04-22 Added -fs fullscreen option (for Wayland or VAAPI plugins only), Changed -rpi to be for framebuffer (“lite”) RPi systems and added -rpigl (OpenGL) and -rpiwl (Wayland) options for RPi Desktop systems. Also modified timestamps from “DTS” to “PTS” for latency improvement, plus internal cleanups.</p>
<p>1.49 2022-03-28 Addded options for dumping video and/or audio to file, for debugging, etc. h264 PPS/SPS NALU’s are shown with -d. Fixed video-not-working for M1 Mac clients.</p>

202
README.md
View File

@@ -1,23 +1,33 @@
# UxPlay 1.52: AirPlay/AirPlay-Mirror server for Linux, macOS, and Unix.
### Now developed at GitHub site [https://github.com/FDH2/UxPlay](https://github.com/FDH2/UxPlay) (where user issues should be posted).
### Now developed at a new GitHub site [https://github.com/FDH2/UxPlay](https://github.com/FDH2/UxPlay) (where user issues should be posted).
Highlights:
* GPLv3, open source.
* Support for both AirPlay Mirror and AirPlay Audio-only (Apple Lossless ALAC) protocols
* Support for both AirPlay Mirror and AirPlay Audio-only (Apple Lossless
ALAC) protocols
from current iOS/iPadOS 15.4 client devices.
* macOS computers (2011 or later) can act either as AirPlay clients, or as the server running UxPlay (tested
on macOS 10.15 Catalina and 12.3 Monterey). Using AirPlay, UxPlay can emulate a second display for macOS clients.
Both Intel and "Apple Silicon" M1 Macs are now fully supported in both roles.
* Support for older 32-bit iOS clients (such as iPad 2nd gen, iPhone 4S, when upgraded to iOS 9.3.5 or later),
and a Windows AirPlay-client emulator, AirMyPC.
* Uses GStreamer, with options to select different output "videosinks" and "audiosinks".
* macOS computers (2011 or later) can act either as AirPlay clients, or
as the server running UxPlay (tested
on macOS 10.15 Catalina and 12.3 Monterey). Using AirPlay, UxPlay can
emulate a second display for macOS clients. Both Intel and "Apple
Silicon" M1 Macs are now fully supported in both roles.
* Support for older 32-bit iOS clients (such as iPad 2nd gen, iPhone 4S,
when upgraded to iOS 9.3.5 or later), and a Windows AirPlay-client
emulator, AirMyPC.
* Uses GStreamer, with options to select different output "videosinks"
and "audiosinks".
* Support for server behind a firewall.
* **New**: Support for Raspberry Pi, with hardware video acceleration by Video4Linux2 (replacement for OpenMAX, which
is no longer supplied in Raspberry Pi OS)
(may require a [patch](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) to the GStreamer Video4Linux2 plugin.)
* **New**: Support for Raspberry Pi, with hardware video acceleration by
Video4Linux2 (replacement for 32-bit-only OpenMAX, which is no longer
supplied in Raspberry Pi OS). (For GStreamer < 1.22,
a [patch](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
to the GStreamer Video4Linux2 plugin (available in the
[UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki)) is required, unless
your distribution has made a backport of changes from the
development version.)
See [success reports](https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:).
This project is a GPLv3 open source unix AirPlay2 Mirror server for Linux, macOS, and \*BSD.
@@ -25,11 +35,12 @@ It was initially developed by
[antimof](http://github.com/antimof/Uxplay) using code
from [RPiPlay](https://github.com/FD-/RPiPlay), which in turn derives from
[AirplayServer](https://github.com/KqsMea8/AirplayServer),
[shairplay](https://github.com/juhovh/shairplay), and [playfair](https://github.com/EstebanKubata/playfair). (The antimof site is
mainly inactive, but periodically posts updates pulled from the [main UxPlay site](https://github.com/FDH2/UxPlay)).
[shairplay](https://github.com/juhovh/shairplay), and [playfair](https://github.com/EstebanKubata/playfair). (The antimof site is no longer involved in
development, but periodically posts updates pulled from the new
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 21.10,
Linux Mint 20.2, Pop!\_OS 21.10 (NVIDIA edition),
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.
Its main use is to act like an AppleTV for screen-mirroring (with audio) of iOS/iPadOS/macOS clients
@@ -60,9 +71,10 @@ this mode is not displayed, but metadata is displayed in the terminal).
_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._ **Note that Apple DRM
(as in Apple TV app content on the client) cannot be decrypted by UxPlay,
and (unlike with a true AppleTV), the client cannot run a http connection on the server
instead of streaming content from one on the client.**
(as found in Apple TV app content on the client) cannot be decrypted by UxPlay,
and (unlike a true AppleTV), the UxPlay server does not allow the Apple
client to directly run a http connection on the server instead of
streaming content from the http conection on the client.**
### Possibility for using hardware-accelerated h264 video-decoding, if available.
@@ -85,42 +97,52 @@ This plugin should be used with options
or earlier, the
plugin is called `nvdec`, and must be built by the user:
see [these instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
This older form of the plugin should be used with the `-vd nvdec -vs glimagesink` uxplay options.
This older form of the NVIDIA plugin should be used with
the `-vd nvdec -vs glimagesink` uxplay options.
* **GPU Support for Raspberry Pi**
Raspberry Pi (RPi) computers can run UxPlay with software decoding of h264 video (by adding `-avdec` to the uxplay options) but this
usually has unacceptable latency, and hardware-accelerated decoding by the Pi's built-in Broadcom GPU should be used.
RPi OS (Bullseye) has abandoned the omx (OpenMAX) driver used till now for this by [RPiPlay](http://github.com/FD-/RPiPlay), in
favor of v4l2 (Video4Linux2). The GStreamer Video4Linux2 plugin only works with UxPlay since GStreamer-1.21.0.0 on the development branch,
but a (partial) backport (as `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`) for RPi OS (Bullseye) has already appeared in current updates.
Until the promised full update appears, or if
you are using a different distribution,
you can find [patching instructions](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches) in
the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki). Patches for
GStreamer-1.18.5 (used in Ubuntu 21.10 for RPi) and GStreamer-1.20.1 (used in Manjaro for RPi) are also available.
On "Desktop" operating systems with X11, use `uxplay -v4l2` (or use ``-rpi `` as a synonym),
and optionally specify a videosink with "`-vs ..`"); use ``uxplay -rpiwl`` as a synonym
for "`-v4l2 -vs waylandsink`" on a Desktop system with Wayland.
On a system without X11 with
framebuffer video (such as RPi OS Bullseye "Lite") use `uxplay -rpifb` as a synonym
for "`uxplay -v4l2 -vs kmssink`".
Raspberry Pi (RPi) computers can run UxPlay with software decoding
of h264 video (by adding `-avdec` to the uxplay options) but this
usually has unacceptable latency, and hardware-accelerated decoding by
the Pi's built-in Broadcom GPU should be used. RPi OS (Bullseye) has
abandoned the omx (OpenMAX) driver used till now for this
by [RPiPlay](http://github.com/FD-/RPiPlay), in favor of v4l2
(Video4Linux2). A GStreamer Video4Linux2 plugin that works with UxPlay
is now in the GStreamer-1.21.0.0 development branch, and will only be
available in the forthcoming GStreamer-1.22 release ,but a (partial)
backport (as `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`) for RPi OS
(Bullseye) has already appeared in its current updates. Until the
promised full update appears, or if you are using a different distribution,
you can find [patching instructions](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki). Patches for
GStreamer-1.18.5 (used in Ubuntu 21.10 for RPi) and GStreamer-1.20.1
(used in Ubuntu 22.04 and Manjaro for RPi) are also available.
On "Desktop" operating systems with X11, if just using `uxplay` does not
work well, use `uxplay -v4l2` (or use ``-rpi `` as a synonym),
and optionally specify a videosink with "`-vs ..`");
use ``uxplay -rpiwl`` as a synonym for "`-v4l2 -vs waylandsink`" 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 `uxplay -rpifb` as a synonym for "`uxplay -v4l2 -vs kmssink`".
### Note to packagers: OpenSSL-3.0.0 solves GPL v3 license issues.
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
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.
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/).
For "GPL-strict" distributions, UxPlay can be built using OpenSSL- 3.0.0,
which has anew [GPLv3-compatible license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/).
# Getting UxPlay:
Either download and unzip [UxPlay-master.zip](https://github.com/FDH2/UxPlay/archive/refs/heads/master.zip),
or (if git is installed): "git clone https://github.com/FDH2/UxPlay". You can also download a recent or earlier
version listed in [Releases](https://github.com/FDH2/UxPlay/releases).
or (if git is installed): "git clone https://github.com/FDH2/UxPlay". You
can also download a recent or earlier version listed
in [Releases](https://github.com/FDH2/UxPlay/releases).
*Current UxPlay is also a pull request on the
original site https://github.com/antimof/UxPlay ; that original
@@ -129,42 +151,55 @@ now being periodically merged with the antimof tree (thank you antimof!).
## Building UxPlay on Linux (or \*BSD):
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS, see below).
See [Troubleshooting](#troubleshooting) below for help with any difficulties.
(Instructions for Debian/Ubuntu; adapt these for other Linuxes; for macOS,
see below). See [Troubleshooting](#troubleshooting) below for help with
any difficulties.
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 "`which pkg-config`",
install pkg-config or its work-alike replacement pkgconf. Also make sure that cmake>=3.4.1
is installed: "`sudo apt-get install cmake`" (add ``build-essential`` and
`pkg-config` (or ``pkgconf``) to this if needed).
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 "`which pkg-config`", install pkg-config or its work-alike replacement
pkgconf. Also make sure that cmake>=3.4.1 is installed:
"`sudo apt-get install cmake`" (add ``build-essential`` and `pkg-config`
(or ``pkgconf``) to this if needed).
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).
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).
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:
downloaded source code ("UxPlay-\*", "\*" = "master" or the release tag for
zipfile downloads, "UxPlay" for "git clone" downloads), then follow the instructions below:
**Note:** 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 `-DNO_MARCH_NATIVE=ON`.
**Note:** 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 `-DNO_MARCH_NATIVE=ON`.
1. `sudo apt-get install libssl-dev libplist-dev` (unless you need to build OpenSSL and libplist from source).
1. `sudo apt-get install libssl-dev libplist-dev`
(unless you need to build OpenSSL and libplist from source).
2. `sudo apt-get install libavahi-compat-libdnssd-dev libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev`.
3. `sudo apt-get install libx11-dev` (only needed if you invoke the "ZOOMFIX" X11 display-name fix in the next step)
3. `sudo apt-get install libx11-dev` (only needed if you invoke
the "ZOOMFIX" X11 display-name fix in the next step)
4. `cmake .` (or "`cmake -DZOOMFIX=ON .`" to get a screen-sharing fix to
make X11 mirror display windows visible to screen-sharing applications such as
Zoom, see [Improvements](#improvements) \#3 below). **ZOOMFIX is only needed
for GStreamer-1.18.x or earlier**.
make X11 mirror display windows visible to screen-sharing applications
such as Zoom, see [Improvements](#improvements) \#3 below).
**ZOOMFIX is only needed for GStreamer-1.18.x or earlier**.
5. `make`
6. `sudo make install` (you can afterwards uninstall with `sudo make uninstall` in the same directory in which this was run)
7. Install GStreamer plugins that you need: `sudo apt-get install gstreamer1.0-<plugin>`; values of
`<plugin>` needed are: "**plugins-base**", "**libav**" (for sound), "**plugins-good**" (for v4l2 hardware h264 decoding)
and "**plugins-bad**" (for h264 decoding). Also needed may be "**gl**" for OpenGL support (which may be useful, and should
be used with h264 decoding by the NVIDIA GPU), and "**x**" for X11 support, although these may already be installed; "**vaapi**"
is needed for hardware-accelerated h264 video decoding by Intel or AMD graphics (but not for use with NVIDIA using proprietary drivers).
Also install "**tools**" to get the utility gst-inspect-1.0 for examining the GStreamer installation.
6. `sudo make install` (you can afterwards uninstall
with `sudo make uninstall` in the same directory in which this was run)
7. Install GStreamer plugins that you
need: `sudo apt-get install gstreamer1.0-<plugin>`; values of
`<plugin>` needed are: "**plugins-base**", "**libav**" (for sound),
"**plugins-good**" (for v4l2 hardware h264 decoding)
and "**plugins-bad**" (for h264 decoding). Also needed may
be "**gl**" for OpenGL support (which may be useful, and should
be used with h264 decoding by the NVIDIA GPU), and "**x**" for
X11 support, although these may already be installed; "**vaapi**"
is needed for hardware-accelerated h264 video decoding by Intel
or AMD graphics (but not for use with NVIDIA using proprietary drivers).
Also install "**tools**" to get the utility gst-inspect-1.0 for
examining the GStreamer installation.
_If you intend to modify the code, use a separate "build" directory:
replace_ "`cmake [ ] .`" _by_ "``mkdir build ; cd build ; cmake [ ] ..``"; _you can then clean
@@ -177,13 +212,22 @@ files to somewhere like `/usr/local/share/doc/uxplay`).
It can also be found in the build directory after the build
processs.
**Finally, run uxplay in a terminal window**. 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 ```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 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 [Troubleshooting](#troubleshooting) below for
help with this or other problems. See [Usage](#usage) for run-time options.
**Finally, run uxplay in a terminal window**. 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 ```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
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 [Troubleshooting](#troubleshooting) below for
help with this or other problems. One common problem involves GStreamer
attempting to use incorrectly
configured or absent accelerated hardware h264 video decoding (e.g., VAAPI).
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.
See [Usage](#usage) for run-time options.
* **Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma Linux):**
(sudo yum install) openssl-devel libplist-devel avahi-compat-libdns_sd-devel (some from the "PowerTools" add-on repository)
@@ -606,8 +650,12 @@ tvOS 12.2.1); it seems that the use of "legacy" protocol just requires bit 27 (l
"features" plist code (reported to the client by the AirPlay server) to be set.
# ChangeLog
1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted streaming debug output (readable aligned timestamps with
decimal points in seconds). Eliminate memory leaks (found by valgrind).
1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted
streaming debug output (readable aligned timestamps with
decimal points in seconds). Eliminate memory leaks
(found by valgrind). Support for display of ALAC
(audio-only) metadata (soundtrack artist names, titles etc.)
in the uxplay terminal.
1.51 2022-04-24 Reworked options forVideo4Linux2 support (new option -v4l2) and short options -rpi, -rpifb, -rpiwl as
synonyms for -v4l2, -v4l2 -vs kmssink, and -v4l2 -vs waylandsink. Reverted a change from 1.48 that broke

68
README.txt
View File

@@ -1,7 +1,7 @@
UxPlay 1.52: AirPlay/AirPlay-Mirror server for Linux, macOS, and Unix.
======================================================================
### Now developed at GitHub site <https://github.com/FDH2/UxPlay> (where user issues should be posted).
### Now developed at a new GitHub site <https://github.com/FDH2/UxPlay> (where user issues should be posted).
Highlights:
@@ -21,10 +21,13 @@ Highlights:
and "audiosinks".
- Support for server behind a firewall.
- **New**: Support for Raspberry Pi, with hardware video acceleration
by Video4Linux2 (replacement for OpenMAX, which is no longer
supplied in Raspberry Pi OS) (may require a
by Video4Linux2 (replacement for 32-bit-only OpenMAX, which is no
longer supplied in Raspberry Pi OS). (For GStreamer \< 1.22, a
[patch](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
to the GStreamer Video4Linux2 plugin.) See [success
to the GStreamer Video4Linux2 plugin (available in the [UxPlay
Wiki](https://github.com/FDH2/UxPlay/wiki)) is required, unless your
distribution has made a backport of changes from the development
version.) See [success
reports](https://github.com/FDH2/UxPlay/wiki/UxPlay-on-Raspberry-Pi:-success-reports:).
This project is a GPLv3 open source unix AirPlay2 Mirror server for
@@ -34,12 +37,12 @@ Linux, macOS, and \*BSD. It was initially developed by
[AirplayServer](https://github.com/KqsMea8/AirplayServer),
[shairplay](https://github.com/juhovh/shairplay), and
[playfair](https://github.com/EstebanKubata/playfair). (The antimof site
is mainly inactive, but periodically posts updates pulled from the [main
UxPlay site](https://github.com/FDH2/UxPlay)).
is no longer involved in development, but periodically posts updates
pulled from the new 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 21.10, Linux Mint
20.2, Pop!\_OS 21.10 (NVIDIA edition), Rocky Linux 8.5 (a CentOS
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.
@@ -72,10 +75,11 @@ mode which streams Apple Lossless (ALAC) audio without screen mirroring
is displayed in the terminal). *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.* **Note that Apple DRM (as in Apple TV app
content on the client) cannot be decrypted by UxPlay, and (unlike with a
true AppleTV), the client cannot run a http connection on the server
instead of streaming content from one on the client.**
Mirror mode connection.* **Note that Apple DRM (as found in Apple TV app
content on the client) cannot be decrypted by UxPlay, and (unlike a true
AppleTV), the UxPlay server does not allow the Apple client to directly
run a http connection on the server instead of streaming content from
the http conection on the client.**
### Possibility for using hardware-accelerated h264 video-decoding, if available.
@@ -102,7 +106,7 @@ options `uxplay -vd nvh264dec -vs glimagesink`. For GStreamer-1.16.3 or
earlier, the plugin is called `nvdec`, and must be built by the user:
see [these
instructions](https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins).
This older form of the plugin should be used with the
This older form of the NVIDIA plugin should be used with the
`-vd nvdec -vs glimagesink` uxplay options.
- **GPU Support for Raspberry Pi**
@@ -113,21 +117,23 @@ This older form of the plugin should be used with the
by the Pi's built-in Broadcom GPU should be used. RPi OS (Bullseye)
has abandoned the omx (OpenMAX) driver used till now for this by
[RPiPlay](http://github.com/FD-/RPiPlay), in favor of v4l2
(Video4Linux2). The GStreamer Video4Linux2 plugin only works with
UxPlay since GStreamer-1.21.0.0 on the development branch, but a
(Video4Linux2). A GStreamer Video4Linux2 plugin that works with
UxPlay is now in the GStreamer-1.21.0.0 development branch, and will
only be available in the forthcoming GStreamer-1.22 release ,but a
(partial) backport (as `gstreamer1.0-plugins-good-1.18.4-2+~rpt1`)
for RPi OS (Bullseye) has already appeared in current updates. Until
the promised full update appears, or if you are using a different
distribution, you can find [patching
for RPi OS (Bullseye) has already appeared in its current updates.
Until the promised full update appears, or if you are using a
different distribution, you can find [patching
instructions](https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches)
in the [UxPlay Wiki](https://github.com/FDH2/UxPlay/wiki). Patches
for GStreamer-1.18.5 (used in Ubuntu 21.10 for RPi) and
GStreamer-1.20.1 (used in Manjaro for RPi) are also available. On
"Desktop" operating systems with X11, use `uxplay -v4l2` (or use
`-rpi` as a synonym), and optionally specify a videosink with
"`-vs ..`"); use `uxplay -rpiwl` as a synonym for
"`-v4l2 -vs waylandsink`" on a Desktop system with Wayland. On a
system without X11 with framebuffer video (such as RPi OS Bullseye
GStreamer-1.20.1 (used in Ubuntu 22.04 and Manjaro for RPi) are also
available. On "Desktop" operating systems with X11, if just using
`uxplay` does not work well, use `uxplay -v4l2` (or use `-rpi` as a
synonym), and optionally specify a videosink with "`-vs ..`"); use
`uxplay -rpiwl` as a synonym for "`-v4l2 -vs waylandsink`" 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 `uxplay -rpifb` as a synonym for
"`uxplay -v4l2 -vs kmssink`".
@@ -142,7 +148,7 @@ distributions treat OpenSSL as a "System Library" which the GPL allows
linking to.
For "GPL-strict" distributions, UxPlay can be built using OpenSSL-
3.0.0, which has a new [GPLv3-compatible
3.0.0, which has anew [GPLv3-compatible
license](https://www.openssl.org/blog/blog/2021/09/07/OpenSSL3.Final/).
Getting UxPlay:
@@ -237,8 +243,12 @@ 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 [Troubleshooting](#troubleshooting) below
for help with this or other problems. See [Usage](#usage) for run-time
options.
for help with this or other problems. One common problem involves
GStreamer attempting to use incorrectly configured or absent accelerated
hardware h264 video decoding (e.g., VAAPI). 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. See [Usage](#usage)
for run-time options.
- **Red Hat, Fedora, CentOS (now continued as Rocky Linux or Alma
Linux):** (sudo yum install) openssl-devel libplist-devel
@@ -784,7 +794,9 @@ ChangeLog
1.52 2022-05-05 Cleaned up initial audio sync code, and reformatted
streaming debug output (readable aligned timestamps with decimal points
in seconds). Eliminate memory leaks (found by valgrind).
in seconds). Eliminate memory leaks (found by valgrind). Support for
display of ALAC (audio-only) metadata (soundtrack artist names, titles
etc.) in the uxplay terminal.
1.51 2022-04-24 Reworked options forVideo4Linux2 support (new option
-v4l2) and short options -rpi, -rpifb, -rpiwl as synonyms for -v4l2,