1876 lines
111 KiB
HTML
1876 lines
111 KiB
HTML
<h1
|
||
id="uxplay-1.71-airplay-mirror-and-airplay-audio-server-for-linux-macos-and-unix-now-also-runs-on-windows.">UxPlay
|
||
1.71: AirPlay-Mirror and AirPlay-Audio server for Linux, macOS, and Unix
|
||
(now also runs on Windows).</h1>
|
||
<h3
|
||
id="now-developed-at-the-github-site-httpsgithub.comfdh2uxplay-where-all-user-issues-should-be-posted-and-latest-versions-can-be-found."><strong>Now
|
||
developed at the GitHub site <a href="https://github.com/FDH2/UxPlay"
|
||
class="uri">https://github.com/FDH2/UxPlay</a> (where ALL user issues
|
||
should be posted, and latest versions can be found).</strong></h3>
|
||
<ul>
|
||
<li><em><strong>NEW in v1.71</strong>: Support for (YouTube) HLS (HTTP
|
||
Live Streaming) video with the new “-hls” option.</em> Click on the
|
||
airplay icon in the YouTube app to stream video. (You may need to wait
|
||
until advertisements have finished or been skipped before clicking the
|
||
YouTube airplay icon.) <strong>Please report any issues with this new
|
||
feature of UxPlay</strong>.</li>
|
||
</ul>
|
||
<h2 id="highlights">Highlights:</h2>
|
||
<ul>
|
||
<li>GPLv3, open source.</li>
|
||
<li>Originally supported only AirPlay Mirror protocol, now has added
|
||
support for AirPlay Audio-only (Apple Lossless ALAC) streaming from
|
||
current iOS/iPadOS clients. <strong>Now with support for Airplay HLS
|
||
video-streaming (currently only YouTube video).</strong></li>
|
||
<li>macOS computers (2011 or later, both Intel and “Apple Silicon” M1/M2
|
||
systems) can act either as AirPlay clients, or as the server running
|
||
UxPlay. Using AirPlay, UxPlay can emulate a second display for macOS
|
||
clients.</li>
|
||
<li>Support for older iOS clients (such as 32-bit iPad 2nd gen., iPod
|
||
Touch 5th gen. and iPhone 4S, when upgraded to iOS 9.3.5, or later
|
||
64-bit devices), plus a Windows AirPlay-client emulator, AirMyPC.</li>
|
||
<li>Uses GStreamer plugins for audio and video rendering (with options
|
||
to select different hardware-appropriate output “videosinks” and
|
||
“audiosinks”, and a fully-user-configurable video streaming
|
||
pipeline).</li>
|
||
<li>Support for server behind a firewall.</li>
|
||
<li>Raspberry Pi support <strong>both with and without hardware video
|
||
decoding</strong> by the Broadcom GPU. <em>Tested on Raspberry Pi Zero 2
|
||
W, 3 Model B+, 4 Model B, and 5.</em></li>
|
||
<li>Support for running on Microsoft Windows (builds with the MinGW-64
|
||
compiler in the unix-like MSYS2 environment).</li>
|
||
</ul>
|
||
<p>Note: AirPlay2 multi-room audio streaming is not supported: use <a
|
||
href="https://github.com/mikebrady/shairport-sync">shairport-sync</a>
|
||
for that.</p>
|
||
<h2 id="packaging-status-linux-and-bsd-distributions">Packaging status
|
||
(Linux and *BSD distributions)</h2>
|
||
<p><a href="https://repology.org/project/uxplay/versions"><img
|
||
src="https://repology.org/badge/vertical-allrepos/uxplay.svg"
|
||
alt="Current Packaging status" /></a>.</p>
|
||
<ul>
|
||
<li><p>Install uxplay on Debian-based Linux systems with
|
||
“<code>sudo apt install uxplay</code>”; on FreeBSD with
|
||
“<code>sudo pkg install uxplay</code>”. Also available on Arch-based
|
||
systems through AUR. Since v. 1.66, uxplay is now also packaged in RPM
|
||
format by Fedora 38 (“<code>sudo dnf install uxplay</code>”).</p></li>
|
||
<li><p>For other RPM-based distributions which have not yet packaged
|
||
UxPlay, a RPM “specfile” <strong>uxplay.spec</strong> is now provided
|
||
with recent <a
|
||
href="https://github.com/FDH2/UxPlay/releases">releases</a> (see their
|
||
“Assets”), and can also be found in the UxPlay source top directory. See
|
||
the section on using this specfile for <a
|
||
href="#building-an-installable-rpm-package">building an installable RPM
|
||
package</a>.</p></li>
|
||
</ul>
|
||
<p>After installation:</p>
|
||
<ul>
|
||
<li><p>(On Linux and *BSD): if a firewall is active on the server
|
||
hosting UxPlay, make sure the default network port (UDP 5353) for
|
||
mDNS/DNS-SD queries is open (see <a
|
||
href="#troubleshooting">Troubleshooting</a> below for more details);
|
||
also open three UDP and three TCP ports for Uxplay, and use the “uxplay
|
||
-p <n>” option (see “<code>man uxplay</code>” or
|
||
“<code>uxplay -h</code>”).</p></li>
|
||
<li><p>Even if you install your distribution’s pre-compiled uxplay
|
||
binary package, you may need to read the instructions below for <a
|
||
href="#running-uxplay">running UxPlay</a> to see which of your
|
||
distribution’s <strong>GStreamer plugin packages</strong> you should
|
||
also install.</p></li>
|
||
<li><p>For Audio-only mode (Apple Music, etc.) best quality is obtained
|
||
with the option “uxplay -async”, but there is then a 2 second latency
|
||
imposed by iOS.</p></li>
|
||
<li><p>Add any UxPlay options you want to use as defaults to a startup
|
||
file <code>~/.uxplayrc</code> (see “<code>man uxplay</code>” or
|
||
“<code>uxplay -h</code>” for format and other possible locations). In
|
||
particular, if your system uses PipeWire audio or Wayland video systems,
|
||
you may wish to add “as pipewiresink” or “vs waylandsink” as defaults to
|
||
the file. <em>(Output from terminal commands “ps waux | grep pulse” or
|
||
“pactl info” will contain “pipewire” if your Linux/BSD system uses
|
||
it).</em></p></li>
|
||
<li><p>On Raspberry Pi: models using hardware h264 video decoding by the
|
||
Broadcom GPU (models 4B and earlier) may require the uxplay option
|
||
-bt709. If you use Ubuntu 22.10 or earlier, GStreamer must be <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">patched</a>
|
||
to use hardware video decoding by the Broadcom GPU (also recommended but
|
||
optional for Raspberry Pi OS (Bullseye): the patched GStreamer does not
|
||
need option ” -bt709`“. The need for -bt709 when hardware video decoding
|
||
is used seems to have reappeared starting with GStreamer-1.22.</p></li>
|
||
</ul>
|
||
<p>To (easily) compile the latest UxPlay from source, see the section <a
|
||
href="#getting-uxplay">Getting UxPlay</a>.</p>
|
||
<h1 id="detailed-description-of-uxplay">Detailed description of
|
||
UxPlay</h1>
|
||
<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
|
||
OpenMAX-based <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 “Buster”, 11 “Bullseye”, 12 “Bookworm”), Ubuntu (20.04 LTS,
|
||
22.04 LTS, 23.04 (also Ubuntu derivatives Linux Mint, Pop!_OS), Red Hat
|
||
and clones (Fedora 38, Rocky Linux 9.2), openSUSE Leap 15.5, Mageia 9,
|
||
OpenMandriva “ROME”, PCLinuxOS, Arch Linux, Manjaro, and should run on
|
||
any Linux system. Also tested on macOS Catalina and Ventura (Intel) and
|
||
Sonoma (M2), FreeBSD 14.0, Windows 10 and 11 (64 bit).</p>
|
||
<p>On Raspberry Pi 4 model B, it is tested on Raspberry Pi OS (Bullseye
|
||
and Bookworm) (32- and 64-bit), Ubuntu 22.04 LTS and 23.04, Manjaro RPi4
|
||
23.02, and (without hardware video decoding) on openSUSE 15.5. Also
|
||
tested on Raspberry Pi Zero 2 W, 3 model B+, and now 5.</p>
|
||
<p>Its main use is to act like an AppleTV for screen-mirroring (with
|
||
audio) of iOS/iPadOS/macOS clients (iPhone, iPod Touch, iPad, Mac
|
||
computers) on the server display of a host running Linux, macOS, or
|
||
other unix (and now also Microsoft Windows). UxPlay supports Apple’s
|
||
AirPlay2 protocol using “Legacy Protocol”, but some features are
|
||
missing. (Details of what is publicly known about Apple’s AirPlay 2
|
||
protocol can be found <a
|
||
href="https://openairplay.github.io/airplay-spec/">here</a>, <a
|
||
href="https://github.com/SteeBono/airplayreceiver/wiki/AirPlay2-Protocol">here</a>
|
||
and <a href="https://emanuelecozzi.net/docs/airplay2">here</a>; see also
|
||
<a href="https://pyatv.dev/documentation/protocols">pyatv</a> which
|
||
could be a resource for adding modern protocols.) While there is no
|
||
guarantee that future iOS releases will keep supporting “Legacy
|
||
Protocol”, iOS 17 continues support.</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 <strong>AirPlay Mirror</strong> mode (which streams
|
||
lossily-compressed AAC audio while mirroring the client screen, or in
|
||
the alternative <strong>AirPlay Audio</strong> mode which streams Apple
|
||
Lossless (ALAC) audio without screen mirroring. In
|
||
<strong>Audio</strong> mode, metadata is displayed in the uxplay
|
||
terminal; if UxPlay option <code>-ca <name></code> is used, the
|
||
accompanying cover art is also output to a periodically-updated file
|
||
<code><name></code>, and can be viewed with a (reloading) graphics
|
||
viewer of your choice. <em>Switching between</em>
|
||
<strong>Mirror</strong> <em>and</em> <strong>Audio</strong> <em>modes
|
||
during an active connection is possible: in</em> <strong>Mirror</strong>
|
||
<em>mode, stop mirroring (or close the mirror window) and start an</em>
|
||
<strong>Audio</strong> <em>mode connection, switch back by initiating
|
||
a</em> <strong>Mirror</strong> <em>mode connection; cover-art display
|
||
stops/restarts as you leave/re-enter</em> <strong>Audio</strong>
|
||
<em>mode.</em></p>
|
||
<ul>
|
||
<li><p><strong>Note that Apple video-DRM (as found in “Apple TV app”
|
||
content on the client) cannot be decrypted by UxPlay, and the Apple TV
|
||
app cannot be watched using UxPlay’s AirPlay Mirror mode (only the
|
||
unprotected audio will be streamed, in AAC format).</strong></p></li>
|
||
<li><p><strong>With the new “-hls” option, UxPlay now also supports
|
||
non-Mirror AirPlay video streaming (where the client controls a web
|
||
server on the AirPlay server that directly receives HLS content to avoid
|
||
it being decoded and re-encoded by the client). This currently only
|
||
supports streaming of YouTube videos. Without the -hls option, using the
|
||
icon for AirPlay video in apps such as the YouTube app will only send
|
||
audio (in lossless ALAC format) without the accompanying
|
||
video.</strong></p></li>
|
||
</ul>
|
||
<h3
|
||
id="possibility-for-using-hardware-accelerated-h264h265-video-decoding-if-available.">Possibility
|
||
for using hardware-accelerated h264/h265 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>
|
||
<ul>
|
||
<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 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>
|
||
<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. For GStreamer-1.16.3 or earlier,
|
||
the plugin is called <code>nvdec</code>, and must be <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/NVIDIA-nvdec-and-nvenc-plugins">built
|
||
by the user</a>.</p></li>
|
||
<li><p><strong>Video4Linux2 support for h264 hardware decoding on
|
||
Raspberry Pi (Pi 4B and older)</strong></p>
|
||
<p>Raspberry Pi (RPi) computers (tested on Pi 4 Model B) can now run
|
||
UxPlay using software video decoding, but hardware-accelerated h264/h265
|
||
decoding by firmware in the Pi’s Broadcom 2835 GPU is prefered. UxPlay
|
||
accesses this using the GStreamer-1.22 Video4Linux2 (v4l2) plugin; Uses
|
||
the out-of-mainline Linux kernel module bcm2835-codec maintained by
|
||
Raspberry Pi, so far only included in Raspberry Pi OS, and two other
|
||
distributions (Ubuntu, Manjaro) available with Raspberry Pi Imager.
|
||
<em>(For GStreamer < 1.22, see the <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">UxPlay
|
||
Wiki</a>)</em>. Pi model 5 has no support for hardware H264 decoding, as
|
||
its CPU is powerful enough for satisfactory software H264
|
||
decoding</p></li>
|
||
<li><p><strong>Support for h265 (HEVC) hardware decoding on Raspberry Pi
|
||
(Pi 4 model B and Pi 5)</strong></p>
|
||
<p>These Raspberry Pi models have a dedicated HEVC decoding block (not
|
||
the GPU), with a driver “rpivid” which is not yet in the mainline Linux
|
||
kernel (but is planned to be there in future). Unfortunately it produces
|
||
decoded video in a non-standard pixel format (NC30 or “SAND”) which will
|
||
not be supported by GStreamer until the driver is in the mainline
|
||
kernel; without this support, UxPlay support for HEVC hardware decoding
|
||
on Raspberry Pi will not work.</p></li>
|
||
</ul>
|
||
<h3 id="note-to-packagers">Note to packagers:</h3>
|
||
<p>UxPlay’s GPLv3 license does not have an added “GPL exception”
|
||
explicitly allowing it to be distributed in compiled form when linked to
|
||
OpenSSL versions <strong>prior to v. 3.0.0</strong> (older versions of
|
||
OpenSSL have a license clause incompatible with the GPL unless OpenSSL
|
||
can be regarded as a “System Library”, which it is in *BSD). Many Linux
|
||
distributions treat OpenSSL as a “System Library”, but some
|
||
(e.g. Debian) do not: in this case, the issue is solved by linking with
|
||
OpenSSL-3.0.0 or later.</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>
|
||
<ul>
|
||
<li>A recent UxPlay can also be found on the original <a
|
||
href="https://github.com/antimof/UxPlay">antimof site</a>; that original
|
||
project is inactive, but is usually kept current or almost-current with
|
||
the <a href="https://github.com/FDH2/UxPlay">active UxPlay github
|
||
site</a> (thank you antimof!).</li>
|
||
</ul>
|
||
<h2 id="building-uxplay-on-linux-or-bsd">Building UxPlay on Linux (or
|
||
*BSD):</h2>
|
||
<h3 id="debian-based-systems">Debian-based systems:</h3>
|
||
<p>(Adapt these instructions for non-Debian-based Linuxes or *BSD; for
|
||
macOS, see specific instruction 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>=3.10 is installed: “<code>sudo apt 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” based systems
|
||
(e.g, Ubuntu 18.04) or newer; on Debian 10 systems “libplist” is an
|
||
older version, you need “libplist3”.) If it does not, you may need to
|
||
build and install these from source (see instructions at the end of this
|
||
README).</p>
|
||
<p>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). Similarly, for non-standard (or multiple) GStreamer
|
||
installations, set the environment variable GSTREAMER_ROOT_DIR to the
|
||
directory that contains the “…/gstreamer-1.0/” directory of the
|
||
gstreamer installation that UxPlay should use (if this is <em>e.g.</em>
|
||
“~/my_gstreamer/lib/gstreamer-1.0/”, set this location with
|
||
“<code>export GSTREAMER_ROOT_DIR=$HOME/my_gstreamer/lib</code>”).</p>
|
||
<ul>
|
||
<li>Most users will use the GStreamer supplied by their distribution,
|
||
but a few (in particular users of Raspberry Pi OS Lite Legacy (Buster)
|
||
on a Raspberry Pi model 4B who wish to stay on that unsupported Legacy
|
||
OS for compatibility with other apps) should instead build a newer
|
||
Gstreamer from source following <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).">these
|
||
instructions</a> . <strong>Do this <em>before</em> building
|
||
UxPlay</strong>.</li>
|
||
</ul>
|
||
<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>If you use X11 Windows on Linux or *BSD, and wish to toggle in/out of
|
||
fullscreen mode with a keypress (F11 or Alt_L+Enter) UxPlay needs to be
|
||
built with a dependence on X11. Starting with UxPlay-1.59, this will be
|
||
done by default <strong>IF</strong> the X11 development libraries are
|
||
installed and detected. Install these with
|
||
“<code>sudo apt install libx11-dev</code>”. If GStreamer < 1.20 is
|
||
detected, a fix needed by screen-sharing apps (<em>e.g.</em>, Zoom) will
|
||
also be made.</p>
|
||
<ul>
|
||
<li>If X11 development libraries are present, but you wish to build
|
||
UxPlay <em>without</em> any X11 dependence, use the cmake option
|
||
<code>-DNO_X11_DEPS=ON</code>.</li>
|
||
</ul>
|
||
<ol type="1">
|
||
<li><code>sudo apt install libssl-dev libplist-dev</code>“. (<em>unless
|
||
you need to build OpenSSL and libplist from source</em>).</li>
|
||
<li><code>sudo apt install libavahi-compat-libdnssd-dev</code></li>
|
||
<li><code>sudo apt install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev</code>.
|
||
(*<em>Skip if you built Gstreamer from source</em>)</li>
|
||
<li><code>cmake .</code> (<em>For a cleaner build, which is useful if
|
||
you modify the source, replace this by</em>
|
||
“<code>mkdir build; cd build; cmake ..</code>”: <em>you can then delete
|
||
the contents of the <code>build</code> directory if needed, without
|
||
affecting the source.</em>) Also add any cmake “<code>-D</code>” options
|
||
here as needed (e.g, <code>-DNO_X11_DEPS=ON</code> or
|
||
<code>-DNO_MARCH_NATIVE=ON</code>).</li>
|
||
<li><code>make</code></li>
|
||
<li><code>sudo make install</code> (you can afterwards uninstall with
|
||
<code>sudo make uninstall</code> in the same directory in which this was
|
||
run).</li>
|
||
</ol>
|
||
<p>This installs the executable file “<code>uxplay</code>” to
|
||
<code>/usr/local/bin</code>, (and installs a manpage to somewhere
|
||
standard like <code>/usr/local/share/man/man1</code> and README files to
|
||
somewhere like <code>/usr/local/share/doc/uxplay</code>). (If “man
|
||
uxplay” fails, check if $MANPATH is set: if so, the path to the manpage
|
||
(usually /usr/local/share/man/) needs to be added to $MANPATH .) The
|
||
uxplay executable can also be found in the build directory after the
|
||
build process, if you wish to test before installing (in which case the
|
||
GStreamer plugins must first be installed).</p>
|
||
<h3 id="building-on-non-debian-linux-and-bsd">Building on non-Debian
|
||
Linux and *BSD</h3>
|
||
<p>**For those with RPM-based distributions, a RPM spec file uxplay.spec
|
||
is also available: see <a
|
||
href="#building-an-installable-rpm-package">Building an installable rpm
|
||
package</a>.</p>
|
||
<ul>
|
||
<li><p><strong>Red Hat, or clones like CentOS (now continued as Rocky
|
||
Linux or Alma Linux):</strong> (sudo dnf install, or sudo yum install)
|
||
openssl-devel libplist-devel avahi-compat-libdns_sd-devel
|
||
gstreamer1-devel gstreamer1-plugins-base-devel (+libX11-devel for
|
||
fullscreen X11) <em>(some of these may be in the “CodeReady” add-on
|
||
repository, called “PowerTools” by clones)</em></p></li>
|
||
<li><p><strong>Mageia, PCLinuxOS, OpenMandriva:</strong> Same as Red
|
||
Hat, except for name changes: (Mageia) “gstreamer1.0-devel”,
|
||
“gstreamer-plugins-base1.0-devel”; (OpenMandriva) “libopenssl-devel”,
|
||
“gstreamer-devel”, “libgst-plugins-base1.0-devel”. PCLinuxOS: same as
|
||
Mageia, but uses synaptic (or apt) as its package manager.</p></li>
|
||
<li><p><strong>openSUSE:</strong> (sudo zypper install)
|
||
libopenssl-3-devel (formerly libopenssl-devel) libplist-2_0-devel
|
||
(formerly libplist-devel) avahi-compat-mDNSResponder-devel
|
||
gstreamer-devel gstreamer-plugins-base-devel (+ libX11-devel for
|
||
fullscreen X11).</p></li>
|
||
<li><p><strong>Arch Linux</strong> (<em>Also available as a package in
|
||
AUR</em>): (sudo pacman -Syu) openssl libplist avahi
|
||
gst-plugins-base.</p></li>
|
||
<li><p><strong>FreeBSD:</strong> (sudo pkg install) libplist gstreamer1.
|
||
Either avahi-libdns or mDNSResponder must also be installed to provide
|
||
the dns_sd library. OpenSSL is already installed as a System
|
||
Library.</p></li>
|
||
</ul>
|
||
<h4 id="building-an-installable-rpm-package">Building an installable RPM
|
||
package</h4>
|
||
<p>First-time RPM builders should first install the rpm-build and
|
||
rpmdevtools packages, then create the rpmbuild tree with
|
||
“<code>rpmdev-setuptree</code>”. Then download and copy uxplay.spec into
|
||
<code>~/rpmbuild/SPECS</code>. In that directory, run
|
||
“<code>rpmdev-spectool -g -R uxplay.spec</code>” to download the
|
||
corresponding source file <code>uxplay-*.tar.gz</code> into
|
||
<code>~/rpmbuild/SOURCES</code> (“rpmdev-spectool” may also be just
|
||
called “spectool”); then run “<code>rpmbuild -ba uxplay.spec</code>”
|
||
(you will need to install any required dependencies this reports). This
|
||
should create the uxplay RPM package in a subdirectory of
|
||
<code>~/rpmbuild/RPMS</code>. (<strong>uxplay.spec</strong> is tested on
|
||
Fedora 38, Rocky Linux 9.2, openSUSE Leap 15.5, Mageia 9, OpenMandriva,
|
||
PCLinuxOS; it can be easily modified to include dependency lists for
|
||
other RPM-based distributions.)</p>
|
||
<h2 id="running-uxplay">Running UxPlay</h2>
|
||
<h3
|
||
id="installing-plugins-debian-based-linux-distributions-including-ubuntu-and-raspberry-pi-os-skip-if-you-built-a-complete-gstreamer-from-source">Installing
|
||
plugins (Debian-based Linux distributions, including Ubuntu and
|
||
Raspberry Pi OS) (<em>skip if you built a complete GStreamer from
|
||
source</em>)</h3>
|
||
<p>Next install the GStreamer plugins that are needed with
|
||
<code>sudo apt install gstreamer1.0-<plugin></code>. Values of
|
||
<code><plugin></code> required are:</p>
|
||
<ol type="1">
|
||
<li>“<strong>plugins-base</strong>”</li>
|
||
<li>“<strong>libav</strong>” (for sound),</li>
|
||
<li>“<strong>plugins-good</strong>” (for v4l2 hardware h264
|
||
decoding)</li>
|
||
<li>“<strong>plugins-bad</strong>” (for h264 decoding).</li>
|
||
</ol>
|
||
<p><strong>Debian-based distributions split some of the plugin packages
|
||
into smaller pieces:</strong> some that may also be needed include
|
||
“<strong>gl</strong>” for OpenGL support (this provides the “-vs
|
||
glimagesink” videosink, which can be very useful in many systems
|
||
(including Raspberry Pi), and should always be used when using h264/h265
|
||
decoding by a NVIDIA GPU), “<strong>gtk3</strong>” (which provides the
|
||
“-vs gtksink” videosink), and “<strong>x</strong>” for X11 support,
|
||
although these may already be installed; “<strong>vaapi</strong>” is
|
||
needed for hardware-accelerated h264 video decoding by Intel or AMD
|
||
graphics (but not for use with NVIDIA using proprietary drivers). If
|
||
sound is not working,
|
||
“<strong>alsa</strong>”“,”<strong>pulseaudio</strong>”, or
|
||
“<strong>pipewire</strong>” plugins may need to be installed, depending
|
||
on how your audio is set up.</p>
|
||
<ul>
|
||
<li>Also install “<strong>gstreamer1.0-tools</strong>” to get the
|
||
utility gst-inspect-1.0 for examining the GStreamer installation.</li>
|
||
</ul>
|
||
<h3
|
||
id="installing-plugins-non-debian-based-linux-or-bsd-skip-if-you-built-a-complete-gstreamer-from-source">Installing
|
||
plugins (Non-Debian-based Linux or *BSD) (<em>skip if you built a
|
||
complete GStreamer from source</em>)</h3>
|
||
<p>In some cases, because of patent issues, the libav plugin feature
|
||
<strong>avdec_aac</strong> needed for decoding AAC audio in mirror mode
|
||
is not provided in the official distribution: get it from community
|
||
repositories for those distributions.</p>
|
||
<ul>
|
||
<li><p><strong>Red Hat, or clones like CentOS (now continued as Rocky
|
||
Linux or Alma Linux):</strong> Install gstreamer1-libav
|
||
gstreamer1-plugins-bad-free (+ gstreamer1-vaapi for Intel/AMD graphics).
|
||
In recent Fedora, gstreamer1-libav is renamed gstreamer1-plugin-libav.
|
||
<strong>To get avdec_aac, install packages from <a
|
||
href="https://rpmfusion.org">rpmfusion.org</a></strong>: (get
|
||
ffmpeg-libs from rpmfusion; on RHEL or clones, but not recent Fedora,
|
||
also get gstreamer1-libav from there).</p></li>
|
||
<li><p><strong>Mageia, PCLinuxOS, OpenMandriva:</strong> Install
|
||
gstreamer1.0-libav gstreamer1.0-plugins-bad (+ gstreamer1.0-vaapi for
|
||
Intel/AMD graphics). <strong>On Mageia, to get avdec_aac, install ffmpeg
|
||
from the “tainted” repository</strong>, (which also provides a more
|
||
complete gstreamer1.0-plugins-bad).</p></li>
|
||
<li><p><strong>openSUSE:</strong> Install gstreamer-plugins-libav
|
||
gstreamer-plugins-bad (+ gstreamer-plugins-vaapi for Intel/AMD
|
||
graphics). <strong>To get avdec_aac, install libav* packages for
|
||
openSUSE from <a
|
||
href="https://ftp.gwdg.de/pub/linux/misc/packman/suse/">Packman</a>
|
||
“Essentials”</strong>; recommendation: after adding the Packman
|
||
repository, use the option in YaST Software management to switch all
|
||
system packages for multimedia to Packman).</p></li>
|
||
<li><p><strong>Arch Linux</strong> Install gst-plugins-good
|
||
gst-plugins-bad gst-libav (+ gstreamer-vaapi for Intel/AMD
|
||
graphics).</p></li>
|
||
<li><p><strong>FreeBSD:</strong> Install gstreamer1-libav,
|
||
gstreamer1-plugins, gstreamer1-plugins-* (* = core, good, bad, x, gtk,
|
||
gl, vulkan, pulse, v4l2, …), (+ gstreamer1-vaapi for Intel/AMD
|
||
graphics).</p></li>
|
||
</ul>
|
||
<h3 id="starting-and-running-uxplay">Starting and running UxPlay</h3>
|
||
<p>Since UxPlay-1.64, UxPlay can be started with options read from a
|
||
configuration file, which will be the first found of (1) a file with a
|
||
path given by environment variable <code>$UXPLAYRC</code>, (2)
|
||
<code>~/.uxplayrc</code> in the user’s home directory (“~”), (3)
|
||
<code>~/.config/uxplayrc</code>. The format is one option per line,
|
||
omitting the initial <code>"-"</code> of the command-line option. Lines
|
||
in the configuration file beginning with <code>"#"</code> are treated as
|
||
comments and ignored.</p>
|
||
<p><strong>Run uxplay in a terminal window</strong>. On some systems,
|
||
you can specify fullscreen mode with the <code>-fs</code> option, or
|
||
toggle into and out of fullscreen mode with F11 or (held-down left
|
||
Alt)+Enter keys. Use Ctrl-C (or close the window) to terminate it when
|
||
done. If the UxPlay server 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> (on
|
||
non-systemd systems, such as *BSD, use
|
||
<code>sudo service avahi-daemon [status, start, stop, restart, ...]</code>).
|
||
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: <strong>if a firewall is active, also open UDP port 5353 (for
|
||
mDNS queries) needed by Avahi</strong>. See <a
|
||
href="#troubleshooting">Troubleshooting</a> below for help with this or
|
||
other problems.</p>
|
||
<ul>
|
||
<li><p>Unlike an Apple TV, the UxPlay server does not by default require
|
||
clients to initially “pair” with it using a pin code displayed by the
|
||
server (after which the client “trusts” the server, and does not need to
|
||
repeat this). Since v1.67, Uxplay offers such “pin-authentication” as an
|
||
option: see “<code>-pin</code>” and “<code>-reg</code>” in <a
|
||
href="#usage">Usage</a> for details, if you wish to use it. <em>Some
|
||
clients with MDM (Mobile Device Management, often present on
|
||
employer-owned devices) are required to use pin-authentication: UxPlay
|
||
will provide this even when running without the pin
|
||
option.</em></p></li>
|
||
<li><p>By default, UxPlay is locked to its current client until that
|
||
client drops the connection; since UxPlay-1.58, the option
|
||
<code>-nohold</code> modifies this behavior so that when a new client
|
||
requests a connection, it removes the current client and takes over.
|
||
UxPlay 1.66 introduces a mechanism ( <code>-restrict</code>,
|
||
<code>-allow <id></code>, <code>-block <id></code>) to
|
||
control which clients are allowed to connect, using their “deviceID”
|
||
(which in Apple devices appears to be immutable).</p></li>
|
||
<li><p>In Mirror mode, GStreamer has a choice of <strong>two</strong>
|
||
methods to play video with its accompanying audio: prior to UxPlay-1.64,
|
||
the video and audio streams were both played as soon as possible after
|
||
they arrived (the GStreamer “<em>sync=false</em>” method), with a
|
||
GStreamer internal clock used to try to keep them synchronized.
|
||
<strong>Starting with UxPlay-1.64, the other method (GStreamer’s
|
||
“<em>sync=true</em>” mode), which uses timestamps in the audio and video
|
||
streams sent by the client, is the new default</strong>. On
|
||
low-decoding-power UxPlay hosts (such as Raspberry Pi Zero W or 3 B+
|
||
models) this will drop video frames that cannot be decoded in time to
|
||
play with the audio, making the video jerky, but still
|
||
synchronized.</p></li>
|
||
</ul>
|
||
<p>The older method which does not drop late video frames worked well on
|
||
more powerful systems, and is still available with the UxPlay option
|
||
“<code>-vsync no</code>”; this method is adapted to “live streaming”,
|
||
and may be better when using UxPlay as a second monitor for a Mac
|
||
computer, for example, while the new default timestamp-based method is
|
||
best for watching a video, to keep lip movements and voices
|
||
synchronized. (Without use of timestamps, video will eventually lag
|
||
behind audio if it cannot be decoded fast enough: hardware-accelerated
|
||
video-decoding helped to prevent this previously when timestamps were
|
||
not being used.)</p>
|
||
<ul>
|
||
<li>In Audio-only mode the GStreamer “sync=false” mode (not using
|
||
timestamps) is still the default, but if you want to keep the audio
|
||
playing on the server synchronized with the video showing on the client,
|
||
use the <code>-async</code> timestamp-based option. (An example might be
|
||
if you want to follow the Apple Music lyrics on the client while
|
||
listening to superior sound on the UxPlay server). This delays the video
|
||
on the client to match audio on the server, so leads to a slight delay
|
||
before a pause or track-change initiated on the client takes effect on
|
||
the audio played by the server.</li>
|
||
</ul>
|
||
<p>AirPlay volume-control attenuates volume (gain) by up to -30dB: the
|
||
decibel range -30:0 can be rescaled from <em>Low</em>:0, or
|
||
<em>Low</em>:<em>High</em>, using the option <code>-db</code> (“-db
|
||
<em>Low</em>” or “-db <em>Low</em>:<em>High</em>”), <em>Low</em> must be
|
||
negative. Rescaling is linear in decibels. Note that GStreamer’s audio
|
||
format will “clip” any audio gain above +20db, so keep <em>High</em>
|
||
below that level. The option <code>-taper</code> provides a “tapered”
|
||
AirPlay volume-control profile some users may prefer.</p>
|
||
<p>The -vsync and -async options also allow an optional positive (or
|
||
negative) audio-delay adjustment in <em>milliseconds</em> for
|
||
fine-tuning : <code>-vsync 20.5</code> delays audio relative to video by
|
||
0.0205 secs; a negative value advances it.)</p>
|
||
<ul>
|
||
<li><p>you may find video is improved by the setting -fps 60 that allows
|
||
some video to be played at 60 frames per second. (You can see what
|
||
framerate is actually streaming by using -vs fpsdisplaysink, and/or
|
||
-FPSdata.) When using this, you should use the default timestamp-based
|
||
synchronization option <code>-vsync</code>.</p></li>
|
||
<li><p>Since UxPlay-1.54, you can display the accompanying “Cover Art”
|
||
from sources like Apple Music in Audio-Only (ALAC) mode: run
|
||
“<code>uxplay -ca <name> &</code>” in the background, then run
|
||
a image viewer with an autoreload feature: an example is “feh”: run
|
||
“<code>feh -R 1 <name></code>” in the foreground; terminate feh
|
||
and then Uxplay with “<code>ctrl-C fg ctrl-C</code>”.</p></li>
|
||
</ul>
|
||
<p>By default, GStreamer uses an algorithm to search for the best
|
||
“videosink” (GStreamer’s term for a graphics driver to display images)
|
||
to use. You can overide this with the uxplay option
|
||
<code>-vs <videosink></code>. Which videosinks are available
|
||
depends on your operating system and graphics hardware: use
|
||
“<code>gst-inspect-1.0 | grep sink | grep -e video -e Video -e image</code>”
|
||
to see what is available. Some possibilites on Linux/*BSD are:</p>
|
||
<ul>
|
||
<li><p><strong>glimagesink</strong> (OpenGL),
|
||
<strong>waylandsink</strong></p></li>
|
||
<li><p><strong>xvimagesink</strong>, <strong>ximagesink</strong>
|
||
(X11)</p></li>
|
||
<li><p><strong>kmssink</strong>, <strong>fbdevsink</strong> (console
|
||
graphics without X11)</p></li>
|
||
<li><p><strong>vaapisink</strong> (for Intel/AMD hardware-accelerated
|
||
graphics); for NVIDIA hardware graphics (with CUDA) use
|
||
<strong>glimagesink</strong> combined with “<code>-vd nvh264dec</code>”
|
||
(or “nvh264sldec”, a new variant which will become “nvh264dec” in
|
||
GStreamer-1.24).</p></li>
|
||
<li><p>If the server is “headless” (no attached monitor, renders audio
|
||
only) use <code>-vs 0</code>.</p></li>
|
||
</ul>
|
||
<p>Note that videosink options can set using quoted arguments to -vs:
|
||
<em>e.g.</em>, <code>-vs "xvimagesink display=:0"</code>: ximagesink and
|
||
xvimagesink allow an X11 display name to be specified, and waylandsink
|
||
has a similar option. Videosink options (“properties”) can be found in
|
||
their GStreamer description pages,such as
|
||
https://gstreamer.freedesktop.org/documentation/xvimagesink .</p>
|
||
<p>GStreamer also searches for the best “audiosink”; override its choice
|
||
with <code>-as <audiosink></code>. Choices on Linux include
|
||
pulsesink, alsasink, pipewiresink, oss4sink; see what is available with
|
||
<code>gst-inspect-1.0 | grep sink | grep -e audio -e Audio</code>.</p>
|
||
<p><strong>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, or just uninstall
|
||
the GStreamer vaapi plugin.</strong></p>
|
||
<p>See <a href="#usage">Usage</a> for more run-time options.</p>
|
||
<h3
|
||
id="special-instructions-for-raspberry-pi-tested-on-raspberry-pi-zero-2-w-3-model-b-4-model-b-and-5-only"><strong>Special
|
||
instructions for Raspberry Pi (tested on Raspberry Pi Zero 2 W, 3 Model
|
||
B+, 4 Model B, and 5 only)</strong>:</h3>
|
||
<ul>
|
||
<li><p>For Framebuffer video (for Raspberry Pi OS “Lite” and other
|
||
non-X11 distributions) use the KMS videosink “-vs kmssink” (the DirectFB
|
||
framebuffer videosink “dfbvideosink” is broken on the Pi, and
|
||
segfaults). <em>In this case you should explicitly use the “-vs kmssink”
|
||
option, as without it, autovideosink does not find the correct
|
||
videosink.</em></p></li>
|
||
<li><p>Raspberry Pi 5 does not provide hardware H264 decoding (and does
|
||
not need it).</p></li>
|
||
<li><p>Pi Zero 2 W, 3 Model B+ and 4 Model B should use hardware H264
|
||
decoding by the Broadcom GPU, but it requires an out-of-mainstream
|
||
kernel module bcm2835_codec maintained in the <a
|
||
href="https://github.com/raspberrypi/linux">Raspberry Pi kernel
|
||
tree</a>; distributions that are known to supply it include Raspberry Pi
|
||
OS, Ubuntu, and Manjaro-RPi4. Use software decoding (option -avdec) if
|
||
this module is not available.</p></li>
|
||
<li><p>Uxplay uses the Video4Linux2 (v4l2) plugin from GStreamer-1.22
|
||
and later to access the GPU, if hardware H264 decoding is used. This
|
||
should happen automatically. The option -v4l2 can be used, but it is
|
||
usually best to just let GStreamer find the best video pipeline by
|
||
itself.</p></li>
|
||
<li><p>On older distributions (GStreamer < 1.22), the v4l2 plugin
|
||
needs a patch: see the <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">UxPlay
|
||
Wiki</a>. Legacy Raspberry Pi OS (Bullseye) has a partially-patched
|
||
GStreamer-1.18.4 which needs the uxplay option -bt709 (and don’t use
|
||
-v4l2); it is still better to apply the full patch from the UxPlay Wiki
|
||
in this case.</p></li>
|
||
<li><p><strong>It appears that when hardware h264 video decoding is
|
||
used, the option -bt709 became needed again in GStreamer-1.22 and
|
||
later.</strong></p></li>
|
||
<li><p>For “double-legacy” Raspberry Pi OS (Buster), there is no patch
|
||
for GStreamer-1.14. Instead, first build a complete newer
|
||
GStreamer-1.18.6 from source using <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Building-latest-GStreamer-from-source-on-distributions-with-older-GStreamer-(e.g.-Raspberry-Pi-OS-).">these
|
||
instructions</a> before building UxPlay.</p></li>
|
||
<li><p>Raspberry Pi 3 Model B+ running a 32 bit OS can also access the
|
||
GPU with the GStreamer OMX plugin (use option
|
||
“<code>-vd omxh264dec</code>”), but this is broken by Pi 4 Model B
|
||
firmware. OMX support was removed from Raspberry Pi OS (Bullseye), but
|
||
is present in Buster.</p></li>
|
||
<li><p><strong>H265 (4K)</strong> video is potentially supported by
|
||
hardware decoding on Raspberry Pi 5 models, as well as on Raspberry Pi 4
|
||
model B, using a dedicated HEVC decoding block, but the “rpivid” kernel
|
||
driver for this is not yet supported by GStreamer (this driver decodes
|
||
video into a non-standard format that cannot be supported by GStreamer
|
||
until the driver is in the mainline Linux kernel). Raspberry Pi provides
|
||
a version of ffmpeg that can use that format, but at present UxPlay
|
||
cannot use this. The best solution would be for the driver to be
|
||
“upstreamed” to the kernel, allowing GStreamer support. (Software HEVC
|
||
decoding works, but does not seem to give satisfactory results on the
|
||
Pi).</p></li>
|
||
</ul>
|
||
<p>Even with GPU video decoding, some frames may be dropped by the
|
||
lower-power models to keep audio and video synchronized using
|
||
timestamps. In Legacy Raspberry Pi OS (Bullseye), raspi-config
|
||
“Performance Options” allows specifying how much memory to allocate to
|
||
the GPU, but this setting appears to be absent in Bookworm (but it can
|
||
still be set to e.g. 128MB by adding a line “gpu_mem=128” in
|
||
/boot/config.txt). A Pi Zero 2 W (which has 512MB memory) worked well
|
||
when tested in 32 bit Bullseye or Bookworm Lite with 128MB allocated to
|
||
the GPU (default seems to be 64MB).</p>
|
||
<p>The basic uxplay options for R Pi are
|
||
<code>uxplay [-vs <videosink>]</code>. The choice
|
||
<code><videosink></code> = <code>glimagesink</code> is sometimes
|
||
useful. With the Wayland video compositor, use
|
||
<code><videosink></code> = <code>waylandsink</code>. With
|
||
framebuffer video, use <code><videosink></code> =
|
||
<code>kmssink</code>.</p>
|
||
<ul>
|
||
<li>Tip: to start UxPlay on a remote host (such as a Raspberry Pi) using
|
||
ssh:</li>
|
||
</ul>
|
||
<!-- -->
|
||
<pre><code> ssh user@remote_host
|
||
export DISPLAY=:0
|
||
nohup uxplay [options] > FILE &</code></pre>
|
||
<p>Sound and video will play on the remote host; “nohup” will keep
|
||
uxplay running if the ssh session is closed. Terminal output is saved to
|
||
FILE (which can be /dev/null to discard it)</p>
|
||
<h2
|
||
id="building-uxplay-on-macos-intel-x86_64-and-apple-silicon-m1m2-macs">Building
|
||
UxPlay on macOS: <strong>(Intel X86_64 and “Apple Silicon” M1/M2
|
||
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>These instructions for macOS assume 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 >= 3.13 is installed: this can be
|
||
done with package managers <a
|
||
href="http://www.macports.org">MacPorts</a>
|
||
(<code>sudo port install cmake</code>), <a
|
||
href="http://brew.sh">Homebrew</a> (<code>brew install cmake</code>), or
|
||
by a download from <a href="https://cmake.org/download/"
|
||
class="uri">https://cmake.org/download/</a>. Also install
|
||
<code>git</code> if you will use it to fetch UxPlay.</p>
|
||
<p>Next install libplist and openssl-3.x. Note that static versions of
|
||
these libraries will be used in the macOS builds, so they can be
|
||
uninstalled after building uxplay, if you wish.</p>
|
||
<ul>
|
||
<li><p>If you use Homebrew:
|
||
<code>brew install libplist openssl@3</code></p></li>
|
||
<li><p>if you use MacPorts:
|
||
<code>sudo port install libplist-devel openssl3</code></p></li>
|
||
</ul>
|
||
<p>Otherwise, build libplist and openssl from source: see instructions
|
||
near the end of this README; requires development tools (autoconf,
|
||
automake, libtool, <em>etc.</em>) to be installed.</p>
|
||
<p>Next get the latest macOS release of GStreamer-1.0.</p>
|
||
<p><strong>Using “Official” GStreamer (Recommended for both MacPorts and
|
||
Homebrew users)</strong>: install the GStreamer release for macOS from
|
||
<a href="https://gstreamer.freedesktop.org/download/"
|
||
class="uri">https://gstreamer.freedesktop.org/download/</a>. (This
|
||
release contains its own pkg-config, so you don’t have to install one.)
|
||
Install both the gstreamer-1.0 and gstreamer-1.0-devel packages. After
|
||
downloading, Shift-Click on them to install (they install to
|
||
/Library/FrameWorks/GStreamer.framework). Homebrew or MacPorts users
|
||
should <strong>not</strong> install (or should uninstall) the GStreamer
|
||
supplied by their package manager, if they use the “official”
|
||
release.</p>
|
||
<ul>
|
||
<li>Since GStreamer v1.22, the “Official” (gstreamer.freedesktop.org)
|
||
macOS binaries require a wrapper “gst_macos_main” around the actual main
|
||
program (uxplay). This should have been applied during the UxPlay
|
||
compilation process, and the initial UxPlay terminal message should
|
||
confirm it is being used. (UxPlay can also be built using “Official”
|
||
GStreamer v.1.20.7 binaries, which work without the wrapper.)</li>
|
||
</ul>
|
||
<p><strong>Using Homebrew’s GStreamer</strong>: pkg-config is needed:
|
||
(“brew install pkg-config gstreamer”). This causes a large number of
|
||
extra packages to be installed by Homebrew as dependencies. The <a
|
||
href="https://formulae.brew.sh/formula/gstreamer#default">Homebrew
|
||
gstreamer installation</a> has recently been reworked into a single
|
||
“formula” named <code>gstreamer</code>, which now works without needing
|
||
GST_PLUGIN_PATH to be set in the enviroment. Homebrew installs gstreamer
|
||
to <code>HOMEBREW_PREFIX/lib/gstreamer-1.0</code> where by default
|
||
<code>HOMEBREW_PREFIX/*</code> is <code>/opt/homebrew/*</code> on Apple
|
||
Silicon Macs, and <code>/usr/local/*</code> on Intel Macs; do not put
|
||
any extra non-Homebrew plugins (that you build yourself) there, and
|
||
instead set GST_PLUGIN_PATH to point to their location (Homebrew does
|
||
not supply a complete GStreamer, but seems to have everything needed for
|
||
UxPlay). <strong>New: the UxPlay build script will now also detect
|
||
Homebrew installations in non-standard locations indicated by the
|
||
environment variable <code>$HOMEBREW_PREFIX</code>.</strong></p>
|
||
<p><strong>Using GStreamer installed from MacPorts</strong>: this is
|
||
<strong>not</strong> recommended, as currently the MacPorts GStreamer is
|
||
old (v1.16.2), unmaintained, and built to use X11:</p>
|
||
<ul>
|
||
<li>Instead <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Building-GStreamer-from-Source-on-macOS-with-MacPorts">build
|
||
gstreamer yourself</a> if you use MacPorts and do not want to use the
|
||
“Official” Gstreamer binaries.</li>
|
||
</ul>
|
||
<p><em>(If you really wish to use the MacPorts GStreamer-1.16.2, install
|
||
pkgconf (“sudo port install pkgconf”), then “sudo port install
|
||
gstreamer1-gst-plugins-base gstreamer1-gst-plugins-good
|
||
gstreamer1-gst-plugins-bad gstreamer1-gst-libav”. For X11 support on
|
||
macOS, compile UxPlay using a special cmake option
|
||
<code>-DUSE_X11=ON</code>, and run it from an XQuartz terminal with -vs
|
||
ximagesink; older non-retina macs require a lower resolution when using
|
||
X11: <code>uxplay -s 800x600</code>.)</em></p>
|
||
<p>After installing GStreamer, build and install uxplay: 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>
|
||
<li><p>Running UxPlay while checking for GStreamer warnings (do this
|
||
with “export GST_DEBUG=2” before runnng UxPlay) reveals that with the
|
||
default (since UxPlay 1.64) use of timestamps for video synchonization,
|
||
many video frames are being dropped (only on macOS), perhaps due to
|
||
another error (about videometa) that shows up in the GStreamer warnings.
|
||
<strong>Recommendation: use the new UxPlay “no timestamp” option
|
||
“<code>-vsync no</code>”</strong> (you can add a line “vsync no” in the
|
||
uxplayrc configuration file).</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>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; the option
|
||
<code>-vs "osxvideosink force-aspect-ratio=true"</code> can be used to
|
||
make the window have the correct aspect ratio when it first
|
||
opens.</p></li>
|
||
</ul>
|
||
<h2
|
||
id="building-uxplay-on-microsoft-windows-using-msys2-with-the-mingw-64-compiler.">Building
|
||
UxPlay on Microsoft Windows, using MSYS2 with the MinGW-64
|
||
compiler.</h2>
|
||
<ul>
|
||
<li>tested on Windows 10 and 11, 64-bit.</li>
|
||
</ul>
|
||
<ol type="1">
|
||
<li><p>Download and install <strong>Bonjour SDK for Windows
|
||
v3.0</strong>. You can download the SDK without any registration at <a
|
||
href="https://www.softpedia.com/get/Programming/SDK-DDK/Bonjour-SDK.shtml">softpedia.com</a>,
|
||
or get it from the official Apple site <a
|
||
href="https://developer.apple.com/download/all/?q=Bonjour%20SDK%20for%20Windows">https://developer.apple.com/download</a>
|
||
(Apple makes you register as a developer to access it from their site).
|
||
This should install the Bonjour SDK as
|
||
<code>C:\Program Files\Bonjour SDK</code>.</p></li>
|
||
<li><p>(This is for 64-bit Windows; a build for 32-bit Windows should be
|
||
possible, but is not tested.) The unix-like MSYS2 build environment will
|
||
be used: download and install MSYS2 from the official site <a
|
||
href="https://www.msys2.org">https://www.msys2.org/</a>. Accept the
|
||
default installation location <code>C:\mysys64</code>.</p></li>
|
||
<li><p><a href="https://packages.msys2.org/package/">MSYS2 packages</a>
|
||
are installed with a variant of the “pacman” package manager used by
|
||
Arch Linux. Open a “MSYS2 MINGW64” terminal from the MSYS2 tab in the
|
||
Windows Start menu, and update the new MSYS2 installation with “pacman
|
||
-Syu”. Then install the <strong>MinGW-64</strong> compiler and
|
||
<strong>cmake</strong></p>
|
||
<pre><code>pacman -S mingw-w64-x86_64-cmake mingw-w64-x86_64-gcc</code></pre>
|
||
<p>The compiler with all required dependencies will be installed in the
|
||
msys64 directory, with default path <code>C:/msys64/mingw64</code>. Here
|
||
we will simply build UxPlay from the command line in the MSYS2
|
||
environment (this uses “<code>ninja</code>” in place of
|
||
“<code>make</code>” for the build system).</p></li>
|
||
<li><p>Download the latest UxPlay from github <strong>(to use
|
||
<code>git</code>, install it with <code>pacman -S git</code>, then
|
||
“<code>git clone https://github.com/FDH2/UxPlay</code>”)</strong>, then
|
||
install UxPlay dependencies (openssl is already installed with
|
||
MSYS2):</p>
|
||
<p><code>pacman -S mingw-w64-x86_64-libplist mingw-w64-x86_64-gstreamer mingw-w64-x86_64-gst-plugins-base</code></p>
|
||
<p>If you are trying a different Windows build system, MSVC versions of
|
||
GStreamer for Windows are available from the <a
|
||
href="https://gstreamer.freedesktop.org/download/">official GStreamer
|
||
site</a>, but only the MinGW 64-bit build on MSYS2 has been
|
||
tested.</p></li>
|
||
<li><p>cd to the UxPlay source directory, then
|
||
“<code>mkdir build</code>” and “<code>cd build</code>”. The build
|
||
process assumes that the Bonjour SDK is installed at
|
||
<code>C:\Program Files\Bonjour SDK</code>. If it is somewhere else, set
|
||
the enviroment variable BONJOUR_SDK_HOME to point to its location. Then
|
||
build UxPlay with</p>
|
||
<p><code>cmake ..</code></p>
|
||
<p><code>ninja</code></p></li>
|
||
<li><p>Assuming no error in either of these, you will have built the
|
||
uxplay executable <strong>uxplay.exe</strong> in the current (“build”)
|
||
directory. The “sudo make install” and “sudo make uninstall” features
|
||
offered in the other builds are not available on Windows; instead, the
|
||
MSYS2 environment has <code>/mingw64/...</code> available, and you can
|
||
install the uxplay.exe executable in <code>C:/msys64/mingw64/bin</code>
|
||
(plus manpage and documentation in
|
||
<code>C:/msys64/mingw64/share/...</code>) with</p>
|
||
<p><code>cmake --install . --prefix /mingw64</code></p>
|
||
<p>To be able to view the manpage, you need to install the manpage
|
||
viewer with “<code>pacman -S man</code>”.</p></li>
|
||
</ol>
|
||
<p>To run <strong>uxplay.exe</strong> you need to install some gstreamer
|
||
plugin packages with
|
||
<code>pacman -S mingw-w64-x86_64-gst-<plugin></code>, where the
|
||
required ones have <code><plugin></code> given by</p>
|
||
<ol type="1">
|
||
<li><strong>libav</strong></li>
|
||
<li><strong>plugins-good</strong></li>
|
||
<li><strong>plugins-bad</strong></li>
|
||
</ol>
|
||
<p>Other possible MSYS2 gstreamer plugin packages you might use are
|
||
listed in <a href="https://packages.msys2.org/package/">MSYS2
|
||
packages</a>.</p>
|
||
<p>You also will need to grant permission to the uxplay executable
|
||
uxplay.exe to access data through the Windows firewall. You may
|
||
automatically be offered the choice to do this when you first run
|
||
uxplay, or you may need to do it using <strong>Windows
|
||
Settings->Update and Security->Windows Security->Firewall &
|
||
network protection -> allow an app through firewall</strong>. If your
|
||
virus protection flags uxplay.exe as “suspicious” (but without a true
|
||
malware signature) you may need to give it an exception.</p>
|
||
<p>Now test by running “<code>uxplay</code>” (in a MSYS2 terminal
|
||
window). If you need to specify the audiosink, there are two main
|
||
choices on Windows: the older DirectSound plugin
|
||
“<code>-as directsoundsink</code>”, and the more modern Windows Audio
|
||
Session API (wasapi) plugin “<code>-as wasapisink</code>”, which
|
||
supports <a
|
||
href="https://gstreamer.freedesktop.org/documentation/wasapi/wasapisink.html">additional
|
||
options</a> such as</p>
|
||
<pre><code>uxplay -as 'wasapisink device=\"<guid>\"' </code></pre>
|
||
<p>where <code><guid></code> specifies an available audio device
|
||
by its GUID, which can be found using
|
||
“<code>gst-device-monitor-1.0 Audio</code>”: <code><guid></code>
|
||
has a form like
|
||
<code>\{0.0.0.00000000\}.\{98e35b2b-8eba-412e-b840-fd2c2492cf44\}</code>.
|
||
If “<code>device</code>” is not specified, the default audio device is
|
||
used.</p>
|
||
<p>If you wish to specify the videosink using the
|
||
<code>-vs <videosink></code> option, some choices for
|
||
<code><videosink></code> are <code>d3d11videosink</code>,
|
||
<code>d3dvideosink</code>, <code>glimagesink</code>,
|
||
<code>gtksink</code>.</p>
|
||
<ul>
|
||
<li>With Direct3D 11.0 or greater, you can either always be in
|
||
fullscreen mode using option
|
||
<code>-vs "d3d11videosink fullscreen-toggle-mode=property fullscreen=true"</code>,
|
||
or get the ability to toggle into and out of fullscreen mode using the
|
||
Alt-Enter key combination with option
|
||
<code>-vs "d3d11videosink fullscreen-toggle-mode=alt-enter"</code>. For
|
||
convenience, these options will be added if just
|
||
<code>-vs d3d11videosink</code> with or without the fullscreen option
|
||
“-fs” is used. <em>(Windows users may wish to add
|
||
“<code>vs d3d11videosink</code>” (no initial “<code>-</code>”) to the
|
||
UxPlay startup options file; see “man uxplay” or “uxplay -h”.)</em></li>
|
||
</ul>
|
||
<p>The executable uxplay.exe can also be run without the MSYS2
|
||
environment, in the Windows Terminal, with
|
||
<code>C:\msys64\mingw64\bin\uxplay</code>.</p>
|
||
<h1 id="usage">Usage</h1>
|
||
<p>Options:</p>
|
||
<ul>
|
||
<li>These can also be written (one option per line, without the initial
|
||
“<code>-</code>” character) in the UxPlay startup file (either given by
|
||
environment variable <code>$UXPLAYRC</code>, or <code>~/.uxplayrc</code>
|
||
or <code>~/.config/uxplayrc</code>); lines begining with
|
||
“<code>#</code>” are treated as comments, and ignored. Command line
|
||
options supersede options in the startup file.</li>
|
||
</ul>
|
||
<p><strong>-n server_name</strong> (Default: UxPlay);
|
||
server_name@_hostname_ will be the name that appears offering AirPlay
|
||
services to your iPad, iPhone etc, where <em>hostname</em> is the name
|
||
of the server running uxplay. This will also now be the name shown above
|
||
the mirror display (X11) window.</p>
|
||
<p><strong>-nh</strong> Do not append “<span class="citation"
|
||
data-cites="_hostname_">@_hostname_</span>” at the end of the AirPlay
|
||
server name.</p>
|
||
<p><strong>-h265</strong> Activate “ScreenMultiCodec” support (AirPlay
|
||
“Features” bit 42) for accepting h265 (4K/HEVC) video in addition to
|
||
h264 video (1080p) in screen-mirror mode. When this option is used, two
|
||
“video pipelines” (one for h264, one for h265) are created. If any
|
||
GStreamer plugins in the pipeline are specific for h264 or h265, the
|
||
correct version will be used in each pipeline. A wired Client-Server
|
||
ethernet connection is preferred over Wifi for 4K video, and might be
|
||
required by the client. Only recent Apple devices (M1/M2 Macs or iPads,
|
||
and some iPhones) can send h265 video if a resolution “-s wxh” with h
|
||
> 1080 is requested. The “-h265” option changes the default
|
||
resolution (“-s” option) from 1920x1080 to 3840x2160, and leaves default
|
||
maximum framerate (“-fps” option) at 30fps.</p>
|
||
<p><strong>-hls</strong> Activate HTTP Live Streaming support. With this
|
||
option YouTube videos can be streamed directly from YouTube servers to
|
||
UxPlay (without passing through the client) by clicking on the AirPlay
|
||
icon in the YouTube app.</p>
|
||
<p><strong>-pin [nnnn]</strong>: (since v1.67) use Apple-style
|
||
(one-time) “pin” authentication when a new client connects for the first
|
||
time: a four-digit pin code is displayed on the terminal, and the client
|
||
screen shows a login prompt for this to be entered. When “-pin” is used
|
||
by itself, a new random pin code is chosen for each authentication; if
|
||
“-pin nnnn” (e.g., “-pin 3939”) is used, this will set an unchanging
|
||
fixed code. Authentication adds the server to the client’s list of
|
||
“trusted servers” and the client will not need to reauthenticate
|
||
provided that the client and server public keys remain unchanged. (By
|
||
default since v1.68, the server public key is generated from the MAC
|
||
address, which can be changed with the -m option; see the -key option
|
||
for an alternative method of key generation). <em>(Add a line “pin” in
|
||
the UxPlay startup file if you wish the UxPlay server to use the pin
|
||
authentication protocol).</em></p>
|
||
<p><strong>-reg [<em>filename</em>]</strong>: (since v1.68). If “-pin”
|
||
is used, this option maintains a register of pin-authenticated “trusted
|
||
clients” in $HOME/.uxplay.register (or optionally, in
|
||
<em>filename</em>). Without this option, returning clients that skip
|
||
pin-authentication are trusted and not checked. This option may be
|
||
useful if UxPlay is used in a more public environment, to record client
|
||
details; the register is text, one line per client, with client’s public
|
||
key (base-64 format), Device ID, and Device name; commenting out (with
|
||
“#”) or deleting a line deregisters the corresponding client (see
|
||
options -restrict, -block, -allow for more ways to control client
|
||
access). <em>(Add a line “reg” in the startup file if you wish to use
|
||
this feature.)</em></p>
|
||
<p><strong>-vsync [x]</strong> (In Mirror mode:) this option
|
||
(<strong>now the default</strong>) uses timestamps to synchronize audio
|
||
with video on the server, with an optional audio delay in (decimal)
|
||
milliseconds (<em>x</em> = “20.5” means 0.0205 seconds delay: positive
|
||
or negative delays less than a second are allowed.) It is needed on
|
||
low-power systems such as Raspberry Pi without hardware video
|
||
decoding.</p>
|
||
<p><strong>-vsync no</strong> (In Mirror mode:) this switches off
|
||
timestamp-based audio-video synchronization, restoring the default
|
||
behavior prior to UxPlay-1.64. Standard desktop systems seem to work
|
||
well without use of timestamps: this mode is appropriate for “live
|
||
streaming” such as using UxPlay as a second monitor for a mac computer,
|
||
or monitoring a webcam; with it, no video frames are dropped.</p>
|
||
<p><strong>-async [x]</strong> (In Audio-Only (ALAC) mode:) this option
|
||
uses timestamps to synchronize audio on the server with video on the
|
||
client, with an optional audio delay in (decimal) milliseconds
|
||
(<em>x</em> = “20.5” means 0.0205 seconds delay: positive or negative
|
||
delays less than a second are allowed.) Because the client adds a video
|
||
delay to account for latency, the server in -async mode adds an
|
||
equivalent audio delay, which means that audio changes such as a pause
|
||
or a track-change will not take effect immediately. <em>This might in
|
||
principle be mitigated by using the <code>-al</code> audio latency
|
||
setting to change the latency (default 0.25 secs) that the server
|
||
reports to the client, but at present changing this does not seem to
|
||
have any effect</em>.</p>
|
||
<p><strong>-async no</strong>. This is the still the default behavior in
|
||
Audio-only mode, but this option may be useful as a command-line option
|
||
to switch off a <code>-async</code> option set in a “uxplayrc”
|
||
configuration file.</p>
|
||
<p><strong>-db <em>low</em>[:<em>high</em>]</strong> Rescales the
|
||
AirPlay volume-control attenuation (gain) from -30dB:0dB to
|
||
<em>low</em>:0dB or <em>low</em>:<em>high</em>. The lower limit
|
||
<em>low</em> must be negative (attenuation); the upper limit
|
||
<em>high</em> can be either sign. (GStreamer restricts
|
||
volume-augmentation by <em>high</em> so that it cannot exceed +20dB).
|
||
The rescaling is “flat”, so that for -db -50:10, a change in Airplay
|
||
attenuation by -7dB is translated to a -7 x (60/30) = -14dB attenuation,
|
||
and the maximum volume (AirPlay 0dB) is a 10dB augmentation, and Airplay
|
||
-30dB would become -50dB. Note that the minimum AirPlay value (-30dB
|
||
exactly) is translated to “mute”.</p>
|
||
<p><strong>-taper</strong> Provides a “tapered” Airplay volume-control
|
||
profile (matching the one called “dasl-tapering” in <a
|
||
href="https://github.com/mikebrady/shairport-sync">shairport-sync</a>):
|
||
each time the length of the volume slider (or the number of steps above
|
||
mute, where 16 steps = full volume) is reduced by 50%, the perceived
|
||
volume is halved (a 10dB attenuation). (This is modified at low volumes,
|
||
to use the “untapered” volume if it is louder.)</p>
|
||
<p><strong>-s wxh</strong> e.g. -s 1920x1080 (= “1080p”), the default
|
||
width and height resolutions in pixels for h264 video. (The default
|
||
becomes 3840x2160 (= “4K”) when the -h265 option is used.) This is just
|
||
a request made to the AirPlay client, and perhaps will not be the final
|
||
resolution you get. w and h are whole numbers with four digits or less.
|
||
Note that the <strong>height</strong> pixel size is the controlling one
|
||
used by the client for determining the streaming format; the width is
|
||
dynamically adjusted to the shape of the image (portrait or landscape
|
||
format, depending on how an iPad is held, for example).</p>
|
||
<p><strong>-s wxh@r</strong> As above, but also informs the AirPlay
|
||
client about the screen refresh rate of the display. Default is r=60 (60
|
||
Hz); r must be a whole number less than 256.</p>
|
||
<p><strong>-o</strong> turns on an “overscanned” option for the display
|
||
window. This reduces the image resolution by using some of the pixels
|
||
requested by option -s wxh (or their default values 1920x1080) by adding
|
||
an empty boundary frame of unused pixels (which would be lost in a
|
||
full-screen display that overscans, and is not displayed by gstreamer).
|
||
Recommendation: <strong>don’t use this option</strong> unless there is
|
||
some special reason to use it.</p>
|
||
<p><strong>-fs</strong> uses fullscreen mode, but only works with X11,
|
||
Wayland, VAAPI, and D3D11 (Windows).</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>If the -p option is not used, the ports are chosen dynamically
|
||
(randomly), which will not work if a firewall is running.</p>
|
||
<p><strong>-avdec</strong> forces use of software h264 decoding using
|
||
Gstreamer element avdec_h264 (libav h264 decoder). This option should
|
||
prevent autovideosink choosing a hardware-accelerated videosink plugin
|
||
such as vaapisink.</p>
|
||
<p><strong>-vp <em>parser</em></strong> choses the GStreamer pipeline’s
|
||
h264 parser element, default is h264parse. Using quotes “…” allows
|
||
options to be added.</p>
|
||
<p><strong>-vd <em>decoder</em></strong> chooses the GStreamer
|
||
pipeline’s h264 decoder element, instead of the default value
|
||
“decodebin” which chooses it for you. Software decoding is done by
|
||
avdec_h264; various hardware decoders include: vaapih264dec, nvdec,
|
||
nvh264dec, v4l2h264dec (these require that the appropriate hardware is
|
||
available). Using quotes “…” allows some parameters to be included with
|
||
the decoder name.</p>
|
||
<p><strong>-vc <em>converter</em></strong> chooses the GStreamer
|
||
pipeline’s videoconverter element, instead of the default value
|
||
“videoconvert”. When using Video4Linux2 hardware-decoding by a
|
||
GPU,<code>-vc v4l2convert</code> will also use the GPU for video
|
||
conversion. Using quotes “…” allows some parameters to be included with
|
||
the converter name.</p>
|
||
<p><strong>-vs <em>videosink</em></strong> chooses the GStreamer
|
||
videosink, instead of the default value “autovideosink” which chooses it
|
||
for you. Some videosink choices are: ximagesink, xvimagesink, vaapisink
|
||
(for intel graphics), gtksink, glimagesink, waylandsink, osxvideosink
|
||
(for macOS), kmssink (for systems without X11, like Raspberry Pi OS
|
||
lite) or fpsdisplaysink (which shows the streaming framerate in fps).
|
||
Using quotes “…” allows some parameters to be included with the
|
||
videosink name. For example, <strong>fullscreen</strong> mode is
|
||
supported by the vaapisink plugin, and is obtained using
|
||
<code>-vs "vaapisink fullscreen=true"</code>; this also works with
|
||
<code>waylandsink</code>. The syntax of such options is specific to a
|
||
given plugin (see GStreamer documentation), and some choices of
|
||
videosink might not work on your system.</p>
|
||
<p><strong>-vs 0</strong> suppresses display of streamed video. In
|
||
mirror mode, the client’s screen is still mirrored at a reduced rate of
|
||
1 frame per second, but is not rendered or displayed. This option should
|
||
always be used if the server is “headless” (with no attached screen to
|
||
display video), and only used to render audio, which will be AAC
|
||
lossily-compressed audio in mirror mode with unrendered video, and
|
||
superior-quality ALAC Apple Lossless audio in Airplay audio-only
|
||
mode.</p>
|
||
<p><strong>-v4l2</strong> Video settings for hardware h264 video
|
||
decoding in the GPU by Video4Linux2. Equivalent to
|
||
<code>-vd v4l2h264dec -vc v4l2convert</code>.</p>
|
||
<p><strong>-bt709</strong> A workaround for the failure of the older
|
||
Video4Linux2 plugin to recognize Apple’s use of an uncommon (but
|
||
permitted) “full-range color” variant of the bt709 color standard for
|
||
digital TV. This is no longer needed by GStreamer-1.20.4 and backports
|
||
from it.</p>
|
||
<p><strong>-rpi</strong> Equivalent to “-v4l2” (Not valid for Raspberry
|
||
Pi model 5, and removed in UxPlay 1.67)</p>
|
||
<p><strong>-rpigl</strong> Equivalent to “-rpi -vs glimagesink”.
|
||
(Removed since UxPlay 1.67)</p>
|
||
<p><strong>-rpifb</strong> Equivalent to “-rpi -vs kmssink” (Removed
|
||
since UxPlay 1.67)</p>
|
||
<p><strong>-rpiwl</strong> Equivalent to “-rpi -vs waylandsink”.
|
||
(Removed since UxPlay 1.67)</p>
|
||
<p><strong>-as <em>audiosink</em></strong> chooses the GStreamer
|
||
audiosink, instead of letting autoaudiosink pick it for you. Some
|
||
audiosink choices are: pulsesink, alsasink, pipewiresink, osssink,
|
||
oss4sink, jackaudiosink, osxaudiosink (for macOS), wasapisink,
|
||
directsoundsink (for Windows). Using quotes “…” might allow some
|
||
optional parameters (e.g. <code>-as "alsasink device=..."</code> to
|
||
specify a non-default output device). The syntax of such options is
|
||
specific to a given plugin (see GStreamer documentation), and some
|
||
choices of audiosink might not work on your system.</p>
|
||
<p><strong>-as 0</strong> (or just <strong>-a</strong>) suppresses
|
||
playing of streamed audio, but displays streamed video.</p>
|
||
<p><strong>-al <em>x</em></strong> specifies an audio latency <em>x</em>
|
||
in (decimal) seconds in Audio-only (ALAC), that is reported to the
|
||
client. Values in the range [0.0, 10.0] seconds are allowed, and will be
|
||
converted to a whole number of microseconds. Default is 0.25 sec (250000
|
||
usec). <em>(However, the client appears to ignore this reported latency,
|
||
so this option seems non-functional.)</em></p>
|
||
<p><strong>-ca <em>filename</em></strong> provides a file (where
|
||
<em>filename</em> can include a full path) used for output of “cover
|
||
art” (from Apple Music, <em>etc.</em>,) in audio-only ALAC mode. This
|
||
file is overwritten with the latest cover art as it arrives. Cover art
|
||
(jpeg format) is discarded if this option is not used. Use with a image
|
||
viewer that reloads the image if it changes, or regularly (<em>e.g.</em>
|
||
once per second.). To achieve this, run
|
||
“<code>uxplay -ca [path/to/]filename &</code>” in the background,
|
||
then run the the image viewer in the foreground. Example, using
|
||
<code>feh</code> as the viewer: run
|
||
“<code>feh -R 1 [path/to/]filename</code>” (in the same terminal window
|
||
in which uxplay was put into the background). To quit, use
|
||
<code>ctrl-C fg ctrl-C</code> to terminate the image viewer, bring
|
||
<code>uxplay</code> into the foreground, and terminate it too.</p>
|
||
<p><strong>-reset n</strong> sets a limit of <em>n</em> consecutive
|
||
timeout failures of the client to respond to ntp requests from the
|
||
server (these are sent every 3 seconds to check if the client is still
|
||
present, and synchronize with it). After <em>n</em> failures, the client
|
||
will be presumed to be offline, and the connection will be reset to
|
||
allow a new connection. The default value of <em>n</em> is 5; the value
|
||
<em>n</em> = 0 means “no limit” on timeouts.</p>
|
||
<p><strong>-nofreeze</strong> closes the video window after a reset due
|
||
to ntp timeout (default is to leave window open to allow a smoother
|
||
reconection to the same client). This option may be useful in fullscreen
|
||
mode.</p>
|
||
<p><strong>-nc</strong> maintains previous UxPlay < 1.45 behavior
|
||
that does <strong>not close</strong> the video window when the the
|
||
client sends the “Stop Mirroring” signal. <em>This option is currently
|
||
used by default in macOS, as the window created in macOS by GStreamer
|
||
does not terminate correctly (it causes a segfault) if it is still open
|
||
when the GStreamer pipeline is closed.</em></p>
|
||
<p><strong>-nohold</strong> Drops the current connection when a new
|
||
client attempts to connect. Without this option, the current client
|
||
maintains exclusive ownership of UxPlay until it disconnects.</p>
|
||
<p><strong>-restrict</strong> Restrict clients allowed to connect to
|
||
those specified by <code>-allow <deviceID></code>. The deviceID
|
||
has the form of a MAC address which is displayed by UxPlay when the
|
||
client attempts to connect, and appears to be immutable. It has the
|
||
format <code>XX:XX:XX:XX:XX:XX</code>, X = 0-9,A-F, and is possibly the
|
||
“true” hardware MAC address of the device. Note that iOS clients
|
||
generally expose different random “private Wi_Fi addresses” (“fake” MAC
|
||
addresses) to different networks (for privacy reasons, to prevent
|
||
tracking), which may change, and do not correpond to the deviceID.</p>
|
||
<p><strong>-restrict no</strong> Remove restrictions (default). This is
|
||
useful as a command-line argument to overide restrictions set in the
|
||
Startup file.</p>
|
||
<p><strong>-allow <em>id</em></strong> Adds the deviceID = <em>id</em>
|
||
to the list of allowed clients when client restrictions are being
|
||
enforced. Usually this will be an entry in the uxplayrc startup
|
||
file.</p>
|
||
<p><strong>-block <em>id</em></strong> Always block clients with
|
||
deviceID = <em>id</em>, even when client restrictions are not being
|
||
enforced generally. Usually this will be an entry in the uxplayrc
|
||
startup file.</p>
|
||
<p><strong>-FPSdata</strong> Turns on monitoring of regular reports
|
||
about video streaming performance that are sent by the client. These
|
||
will be displayed in the terminal window if this option is used. The
|
||
data is updated by the client at 1 second intervals.</p>
|
||
<p><strong>-fps n</strong> sets a maximum frame rate (in frames per
|
||
second) for the AirPlay client to stream video; n must be a whole number
|
||
less than 256. (The client may choose to serve video at any frame rate
|
||
lower than this; default is 30 fps.) A setting of 60 fps may give you
|
||
improved video but is not recommended on Raspberry Pi. A setting below
|
||
30 fps might be useful to reduce latency if you are running more than
|
||
one instance of uxplay at the same time. <em>This setting is only an
|
||
advisory to the client device, so setting a high value will not force a
|
||
high framerate.</em> (You can test using “-vs fpsdisplaysink” to see
|
||
what framerate is being received, or use the option -FPSdata which
|
||
displays video-stream performance data continuously sent by the client
|
||
during video-streaming.)</p>
|
||
<p><strong>-f {H|V|I}</strong> implements “videoflip” image transforms:
|
||
H = horizontal flip (right-left flip, or mirror image); V = vertical
|
||
flip ; I = 180 degree rotation or inversion (which is the combination of
|
||
H with V).</p>
|
||
<p><strong>-r {R|L}</strong> 90 degree Right (clockwise) or Left
|
||
(counter-clockwise) rotations; these image transforms are carried out
|
||
after any <strong>-f</strong> transforms.</p>
|
||
<p><strong>-m [mac]</strong> changes the MAC address (Device ID) used by
|
||
UxPlay (default is to use the true hardware MAC address reported by the
|
||
host computer’s network card). (Different server_name, MAC addresses,
|
||
and network ports are needed for each running uxplay if you attempt to
|
||
run more than one instance of uxplay on the same computer.) If [mac] (in
|
||
form xx:xx:xx:xx:xx:xx, 6 hex octets) is not given, a random MAC address
|
||
is generated. If UxPlay fails to find the true MAC address of a network
|
||
card, (more specifically, the MAC address used by the first active
|
||
network interface detected) a random MAC address will be used even if
|
||
option <strong>-m</strong> was not specified. (Note that a random MAC
|
||
address will be different each time UxPlay is started).</p>
|
||
<p><strong>-key [<em>filename</em>]</strong>: This (more secure) option
|
||
for generating and storing a persistant public key (needed for the -pin
|
||
option) has been replaced by default with a (less secure) method which
|
||
generates a key from the server’s “device ID” (MAC address, which can be
|
||
changed with the -m option, conveniently as a startup file option). When
|
||
the -key option is used, a securely generated keypair is generated and
|
||
stored in <code>$HOME/.uxplay.pem</code>, if that file does not exist,
|
||
or read from it, if it exists. (Optionally, the key can be stored in
|
||
<em>filename</em>.) This method is more secure than the new default
|
||
method, (because the Device ID is broadcast in the DNS_SD announcement)
|
||
but still leaves the private key exposed to anyone who can access the
|
||
pem file. This option should be set in the UxPlay startup file as a line
|
||
“key” or “key <em>filename</em>” (no initial “-”), where
|
||
<em>filename</em> is a full path which should be enclosed in quotes
|
||
(<code>"...."</code>) if it contains any blank spaces. <strong>Because
|
||
the default method is simpler, and security of client access to uxplay
|
||
is unlikely to be an important issue, the -key option is no longer
|
||
recommended</strong>.</p>
|
||
<p><strong>-dacp [<em>filename</em>]</strong>: Export current client
|
||
DACP-ID and Active-Remote key to file: default is $HOME/.uxplay.dacp.
|
||
(optionally can be changed to <em>filename</em>). Can be used by remote
|
||
control applications. File is transient: only exists while client is
|
||
connected.</p>
|
||
<p><strong>-vdmp</strong> Dumps h264 video to file videodump.h264. -vdmp
|
||
n dumps not more than n NAL units to videodump.x.h264; x= 1,2,…
|
||
increases each time a SPS/PPS NAL unit arrives. To change the name
|
||
<em>videodump</em>, use -vdmp [n] <em>filename</em>.</p>
|
||
<p><strong>-admp</strong> Dumps audio to file audiodump.x.aac (AAC-ELD
|
||
format audio), audiodump.x.alac (ALAC format audio) or audiodump.x.aud
|
||
(other-format audio), where x = 1,2,3… increases each time the audio
|
||
format changes. -admp <em>n</em> restricts the number of packets dumped
|
||
to a file to <em>n</em> or less. To change the name <em>audiodump</em>,
|
||
use -admp [n] <em>filename</em>. <em>Note that (unlike dumped video) the
|
||
dumped audio is currently only useful for debugging, as it is not
|
||
containerized to make it playable with standard audio players.</em></p>
|
||
<p><strong>-d</strong> Enable debug output. Note: this does not show
|
||
GStreamer error or debug messages. To see GStreamer error and warning
|
||
messages, set the environment variable GST_DEBUG with “export
|
||
GST_DEBUG=2” before running uxplay. To see GStreamer information
|
||
messages, set GST_DEBUG=4; for DEBUG messages, GST_DEBUG=5; increase
|
||
this to see even more of the GStreamer inner workings.</p>
|
||
<h1 id="troubleshooting">Troubleshooting</h1>
|
||
<p>Note: <code>uxplay</code> is run from a terminal command line, and
|
||
informational messages are written to the terminal.</p>
|
||
<h3 id="problems-in-compiling-uxplay.">0. Problems in compiling
|
||
UxPlay.</h3>
|
||
<p>One user (on Ubuntu) found compilation failed with messages about
|
||
linking to “usr/local/lib/libcrypto.a” and “zlib”. This was because (in
|
||
addition to the standard ubuntu installation of libssl-dev), the user
|
||
was unaware that a second installation with libcrypto in /usr/local was
|
||
present. Solution: when more than one installation of OpenSSL is
|
||
present, set the environment variable OPEN_SSL_ROOT_DIR to point to the
|
||
correct one; on 64-bit Ubuntu, this is done by running
|
||
<code>export OPENSSL_ROOT_DIR=/usr/lib/X86_64-linux-gnu/</code> before
|
||
running cmake.</p>
|
||
<h3 id="avahidns_sd-bonjourzeroconf-issues">1. <strong>Avahi/DNS_SD
|
||
Bonjour/Zeroconf issues</strong></h3>
|
||
<p>The DNS_SD Service-Discovery (“Bonjour” or “Zeroconf”) service is
|
||
required for UxPlay to work. On Linux, it will be usually provided by
|
||
Avahi, and to troubleshoot this, you should use the tool
|
||
<code>avahi-browse</code>. (You may need to install a separate package
|
||
with a name like <code>avahi-utils</code> to get this.)</p>
|
||
<p>On Linux, make sure Avahi is installed, and start the avahi-daemon
|
||
service on the system running uxplay (your distribution will document
|
||
how to do this, for example:
|
||
<code>sudo systemctl <cmd> avahi-daemon</code> or
|
||
<code>sudo service avahi-daemon <cmd></code>, with
|
||
<code><cmd></code> one of enable, disable, start, stop, status.
|
||
You might need to edit the avahi-daemon.conf file (it is typically in
|
||
/etc/avahi/, find it with
|
||
“<code>sudo find /etc -name avahi-daemon.conf</code>”): make sure that
|
||
“disable-publishing” is <strong>not</strong> a selected option). Some
|
||
systems may instead use the mdnsd daemon as an alternative to provide
|
||
DNS-SD service. (FreeBSD offers both alternatives, but only Avahi was
|
||
tested; see <a
|
||
href="https://gist.github.com/reidransom/6033227">here</a>.)</p>
|
||
<ul>
|
||
<li><strong>uxplay starts, but either stalls or stops after “Initialized
|
||
server socket(s)” appears (<em>without the server name showing on the
|
||
client</em>)</strong>.</li>
|
||
</ul>
|
||
<p>If UxPlay stops with the “No DNS-SD Server found” message, this means
|
||
that your network <strong>does not have a running Bonjour/zeroconf
|
||
DNS-SD server.</strong> Before v1.60, UxPlay used to stall silently if
|
||
DNS-SD service registration failed, but now stops with an error message
|
||
returned by the DNSServiceRegister function: kDNSServiceErr_Unknown if
|
||
no DNS-SD server was found: <em>(A NixOS user found that in NixOS, this
|
||
error can also occur if avahi-daemon service IS running with publishing
|
||
enabled, but reports “the error disappeared on NixOS by setting
|
||
services.avahi.openFirewall to true”.)</em> Other mDNS error codes are
|
||
in the range FFFE FF00 (-65792) to FFFE FFFF (-65537), and are listed in
|
||
the dnssd.h file. An older version of this (the one used by avahi) is
|
||
found <a
|
||
href="https://github.com/lathiat/avahi/blob/master/avahi-compat-libdns_sd/dns_sd.h">here</a>.
|
||
A few additional error codes are defined in a later version from <a
|
||
href="https://opensource.apple.com/source/mDNSResponder/mDNSResponder-544/mDNSShared/dns_sd.h.auto.html">Apple</a>.</p>
|
||
<p>If UxPlay stalls <em>without an error message</em> and <em>without
|
||
the server name showing on the client</em>, <strong>this is a network
|
||
problem</strong> (if your UxPlay version is older than 1.60, it is also
|
||
the behavior when no DNS-SD server is found.)</p>
|
||
<p>A useful tool for examining such network problems from the client end
|
||
is the (free) Discovery DNS-SD browser <a
|
||
href="https://apps.apple.com/us/developer/lily-ballard/id305441020">available
|
||
in the Apple App Store</a> for both iOS (works on iPadOS too) and
|
||
macOS.</p>
|
||
<ul>
|
||
<li>Some users using dual-band (2.4GHz/5GHz) routers have reported that
|
||
clients using the 5GHz band (sometimes) “fail to see UxPlay” (i.e., do
|
||
not get a response to their mDNS queries), but the 2.4GHz band works.
|
||
Other projects using Bonjour/mDNS have had similar reports; the issue
|
||
seems to be router-specific, perhaps related to “auto” rather than fixed
|
||
channel selection (5GHz has many more channels to switch between), or
|
||
channel width selections; one speculation is that since mDNS uses UDP
|
||
protocol (where “lost” messages are not resent), a mDNS query might get
|
||
lost if channel switching occurs during the query.</li>
|
||
</ul>
|
||
<p>If your router has this problem, a reported “fix” is to (at least on
|
||
5GHz) use fixed channel and/or fixed (not dynamic) channel width.</p>
|
||
<ul>
|
||
<li><strong>Avahi works at first, but new clients do not see UxPlay, or
|
||
clients that initially saw it stop doing so after they
|
||
disconnect</strong>.</li>
|
||
</ul>
|
||
<p>This is usually because Avahi is only using the “loopback” network
|
||
interface, and is not receiving mDNS queries from new clients that were
|
||
not listening when UxPlay started.</p>
|
||
<p>To check this, after starting uxplay, use the utility
|
||
<code>avahi-browse -a -t</code> <strong>in a different terminal
|
||
window</strong> on the server to verify that the UxPlay AirTunes and
|
||
AirPlay services are correctly registered (only the AirTunes service is
|
||
used in the “Legacy” AirPlay Mirror mode used by UxPlay, but the AirPlay
|
||
service is used for the initial contact).</p>
|
||
<p>The results returned by avahi-browse should show entries for uxplay
|
||
like</p>
|
||
<pre><code>+ eno1 IPv6 UxPlay AirPlay Remote Video local
|
||
+ eno1 IPv4 UxPlay AirPlay Remote Video local
|
||
+ lo IPv4 UxPlay AirPlay Remote Video local
|
||
+ eno1 IPv6 863EA27598FE@UxPlay AirTunes Remote Audio local
|
||
+ eno1 IPv4 863EA27598FE@UxPlay AirTunes Remote Audio local
|
||
+ lo IPv4 863EA27598FE@UxPlay AirTunes Remote Audio local</code></pre>
|
||
<p>If only the loopback (“lo”) entries are shown, a firewall on the
|
||
UxPlay host is probably blocking full DNS-SD service, and you need to
|
||
open the default UDP port 5353 for mDNS requests, as loopback-based
|
||
DNS-SD service is unreliable.</p>
|
||
<p>If the UxPlay services are listed by avahi-browse as above, but are
|
||
not seen by the client, the problem is likely to be a problem with the
|
||
local network.</p>
|
||
<h3
|
||
id="uxplay-starts-but-stalls-after-initialized-server-sockets-appears-with-the-server-name-showing-on-the-client-but-the-client-fails-to-connect-when-the-uxplay-server-is-selected.">2.
|
||
uxplay starts, but stalls after “Initialized server socket(s)” appears,
|
||
<em>with the server name showing on the client</em> (but the client
|
||
fails to connect when the UxPlay server is selected).</h3>
|
||
<p>This shows that a <em>DNS-SD</em> service is working, clients hear
|
||
UxPlay is available, but the UxPlay server is not receiving the response
|
||
from the client. This is usually because a firewall on the server is
|
||
blocking the connection request from the client. (One user who insisted
|
||
that the firewall had been turned off turned out to have had
|
||
<em>two</em> active firewalls (<em>firewalld</em> and <em>ufw</em>)
|
||
<em>both</em> running on the server!) If possible, either turn off the
|
||
firewall to see if that is the problem, or get three consecutive network
|
||
ports, starting at port n, all three in the range 1024-65535, opened for
|
||
both tcp and udp, and use “uxplay -p n” (or open UDP 7011,6001,6000 TCP
|
||
7100,7000,7001 and use “uxplay -p”).</p>
|
||
<p>If you are <em>really</em> sure there is no firewall, you may need to
|
||
investigate your network transmissions with a tool like netstat, but
|
||
almost always this is a firewall issue.</p>
|
||
<h3 id="problems-after-the-client-server-connection-has-been-made">3.
|
||
Problems <em>after</em> the client-server connection has been made:</h3>
|
||
<p>If you do <em>not</em> see the message
|
||
<code>raop_rtp_mirror starting mirroring</code>, something went wrong
|
||
before the client-server negotiations were finished. For such problems,
|
||
use “uxplay -d” (debug log option) to see what is happening: it will
|
||
show how far the connection process gets before the failure occurs. You
|
||
can compare your debug output to that from a successful start of UxPlay
|
||
in the <a href="https://github.com/FDH2/UxPlay/wiki">UxPlay
|
||
Wiki</a>.</p>
|
||
<p><strong>If UxPlay reports that mirroring started, but you get no
|
||
video or audio, the problem is probably from a GStreamer plugin that
|
||
doesn’t work on your system</strong> (by default, GStreamer uses the
|
||
“autovideosink” and “autoaudiosink” algorithms to guess what are the
|
||
“best” plugins to use on your system). A different reason for no audio
|
||
occurred when a user with a firewall only opened two udp network ports:
|
||
<strong>three</strong> are required (the third one receives the audio
|
||
data).</p>
|
||
<p><strong>Raspberry Pi</strong> devices (<em>Pi 4B+ and earlier: this
|
||
does not apply to the Pi 5, which does not provide hardware h264
|
||
decoding, and does not need it</em>) work best with hardware GPU h264
|
||
video decoding if the Video4Linux2 plugin in GStreamer v1.20.x or
|
||
earlier has been patched (see the UxPlay <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/Gstreamer-Video4Linux2-plugin-patches">Wiki</a>
|
||
for patches). This is fixed in GStreamer-1.22, and by backport patches
|
||
from this in distributions such as Raspberry Pi OS (Bullseye):
|
||
<strong>use option <code>-bt709</code> with the GStreamer-1.18.4 from
|
||
Raspberry Pi OS</strong>. This also needs the bcm2835-codec kernel
|
||
module that is not in the standard Linux kernel (it is available in
|
||
Raspberry Pi OS, Ubuntu and Manjaro).</p>
|
||
<ul>
|
||
<li><strong>If this kernel module is not available in your Raspberry Pi
|
||
operating system, or if GStreamer < 1.22 is not patched, use option
|
||
<code>-avdec</code> for software h264-decoding.</strong></li>
|
||
</ul>
|
||
<p>Sometimes “autovideosink” may select the OpenGL renderer
|
||
“glimagesink” which may not work correctly on your system. Try the
|
||
options “-vs ximagesink” or “-vs xvimagesink” to see if using one of
|
||
these fixes the problem.</p>
|
||
<p>Other reported problems are connected to the GStreamer VAAPI plugin
|
||
(for hardware-accelerated Intel graphics, but not NVIDIA graphics). Use
|
||
the option “-avdec” to force software h264 video decoding: this should
|
||
prevent autovideosink from selecting the vaapisink videosink.
|
||
Alternatively, find out if the gstreamer1.0-vaapi plugin is installed,
|
||
and if so, uninstall it. (If this does not fix the problem, you can
|
||
reinstall it.)</p>
|
||
<p>There are some reports of other GStreamer problems with
|
||
hardware-accelerated Intel HD graphics. One user (on Debian) solved this
|
||
with “sudo apt install intel-media-va-driver-non-free”. This is a driver
|
||
for 8’th (or later) generation “*-lake” Intel chips, that seems to be
|
||
related to VAAPI accelerated graphics.</p>
|
||
<p>If you <em>do</em> have Intel HD graphics, and have installed the
|
||
vaapi plugin, but <code>-vs vaapisink</code> does not work, check that
|
||
vaapi is not “blacklisted” in your GStreamer installation: run
|
||
<code>gst-inspect-1.0 vaapi</code>, if this reports
|
||
<code>0 features</code>, you need to
|
||
<code>export GST_VAAPI_ALL_DRIVERS=1</code> before running uxplay, or
|
||
set this in the default environment.</p>
|
||
<p>You can try to fix audio or video problems by using the
|
||
“<code>-as <audiosink></code>” or
|
||
“<code>-vs <videosink></code>” options to choose the GStreamer
|
||
audiosink or videosink , rather than letting GStreamer choose one for
|
||
you. (See above, in <a href="#starting-and-running-uxplay">Starting and
|
||
running UxPlay</a> for choices of <code><audiosink></code> or
|
||
<code><videosink></code>.)</p>
|
||
<p>The “OpenGL renderer” window created on Linux by “-vs glimagesink”
|
||
sometimes does not close properly when its “close” button is clicked.
|
||
(this is a GStreamer issue). You may need to terminate uxplay with
|
||
Ctrl-C to close a “zombie” OpenGl window. If similar problems happen
|
||
when the client sends the “Stop Mirroring” signal, try the no-close
|
||
option “-nc” that leaves the video window open.</p>
|
||
<h3 id="gstreamer-issues-missing-plugins-etc.">4. GStreamer issues
|
||
(missing plugins, etc.):</h3>
|
||
<ul>
|
||
<li>clearing the user’s GStreamer cache with
|
||
<code>rm -rf ~/.cache/gstreamer-1.0/*</code> may be the solution to
|
||
problems where gst-inspect-1.0 does not show a plugin that you believe
|
||
is installed. The cache will be regenerated next time GStreamer is
|
||
started. <strong>This is the solution to puzzling problems that turn out
|
||
to come from corruption of the cache, and should be tried
|
||
first.</strong></li>
|
||
</ul>
|
||
<p>If UxPlay fails to start, with a message that a required GStreamer
|
||
plugin (such as “libav”) was not found, first check with the GStreamer
|
||
tool gst-inspect-1.0 to see what GStreamer knows is available. (You may
|
||
need to install some additional GStreamer “tools” package to get
|
||
gst-inspect-1.0). For, <em>e.g.</em> a libav problem, check with
|
||
“<code>gst-inspect-1.0 libav</code>”. If it is not shown as available to
|
||
GStreamer, but your package manager shows the relevant package as
|
||
installed (as one user found), try entirely removing and reinstalling
|
||
the package. That user found that a solution to a “<strong>Required
|
||
gstreamer plugin ‘libav’ not found</strong>” message that kept recurring
|
||
was to clear the user’s gstreamer cache.</p>
|
||
<p>If it fails to start with an error like
|
||
‘<code>no element "avdec_aac"</code>’ this is because even though
|
||
gstreamer-libav is installed. it is incomplete because some plugin
|
||
features are missing: “<code>gst-inspect-1.0 | grep avdec_aac</code>”
|
||
will show if avdec_aac is available. Unlike other GStreamer plugins, the
|
||
libav plugin is a front end to FFmpeg codecs which provide avdec_*.</p>
|
||
<ul>
|
||
<li><p>Some distributions (RedHat, SUSE, etc) provide incomplete
|
||
versions of FFmpeg because of patent issues with codecs used by certain
|
||
plugins. In those cases there will be some “extra package” provider like
|
||
<a href="https://rpmfusion.org">RPM fusion</a> (RedHat), <a
|
||
href="http://packman.links2linux.org/">packman</a> (SUSE) where you can
|
||
get complete packages (your distribution will usually provide
|
||
instructions for this, Mageia puts them in an optional “tainted” repo).
|
||
The packages needed may be “ffmpeg*” or “libav*” packages: the GStreamer
|
||
libav plugin package does not contain any codecs itself, it just
|
||
provides a way for GStreamer to use ffmpeg/libav codec libraries which
|
||
must be installed separately. For similar reasons, distributions may
|
||
ship incomplete packages of GStreamer “plugins-bad”. Use user on Fedora
|
||
thought they had installed from rpmfusion, but the system had not
|
||
obeyed: <em>“Adding –allowerasing to the dnf command fixed it after a
|
||
restart”</em>.</p></li>
|
||
<li><p>starting with release UxPlay-1.65.3, UxPlay will continue to
|
||
function, but without audio in mirror mode, if avdec_aac is
|
||
missing.</p></li>
|
||
</ul>
|
||
<p>To troubleshoot GStreamer execute “export GST_DEBUG=2” to set the
|
||
GStreamer debug-level environment-variable in the terminal where you
|
||
will run uxplay, so that you see warning and error messages; see <a
|
||
href="https://gstreamer.freedesktop.org/documentation/tutorials/basic/debugging-tools.html">GStreamer
|
||
debugging tools</a> for how to see much more of what is happening inside
|
||
GStreamer. Run “gst-inspect-1.0” to see which GStreamer plugins are
|
||
installed on your system.</p>
|
||
<p>Some extra GStreamer packages for special plugins may need to be
|
||
installed (or reinstalled: a user using a Wayland display system as an
|
||
alternative to X11 reported that after reinstalling Lubuntu 18.4, UxPlay
|
||
would not work until gstreamer1.0-x was installed, presumably for
|
||
Wayland’s X11-compatibility mode). Different distributions may break up
|
||
GStreamer 1.x into packages in different ways; the packages listed above
|
||
in the build instructions should bring in other required GStreamer
|
||
packages as dependencies, but will not install all possible plugins.</p>
|
||
<p>The GStreamer video pipeline, which is shown in the initial output
|
||
from <code>uxplay -d</code>, has the default form</p>
|
||
<pre><code>appsrc name=video_source ! queue ! h264parse ! decodebin ! videoconvert ! autovideosink name=video_sink sync=false</code></pre>
|
||
<p>The pipeline is fully configurable: default elements “h264parse”,
|
||
“decodebin”, “videoconvert”, and “autovideosink” can respectively be
|
||
replaced by using uxplay options <code>-vp</code>, <code>-vd</code>,
|
||
<code>-vc</code>, and <code>-vs</code>, if there is any need to modify
|
||
it (entries can be given in quotes “…” to include options).</p>
|
||
<h3 id="mirror-screen-freezes-a-network-problem">5. Mirror screen
|
||
freezes (a network problem):</h3>
|
||
<p>This can happen if the TCP video stream from the client stops
|
||
arriving at the server, probably because of network problems (the UDP
|
||
audio stream may continue to arrive). At 3-second intervals, UxPlay
|
||
checks that the client is still connected by sending it a request for a
|
||
NTP time signal. If a reply is not received from the client within a 0.3
|
||
sec time-window, an “ntp timeout” is registered. If a certain number
|
||
(currently 5) of consecutive ntp timeouts occur, UxPlay assumes that the
|
||
client is “dead”, and resets the connection, becoming available for
|
||
connection to a new client, or reconnection to the previous one.
|
||
Sometimes the connection may recover before the timeout limit is
|
||
reached, and if the default limit is not right for your network, it can
|
||
be modified using the option “-reset <em>n</em>”, where <em>n</em> is
|
||
the desired timeout-limit value (<em>n</em> = 0 means “no limit”). If
|
||
the connection starts to recover after ntp timeouts, a corrupt video
|
||
packet from before the timeout may trigger a “connection reset by peer”
|
||
error, which also causes UxPlay to reset the connection.</p>
|
||
<ul>
|
||
<li>When the connection is reset, the “frozen” mirror screen of the
|
||
previous connection is left in place, but does <strong>not</strong>
|
||
block new connections, and will be taken over by a new client connection
|
||
when it is made.</li>
|
||
</ul>
|
||
<h3
|
||
id="protocol-issues-with-decryption-of-the-encrypted-audio-and-video-streams-sent-by-the-client.">6.
|
||
Protocol issues (with decryption of the encrypted audio and video
|
||
streams sent by the client).</h3>
|
||
<p>A protocol failure may trigger 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.</p>
|
||
<p>The protocol was modifed in UxPlay-1.65 after it was discovered that
|
||
the client-server “pairing” step could be avoided (leading to a much
|
||
quicker connection setup, without a 5 second delay) by disabling
|
||
“Supports Legacy Pairing” (bit 27) in the “features” code UxPlay
|
||
advertises on DNS-SD Service Discovery. Most clients will then not
|
||
attempt the setup of a “shared secret key” when pairing, which is used
|
||
by AppleTV for simultaneous handling of multiple clients (UxPlay only
|
||
supports one client at a time). <strong>This change is now well-tested,
|
||
but in case it causes any protocol failures, UxPlay can be reverted to
|
||
the previous behavior by uncommenting the previous “FEATURES_1” setting
|
||
(and commenting out the new one) in lib/dnssdint.h, and then rebuilding
|
||
UxPlay.</strong> (“Pairing” is re-enabled when the new Apple-style
|
||
one-time “pin” authentication is activated by running UxPlay with the
|
||
“-pin” option introduced in UxPlay 1.67.)</p>
|
||
<p>Protocol failure 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
|
||
<code>UxPlay/lib/global.h</code>. 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 for DNS-SD Service Discovery, Uxplay declares itself to be
|
||
an AppleTV3,2 (a 32 bit device) with a sourceVersion 220.68; this can
|
||
also be changed in global.h. UxPlay also 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), so it does not seem to matter
|
||
what version UxPlay claims to be.</p>
|
||
<h1 id="changelog">Changelog</h1>
|
||
<p>1.71 2024-12-13 Add support for HTTP Live Streaming (HLS), initially
|
||
only for YouTube movies. Fix issue with NTP timeout on Windows.</p>
|
||
<p>1.70 2024-10-04 Add support for 4K (h265) video (resolution 3840 x
|
||
2160). Fix issue with GStreamer >= 1.24 when client sleeps, then
|
||
wakes.</p>
|
||
<p>1.69 2024-08-09 Internal improvements (e.g. in -nohold option,
|
||
identifying GStreamer videosink selected by autovideosink, finding X11
|
||
display) in anticipation of future HLS video support. New -nofreeze
|
||
option to not leave frozen video in place when a network connection is
|
||
reset. Fixes for GStreamer-1.24.x changes.</p>
|
||
<p>1.68 2023-12-31 New simpler (default) method for generating a
|
||
persistent public key from the server MAC address (which can now be set
|
||
with the -m option). (The previous method is still available with -key
|
||
option). New option -reg to maintain a register of pin-authenticated
|
||
clients. Corrected volume-control: now interprets AirPlay volume range
|
||
-30dB:0dB as decibel gain attenuation, with new option -db low[:high]
|
||
for “flat” rescaling of the dB range. Add -taper option for a “tapered”
|
||
AirPlay volume-control profile.</p>
|
||
<p>1.67 2023-11-30 Add support for Apple-style one-time pin
|
||
authentication of clients with option “-pin”: (uses SRP6a authentication
|
||
protocol and public key persistence). Detection with error message of
|
||
(currently) unsupported H265 video when requesting high resolution over
|
||
wired ethernet. Removed rpi* options (which are not valid with new
|
||
Raspberry Pi model 5, and can be replaced by combinations of other
|
||
options). Added optional argument “mac” to “-m” option, to specify a
|
||
replacement MAC address/Device ID. Update llhttp to v. 9.1.3. Add -dacp
|
||
option for exporting current client DACP info (for remotes).</p>
|
||
<p>1.66 2023-09-05 Fix IPV6 support. Add option to restrict clients to
|
||
those on a list of allowed deviceIDs, or to block connections from
|
||
clients on a list of blocked deviceIDs. Fix for #207 from <span
|
||
class="citation" data-cites="thiccaxe">@thiccaxe</span> (screen lag in
|
||
vsync mode after client wakes from sleep).</p>
|
||
<p>1.65.3 2023-07-23 Add RPM spec file; add warning if required
|
||
gstreamer libav feature “avdec_aac” is missing: (this occurs in
|
||
RPM-based distributions that ship an incomplete FFmpeg for Patent or
|
||
License reasons, and rely on users installing an externally-supplied
|
||
complete FFmpeg). Mirror-mode airplay will now work without audio if
|
||
avdec_aac is missing.</p>
|
||
<p>1.65 2023-06-03 Eliminate pair_setup part of connection protocol to
|
||
allow faster connections with clients (thanks to <span class="citation"
|
||
data-cites="shuax">@shuax</span> #176 for this discovery); to revert,
|
||
uncomment a line in lib/dnssdint.h. Disconnect from audio device when
|
||
connection closes, to not block its use by other apps if uxplay is
|
||
running but not connected. Fix for AirMyPC client (broken since 1.60),
|
||
so its older non-NTP timestamp protocol works with -vsync. Corrected
|
||
parsing of configuration file entries that were in quotes.</p>
|
||
<p>1.64 2023-04-23 Timestamp-based synchronization of audio and video is
|
||
now the default in Mirror mode. (Use “-vsync no” to restore previous
|
||
behavior.) A configuration file can now be used for startup options.
|
||
Also some internal cleanups and a minor bugfix that fixes #192.</p>
|
||
<p>1.63 2023-02-12 Reworked audio-video synchronization, with new
|
||
options -vsync (for Mirror mode) and -async (for Audio-Only mode, to
|
||
sync with client video). Option -vsync makes software h264 decoding of
|
||
streamed videos with option -avdec viable on some recent Raspberry Pi
|
||
models. Internal change: all times are now processed in nanoseconds
|
||
units. Removed -ao option introduced in 1.62.</p>
|
||
<p>1.62 2023-01-18 Added Audio-only mode time offset -ao x to allow user
|
||
synchronization of ALAC audio playing on the server with video, song
|
||
lyrics, etc. playing on the client. x = 5.0 appears to be optimal in
|
||
many cases. Quality fixes: cleanup in volume changes, timestamps, some
|
||
bugfixes.</p>
|
||
<p>1.61 2022-12-30 Removed -t option (workaround for an Avahi issue,
|
||
correctly solved by opening network port UDP 5353 in firewall). Remove
|
||
-g debug flag from CMAKE_CFLAGS. Postpend (instead of prepend) build
|
||
environment CFLAGS to CMAKE_CFLAGS. Refactor parts of uxplay.cpp</p>
|
||
<p>1.60 2022-12-15 Added exit with error message if DNSServiceRegister
|
||
fails (instead of just stalling). Test for Client’s attempt to using
|
||
unsupported AirPlay 2 “REMOTE CONTROL” protocol (with no timing
|
||
channel), and exit if this occurs. Reworked metadata processing to
|
||
correctly parse DMAP header (previous version worked with DMAP messages
|
||
currently received, but was not correct).</p>
|
||
<p>1.59 2022-12-12 remove “ZOOMFIX” compile option and make compilation
|
||
with X11-dependence the default if X11 development libraries are
|
||
detected (this now also provides fullscreen mode with a F11 or Alt+Enter
|
||
key toggle); ZOOMFIX is now automatically applied for GStreamer <
|
||
1.20. New cmake option -DNO_X11_DEPS compiles uxplay without X11
|
||
dependence. Reworked internal metadata handling. Fix segfault with “-vs
|
||
0”.</p>
|
||
<p>1.58 2022-10-29 Add option “-nohold” that will drop existing
|
||
connections when a new client connects. Update llhttp to v8.1.0.</p>
|
||
<p>1.57 2022-10-09 Minor fixes: (fix coredump on AUR on “stop
|
||
mirroring”, occurs when compiled with AUR CFLAGS -DFORTIFY_SOURCE);
|
||
graceful exit when required plugins are missing; improved support for
|
||
builds on Windows. Include audioresample in GStreamer audio
|
||
pipeline.</p>
|
||
<p>1.56 2022-09-01 Added support for building and running UxPlay-1.56 on
|
||
Windows (no changes to Unix (Linux, *BSD, macOS) codebase.)</p>
|
||
<p>1.56 2022-07-30 Remove -bt709 from -rpi, -rpiwl, -rpifb as GStreamer
|
||
is now fixed.</p>
|
||
<p>1.55 2022-07-04 Remove the bt709 fix from -v4l2 and create a new
|
||
-bt709 option (previous “-v4l2” is now “-v4l2 -bt709”). This allows the
|
||
currently-required -bt709 option to be used on its own on RPi without
|
||
-v4l2 (sometimes this give better results).</p>
|
||
<p>1.54 2022-06-25 Add support for “Cover Art” display in Audio-only
|
||
(ALAC) mode. Reverted a change that caused VAAPI to crash with AMD
|
||
POLARIS graphics cards. Minor internal changes to plist code and uxplay
|
||
option parsing.</p>
|
||
<p>1.53 2022-06-13 Internal changes to audio sync code, revised
|
||
documentation, Minor bugfix (fix assertion crash when resent audio
|
||
packets are empty).</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>
|
||
<p>1.48 2022-03-11 Made the GStreamer video pipeline fully configurable,
|
||
for use with hardware h264 decoding. Support for Raspberry Pi.</p>
|
||
<p>1.47 2022-02-05 Added -FPSdata option to display (in the terminal)
|
||
regular reports sent by the client about video streaming performance.
|
||
Internal cleanups of processing of video packets received from the
|
||
client. Added -reset n option to reset the connection after n ntp
|
||
timeouts (also reset after “connection reset by peer” error in video
|
||
stream).</p>
|
||
<p>1.46 2022-01-20 Restore pre-1.44 behavior (1.44 may have broken
|
||
hardware acceleration): once again use decodebin in the video pipeline;
|
||
introduce new option “-avdec” to force software h264 decoding by libav
|
||
h264, if needed (to prevent selection of vaapisink by autovideosink).
|
||
Update llhttp to v6.0.6. UxPlay now reports itself as AppleTV3,2.
|
||
Restrict connections to one client at a time (second client must now
|
||
wait for first client to disconnect).</p>
|
||
<p>1.45 2022-01-10 New behavior: close video window when client requests
|
||
“stop mirroring”. (A new “no close” option “-nc” is added for users who
|
||
wish to retain previous behavior that does not close the video
|
||
window).</p>
|
||
<p>1.44 2021-12-13 Omit hash of aeskey with ecdh_secret for an AirMyPC
|
||
client; make an internal rearrangement of where this hash is done. Fully
|
||
report all initial communications between client and server in -d debug
|
||
mode. Replace decodebin in GStreamer video pipeline by h264-specific
|
||
elements.</p>
|
||
<p>1.43 2021-12-07 Various internal changes, such as tests for
|
||
successful decryption, uniform treatment of informational/debug
|
||
messages, etc., updated README.</p>
|
||
<p>1.42 2021-11-20 Fix MAC detection to work with modern Linux interface
|
||
naming practices, MacOS and *BSD.</p>
|
||
<p>1.41 2021-11-11 Further cleanups of multiple audio format support
|
||
(internal changes, separated RAOP and GStreamer audio/video startup)</p>
|
||
<p>1.40 2021-11-09 Cleanup segfault in ALAC support, manpage location
|
||
fix, show request Plists in debug mode.</p>
|
||
<p>1.39 2021-11-06 Added support for Apple Lossless (ALAC) audio
|
||
streams.</p>
|
||
<p>1.38 2021-10-8 Add -as <em>audiosink</em> option to allow user to
|
||
choose the GStreamer audiosink.</p>
|
||
<p>1.37 2021-09-29 Append “<span class="citation"
|
||
data-cites="hostname">@hostname</span>” to AirPlay Server name, where
|
||
“hostname” is the name of the server running uxplay (reworked change in
|
||
1.36).</p>
|
||
<p>1.36 2021-09-29 Implemented suggestion (by <span class="citation"
|
||
data-cites="mrbesen">@mrbesen</span> and <span class="citation"
|
||
data-cites="PetrusZ">@PetrusZ</span>) to use hostname of machine runing
|
||
uxplay as the default server name</p>
|
||
<p>1.35.1 2021-09-28 Added the -vs 0 option for streaming audio, but not
|
||
displaying video.</p>
|
||
<p>1.35 2021-09-10 now uses a GLib MainLoop, and builds on macOS (tested
|
||
on Intel Mac, 10.15 ). New option -t <em>timeout</em> for relaunching
|
||
server if no connections were active in previous <em>timeout</em>
|
||
seconds (to renew Bonjour registration).</p>
|
||
<p>1.341 2021-09-04 fixed: render logger was not being destroyed by
|
||
stop_server()</p>
|
||
<p>1.34 2021-08-27 Fixed “ZOOMFIX”: the X11 window name fix was only
|
||
being made the first time the GStreamer window was created by uxplay,
|
||
and not if the server was relaunched after the GStreamer window was
|
||
closed, with uxplay still running. Corrected in v. 1.34</p>
|
||
<h3 id="building-openssl-1.1.1-from-source.">Building OpenSSL >=
|
||
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/"
|
||
class="uri">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 >=
|
||
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 with git from <a
|
||
href="https://github.com/libimobiledevice/libplist"
|
||
class="uri">https://github.com/libimobiledevice/libplist</a>, or get the
|
||
source from the Releases section (use the *.tar.bz2 release,
|
||
<strong>not</strong> the *.zip or *.tar.gz versions): download <a
|
||
href="https://github.com/libimobiledevice/libplist/releases/download/2.3.0/libplist-2.3.0.tar.bz2">libplist-2.3.0</a>,
|
||
then unpack it (“tar -xvjf libplist-2.3.0.tar.bz2 ; cd libplist-2.3.0”),
|
||
and build/install it: (“./configure ; make ; sudo make install”). This
|
||
will probably install libplist-2.0.* in /usr/local/lib. The new
|
||
libplist-2.3.0 release should be compatible with UxPlay; <a
|
||
href="https://github.com/libimobiledevice/libplist/releases/download/2.2.0/libplist-2.2.0.tar.bz2">libplist-2.2.0</a>
|
||
is also available if there are any issues.</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>
|
||
<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 the developers
|
||
and the appropriate steps will be taken.</p>
|
||
<p>Given the large number of third-party AirPlay receivers (mostly
|
||
closed-source) available for purchase, it is our understanding that an
|
||
open source implementation of the same functionality wouldn’t violate
|
||
any of Apple’s rights either.</p>
|
||
<h1 id="uxplay-authors">UxPlay authors</h1>
|
||
<p><em>[adapted from fdraschbacher’s notes on RPiPlay
|
||
antecedents]</em></p>
|
||
<p>The code in this repository accumulated from various sources over
|
||
time. Here is an attempt at listing the various authors and the
|
||
components they created:</p>
|
||
<p>UxPlay was initially created by <strong>antimof</strong> from
|
||
RPiPlay, by replacing its Raspberry-Pi-adapted OpenMAX video and audio
|
||
rendering system with GStreamer rendering for desktop Linux systems; the
|
||
antimof work on code in <code>renderers/</code> was later backported to
|
||
RPiPlay, and the antimof project became dormant, but was later revived
|
||
at the <a href="http://github.com/FDH2/UxPlay">current GitHub site</a>
|
||
to serve a wider community of users.</p>
|
||
<p>The previous authors of code included in UxPlay by inheritance from
|
||
RPiPlay include:</p>
|
||
<ul>
|
||
<li><strong>EstebanKubata</strong>: Created a FairPlay library called <a
|
||
href="https://github.com/EstebanKubata/playfair">PlayFair</a>. Located
|
||
in the <code>lib/playfair</code> folder. License: GNU GPL</li>
|
||
<li><strong>Juho Vähä-Herttua</strong> and contributors: Created an
|
||
AirPlay audio server called <a
|
||
href="https://github.com/juhovh/shairplay">ShairPlay</a>, including
|
||
support for Fairplay based on PlayFair. Most of the code in
|
||
<code>lib/</code> originally stems from this project. License: GNU
|
||
LGPLv2.1+</li>
|
||
<li><strong>dsafa22</strong>: Created an AirPlay 2 mirroring server <a
|
||
href="https://github.com/dsafa22/AirplayServer">AirplayServer</a> (seems
|
||
gone now), for Android based on ShairPlay. Code is preserved <a
|
||
href="https://github.com/jiangban/AirplayServer">here</a>, and <a
|
||
href="https://github.com/FDH2/UxPlay/wiki/AirPlay2">see here</a> for the
|
||
description of the analysis of the AirPlay 2 mirror protocol that made
|
||
RPiPlay possible, by the AirplayServer author. All code in
|
||
<code>lib/</code> concerning mirroring is dsafa22’s work. License: GNU
|
||
LGPLv2.1+</li>
|
||
<li><strong>Florian Draschbacher</strong> (FD-) and contributors:
|
||
adapted dsafa22’s Android project for the Raspberry Pi, with extensive
|
||
cleanups, debugging and improvements. The project <a
|
||
href="https://github.com/FD-/RPiPlay">RPiPlay</a> is basically a port of
|
||
dsafa22’s code to the Raspberry Pi, utilizing OpenMAX and OpenSSL for
|
||
better performance on the Pi. License GPL v3. FD- has written an
|
||
interesting note on the history of <a
|
||
href="http://github.com/FD-/RPiPlay#airplay-protocol-versions">Airplay
|
||
protocol versions</a>, available at the RPiPlay github repository.</li>
|
||
</ul>
|
||
<p>Independent of UxPlay, but used by it and bundled with it:</p>
|
||
<ul>
|
||
<li><strong>Fedor Indutny</strong> (of Node.js, and formerly Joyent,
|
||
Inc) and contributors: Created an http parsing library called <a
|
||
href="https://github.com/nodejs/llhttp">llhttp</a>. Located at
|
||
<code>lib/llhttp/</code>. License: MIT</li>
|
||
</ul>
|